Skip to main content

Install the Cumulus Parachain Template

With our relay chain ready to be launched, we now need to ensure we have a parachain that meets the aforementioned requirements.

In this page, you will:

  • Install and compile the substrate-parachain-template
  • Configure the ParaID & Chain Spec
  • Generate your parachain's runtime and genesis state (Wasm)
  • If you don't wish to customize or go through this process, refer to the parachain-guide-resources repository

Install the substrate-parachain-template

The substrate-parachain-template is a Cumulus ready node template. If you have taken the previous Intro to Substrate course, you may have used a similar template. That template was a standalone chain - this template contains the requirements that a parachain needs to fulfill in order to connect to the relay chain and follow the Parachains Protocol.

  1. Start by cloning the repository with the same version as the relay chain:

    git clone --depth 1 --branch polkadot-v1.0.0
  2. Ensure we're on our own branch, and now build

    ⌛ This will take some time

    Depending on your machine, this may take 45-60 minutes.

    cd substrate-parachain-template
    git switch -c my-branch-v1.0.0
    # Build
    cargo build --release

Once your parachain is compiled, the process of altering it (if required) and recompiling will be trivial.

Create a symlink to easily run your parachain binary.

For ease of use, consider adding the target executable to your local path or creating a symlink:

# Replace <path> with the path to your cloned substrate-parachain-template repo
# The last line may need to be replaced!
ln -s <path>/target/release/parachain-template-node /usr/local/bin/parachain-template-node
# Use directly in path!

parachain-template-node --help
If you don't wish to customize or go through this process, refer to the

parachain-guide-resources repository

The repository has everything required to proceed to running your chains.

Parachain Chain Specification

Just as the relay chain had a chain spec, the parachain must have one as well. It is generated in the same way:

  1. Firstly, generate the JSON file:

    # Run from locally compiled repository
    ./substrate-parachain-template/target/release/parachain-template-node build-spec > ./parachain/parachain_chain_spec.json
  2. Once this is built, also build the raw, SCALE-encoded file:

    # Run from locally compiled repository
    ./substrate-parachain-template/target/release/parachain-template-node build-spec \
    --chain ./parachain/parachain_chain_spec.json \
    --disable-default-bootnode --raw > raw-parachain-chainspec.json

    If this succeeded, you will see the following output:

    2023-09-13 13:25:01 Building chain spec
    2023-09-13 13:25:01 assembling new collators for new session 0 at #0
    2023-09-13 13:25:01 assembling new collators for new session 1 at #0

Parachain Genesis & Runtime State

If you recall, the runtime of every Substrate-based chain is compiled down to Web Assembly (Wasm). This enables the runtime to be portable and stored on the relay chain, which is used for the purpose of validating state transitions from the parachain's collator.

The genesis configuration must also be configured, as the relay chain will require it when registering it in the next section. These both depend on the parachain_chain_spec.json which we previously generated.

As always, these are already available within the parachain-guide-resources repository.

Optional: Generating The Runtime Wasm Bundle

./substrate-parachain-template/target/release/parachain-template-node export-genesis-wasm \
--chain ./parachain/parachain_chain_spec_raw.json ./parachain/parachain-wasm

# or, with symlink:
parachain-template-node export-genesis-wasm \
--chain ./parachain/parachain_chain_spec_raw.json parachain-wasm

Optional: Generating the Genesis State Bundle

./substrate-parachain-template/target/release/parachain-template-node export-genesis-state \
--chain ./parachain/parachain_chain_spec_raw.json ./parachain/parachain-genesis-state

# or, with symlink:
parachain-template-node export-genesis-state \
--chain ./parachain/parachain_chain_spec_raw.json ./parachain/parachain-genesis-state

By now, you should have three total files generated and/or available under the parachains/ directory:

  • Parachain Runtime: parachain-wasm
  • Genesis State: parachain-genesis-state
  • JSON Chain Spec: parachain_chain_spec.json
  • Raw Chain Spec: parachain_chain_spec_raw.json

With these, we are now able to run our relay chain validators, run our parachain collator, and finally register our parachain.