Test runtime upgrades
The following guide shows how to test runtime upgrades.
A key feature of Substrate is its support for forkless upgrades. Testing the blockchain runtime upgrade process is essential to ensure a seamless network transition without disruptions.
To simulate and validate the process of upgrading a blockchain's runtime, the on-runtime-upgrade
executes the OnRuntimeUpgrade
hooks of a runtime against the state of a live blockchain or a snapshot.
Hence, there are two subcommands live
and snap
to specify the source of the runtime state.
Usage: pop test on-runtime-upgrade [OPTIONS] [COMMAND]
Commands:
live A live chain
snap A state snapshot
help Print this message or the help of the given subcommand(s)
Test migrations
By running the command pop test on-runtime-upgrade
, you can test the Runtime Upgrades and Storage Migrations in a simulated environment.
┌ Pop CLI : Testing migrations
│
◆ Do you want to specify which runtime to run the migration on?
│ If not provided, use the code of the remote node, or a snapshot.
│ ● Yes / ○ No
└
Before running the migration, you will be prompted to confirm if you want to specify which runtime to run the migration on:
If you choose to specify, you will be prompted to select the runtime to run the migration on. The feature requires your runtime to be built with
--try-runtime
feature.
Pop CLI will automatically locate the runtime binary based on the provided
--profile
. Pop CLI will automatically build the runtime if not found.
If not, the migration will be run against the code that's currently running on the remote node or the one stored inside the snapshot file you provide.
Snapshot can be created with
pop test create-snapshot
.
Test migrations against a live chain
◆ Select source of runtime state:
│ ● Live (Run the migrations on top of live state.)
│ ○ Snapshot
|
◇ Enter the live chain of your node:
│ wss://rpc1.paseo.popnetwork.xyz
│
◆ Enter the block hash (optional):
│ 0x1234567890abcdef1234567890abcdef
└
You'll be asked to enter the URI of a live node and optionally provide a block hash. If a block hash is given, the state will be executed at the specified block hash on the provided network.
To run the migrations on top of live state manually:
pop test on-runtime-upgrade \
--runtime=<path_to_runtime_binary> \
live \
--uri=wss://rpc1.paseo.popnetwork.xyz \
--at=0x1234567890abcdef1234567890abcdef
Note: The specified runtime and the remote node's runtime must have the same name and version. If not, the migration will fail. You can add the flag --disable-spec-version-check
and --disable-spec-name-check
to bypass the checks.
pop test on-runtime-upgrade \
--runtime=<path_to_runtime_binary> \
--disable-spec-version-check \
--disable-spec-name-check \
live \
--uri=wss://rpc1.paseo.popnetwork.xyz \
--at=0x1234567890abcdef1234567890abcdef
After that, you can select the upgrade checks to perform:
◆ Select upgrade checks to perform:
│ ○ none
│ ● all (Run the `try_state`, `pre_upgrade` and `post_upgrade` checks)
│ ○ try-state
│ ○ pre-and-post
└
Test migrations with a snapshot file
A second approach to test migrations is with a snapshot file. First, you need to create a snapshot file of a live network. You can do this by running the following command:
pop test create-snapshot
The interactive interface to prompts for the live URI and the path of the snapshot file:
┌ Pop CLI : Creating a snapshot file
│
▲ NOTE: `create-snapshot` only works with the remote node. No runtime required.
│
◇ Enter the URI of the remote node:
│ wss://rpc1.paseo.popnetwork.xyz
│
◇ Enter the path to write the snapshot to (optional):
│ If not provided `<spec-name>-<spec-version>@<block-hash>.snap` will be used.
│ example.snap
To skip the interactive prompt, use the --uri
and --path
flags:
pop test create-snapshot --uri wss://rpc1.paseo.popnetwork.xyz ./example.snap
If the path of snapshot file is not provided, the default name following a format <spec-name>-<spec-version>@<block-hash>.snap
will be used. Note that the remote node must be built with --try-runtime
feature enabled.
Assume there is a snapshot file created with the name example.snap
:
◇ Enter path to your snapshot file?
│ Snapshot file can be generated using `pop test create-snapshot` command.
│ ./example.snap
To run migrations with a snapshot manually:
pop test on-runtime-upgrade \
--runtime=<path_to_runtime_binary> \
--blocktime=6000 \
--checks=all \
snap \
--path=./example.snap
Learning Resources
🧑🏫 To learn about Polkadot in general, Polkadot.network website is a good starting point.
🧑🔧 For technical introduction of the
try-runtime
, here.Learn more about Runtime Upgrades and Storage Migrations.
Need help?
Ask on Polkadot Stack Exchange (tag it pop
) or drop by our Telegram. We're here to help!
Last updated
Was this helpful?