https://github.com/hack-ink/polkadot-runtime-releaser
Streamline the process of releasing a new runtime for the Polkadot-SDK-based chain.
https://github.com/hack-ink/polkadot-runtime-releaser
Last synced: 28 days ago
JSON representation
Streamline the process of releasing a new runtime for the Polkadot-SDK-based chain.
- Host: GitHub
- URL: https://github.com/hack-ink/polkadot-runtime-releaser
- Owner: hack-ink
- License: gpl-3.0
- Created: 2024-11-13T14:18:44.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-10-20T00:21:19.000Z (8 months ago)
- Last Synced: 2025-12-28T22:40:48.895Z (5 months ago)
- Language: Rust
- Size: 422 KB
- Stars: 2
- Watchers: 1
- Forks: 2
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Polkadot Runtime Releaser
### Streamline the process of releasing a new runtime for polkadot-sdk-based runtime.
[](https://www.gnu.org/licenses/gpl-3.0)
[](https://github.com/hack-ink/polkadot-runtime-releaser/actions/workflows/checks.yml)
[](https://github.com/hack-ink/polkadot-runtime-releaser/actions/workflows/release.yml)
[](https://github.com/hack-ink/polkadot-runtime-releaser/tags)
[](https://github.com/hack-ink/polkadot-runtime-releaser)
[](https://github.com/hack-ink/polkadot-runtime-releaser)
## Setup Guide
### Polkadot Runtime Releaser CLI
#### Install from Source Code
```sh
git clone https://github.com/hack-ink/polkadot-runtime-releaser
cd polkadot-runtime-releaser
cargo install --path cli
```
#### Install from [crates.io](https://crates.io)
```sh
cargo install polkadot-runtime-releaser-cli
```
#### Install from GitHub
```sh
# 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:
```toml
[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](https://ghcr.io/hack-ink/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`](https://github.com/polkadot-fellows/runtimes/blob/46dcafcee64fe4d8c722d071a4a0ca983fcc2f08/relay/polkadot/Cargo.toml#L2).
- The generated WASM file name must be in `{}_runtime.compact.compressed.wasm` format. For example, see [`polkadot_runtime.compact.compressed.wasm`](https://github.com/polkadot-fellows/runtimes/releases/tag/v1.3.4).
### GitHub
> Why do we need to override the runtime?
>
> Always keep the on-chain runtime as minimal as possible which can help reduce the runtime size and improve the performance.
> Override with the `force-debug` runtime, you can get more debug information in the runtime log.
> Override with the `evm-tracing` runtime, you can enable the EVM tracing feature in the runtime.
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](https://github.com/AstarNetwork/Astar)
- [Runtime Overrides](https://github.com/sentioxyz/astar-runtime-overrides)
- Darwinia
- [Runtime](https://github.com/darwinia-network/darwinia)
- [Runtime Overrides](https://github.com/darwinia-network/darwinia-release)
- Moonbeam
- [Runtime](https://github.com/moonbeam-foundation/moonbeam)
- [Runtime Overrides](https://github.com/moonbeam-foundation/moonbeam-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](https://github.com/hack-ink/polkadot-runtime-releaser-workshop) for a production-ready example.
All actions are available in the [action](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]
Arguments:
The target runtime to build.
This should be the name of the runtime crate in the file.
Options:
-f, --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
The toolchain version to use for the build; by default, it is set to .
This won't take effect if there is a file in the project directory,
and that's the recommended way to specify the toolchain version.
-v, --image-version
Image version of the .
[default: 0.2.0]
-i, --override-docker-image
Overwrite the default docker image with the specified one.
Use `docker images` to list the available images on your system.
-d, --workdir
The polkadot-sdk-based project directory; by default, it is set to the current directory.
-o, --output-dir
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
```sh
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]
Arguments:
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
```sh
prr inspect -b
```
### License
Licensed under [GPL-3.0](LICENSE).