Run a Parachain Network Using Zombienet

Introduction

Zombienet is a testing framework designed for Polkadot SDK-based blockchain networks. It enables developers to efficiently deploy and test ephemeral blockchain environments using a simple CLI.

This tutorial walks you through spawning a local parachain test network using Zombienet's native provider. You will build a custom parachain binary from the Polkadot SDK parachain template, download the relay chain binaries, configure a network with two relay chain validators and a parachain collator, and verify that the network produces blocks.

For detailed information about Zombienet installation methods, providers, CLI commands, and configuration options, refer to the Zombienet reference page.

Prerequisites

Before starting, ensure you have the following installed:

• Rust and Cargo

• The wasm32-unknown-unknown target. Add it with:

  rustup target add wasm32-unknown-unknown

• Zombienet - see the reference page for installation instructions

• Git

Set Up the Parachain Template

Clone and build the Polkadot SDK parachain template:

1. Clone the repository:

   git clone --branch v0.0.5 \
     https://github.com/paritytech/polkadot-sdk-parachain-template \
   && cd polkadot-sdk-parachain-template

2. Build the parachain node binary:

   cargo build --release

   This compiles the parachain-template-node binary to target/release/.

3. Add the binary to your PATH:

   export PATH=$PATH:$(pwd)/target/release

Download Relay Chain Binaries

You need the Polkadot relay chain binaries (polkadot, polkadot-prepare-worker, and polkadot-execute-worker) to run the relay chain validators.

Note

When using the parachain template v0.0.5, ensure you use a compatible relay chain binary. The recommended version is polkadot-stable2512-2, which you can download from the Polkadot SDK releases.

Download the binaries for your platform and make them executable:

mkdir -p bin
curl -L -o bin/polkadot \
  https://github.com/paritytech/polkadot-sdk/releases/download/polkadot-stable2512-2/polkadot
curl -L -o bin/polkadot-prepare-worker \
  https://github.com/paritytech/polkadot-sdk/releases/download/polkadot-stable2512-2/polkadot-prepare-worker
curl -L -o bin/polkadot-execute-worker \
  https://github.com/paritytech/polkadot-sdk/releases/download/polkadot-stable2512-2/polkadot-execute-worker
chmod +x bin/polkadot bin/polkadot-prepare-worker bin/polkadot-execute-worker

Alternatively, you can use Zombienet's setup command:

zombienet setup polkadot polkadot-parachain

Generate a Paseo Local Chain Spec

To run a local Paseo-based relay chain, you need to generate a chain spec using chain-spec-builder and the Paseo runtime. This creates a local testnet chain spec with development accounts (Alice, Bob) as validators.

1. Download chain-spec-builder from the Polkadot SDK releases:

   curl -L -o bin/chain-spec-builder \
     https://github.com/paritytech/polkadot-sdk/releases/download/polkadot-stable2512-2/chain-spec-builder
   chmod +x bin/chain-spec-builder

2. Download the Paseo runtime Wasm from the Paseo runtimes releases:

   curl -L -o bin/paseo_runtime.compressed.wasm \
     https://github.com/paseo-network/runtimes/releases/download/INSERT_PASEO_RUNTIME_VERSION/paseo_runtime.compressed.wasm

3. Generate the local testnet chain spec:

   bin/chain-spec-builder -c configs/paseo-local.json \
     create -r bin/paseo_runtime.compressed.wasm named-preset local_testnet

   This creates a configs/paseo-local.json chain spec with the local_testnet preset, which includes Alice and Bob as validators.

Configure the Network

Create a network.toml file that defines the network topology. This configuration sets up a relay chain with two validators and a parachain with one collator, using the Paseo local chain spec generated in the previous step:

[settings]
timeout = 1000
provider = "native"

[relaychain]
chain_spec_path = "./configs/paseo-local.json"
default_command = "./bin/polkadot"

[[relaychain.nodes]]
name = "alice"
validator = true
rpc_port = 9944

[[relaychain.nodes]]
name = "bob"
validator = true
rpc_port = 9945

[[parachains]]
id = 1000

[[parachains.collators]]
name = "collator01"
command = "./polkadot-sdk-parachain-template/target/release/parachain-template-node"
rpc_port = 9988

For a full reference of all available configuration options, see the Zombienet configuration reference.

Spawn the Network

Launch the network using Zombienet:

zombienet spawn network.toml --provider native

Zombienet will:

1. Generate chain specifications.
2. Start relay chain validators (Alice and Bob).
3. Register and start the parachain collator.
4. Display connection endpoints and logs.

Wait for the output to confirm the network has launched. You'll see RPC endpoints for each node.

Verify the Network

Once the network is running, verify that the relay chain is producing blocks by querying the RPC endpoint:

curl -s -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"chain_getHeader","params":[],"id":1}' \
  http://127.0.0.1:9944

The response should include a number field showing the current block number, confirming the relay chain is producing blocks.

You can also check the parachain collator:

curl -s -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"chain_getHeader","params":[],"id":1}' \
  http://127.0.0.1:9988

To stop the network, press Ctrl + C in the terminal where Zombienet is running.

View tests

Where to Go Next

• Zombienet Reference

  ---

  Explore the full Zombienet configuration reference, including all settings, relay chain, parachain, and collator options.

  → Zombienet Reference

• Zombienet Support

  ---

  Parity Technologies has designed and developed this framework, now maintained by the Zombienet team.

  For further support and information, refer to the following contact points:

  → Zombienet repository

  → Element public channel