Running Kusama and Polkadot from the same code: explained

Starting with version 0.8.0 of the Polkadot code, the codebase is shared between three chains: Polkadot, Kusama, and Westend. How is it possible that a single codebase can power chains that are so different? Why does renaming the program from polkadot to kusama cause it to run another chain?

Video version


We recommend you familiarize yourself with the concept of Substrate-based chains and specifically Polkadot before reading on. The two linked resources should consume no more than 10 minutes of your time, and video versions are also available.


When you compile a Substrate-based chain, you end up with two outputs:

  1. the WASM blob
  2. the executable binary

The WASM

The WASM blob is what gets included in the blockchain itself, and that's what we can use to achieve forkless upgrades.

The Polkadot codebase is configured so that it produces three different WASM binaries on compilation. That is defined in the project's Cargo.toml file. Indeed, after we compile a 0.8.x version, we can see the WASM blobs in target/release/wbuild:

But if we check the executable binary that is the result of our compilation, we get a single file: polkadot. Even more curiously, if we rename it to kusama, it will automatically run as Kusama, otherwise it will default to Polkadot. What gives?

The Binary

The binary contains the logic of all three chains, but based on the chain specification loaded by the provided chain name, some of that functionality will remain untouched. The chain specification for each chain is generated separately by the runtime of that chain.

Every chain's runtime is defined in its own crate, a Rust module if you will, and they all share some common functionality through the polkadot-runtime-common crate.

This common create is a dependency of all three runtimes in the binary, but built only once and then invoked by each separate runtime which builds custom functionality on top of and around it.

If you're thinking "what a waste of computer resources to have the functionality in but not used", keep in mind that this is the more convenient route for now. Splitting the repository into three isolated ones would create overhead which isn't worth it when compared to the overhead in extra storage space used by the slightly bigger binary and two additional WASM blobs.

So what about the last mystery - the fact that renaming polkadot to kusama causes the binary to run Kusama? That's defined in the command.rs file which looks for the name of the executable which launched it. If the name isn't familiar, it'll fall back to the --chain flag, listening for something like --chain=kusama, or --chain=westend.


Remember to subscribe to our newsletter to be kept up to date on new posts and to be kept in the loop about Web 3.0 developments.

Related posts