In this tutorial, you will configure a local relay chain and connect a parachain template for use in a local testing environment.
Before you begin, verify the following:
- You have configured your environment for Substrate development by installing Rust and the Rust toolchain.
- You have completed the Build a local blockchain tutorial previously.
- You know how to generate chain specifications for a private network of trusted validators as described in Add trusted nodes.
- You are generally familiar with the architecture of Polkadot and parachains.
By completing this tutorial, you will accomplish the following objectives:
- Identify software requirements.
- Set up your parachain build environment.
- Prepare a relay chain specification.
- Start a relay chain locally.
You must use the exact versions set forth in this tutorial. Parachains are very tightly coupled with the relay chain codebase that they connect to because they share so many common dependencies. Be sure to use the corresponding version of Polkadot with any other software when working on any examples throughout the Substrate documentation. You must stay synchronized with relay chain upgrades for your parachain to continue running successfully. If you don't keep up with relay chain upgrades, it's likely that your network will stop producing blocks.
All tutorials in the docs have been tested to work with:
- Substrate Parachain Template
- Polkadot-JS Apps
v0.116.2-34. 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.
A slightly modified version of Polkadot's built in
rococo-local network configuration will serve as the relay chain for this tutorial.
# Clone the Polkadot Repository, with correct version git clone --depth 1 --branch release-v0.9.26 https://github.com/paritytech/polkadot.git # Switch into the Polkadot directory cd polkadot # Build the relay chain Node cargo b -r
Compiling the node can take 15 to 60 minuets to complete.
# Check if the help page prints to ensure the node is built correctly ./target/release/polkadot --help
If the help page is printed, you have succeeded in building a Polkadot node.
You will need a chain specification for your relay chain network. As we want to use a local testnet, a custom configuration may be needed to set development or custom keys for validators, boot node addresses, etc.
A relay chain must have one more validator nodes running than the total of connected parachain collators. For testing these typically must be hard coded into your chain specs. For example, if you want to connect two parachains with a single collator, run three or more relay chain validator nodes, and ensure they all are specified in your chain spec.
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.
This tutorial includes a sample chain specification file with two validator relay chain nodes—Alice and Bob—as authorities. You can use this sample chain specification without modification for a local test network and a single parachain. This is useful for registering a single parachain:
You can read and edit the plain chain specification file. However, the chain specification file must be converged to the SCALE-encoded raw format before it can be used to start a node. For information about converting a chain specification to use the raw format, see the Customize a chain specification guide.
The sample chain specification is only valid for a single parachain with two validator nodes. If you add other validators, add additional parachains to your relay chain, or want to use custom non-development keys, you'll need to create a custom chain specification that fit your needs.
Before you can start block production for a parachains, you need to launch a relay chain for them to connect to. This section describes how to start both nodes using the two-validator raw chain spec. The steps are similar 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 in this command use default values and can be omitted.
However, the values are included here as a reminder to always check these values.
After the node starts, no other nodes on the same local machine can use these ports.
🏷 Local node identity is: 12D3KooWGjsmVmZCM1jPtVNp6hRbbkGBK3LADYNniJAKJ19NUYiq
When the node starts you will see several log messages, including the node's Peer ID. Take note of this, as you will need it when connecting other nodes to it.
The command to start the second node is similar to the command to start the first node with a few important differences.
./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
Notice that this command uses a a different base path (
/tmp/relay-bob), validator key (
--bob), and ports (
The command to start the second node also includes the
--bootnodes command-line option to specify the IP address and peer identifier of the first node.
bootnodes option is not strictly necessary if you are running the entire network on a single local machine, but it is necessary when using a connection to a non-local network without any specified bootnodes in the chain spec, as is the case with the rococo-custom-2-plain.json example we are using.
For this tutorial, your final chain spec filename must start with
rococo or the node will not know what runtime logic to include.
Manually building and configuring a relay chain is a great exercise. However, after you have done it a few times, you likely want to automate the process. There are many ways to go about this, here are a few for reference:
parachain-launchis a script that generates a docker compose file allowing you to launch a testnet of multiple blockchain nodes.
zombienetis a CLI tool that enables you to spawn ephemeral Polkadot/Substrate networks and perform tests against them.
With a running relay chain, naturally you will want to connect a parachain to it!