Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update try-runtime.md #2043

Merged
merged 2 commits into from
Aug 18, 2023
Merged

Update try-runtime.md #2043

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d0f626e
Update try-runtime.md
liamaharon Aug 17, 2023
f5bc57c
Update content/md/en/docs/reference/command-line-tools/try-runtime.md
liamaharon Aug 18, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
186 changes: 1 addition & 185 deletions content/md/en/docs/reference/command-line-tools/try-runtime.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,188 +10,4 @@ keywords:
- storage migration
---

The `try-runtime` command-line tool enables you to query a snapshot of runtime storage using an [in-memory-externalities](https://paritytech.github.io/substrate/master/sp_state_machine/struct.TestExternalities.html) 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:

```shell
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:

```shell
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.

| Command | Description
| ------- | -----------
| `on-runtime-upgrade` | Executes the migrations of the local runtime.
| `execute-block` | Executes the given block against some state.
| `offchain-worker`| Executes *the offchain worker hooks* of a given block against some state.
| `follow-chain` | Follows the given chain's finalized blocks and applies all of its extrinsics.
| `help`| Displays usage information for try-runtime the specified subcommand.

## Options

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

| Option | Description
| ------ | -----------
| `--chain <CHAIN_SPEC>` | Specifies the chain specification to use. You can use a predefined chain specification name, such as `dev`, `local`, or `staging` or the path to a file that contains the chain specification, for example, the chain specification generated by using the `build-spec` subcommand.
| `--dev` | Starts the node in development mode in a fresh state. No state is persisted if you run the node using this flag. This option sets `--chain=dev`, `--force-authoring`, `--rpc-cors=all`, `--alice`, and `--tmp` flags, unless explicitly overridden.
| `-d`, `--base-path <path>` | Specifies a custom base path.
| `-l`, `--log <log-pattern>...` | Sets a custom logging filter. The syntax to use is `<log-target>=<level>`, for example `-lsync=debug`. The valid log levels from least to most verbose are `error`, `warn`, `info`, `debug`, and `trace`. By default, all targets log `info` level messages. You can set the global log level with `-l<level>`.
| `--detailed-log-output` | Enables detailed log output, including the log target, log level and thread name. This option is automatically enabled when log level is higher than `info`.
| `--disable-log-color` | Disables log color output.
| `--enable-log-reloading` | Enables feature to dynamically update and reload the log filter. Be aware that enabling this feature can lead to a performance decrease up to factor six or more. Depending on the global logging level the performance decrease changes. The `system_addLogFilter` and `system_resetLogFilter` RPCs will have no effect with this option not being set.
| `--tracing-targets <targets>` | Sets a custom profiling filter. Syntax is the same as for logging: <target>=<level>.
| `--tracing-receiver <receiver>` | Specifies a receiver to process tracing messages.
| `--execution <strategy>` | Determines the execution strategy used by all execution contexts. Valid values are `Native`, `Wasm`, `Both` or `NativeElseWasm`.
| `--wasm-execution <method>` | Specifies the method for executing WebAssembly runtime code. Valid values are `interpreted`, or `compiled`. The default is `Compiled`.
| `--wasm-instantiation-strategy <strategy>` | Specifies the WebAssembly instantiation method to use if `wasm-execution` is set to `compiled`. The default strategy is `pooling-copy-on-write`.
| `--heap-pages <heap_pages>` | Specifies the number of 64KB pages to allocate for WebAssembly execution. The defaults is`sc_service::Configuration.default_heap_pages`.
| `--no-spec-check-panic` | Allows the specification check to issue a warning rather than panic.
| `--state-version <state_version>` | Specifies the state version that is used by the chain. The default is 1.
| `-h, --help` | Displays usage information (use `-h` for a summary).
| `-V, --version` | Displays version information.

## Examples

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

```bash
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:

```bash
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:

```bash
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:

```bash
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`](https://github.com/maxsam4/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:

```bash
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:

```bash
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:

```bash
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:

```bash
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](/build/runtime-storage#storage-value-keys)
- [OnRuntimeUpgrade](https://paritytech.github.io/substrate/master/frame_support/traits/trait.OnRuntimeUpgrade.html)
- [try-runtime-upgrade](https://paritytech.github.io/substrate/master/frame_executive/struct.Executive.html#method.try_runtime_upgrade)

`try-runtime` documentation has been moved [here](https://paritytech.github.io/try-runtime-cli/try_runtime).
liamaharon marked this conversation as resolved.
Show resolved Hide resolved