How to verify `runtime-upgrade` using `try-runtime

Question

I am trying to verify a simple runtime-upgrade using try-runtime. I followed https://docs.substrate.io/reference/how-to-guides/tools/use-try-runtime/ and https://docs.substrate.io/reference/command-line-tools/try-runtime/ to configure try-runtime.

I started a relaychain on local and connected my parachain. After that I increased authoring_version, spec_version, transaction_version by one.

I executed below command

cargo run  --release --features try-runtime -- try-runtime --chain rococo-local-raw.json --wasm-execution=compiled on-runtime-upgrade live --uri=ws://localhost:8844

and got below log

2022-06-28 19:25:24 Connection established to target: Target { sockaddrs: [], host: "localhost", host_header: "localhost:8844", _mode: Plain, path_and_query: "/" }
2022-06-28 19:25:24 scraping key-pairs from remote @ 0x54c6e42d70afcea8a69d6d4fa5bb6a4e88a56f12d4d6439d6f1327390c9d1890    
2022-06-28 19:25:24 downloading data for all pallets.    
2022-06-28 19:25:24 adding data for hashed key: 26aa394eea5630e07c48ae0c9558cef7f9cce9c888469bb1a0dceaa129672ef8    
2022-06-28 19:25:24 👩‍👦 scraping child-tree data from 0 top keys    
2022-06-28 19:25:24 injecting a total of 272 top keys    
2022-06-28 19:25:24 injecting a total of 0 child keys    
2022-06-28 19:25:24 initialized state externalities with storage root 0x6e3a0b89918cb69a8c1864afc1879fce3af15f080002f13ce217fddafa55449e    
2022-06-28 19:25:26 Connection established to target: Target { sockaddrs: [], host: "localhost", host_header: "localhost:8844", _mode: Plain, path_and_query: "/" }
2022-06-28 19:25:26 found matching spec name: "test-parachain"    
2022-06-28 19:25:26 found matching spec version: 4    
2022-06-28 19:25:26 try-runtime::on_runtime_upgrade parachain-template.    
2022-06-28 19:25:26 [138] 💸 Running migration with current storage version StorageVersion(1) / onchain StorageVersion(1)    
2022-06-28 19:25:26 [138] 💸 Migration did not executed. This probably should be removed    
2022-06-28 19:25:26 ✅ no migration for System    
2022-06-28 19:25:26 ⚠️ ParachainSystem declares internal migrations (which *might* execute). On-chain `StorageVersion(1)` vs current storage version `StorageVersion(1)`    
2022-06-28 19:25:26 ✅ no migration for Timestamp    
2022-06-28 19:25:26 ✅ no migration for ParachainInfo    
2022-06-28 19:25:26 ✅ no migration for TransactionPayment    
2022-06-28 19:25:26 ✅ no migration for Authorship    
2022-06-28 19:25:26 ✅ no migration for Session    
2022-06-28 19:25:26 ✅ no migration for Aura    
2022-06-28 19:25:26 ✅ no migration for AuraExt    
2022-06-28 19:25:26 ⚠️ XcmpQueue declares internal migrations (which *might* execute). On-chain `StorageVersion(1)` vs current storage version `StorageVersion(1)`    
2022-06-28 19:25:26 ⚠️ PolkadotXcm declares internal migrations (which *might* execute). On-chain `StorageVersion(0)` vs current storage version `StorageVersion(0)`    
2022-06-28 19:25:26 ✅ no migration for CumulusXcm    
2022-06-28 19:25:26 ✅ no migration for DmpQueue    
2022-06-28 19:25:26 ✅ no migration for XTokens    
2022-06-28 19:25:26 ✅ no migration for UnknownTokens    
2022-06-28 19:25:26 ✅ no migration for OrmlXcm    
2022-06-28 19:25:26 ✅ no migration for Treasury    
2022-06-28 19:25:26 ✅ no migration for Sudo    
2022-06-28 19:25:26 ✅ no migration for SudoOrigin    
2022-06-28 19:25:26 ✅ no migration for Council    
2022-06-28 19:25:26 ✅ no migration for Elections    
2022-06-28 19:25:26 ✅ no migration for Bootstrap    
2022-06-28 19:25:26 ✅ no migration for Utility    
2022-06-28 19:25:26 proof: 7e8e9f24b5fe37d30a429100664875294e7b9012096b41c4eb3aaf947f6ea42908010080fff78063ee78a43efee759a141dd64405df18ec3692c075def50a269d73fa4c79cf14680c3026eb264b25a84e01429e9564dd5bff011025763c472c33c2e81cc40ce8eb8802a18c60535c2eadd08e83fe26b935525c02144f18f53af9e2e055f6455128b1e80382f8597eb729aa4e676c306af30e936ddd8015efec0a833d135a72b45e1a4ba80cf890b0e8bb88ecc91a810cb7167abf988b2c96d782b07f905e3a3a054184fde80680036a0c364f6e7ef02889ac035636b10c6e166aff95ee8a1b4199dd540bb3c805f766a02769c4f3f74c0cfe5e781d43f7cce5248039c24b7a261ec0946bf133f809378787708226b4652132d7afec3add9d0c9e86eba9dbaca3133306d35f7c5948058e418bcf731d38bb0b715e168c72948f69ee197a9d0a2308f1a94e297b08bc880a05fc66697076e96eadd5d00d6029d1018044e0d4ba9453ca34fbef7c80118d7801f4ee836eebafabc11f84945ebfd2301ad3ec6b5786589a18ee9e9006b83b8e380060cba8c601bb318b4492a318599d76b65f31684b3050f492dd0a4b20c079c9480aa9cdcbba128719857cd6b792da28e766df4df00520b28916ed5a051d7f8169980496a14ca32680365b5928d6f7e94baf41f58749aa854498fab5f2cb3d720073f807576c2d2f87fe169a4a81e...1d4c4fd0153f71f566c4e280209cb3f73a369b3dd45351ac06f08666d2ffef955d3f76d3f6f369672f13964080a2ab88fbd63a9d859a9af8a71163b8bfa4337089d9b83b9e7247d3309e5627ee80bccc7e3755b35bfbda8f717e0d15c15ff2e618cbfad9fd4a80be807469a6461d9f05323df7cc47150b3930e2666b0aa3133d304c5f0a6ccf00f78ac824e72d27429ca3b8b004008027d293b7c1f82de8b4cb28ef8cd8f7e6f666edfa59bc72b5fc10d6bbc8e0c9a24c5f0dca42deb008c6559ee789c9b9f70a2c040080ce26713589dfb681da82046f8bebf1c3ba2f8e08eff1891451b75b7627bac301806588166e1e4eacf7963c352e635afc9330b1495dacde5ec41473e03897bf2ff68011c47f863c1b7176e7e4dfe070465f7dd3f126c81c104b40c5f1385a9bddf3c48012d8d13add449830dd394c801f4f2f8e2c74c65f39324b8572c8c3d4311b8bb68000b4806e05d5fab3cfa74da4413d7962efe8a22babc2afc0c38404d30d4a02a3fb1e688010851fbdf91d03d57ce2a55c0dc8bda46491e7fbcdce2fbdb5df4781c0429977801cd299ed858beb2792ed394c4e3c3c1a74eef452868b9bd5b21401ffea4afdb6807e5fa2b3716e2372be89d0fc4df4c28818808be46cc887321eb232be585e1230810e80104c5d0b9012096b41c4eb3aaf947f6ea429080100485d00959dca9d4616632a822d7523ba630400 / 15 nodes    
2022-06-28 19:25:26 proof size: 894.42 KB (915888 bytes)    
2022-06-28 19:25:26 compact proof size: 894.02 KB (915472 bytes)    
2022-06-28 19:25:26 zstd-compressed compact proof 894.04 KB (915499 bytes)    
2022-06-28 19:25:26 TryRuntime_on_runtime_upgrade executed without errors. Consumed weight = 150000000, total weight = 250000000000 (0.0006)   

How would I know whether runtime_upgrade went successfully?

Answer 1

Try Runtime uses a set of functions in the OnRuntimeUpgrade trait you need to implement and plug into your runtime.

/// The runtime upgrade trait.
///
/// Implementing this lets you express what should happen when the runtime upgrades,
/// and changes may need to occur to your module.
pub trait OnRuntimeUpgrade {
    /// Perform a module upgrade.
    ///
    /// # Warning
    ///
    /// This function will be called before we initialized any runtime state, aka `on_initialize`
    /// wasn't called yet. So, information like the block number and any other
    /// block local data are not accessible.
    ///
    /// Return the non-negotiable weight consumed for runtime upgrade.
    fn on_runtime_upgrade() -> crate::weights::Weight {
        0
    }

    /// Execute some pre-checks prior to a runtime upgrade.
    ///
    /// This hook is never meant to be executed on-chain but is meant to be used by testing tools.
    #[cfg(feature = "try-runtime")]
    fn pre_upgrade() -> Result<(), &'static str> {
        Ok(())
    }

    /// Execute some post-checks after a runtime upgrade.
    ///
    /// This hook is never meant to be executed on-chain but is meant to be used by testing tools.
    #[cfg(feature = "try-runtime")]
    fn post_upgrade() -> Result<(), &'static str> {
        Ok(())
    }
}

So you have a pre_upgrade hook which can return a result before the upgrade happens, and a post_upgrade hook which is run after the upgrade.

If you want to test some migration with Try Runtime, you need to implement one of these two hooks.

For example, from the Nomination Pools Pallet:

/// Trivial migration which makes the roles of each pool optional.
///
/// Note: The depositor is not optional since he can never change.
pub struct MigrateToV1<T>(sp_std::marker::PhantomData<T>);
impl<T: Config> OnRuntimeUpgrade for MigrateToV1<T> {
    fn on_runtime_upgrade() -> Weight {
        let current = Pallet::<T>::current_storage_version();
        let onchain = Pallet::<T>::on_chain_storage_version();

        log!(
            info,
            "Running migration with current storage version {:?} / onchain {:?}",
            current,
            onchain
        );

        if current == 1 && onchain == 0 {
            // this is safe to execute on any runtime that has a bounded number of pools.
            let mut translated = 0u64;
            BondedPools::<T>::translate::<OldBondedPoolInner<T>, _>(|_key, old_value| {
                translated.saturating_inc();
                Some(old_value.migrate_to_v1())
            });

            current.put::<Pallet<T>>();

            log!(info, "Upgraded {} pools, storage to version {:?}", translated, current);

            T::DbWeight::get().reads_writes(translated + 1, translated + 1)
        } else {
            log!(info, "Migration did not executed. This probably should be removed");
            T::DbWeight::get().reads(1)
        }
    }

    #[cfg(feature = "try-runtime")]
    fn post_upgrade() -> Result<(), &'static str> {
        // new version must be set.
        assert_eq!(Pallet::<T>::on_chain_storage_version(), 1);
        Ok(())
    }
}

Finally, you need to include this runtime upgrade into your runtime:

/// Executive: handles dispatch to the various modules.
pub type Executive = frame_executive::Executive<
    Runtime,
    Block,
    frame_system::ChainContext<Runtime>,
    Runtime,
    AllPalletsWithSystem,
    InitiatePoolConfigs,
    (
        // Add migration structs here
    ),
>;

You can look at PRs like this to follow along:

https://github.com/paritytech/substrate/pull/11357