srtool

Describes the Docker container and command-line interface for building the Substrate WebAssembly runtime.

The core component of the Substrate runtime toolbox (srtool) is a Docker container that enables you to build the Substrate WebAssembly runtime in a deterministic way. By using this tool, you can ensure that the same source code consistently reproduces an identical WebAssembly blob. You can also use the tool to inspect and audit the runtime for any Substrate-based chain and to integrate building the WebAssembly runtime into your CI/CD pipeline.

Working with the Docker container

Because srtool is a Docker container, you must have Docker available in your build environment to use it. However, you don't need to know anything about using Docker to build a chain using srtool because you can use the srtool-cli command-line interface to work with Docker images.

The srtiool-cli package is a command-line utility written in Rust that installs an executable program called srtool on your computer. This program simplifies your interactions with the srtool Docker container. Over time, the tooling around the srtool Docker image has expanded to include the following tools and helper programs:

• srtool-cli provides a command-line interface to pull the srtool Docker image, get information about the image and tooling used to interact with it, and build the runtime using the srtool Docker container.

• subwasm provides command-line options for working with the metadata and WebAssembly runtime built using srtool. The subwasm program is also used internally to perform tasks in the srtool image.

• srtool-actions provides Github actions to integrate builds produced using the srtool image with your GitHub CI/CD pipelines.

• srtool-app provides a simple graphical user interface for building the runtime using the srtool Docker image.

Installing srtool-cli

The srtool command-line interface enables you to build the WebAssembly runtime using the srtool Docker image. You can install the srtool command-line interface by running the following command:

cargo install --git https://github.com/chevdor/srtool-cli

Basic command usage

The basic syntax for running srtool commands is:

srtool [options] [subcommand]

Options

You can use the following command-line options with the srtool command.

Subcommands

You can use the following subcommands with the srtool command.

Examples

To get version information for the srtool Docker image, run the following command:

srtool version

The command displays output similar to the following:

{
  "name": "srtool",
  "version": "0.9.21",
  "rustc": "1.62.0",
  "subwasm": "0.18.0",
  "tera": "0.2.1",
  "toml": "0.2.1"
}

To get version information for the srtool-cli executable, run the following command:

srtool --version

The command displays output similar to the following:

srtool-cli 0.8.0

srtool build

Use the srtool build command to start a new srtool container to build the runtime for the package you specify. By default, the srtool build command assumes that the Cargo.toml file for the runtime is located in a runtime subdirectory with the name of the chain. For example, the srtool build command use the following locations by default:

• runtime/kusama

• runtime/polkadot

• runtime/rococo

• runtime/westend

If the Cargo.toml file for your runtime is in a different location, you can specify the path as a command-line option.

Basic usage

The basic syntax for running the srtool build command is:

srtool build [options] --package <package> [--runtime-dir <path>] [project-path]

Arguments

By default, the srtool build runs in the current working directory. If your project isn't located in the current working directory, you can specify the path to the project location.

Options

You can use the following command-line options with the srtool build command.

Examples

To build the Westend runtime from the cumulus repository where the path to the Cargo.toml for the runtime is parachains/runtimes/assets/asset-hub-westend, you would run the following command:

srtool build --app --package westmint-runtime --runtime-dir parachains/runtimes/assets/westmint

The first time you run the srtool build command it takes some time to complete. As the runtime compiles, messages about its progress are displayed as standard output. Because this example uses the --app command-line option, JSON output is displayed in a single line at the end of the build similar to the following truncated output:

...
   Compiling cumulus-primitives-parachain-inherent v0.1.0 (/build/primitives/parachain-inherent)
   Compiling cumulus-pallet-parachain-system v0.1.0 (/build/pallets/parachain-system)
    Finished release [optimized] target(s) in 112m 11s
✨ Your Substrate WASM Runtime is ready! ✨
{"gen":"srtool v0.9.21","src":"git","version":"1.0.0","commit":"bd41e3f11887ea2f55fc37be71ff652923388e03","tag":"v0.9.220-rc2","branch":"master","rustc":"rustc 1.62.0 (a8314ef7d 2022-06-27)","pkg":"westmint-runtime","tmsp":"2022-08-22T21:12:18Z","size":"707937","prop":"0x6b8e93443b6660a16f67a6cd34d415af463e2285eda3fd02b9fe052c1ad2ceb9"
... }}}}

