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.
If you aren't familiar with the concept of parachains, please learn about them first before continuing:
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:
With those complete, let's dive in!
1. Hardware and software requirements
2. Build your nodes
3. Parachain node template overview
4. Relay chain specification
5. Start your relay chain
6. Create a custom relay chain spec (optional)
- Set up your parachain build environment
- Start a relay chain
- Customize a relay chain specification
Compiling this project is a resource intensive process! We suggest using a machine with no less than:
- 8 GB of RAM (16 GB is suggested)
- 4 CPU cores (8 cores are suggested)
- 50 GB of free HDD/SSD space
Without the minimal RAM here, you are likely run out of memory resulting in a
SIGKILL error during the compilation process, generally happens on building the
So be sure to monitor your RAM usage with tools like htop and look out as swap memory starting to be used.
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
-jflag 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
This tutorial has been tested on:
- Substrate Parachain Template
- Polkadot-JS Apps
v0.98.2-121. 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.
You must use the exact versions set forth in this tutorial to ensure that you do not run into conflicts.
At the moment, parachains are very tightly coupled with the relay chain codebase they are
connecting to. To have the least amount of hiccups, be sure to use the corresponding tagged
version of Polkadot and Parachain Template when working on this tutorial. So if you are using
v0.9.13, use the equivalent
version of Parachain Template
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! />
In case you haven't, please follow the instructions to setup a local development environment for Substrate.
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.13 # 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.
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.13 # 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.
You will need a chain specification (chain spec) for your relay chain network.
Always have one or more relay chain validator nodes running than the total connected parachains. For example, if you want to connect two parachains, run three or more relay chain validator nodes.
Whichever chain spec file you choose to use we will refer to the file simply as
in the instructions below. You will need to supply the proper path to the chain spec you are using.
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 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 conversion 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.
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 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
./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
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.
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
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.
For this tutorial, your final chain spec filename must start with
rococo or the node will not know what runtime logic to include.