try-runtime

The try-runtime command-line tool enables you to query a snapshot of runtime storage using an in-memory-externalities data structure to store state. With this tool, you can write tests against a snapshot of the runtime state before going to production.

Basic command usage

The basic syntax for running try-runtime commands is:

cargo run --release --features=try-runtime try-runtime [options] [subcommand]

Depending on the subcommand you specify, additional arguments, options, and flags might apply or be required. To view usage information for a specific try-runtime subcommand, specify the subcommand and the --help flag. For example, to see usage information for try-runtime on-runtime-upgrade, you can run the following command:

cargo run --release --features=try-runtime try-runtime on-runtime-upgrade --help

Subcommands

You can use the following subcommands with the try-runtime command-line tool. For reference information and examples that illustrate using these subcommands, select an appropriate command.

Options

You can use the following options with try-runtime commands.

Examples

To use try-runtime from the command line, run your node with the --features=try-runtime flag. For example:

cargo run --release --features=try-runtime try-runtime

To view usage information for a specific try-runtime subcommand, specify the subcommand and the --help flag. For example:

cargo run --release --features=try-runtime try-runtime on-runtime-upgrade --help

Setting RPC command-line options

Typically, you use try-runtime to prepare for storage migration and runtime upgrades. However, RPC calls that query storage are computationally expensive. To prepare a node for testing with try-runtime, you should start the node with the following command-line options:

• --rpc-max-request-size <RPC_MAX_REQUEST_SIZE> to set the maximum RPC request payload size—in megabytes—to ensure RPC calls that query storage aren't rejected. The default is 15MiB.
• --rpc-max-response-size <RPC_MAX_RESPONSE_SIZE> to set the maximum RPC response payload size—in megabytes—to ensure the data retrieved from RPC calls to storage can be returned. The default is 15MiB.
• --rpc-cors all to ensure all WebSocket connections can come through.

For example:

cargo run --release -- \
  --rpc-max-request-size 1000 \
  --rpc-max-response-size 1000 \
  --rpc-cors all \
  --dev

Runtime upgrade

You can use the on-runtime-upgrade subcommand to execute against the given runtime state. For example, you can run try-runtime with on-runtime-upgrade for a chain running locally with a command like this:

cargo run --release --features=try-runtime try-runtime on-runtime-upgrade live ws://localhost:9944

Migration testing

You can combine try-runtime with fork-off-substrate to test your chain before production. Use try-runtime to test your chain's migration and its pre and post states. Then, use fork-off-substrate if you want to check that block production continues after the migration.

Execute block

The execute-block subcommand executes core_execute_block using the given block and the runtime state of the parent block.

Follow chain

The follow-chain subcommand follows a given chain's finalized blocks and applies to all its extrinsics. This subcommand allows you to inspect the behavior of a new runtime over a long period of time with real transactions coming as input.

Offchain worker

The offchain-worker subcommand executes offchainWorkerApi_offchain_worker against the given runtime state. For example, you can use try-runtime to re-execute code from the ElectionProviderMultiPhase offchain worker on localhost:9944 with a command like this:

cargo run -- --release \
   --features=try-runtime \
   try-runtime \
   --execution Wasm \
   --wasm-execution Compiled \
   offchain-worker \
   --header-at 0x491d09f313c707b5096650d76600f063b09835fd820e2916d3f8b0f5b45bec30 \
   live \
   -b 0x491d09f313c707b5096650d76600f063b09835fd820e2916d3f8b0f5b45bec30 \
   -m ElectionProviderMultiPhase \
   --uri wss://localhost:9944

You can run the migrations of the local runtime on the state of SomeChain with a command like this:

RUST_LOG=runtime=trace,try-runtime::cli=trace,executor=trace \
   cargo run try-runtime \
   --execution Native \
   --chain somechain-dev \
   on-runtime-upgrade \
   live \
   --uri wss://rpc.polkadot.io

You can run try-runtime against the state for a specific block number with a command like this:

RUST_LOG=runtime=trace,try-runtime::cli=trace,executor=trace \
   cargo run try-runtime \
   --execution Native \
   --chain dev \
   --no-spec-name-check \
   on-runtime-upgrade \
   live \
   --uri wss://rpc.polkadot.io \
   --at <block-hash>

If the state of a particular pallet is sufficient for your test (e.g. a storage migration), you can use the pallet option of the live subcommand. Only the state/storages of that pallet will be uploaded. The option --no-spec-check-panic might be useful to not panic if local runtime spec name/version is not equal to the uri source:

RUST_LOG=runtime=trace,try-runtime::cli=trace,executor=trace \
   cargo run try-runtime \
   --execution Native \
   --chain somechain-dev \
   --no-spec-check-panic \
   on-runtime-upgrade \
   live \
   --uri wss://rpc.polkadot.io \
   --pallet NominationPools

Notice that this command requires the --no-spec-name-check command-line option.

Where to go next

• Storage keys
• OnRuntimeUpgrade
• try-runtime-upgrade