srtool help

Use the srtool help command to display usage message for srtool or for a specified subcommand.

Basic usage

srtool help [subcommand]

Examples

To display usage information for the build subcommand, run the following command:

subkey help build

srtool info

Use the srtool info command to display information about the srtool container and your repository. By default, the srtool info command assumes that the Cargo.toml file for the runtime is located in a runtime subdirectory with the name of the chain. For example, the srtool info command use the following locations by default:

• runtime/kusama

• runtime/polkadot

• runtime/rococo

• runtime/westend

If the Cargo.toml file for your runtime is in a different location, you can specify the path as a command-line option.

Basic usage

The basic syntax for running the srtool info command is:

srtool info [options] --package <package> [--runtime-dir <path>] [project-path]

Arguments

By default, the srtool info runs in the current working directory. If your project isn't located in the current working directory, you can specify the path to the project location.

Options

You can use the following command-line options with the srtool info command.

Examples

To display information about the srtool container and the local node-template repository, you might run a command similar to the following:

srtool info --package node-template-runtime --runtime-dir runtime

This command displays output similar to the following:

{
  "generator": {
    "name": "srtool",
    "version": "0.9.21"
  },
  "src": "git",
  "version": "4.0.0-dev",
  "git": {
    "commit": "6a8b2b12371395979099d2c79ccc1860531b0449",
    "tag": "",
    "branch": "my-release-branch"
  },
  "rustc": "rustc 1.62.0 (a8314ef7d 2022-06-27)",
  "pkg": "polkadot-runtime",
  "profile": "release"
}

srtool pull

Use the srtool pull command to check for and download the latest version of the srtool Docker image.

Basic usage

The basic syntax for running the srtool pull command is:

srtool pull [options]

Options

You can use the following command-line options with the srtool pull command.

Examples

To check for a new version of the srtool container and Docker image, you might run a command similar to the following:

srtool pull

This command checks the Docker Hub for the latest version of the paritytech/srtool image and begins downloading and extracting the software. For example

Found 1.62.0, we will be using paritytech/srtool:1.62.0 for the build
1.62.0: Pulling from paritytech/srtool
405f018f9d1d: Pull complete 
c49473e7f7b3: Pull complete 
7edf98d07029: Pull complete 
85a50724a6fa: Pull complete 
87fb1e3dee5b: Downloading   19.4MB/170.4MB
469075c5d317: Download complete 
533bfa44b64a: Download complete 
...

When all tasks are complete, the command displays output similar to the following:

Digest: sha256:d5353a63d8fccbef5666e28a8fa0b302d71d4f53cabeb760fe213f3d7df4b8b6
Status: Downloaded newer image for paritytech/srtool:1.62.0
docker.io/paritytech/srtool:1.62.0

If you already have the latest version installed locally, the command displays output similar to the following:

Found 1.62.0, we will be using paritytech/srtool:1.62.0 for the build
1.62.0: Pulling from paritytech/srtool
Digest: sha256:d5353a63d8fccbef5666e28a8fa0b302d71d4f53cabeb760fe213f3d7df4b8b6
Status: Image is up to date for paritytech/srtool:1.62.0
docker.io/paritytech/srtool:1.62.0

srtool version

Use the srtool version command display version information for the srtool container. Use --version if you want the version of the srtool-cli executable.

Basic usage

The basic syntax for running the srtool version command is:

srtool version [options]

Options

You can use the following command-line options with the srtool version command.

Examples

To display information about the srtool container, run the following command:

srtool version       

The command displays output similar to the following:

{
  "name": "srtool",
  "version": "0.9.21",
  "rustc": "1.62.0",
  "subwasm": "0.18.0",
  "tera": "0.2.1",
  "toml": "0.2.1"
}

To display version information for the srtool command-line interface instead of the container, you can run the following command:

srtool version --version

The command displays output similar to the following:

srtool-version 0.8.0