This repository contains both the Cumulus SDK and also specific chains implemented on top of this SDK.
A set of tools for writing Substrate-based Polkadot parachains. Refer to the included overview for architectural details, and the Connect to relay and parachain tutorials for a guided walk-through of using these tools.
It's easy to write blockchains using Substrate, and the overhead of writing parachains' distribution, p2p, database, and synchronization layers should be just as low. This project aims to make it easy to write parachains for Polkadot by leveraging the power of Substrate.
Cumulus clouds are shaped sort of like dots; together they form a system that is intricate, beautiful and functional.
parachain-consensus is a
consensus engine for Substrate
that follows a Polkadot
relay chain. This will run
a Polkadot node internally, and dictate to the client and synchronization algorithms which chain
and treat as best.
A Polkadot collator for the parachain is
implemented by the
polkadot-parachain binary (previously called
Installation and Setup
Before building Cumulus SDK based nodes / runtimes prepare your environment by following Substrate installation instructions.
We use Zombienet to spin up networks for integration tests and local networks. Follow these installation steps to set it up on your machine. A simple network specification with two relay chain nodes and one collator is located at zombienet/examples/small_network.toml.
Which provider should I use?
Zombienet offers multiple providers to run networks. Choose the one that best fits your needs:
- Podman: Choose this if you want to spin up a network quick and easy.
- Native: Choose this if you want to develop and deploy your changes. Requires compilation of the binaries.
- Kubernetes: Choose this for advanced use-cases or running on cloud-infrastructure.
How to run
To run the example network, use the following commands:
# Podman provider zombienet --provider podman spawn ./zombienet/examples/small_network.toml # Native provider, assumes polkadot and polkadot-parachains binary in $PATH zombienet --provider native spawn ./zombienet/examples/small_network.toml
Launch the Relay Chain
# Clone git clone https://github.com/paritytech/polkadot cd polkadot # Compile Polkadot with the real overseer feature cargo build --release --bin polkadot # Generate a raw chain spec ./target/release/polkadot build-spec --chain rococo-local --disable-default-bootnode --raw > rococo-local-cfde.json # Alice ./target/release/polkadot --chain rococo-local-cfde.json --alice --tmp # Bob (In a separate terminal) ./target/release/polkadot --chain rococo-local-cfde.json --bob --tmp --port 30334
Launch the Parachain
# Clone git clone https://github.com/paritytech/cumulus cd cumulus # Compile cargo build --release --bin polkadot-parachain # Export genesis state ./target/release/polkadot-parachain export-genesis-state > genesis-state # Export genesis wasm ./target/release/polkadot-parachain export-genesis-wasm > genesis-wasm # Collator1 ./target/release/polkadot-parachain --collator --alice --force-authoring --tmp --port 40335 --ws-port 9946 -- --execution wasm --chain ../polkadot/rococo-local-cfde.json --port 30335 # Collator2 ./target/release/polkadot-parachain --collator --bob --force-authoring --tmp --port 40336 --ws-port 9947 -- --execution wasm --chain ../polkadot/rococo-local-cfde.json --port 30336 # Parachain Full Node 1 ./target/release/polkadot-parachain --tmp --port 40337 --ws-port 9948 -- --execution wasm --chain ../polkadot/rococo-local-cfde.json --port 30337
Register the parachain
This repository also contains the Statemint runtime (as well as the canary runtime Statemine and the test runtime Westmint). Statemint is a system parachain providing an asset store for the Polkadot ecosystem.
Build & Launch a Node
To run a Statemine or Westmint node (Statemint is not deployed, yet) you will need to compile the
cargo build --release --locked -p polkadot-parachain
Once the executable is built, launch the parachain node via:
CHAIN=westmint # or statemine ./target/release/polkadot-parachain --chain $CHAIN
Refer to the setup instructions to run a local network for development.
contracts-rococo readme for details.
bridge-hubs readme for details.
Rococo is becoming a Community Parachain Testbed for parachain teams in the Polkadot ecosystem. It supports multiple parachains with the differentiation of long-term connections and recurring short-term connections, to see which parachains are currently connected and how long they will be connected for see here.
Rococo is an elaborate style of design and the name describes the painstaking effort that has gone into this project.
Build & Launch Rococo Collators
Collators are similar to validators in the relay chain. These nodes build the blocks that will eventually be included by the relay chain for a parachain.
To run a Rococo collator you will need to compile the following binary:
cargo build --release --locked -p polkadot-parachain
Otherwise you can compile it with Parity CI docker image:
docker run --rm -it -w /shellhere/cumulus \ -v $(pwd):/shellhere/cumulus \ paritytech/ci-linux:production cargo build --release --locked -p polkadot-parachain sudo chown -R $(id -u):$(id -g) target/
If you want to reproduce other steps of CI process you can use the following guide.
Once the executable is built, launch collators for each parachain (repeat once each for chain
./target/release/polkadot-parachain --chain $CHAIN --validator
The network uses horizontal message passing (HRMP) to enable communication between parachains and the relay chain and, in turn, between parachains. This means that every message is sent to the relay chain, and from the relay chain to its destination parachain.
polkadot-parachain with cargo or with Parity CI image as documented in this chapter,
the following will allow producing a new docker image where the compiled binary is injected:
Alternatively, you can build an image with a builder pattern:
docker build --tag $OWNER/$IMAGE_NAME --file ./docker/polkadot-parachain_builder.Containerfile . You may then run your new container: ```bash docker run --rm -it $OWNER/$IMAGE_NAME --collator --tmp --execution wasm --chain /specs/westmint.json