Polkadot SDK's Parachain Template

This is a template for creating a parachain based on Polkadot SDK.

This template is automatically updated after releases in the main Polkadot SDK monorepo.

Table of Contents

• Intro

• Template Structure

• Getting Started

• Starting a Development Chain

  • Omni Node
  • Zombienet setup with Omni Node
  • Parachain Template Node
  • Connect with the Polkadot-JS Apps Front-End
  • Takeaways

• Runtime development

• Contributing

• Getting Help

Intro

• ⏫ This template provides a starting point to build a parachain.

• ☁️ It is based on the Cumulus framework.

• 🔧 Its runtime is configured with a single custom pallet as a starting point, and a handful of ready-made pallets such as a Balances pallet.

• 👉 Learn more about parachains here

Template Structure

A Polkadot SDK based project such as this one consists of:

• 🧮 the Runtime - the core logic of the parachain.
• 🎨 the Pallets - from which the runtime is constructed.
• 💿 a Node - the binary application, not part of the project default-members list and not compiled unless building the project with --workspace flag, which builds all workspace members, and is an alternative to Omni Node.

Getting Started

• 🦀 The template is using the Rust language.

• 👉 Check the Rust installation instructions for your system.

• 🛠️ Depending on your operating system and Rust version, there might be additional packages required to compile this template - please take note of the Rust compiler output.

Fetch parachain template code:

git clone https://github.com/paritytech/polkadot-sdk-parachain-template.git parachain-template

cd parachain-template

Starting a Development Chain

The parachain template relies on a hardcoded parachain id which is defined in the runtime code and referenced throughout the contents of this file as {{PARACHAIN_ID}}. Please replace any command or file referencing this placeholder with the value of the PARACHAIN_ID constant:

pub const PARACHAIN_ID: u32 = 1000;

Omni Node Prerequisites

Omni Node can be used to run the parachain template's runtime. polkadot-omni-node binary crate usage is described at a high-level on crates.io.

Install polkadot-omni-node

Please see the installation section at crates.io/omni-node.

Build parachain-template-runtime

cargo build --release

Install staging-chain-spec-builder

Please see the installation section at crates.io/staging-chain-spec-builder.

Use chain-spec-builder to generate the chain_spec.json file

chain-spec-builder create --relay-chain "rococo-local" --para-id {{PARACHAIN_ID}} --runtime \
    target/release/wbuild/parachain-template-runtime/parachain_template_runtime.wasm named-preset development

Note: the relay-chain and para-id flags are mandatory information required by Omni Node, and for parachain template case the value for para-id must be set to {{PARACHAIN_ID}}, since this is also the value injected through ParachainInfo pallet into the parachain-template-runtime's storage. The relay-chain value is set in accordance with the relay chain ID where this instantiation of parachain-template will connect to.

Run Omni Node

Start Omni Node with the generated chain spec. We'll start it in development mode (without a relay chain config), producing and finalizing blocks based on manual seal, configured below to seal a block with each second.

polkadot-omni-node --chain <path/to/chain_spec.json> --dev --dev-block-time 1000

However, such a setup is not close to what would run in production, and for that we need to setup a local relay chain network that will help with the block finalization. In this guide we'll setup a local relay chain as well. We'll not do it manually, by starting one node at a time, but we'll use zombienet.

Follow through the next section for more details on how to do it.

Zombienet setup with Omni Node

Assuming we continue from the last step of the previous section, we have a chain spec and we need to setup a relay chain. We can install zombienet as described here, and zombienet-omni-node.toml contains the network specification we want to start.

Relay chain prerequisites

Download the polkadot (and the accompanying polkadot-prepare-worker and polkadot-execute-worker) binaries from Polkadot SDK releases. Then expose them on PATH like so:

export PATH="$PATH:<path/to/binaries>"

Update zombienet-omni-node.toml with a valid chain spec path

To simplify the process of using the parachain-template with zombienet and Omni Node, we've added a pre-configured development chain spec (dev_chain_spec.json) to the parachain template. The zombienet-omni-node.toml file of this template points to it, but you can update it to an updated chain spec generated on your machine. To generate a chain spec refer to staging-chain-spec-builder

Then make the changes in the network specification like so:

# ...
[[parachains]]
id = "<PARACHAIN_ID>"
chain_spec_path = "<TO BE UPDATED WITH A VALID PATH>"
# ...

Start the network

zombienet --provider native spawn zombienet-omni-node.toml

Parachain Template Node

As mentioned in the Template Structure section, the node crate is optionally compiled and it is an alternative to Omni Node. Similarly, it requires setting up a relay chain, and we'll use zombienet once more.

Install the parachain-template-node

cargo install --path node

Setup and start the network

For setup, please consider the instructions for zombienet installation here and relay chain prerequisites.

We're left just with starting the network:

zombienet --provider native spawn zombienet.toml

Connect with the Polkadot-JS Apps Front-End

• 🌐 You can interact with your local node using the hosted version of the Polkadot/Substrate Portal: relay chain and parachain.

• 🪐 A hosted version is also available on IPFS.

• 🧑‍🔧 You can also find the source code and instructions for hosting your own instance in the polkadot-js/apps repository.

Takeaways

Development parachains:

• 🔗 Connect to relay chains, and we showcased how to connect to a local one.
• 🧹 Do not persist the state.
• 💰 Are preconfigured with a genesis state that includes several prefunded development accounts.
• 🧑‍⚖️ Development accounts are used as validators, collators, and sudo accounts.

Runtime development

We recommend using chopsticks when the focus is more on the runtime development and OmniNode is enough as is.

Install chopsticks

To use chopsticks, please install the latest version according to the installation guide.

Build a raw chain spec

Build the parachain-template-runtime as mentioned before in this guide and use chain-spec-builder again but this time by passing --raw-storage flag:

chain-spec-builder create --raw-storage --relay-chain "rococo-local" --para-id {{PARACHAIN_ID}} --runtime \
    target/release/wbuild/parachain-template-runtime/parachain_template_runtime.wasm named-preset development

Start chopsticks with the chain spec

npx @acala-network/chopsticks@latest --chain-spec <path/to/chain_spec.json>

Alternatives

OmniNode can be still used for runtime development if using the --dev flag, while parachain-template-node doesn't support it at this moment. It can still be used to test a runtime in a full setup where it is started alongside a relay chain network (see Parachain Template node setup).

Contributing

• 🔄 This template is automatically updated after releases in the main Polkadot SDK monorepo.

• ➡️ Any pull requests should be directed to this source.

• 😇 Please refer to the monorepo's contribution guidelines and Code of Conduct.

Getting Help

• 🧑‍🏫 To learn about Polkadot in general, Polkadot.network website is a good starting point.

• 🧑‍🔧 For technical introduction, here are the Polkadot SDK documentation resources.

• 👥 Additionally, there are GitHub issues and Substrate StackExchange.