Fork a substrate based blockchain

This blog post will guide you through the process of forking a substrate blockchain like Polkadot. Substrate does not offer any forking capabilities out of the box but we can still create a “fork” relatively easily. I created a small script to make the process much easier, you can find the script here.

Forking a blockchain

How does it work?

The script essentially works by creating a new genesis file that contains the current state of the live blockchain in its genesis block. The script first fetches the WASM runtime blob and the current state of the blockchain you are forking. It then creates a new genesis file based on a --dev chain. The state and runtime of the live blockchain is then inserted into the the --dev chain’s genesis configuration. While inserting the state, the script filters out certain modules like Babe and Grandpa to allow the new chain to work with a different set of validators.

This new genesis config is then used to bootstrap a new blockchain. This new blockchain will closely resemble the original chain and allow you to easily test potentially destructive upgrades and features without harming the main blockchain. This script is aimed at creating a development fork. If you want to create an actual fork to maybe restore a dead blockchain, you can modify the filters I’ve added for certain modules to suit your hard fork needs.

Using the script

  1. Clone the script’s repository and install its dependencies

    git clone
    cd fork-off-substrate
    npm i
  2. Create a folder called data inside the top folder (fork-off-substrate).
  3. Copy the executable/binary of your substrate node inside the data folder and rename the executable to binary.
  4. Copy the runtime WASM blob of your substrate chain inside the data folder and rename it to runtime.wasm. To get the WASM blob, compile your substrate chain and look for ./target/release/wbuild/runtime/runtime.compact.wasm. If you are forking Polkadot/Kusama/Westend, you can download the WASM blobs from Polkadot’s release page.
  5. If your substrate chain uses additional custom types, define them in a JSON file of format { "types": "{ <YOUR_TYPES> }" }. Copy the file to the data folder and rename it to schema.json. Example custom types schema.
  6. Either run a full node for your blockchain locally(Recommended) or have an external HTTP RPC endpoint ready.
  7. Run the script
    • If using a local node, simply run the script using npm start.
    • If you are using an external/non-default endpoint, you need to provide it to the script via the HTTP_RPC_ENDPOINT environment variable: 
      HTTP_RPC_ENDPOINT= npm start
  8. You should have the genesis file for the forked chain inside the data folder. It will be called fork.json.
  9. You can now run a new chain using this genesis file:
    ./binary --chain fork.json --alice
    The node can take a few minutes to start due to the size of the genesis block.


Fork off substrate is a tiny script that allows forking a substrate based blockchain for easier and more reliable testing and development.

1 thought on “Fork a substrate based blockchain”

Leave a Comment

Your email address will not be published.