Convert a Solo-Chain to a Parachain

Goal

Add Cumulus and use a relay chain to provide finality

Use Cases

Bootstraping a solo-chain's security
Access XCMP with Parachains on a common relay chain

Overview

Integration of Cumulus for any Substrate chain enables this chain to couple it's finality with a relay chain, like Polkadot. This guide does not inform on how to migrate a running solo-chain, only the steps required to convert the codebase of a node to use Cumulus for consensus instead of something like GRANDPA that is common for other Substrate solo-chains.

DOC WORK IN PROGRESS

This is an overview, not a proper how-to guide presently!

Parachain node template overview

Substrate developers who are familiar with the Substrate node template will find the Substrate parachain template familiar. They have the same general structure featuring node, runtime, and pallets directories. Their runtimes are similar and feature many of the same pallets. Apart from a few new traits, the pallet-template itself is essentially identical. Many of the tutorials can be used with few modifications on the parachain template.

The similarities between these two templates should give you confidence that if you've built a Substrate chain, you will have no problem building a parachain!

Differences from the node template

There are, however, a few important differences between the two templates that are worth observing at the outset.

Parachain info pallet

Parachain template runtime (runtime/Cargo.toml) has integrated parachain-info pallet in. This pallet is designed to inject information about the parachain's registration into its own runtime. Currently it just injects the para ID that the chain is registered at. This allows the runtime to know which cross-chain messages are intended for it.

`register_validate_block!` macro

Each parachain must supply a validate_block function, expressed as a Wasm blob, to the relay chain when registering. The node template does not provide this function, but the parachain template does, Thanks to cumulus, creating this function for a Substrate runtime is as simple as adding one line of code as shown at the bottom of the runtime:

cumulus_pallet_parachain_system::register_validate_block!(
  Runtime = Runtime,
  BlockExecutor = cumulus_pallet_aura_ext::BlockExecutor::<Runtime, Executive>,
  CheckInherents = CheckInherents,
);

No `GRANDPA` pallet

Many popular Substrate runtimes including the node template features a finality-related GRANDPA pallet and its associated GrandpaApi. These are both missing from the parachain template.

This is because parachains follow the finality of the relay chain rather than running their own finality gadget. This is fundamental to Polkadot's architecture and will not change.

Service

The collator service (node/src/service.rs) is entirely different from the one of Node template. While you can find similarities, the structure of the service is much different. This new service is the primary change that cumulus provides.

Note

When modifying an existing Substrate chain to use Cumulus, it is generally best to copy the service code from the parachain template.