Docs
Submit an issue
Appchains on Polkadot
Appchains on Polkadot
  • WELCOME
    • Polkadot Appchains
    • Installing Pop CLI
    • How to contribute
  • GUIDES
    • Set up your development environment
    • Create a new parachain
      • Create an Assets parachain
      • Create a Contracts parachain
      • Create an EVM parachain
    • Benchmarking
    • Build your parachain
      • Build your runtime deterministically
    • Call a chain
    • Launch a Chain
      • Launch a Chain in Development
      • Launch a Chain to Paseo
        • Launch Paseo
        • Set up keys
        • Acquire Coretime
      • Deploy a chain with Polkadot Deployment Portal
      • Running a post-startup command
    • Securely Sign Transactions from CLI
    • Test runtime upgrades
  • POP CLI
    • welcome
    • install
    • new
    • bench
    • build
    • build spec
    • call
    • up
    • clean
    • test
Powered by GitBook
On this page
  • Test migrations
  • Test migrations against a live chain
  • Test migrations with a snapshot file

Was this helpful?

Edit on GitHub
  1. GUIDES

Test runtime upgrades

The following guide shows how to test runtime upgrades.

PreviousSecurely Sign Transactions from CLINextwelcome

Last updated 1 month ago

Was this helpful?

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 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 and 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:

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
└

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

Technical Support

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 .

You'll be asked to enter the URI of a live node and optionally provide a block hash. If a is given, the state will be executed at the specified block hash on the provided network.

🧑‍🏫 To learn about Polkadot in general, website is a good starting point.

🧑‍🔧 For technical introduction of the try-runtime, .

Learn more about and .

Create a question and tag it with ""

Share the StackExchange question in our

OnRuntimeUpgrade
Runtime Upgrades
Storage Migrations
built with --try-runtime feature
block hash
Polkadot.network
here
Runtime Upgrades
Storage Migrations
Polkadot Stack Exchange
pop
Pop Support Telegram channel