Start a Relay Chain

In this tutorial you will start a Polkadot-like chain (the relay chain), use Cumulus to create your own parachain, and connect it to the relay chain all in a local testnet environment.

Before you begin

If you aren't familiar with the concept of parachains, please learn about them first before continuing:

• Parachain Basics
• The Path of a Parachain Block
• Parachain Development Overview

If you are here without any former Substrate experience, you will likely not be able to understand or complete this tutorial. We assume you have completed these tutorials:

• Create Your First Substrate Chain
• Start a Private Network

With those complete, let's dive in!

What you will be doing

Learning outcomes

• Set up your parachain build environment
• Start a relay chain
• Customize a relay chain specification

Hardware and software requirements

Build with underpowered hardware

If you cannot find a machine with the minimums here, try the following solutions which trade longer build times for more limited memory usage.

• Use less threads: cargo -j flag specifies the number of threads used to build. Try to use one less than the CPU cores your machine has.
• Use cargo codegen units feature makes more optimized builds with less ram, but much longer compile times.

# set the number of cores/threads to compile (used to build cumulus/polkadot on rpi 3)
cargo build --release -j 1
# use less codegen units
RUSTFLAGS="-C codegen-units=1" cargo build --release

Software versioning

This tutorial has been tested on:

• Polkadot v0.9.17
• Substrate Parachain Template polkadot-v0.9.17
• Polkadot-JS Apps v0.106.2-29. It is generally expected that the hosted Polkadot-JS Apps should work. If you have issues, build and run this UI yourself at this tagged version/commit.

We're doing our best to keep the parachain template and this tutorial updated presently with the latest release of Polkadot.

Please join the Parachain Technical matrix channel to report any issues you run into and get further support! />

Build your nodes

In case you haven't, please follow the instructions to setup a local development environment for Substrate.

Building the relay chain node

Polkadot network will serve as our relay chain in this workshop. So clone the Polkadot repository and build the node:

# Clone the Polkadot Repository
git clone https://github.com/paritytech/polkadot.git

# Switch into the Polkadot directory
cd polkadot

# Checkout the proper commit
git checkout v0.9.17

# Build the relay chain Node
cargo build --release

# Check if the help page prints to ensure the node is built correctly
./target/release/polkadot --help

After you start the compilation, it will take a while (15 mins to 60 mins) to complete. So go ahead and continue to read through the rest of the workshop during the wait. 😉

If the help page is printed, you have succeeded in building a Polkadot node.

Building the parachain template

We will use the Substrate parachain template to launch our first parachain and make cross-chain asset transfers. The parachain template is similar but not identical to the node template. Later, we will use this parachain template as the starting point for developing our own parachains.

See the guide on converting a solo chain to a parachain for details on how the parachain template was created, and how to convert your chain's logic (not state migrations!) to a parachain.

In a new terminal window:

# Clone the parachain template
git clone https://github.com/substrate-developer-hub/substrate-parachain-template

# Switch into the parachain template directory
cd substrate-parachain-template

# Checkout the proper commit
git checkout polkadot-v0.9.17

# Build the parachain template collator
cargo build --release

# Check if the help page prints to ensure the node is built correctly
./target/release/parachain-collator --help

Again, this will take 15 to 60 mins to complete.

If the help page is printed, you have succeeded in building a Cumulus-based parachain collator.

Relay chain specification

You will need a chain specification (chain spec) for your relay chain network.

Whichever chain spec file you choose to use we will refer to the file simply as chain-spec.json in the instructions below. You will need to supply the proper path to the chain spec you are using.

Pre-configured chain spec files

We have included a two-validator relay chain with Alice and Bob as authorities chan spec file in this tutorial that you can use without modification for a local test network. This is useful for registering a single parachain:

• Plain rococo-local relay chain spec
• Raw rococo-local relay chain spec

Plain chain spec files are in a more human readable and modifiable format for your inspection. You will need to convert it to a SCALE encoded raw chain spec to use when starting your nodes. Jump to the raw chainspec generation section to see how to do that.

The above raw chain specs were created according to the steps in the create your own chain spec section.

Start your relay chain

Before we can attach any cumulus-based parachains, we need to launch a relay chain for them to connect to. This section describes in detail how to start both nodes using the above two-validator raw chain spec as well as the general instructions for starting additional nodes.

Start the alice validator

# Start Relay `Alice` node
./target/release/polkadot \
--alice \
--validator \
--base-path /tmp/relay/alice \
--chain <path to spec json> \
--port 30333 \
--ws-port 9944

The port (port) and websocket port (ws-port) specified here are the defaults and thus those flags can be omitted. However we choose to leave them in to enforce the habit of checking their values. Once this node is launched, no other nodes on the same local machine can use these ports.

When the node starts you will see several log messages. Take note of the node's Peer ID in the logs. We will need it when connecting other nodes to it. It will look something like this:

🏷 Local node identity is: 12D3KooWGjsmVmZCM1jPtVNp6hRbbkGBK3LADYNniJAKJ19NUYiq

Start the bob validator

./target/release/polkadot \
--bob \
--validator \
--base-path /tmp/relay-bob \
--chain <path to spec json> \
--bootnodes /ip4/<Alice IP>/tcp/30333/p2p/<Alice Peer ID> \
--port 30334 \
--ws-port 9945

Bob's command is perfectly analogous to Alice's. It differs from Alice's one by his own base path, his own validator key (--bob), and his own ports. Finally he adds a --bootnodes flag. This flag is not strictly necessary if you are running the entire network on a single local machine, but it is necessary when operating over the network.

Starting additional validators (optional)

If you are using the two-validator raw chain spec, you do not need to start additional nodes, but others may need to start more nodes. Again, this command is entirely analogous. You just need to make sure that nodes on the same local machine do not have conflicting ports or base paths.

./target/release/polkadot \
--charlie \
--validator \
--base-path /tmp/relay-charlie \
--chain <path to spec json> \
--bootnodes /ip4/<Alice IP>/tcp/30333/p2p/<Alice Peer ID> \
--port 30335 \
--ws-port 9946

Custom relay chain specifications

Optionally, explore the how-to guide on configuring a custom chain spec for instructions to tweak the provided plain chain spec for addition of more validators without modification of Polkadot's source code.