Polkadot Runtime Releaser

Streamline the process of releasing a new runtime for polkadot-sdk-based runtime.

Setup Guide

Polkadot Runtime Releaser CLI

Install from Source Code

git clone https://github.com/hack-ink/polkadot-runtime-releaser
cd polkadot-runtime-releaser
cargo install --path cli

Install from crates.io

cargo install polkadot-runtime-releaser-cli

Install from GitHub

# macOS
curl -L https://github.com/hack-ink/polkadot-runtime-releaser/releases/latest/download/prr-aarch64-apple-darwin.zip \
	-o prr.zip &&
	unzip prr.zip &&
	chmod u+x prr &&
	rm prr.zip

# Linux
curl -L https://github.com/hack-ink/polkadot-runtime-releaser/releases/latest/download/prr-x86_64-unknown-linux-gnu.tar.gz |
	tar xz &&
	chmod u+x prr

# If you want to move the binary to `~/.local/bin` (OPTIONAL).
mkdir -p ~/.local/bin && mv prr ~/.local/bin

Rust Toolchain

Having a fixed Rust toolchain version is crucial for building a deterministic runtime.

Create a rust-toolchain.toml file in the root of your project and add the following content:

[toolchain]
# Using Rust `stable` as an example. You can replace it with the desired version.
channel    = "stable"
# `clippy`, `rust-src`, and `rustfmt` are optional. Remove them if not needed.
components = ["cargo", "clippy", "rust-src", "rustc", "rustfmt"]
# `minimal` is enough to build the runtime. Choose the profile you need:
# https://rust-lang.github.io/rustup/concepts/profiles.html
profile    = "minimal"
targets    = ["wasm32-unknown-unknown"]

With this file in place, PRR automatically uses the specified Rust toolchain version. This is the best way to manage the Rust toolchain version for your project.

If you don't have a rust-toolchain.toml file, PRR will generate one with the stable version for you by default.

PRR also supports configuring the Rust toolchain version when no rust-toolchain.toml file is present in the project's root. Use prr build --help for more information.

Docker

Another crucial part of building a deterministic runtime is using the same environment to build the runtime. We use Docker to create a consistent environment.

The default image is polkadot-runtime-releaser, maintained by the hack-ink community. It provides a well-configured environment for building the runtime. Each release is pinned to a specific version of this image to ensure a deterministic environment. However, you can use the -v or --image-version flag to specify a particular version.

PRR also supports using a custom Docker image. Run prr build --help for more information.

Runtime

REQUIREMENT

• PRR makes certain assumptions when handling the runtime:
  • The runtime crate name must follow the {}-runtime format. For example, see polkadot-runtime.
  • The generated WASM file name must be in {}_runtime.compact.compressed.wasm format. For example, see polkadot_runtime.compact.compressed.wasm.

GitHub

To fully leverage PRR, set up two repositories for your project—one for the runtime overrides and the other for the runtime itself. This is a commonly recommended practice. Some notable projects that follow this approach include:

• Astar
  • Runtime
  • Runtime Overrides
• Darwinia
  • Runtime
  • Runtime Overrides
• Moonbeam
  • Runtime
  • Runtime Overrides

Polkadot Runtime Releaser Action

Now, with PRR, all the steps mentioned in the above project setups can be streamlined!

Check the PRR workshop for a production-ready example.

All actions are available in the action directory. Don't forget to check their README for more details.

Usage

Build Command

CLI Help

Build the polkadot-sdk-based runtime

Usage: prr build [OPTIONS] <RUNTIME>

Arguments:
  <RUNTIME>
          The target runtime to build.

          This should be the name of the runtime crate in the <Cargo.toml> file.

Options:
  -f, --features <FEATURES>
          The features to enable for the runtime.

      --no-compressed-only
          Whether to store the compressed runtime only.

      --no-digest
          Whether to generate the digest file for the runtime.

  -t, --toolchain-version <VER>
          The toolchain version to use for the build; by default, it is set to <stable>.

          This won't take effect if there is a <rust-toolchain.toml> file in the project directory,
          and that's the recommended way to specify the toolchain version.

  -v, --image-version <VER>
          Image version of the <ghcr.io/hack-ink/polkadot-runtime-releaser>.

          [default: 0.2.0]

  -i, --override-docker-image <REPOSITORY>
          Overwrite the default docker image with the specified one.

          Use `docker images` to list the available images on your system.

  -d, --workdir <PATH>
          The polkadot-sdk-based project directory; by default, it is set to the current directory.

  -o, --output-dir <PATH>
          The target directory of the cargo build.

          [default: ./polkadot-runtime-releaser-output]

      --cache-output
          Whether to cache and use the output of the build.
          This is useful in local development.

      --cache-registry
          Whether to cache and use the <$HOME/.cargo/registry> registry.
          This is useful in local development.

  -h, --help
          Print help (see a summary with '-h')

Quick Example

git clone https://github.com/polkadot-fellows/runtimes.git
cd runtimes
prr build polkadot-runtime -f on-chain-release-build

Inspect Command

CLI Help

Inspect the WASM runtime

Usage: prr inspect [OPTIONS] <PATH>

Arguments:
  <PATH>  Path to the WASM runtime.

Options:
      --no-check-version  Whether to check the runtime version in the `ParachainSystem::authorized_upgrade` call.
  -b, --beautify          Whether to beautify the JSON output.
  -v, --verbose           Whether to print verbose output.
  -h, --help              Print help

Quick Example

prr inspect <RUNTIME_WASM_FILE> -b

License

^{Licensed under GPL-3.0.}