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 on platforms like Kubernetes, Podman, and native setups. With its simple CLI and Domain Specific Language (DSL) for writing tests, Zombienet streamlines network spawning, testing, and performance validation.

Key features include:

• Multi-provider support: Run networks on Kubernetes, Podman, or locally as native processes.
• Network orchestration: Spawn relay chains with multiple validators and parachains with collators.
• Test DSL: Write natural-language test scripts to evaluate metrics, logs, events, and on-chain storage.
• Monitoring integration: Built-in support for Prometheus, Grafana, and Tempo on supported providers.

Install Zombienet

Zombienet releases are available on the Zombienet repository. Choose one of the following installation methods:

Use the executable

Download the appropriate executable for your operating system from the latest release page. Each release includes executables for Linux and macOS.

Make the downloaded file executable:

chmod +x zombienet-macos-arm64

macOS Gatekeeper: Unidentified Developer

If macOS blocks the app with "cannot be opened because it is from an unidentified developer":

Remove the quarantine attribute so the terminal can run it by running the following command:

xattr -d com.apple.quarantine zombienet-macos-arm64

Verify the installation:

./zombienet-macos-arm64 version

Optionally, move the executable to your PATH:

mv zombienet-macos-arm64 /usr/local/bin/zombienet

Now you can use the zombienet command directly:

zombienet version

Use Nix

For Nix users, the Zombienet repository provides a flake.nix file. You need Flakes enabled.

Run Zombienet directly:

nix run github:paritytech/zombienet/INSERT_ZOMBIENET_VERSION -- \
spawn INSERT_ZOMBIENET_CONFIG_FILE_NAME.toml

Or include Zombienet in your current shell:

nix shell github:paritytech/zombienet/INSERT_ZOMBIENET_VERSION

Use Docker

Run Zombienet using Docker:

docker run -it --rm \
-v $(pwd):/home/nonroot/zombie-net/host-current-files \
paritytech/zombienet

Inside the container, set up the necessary binaries:

npm run zombie -- setup polkadot polkadot-parachain

Add the binaries to your PATH:

export PATH=/home/nonroot/zombie-net:$PATH

Spawn a network:

npm run zombie -- -p native spawn host-current-files/minimal.toml

Providers

Zombienet supports different backend providers for running nodes: Kubernetes, Podman, and native (local processes). Specify the provider using the --provider flag or in your network configuration file:

zombienet spawn network.toml --provider INSERT_PROVIDER

Or set it in the configuration:

network.toml

[settings]
provider = "INSERT_PROVIDER"
...

Ensure to replace INSERT_PROVIDER with the appropriate provider: kubernetes, podman, or native.

Kubernetes

Kubernetes is compatible with GKE, Docker Desktop, and kind.

• Requirements: Install kubectl and ensure proper cluster permissions.
• Features: Uses Prometheus operator for monitoring when available.

Podman

Podman is a daemonless container engine for Linux. Zombienet supports Podman rootless as a provider.

• Requirements: Install Podman on Linux.

• Features: Deploys Prometheus, Tempo, and Grafana for monitoring. Services are accessible at http://127.0.0.1:34123 (Prometheus), http://127.0.0.1:34125 (Tempo), and http://127.0.0.1:41461 (Grafana).

Native

The native provider runs nodes as local processes on your machine.

• Requirements: Have the necessary binaries (polkadot, polkadot-parachain) in your PATH. Install them using:

  zombienet setup polkadot polkadot-parachain

  For custom binaries, specify the path in your configuration or add them to your PATH:

  export PATH=$PATH:INSERT_PATH_TO_BINARY

• Features: No additional monitoring features.

Configure Zombienet

Zombienet uses JSON or TOML configuration files to define network topology, nodes, and parameters. The Zombienet repository provides example configurations.

Basic Configuration

A minimal configuration includes settings, relay chain configuration, and parachain configuration.

Polkadot TestNet chain specs

For Polkadot TestNet, use chain specs from the official Polkadot TestNet chain specs repository. Download the needed files and set chain_spec_path in your config. To download Polkadot Hub TestNet specs, you can use the following command:

wget https://paseo-r2.zondax.ch/chain-specs/paseo-asset-hub.json

TOML

basic-network.toml

[settings]
timeout = 1000

[relaychain]
chain = "paseo"
default_command = "polkadot"

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

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

[[parachains]]
id = 1000
chain_spec_path = "./paseo-asset-hub.json"

    [parachains.collator]
    name = "collator-01"
    command = "polkadot-parachain"

JSON

basic-network.json

{
  "settings": {
    "timeout": 1000
  },
  "relaychain": {
    "chain": "paseo",
    "default_command": "polkadot",
    "nodes": [
      {
        "name": "alice",
        "validator": true
      },
      {
        "name": "bob",
        "validator": true
      }
    ]
  },
  "parachains": [
    {
      "id": 1000,
      "chain_spec_path": "./paseo-asset-hub.json",
      "collator": {
        "name": "collator-01",
        "command": "polkadot-parachain"
      }
    }
  ]
}

CLI Commands

Zombienet provides the following commands:

• spawn <networkConfig>: Spawn the network defined in the configuration file.
• test <testFile>: Run tests on the spawned network.
• setup <binaries>: Download and set up polkadot or polkadot-parachain binaries.
• convert <filePath>: Convert a polkadot-launch configuration to Zombienet format.
• version: Print Zombienet version.
• help: Print help information.

Common flags:

• -p, --provider: Override the provider.
• -d, --dir: Specify directory for network files.
• -m, --monitor: Start as monitor without auto cleanup.
• -c, --spawn-concurrency: Number of concurrent spawning processes.

Settings

Through the keyword settings, it's possible to define the general settings for the network. The available keys are:

• global_volumes? ++"GlobalVolume[]"++: A list of global volumes to use.

  GlobalVolume interface definition

  export interface GlobalVolume {
    name: string;
    fs_type: string;
    mount_path: string;
  }

• bootnode ++"boolean"++: Add bootnode to network. Defaults to true.

• bootnode_domain? ++"string"++: Domain to use for bootnode.

• timeout ++"number"++: Global timeout to use for spawning the whole network.

• node_spawn_timeout? ++"number"++: Timeout to spawn pod/process.

• grafana? ++"boolean"++: Deploy an instance of Grafana.

• prometheus? ++"boolean"++: Deploy an instance of Prometheus.

• telemetry? ++"boolean"++: Enable telemetry for the network.

• jaeger_agent? ++"string"++: The Jaeger agent endpoint passed to the nodes. Only available on Kubernetes.

• tracing_collator_url? ++"string"++: The URL of the tracing collator used to query by the tracing assertion. Should be tempo query compatible.

• tracing_collator_service_name? ++"string"++: Service name for tempo query frontend. Only available on Kubernetes. Defaults to tempo-tempo-distributed-query-frontend.

• tracing_collator_service_namespace? ++"string"++: Namespace where tempo is running. Only available on Kubernetes. Defaults to tempo.

• tracing_collator_service_port? ++"number"++: Port of the query instance of tempo. Only available on Kubernetes. Defaults to 3100.

• enable_tracing? ++"boolean"++: Enable the tracing system. Only available on Kubernetes. Defaults to true.

• provider ++"string"++: Provider to use. Default is kubernetes".

• polkadot_introspector? ++"boolean"++: Deploy an instance of polkadot-introspector. Only available on Podman and Kubernetes. Defaults to false.

• backchannel? ++"boolean"++: Deploy an instance of backchannel server. Only available on Kubernetes. Defaults to false.

• image_pull_policy? ++"string"++: Image pull policy to use in the network. Possible values are Always, IfNotPresent, and Never.

• local_ip? ++"string"++: IP used for exposing local services (rpc/metrics/monitors). Defaults to "127.0.0.1".

• global_delay_network_global_settings? ++"number"++: Delay in seconds to apply to the network.

• node_verifier? ++"string"++: Specify how to verify node readiness or deactivate by using None. Possible values are None and Metric. Defaults to Metric.

For example, the following configuration file defines a minimal example for the settings:

TOML

base-example.toml

[settings]
timeout = 1000
bootnode = false
provider = "kubernetes"
backchannel = false
# ...

JSON

base-example.json

{
    "settings": {
        "timeout": 1000,
        "bootnode": false,
        "provider": "kubernetes",
        "backchannel": false,
        "...": {}
    },
    "...": {}
}

Relay Chain Configuration

You can use the relaychain keyword to define further parameters for the relay chain at start-up. The available keys are:

• default_command? ++"string"++: The default command to run. Defaults to polkadot.

• default_image? ++"string"++: The default Docker image to use.

• default_resources? ++"Resources"++: Represents the resource limits/reservations the nodes need by default. Only available on Kubernetes.

  Resources interface definition

  export interface Resources {
    resources: {
      requests?: {
        memory?: string;
        cpu?: string;
      };
      limits?: {
        memory?: string;
        cpu?: string;
      };
    };
  }

• default_db_snapshot? ++"string"++: The default database snapshot to use.

• default_prometheus_prefix ++"string"++: A parameter for customizing the metric's prefix. Defaults to substrate.

• default_substrate_cli_args_version? ++"SubstrateCliArgsVersion"++: Set the Substrate CLI arguments version.

  SubstrateCliArgsVersion enum definition

  export enum SubstrateCliArgsVersion {
    V0 = 0,
    V1 = 1,
    V2 = 2,
    V3 = 3,
  }

• default_keystore_key_types? ++"string[]"++: Defines which keystore keys should be created.

• chain ++"string"++: The chain name.

• chain_spec_path? ++"string"++: Path to the chain spec file. Should be the plain version to allow customizations.

• chain_spec_command? ++"string"++: Command to generate the chain spec. It can't be used in combination with chain_spec_path.

• default_args? ++"string[]"++: An array of arguments to use as default to pass to the command.

• default_overrides? ++"Override[]"++: An array of overrides to upload to the node.

  Override interface definition

  export interface Override {
    local_path: string;
    remote_name: string;
  }

• random_nominators_count? ++"number"++: If set and the stacking pallet is enabled, Zombienet will generate the input quantity of nominators and inject them into the genesis.

• max_nominations ++"number"++: The max number of nominations allowed by a nominator. Should match the value set in the runtime. Defaults to 24.

• nodes? ++"Node[]"++: An array of nodes to spawn. It is further defined in the Node Configuration section.

• node_groups? ++"NodeGroup[]"++: An array of node groups to spawn. It is further defined in the Node Group Configuration section.

• total_node_in_group? ++"number"++: The total number of nodes in the group. Defaults to 1.

• genesis ++"JSON"++: The genesis configuration.

• default_delay_network_settings? ++"DelayNetworkSettings"++: Sets the expected configuration to delay the network.

  DelayNetworkSettings interface definition

  export interface DelayNetworkSettings {
    latency: string;
    correlation?: string; // should be parsable as float by k8s
    jitter?: string;
  }

Node Configuration

One specific key capable of receiving more subkeys is the nodes key. This key is used to define further parameters for the nodes. The available keys:

• name ++"string"++: Name of the node. Any whitespace will be replaced with a dash (for example, new alice will be converted to new-alice).

• image? ++"string"++: Override default Docker image to use for this node.

• command? ++"string"++: Override default command to run.

• command_with_args? ++"string"++: Override default command and arguments.

• args? ++"string[]"++: Arguments to be passed to the command.

• env? ++"envVars[]"++: Environment variables to set in the container.

  envVars interface definition

  export interface EnvVars {
    name: string;
    value: string;
  }

• prometheus_prefix? ++"string"++: Customizes the metric's prefix for the specific node. Defaults to substrate.

• db_snapshot? ++"string"++: Database snapshot to use.

• substrate_cli_args_version? ++"SubstrateCliArgsVersion"++: Set the Substrate CLI arguments version directly to skip binary evaluation overhead.

  SubstrateCliArgsVersion enum definition

  export enum SubstrateCliArgsVersion {
    V0 = 0,
    V1 = 1,
    V2 = 2,
    V3 = 3,
  }

• resources? ++"Resources"++: Represent the resources limits/reservations needed by the node.

  Resources interface definition

  export interface Resources {
    resources: {
      requests?: {
        memory?: string;
        cpu?: string;
      };
      limits?: {
        memory?: string;
        cpu?: string;
      };
    };
  }

• keystore_key_types? ++"string[]"++: Defines which keystore keys should be created.

• validator ++"boolean"++: Pass the --validator flag to the command. Defaults to true.

• invulnerable ++"boolean"++: If true, add the node to invulnerables in the chain spec. Defaults to false.

• balance ++"number"++: Balance to set in balances for node's account. Defaults to 2000000000000.

• bootnodes? ++"string[]"++: Array of bootnodes to use.

• add_to_bootnodes? ++"boolean"++: Add this node to the bootnode list. Defaults to false.

• ws_port? ++"number"++: WS port to use.

• rpc_port? ++"number"++: RPC port to use.

• prometheus_port? ++"number"++: Prometheus port to use.

• p2p_cert_hash? ++"string"++: Libp2p certhash to use with webRTC transport.

• delay_network_settings? ++"DelayNetworkSettings"++: Sets the expected configuration to delay the network.

  DelayNetworkSettings interface definition

  export interface DelayNetworkSettings {
    latency: string;
    correlation?: string; // should be parsable as float by k8s
    jitter?: string;
  }

The following configuration file defines a minimal example for the relay chain, including the nodes key:

TOML

relaychain-example-nodes.toml

[relaychain]
default_command = "polkadot"
default_image = "polkadot-debug:master"
chain = "paseo"
chain_spec_path = "INSERT_PATH_TO_CHAIN_SPEC"
default_args = ["--chain", "paseo"]

[[relaychain.nodes]]
name = "alice"
validator = true
balance = 1000000000000

[[relaychain.nodes]]
name = "bob"
validator = true
balance = 1000000000000
# ...

JSON

relaychain-example-nodes.json

{
    "relaychain": {
        "default_command": "polkadot",
        "default_image": "polkadot-debug:master",
        "chain": "paseo",
        "chain_spec_path": "INSERT_PATH_TO_CHAIN-SPEC.JSON",
        "default_args": ["--chain", "paseo"],
        "nodes": [
            {
                "name": "alice",
                "validator": true,
                "balance": 1000000000000
            },
            {
                "name": "bob",
                "validator": true,
                "balance": 1000000000000
            }
        ]
    }
}

Node Group Configuration

The node_groups key defines further parameters for the node groups. The available keys are:

• name ++"string"++: Name of the node. Any whitespace will be replaced with a dash (for example, new alice will be converted to new-alice).

• image? ++"string"++: Override default Docker image to use for this node.

• command? ++"string"++: Override default command to run.

• args? ++"string[]"++: Arguments to be passed to the command.

• env? ++"envVars[]"++: Environment variables to set in the container.

  envVars interface definition

  export interface EnvVars {
    name: string;
    value: string;
  }

• overrides? ++"Override[]"++: Array of overrides definitions.

  Override interface definition

  export interface Override {
    local_path: string;
    remote_name: string;
  }

• prometheus_prefix? ++"string"++: Customizes the metric's prefix for the specific node. Defaults to substrate.

• db_snapshot? ++"string"++: Database snapshot to use.

• substrate_cli_args_version? ++"SubstrateCliArgsVersion"++: Set the Substrate CLI arguments version directly to skip binary evaluation overhead.

  SubstrateCliArgsVersion enum definition

  export enum SubstrateCliArgsVersion {
    V0 = 0,
    V1 = 1,
    V2 = 2,
    V3 = 3,
  }

• resources? ++"Resources"++: Represent the resources limits/reservations needed by the node.

  Resources interface definition

  export interface Resources {
    resources: {
      requests?: {
        memory?: string;
        cpu?: string;
      };
      limits?: {
        memory?: string;
        cpu?: string;
      };
    };
  }

• keystore_key_types? ++"string[]"++: Defines which keystore keys should be created.

• count ++"number | string"++: Number of nodes to launch for this group.

• delay_network_settings? ++"DelayNetworkSettings"++: Sets the expected configuration to delay the network.

  DelayNetworkSettings interface definition

  export interface DelayNetworkSettings {
    latency: string;
    correlation?: string; // should be parsable as float by k8s
    jitter?: string;
  }

The following configuration file defines a minimal example for the relay chain, including the node_groups key:

TOML

relaychain-example-node-groups.toml

[relaychain]
default_command = "polkadot"
default_image = "polkadot-debug:master"
chain = "paseo"
chain_spec_path = "INSERT_PATH_TO_CHAIN_SPEC"
default_args = ["--chain", "paseo"]

[[relaychain.node_groups]]
name = "group-1"
count = 2
image = "polkadot-debug:master"
command = "polkadot"
args = ["--chain", "paseo"]
# ...

JSON

relaychain-example-node-groups.json

{
    "relaychain": {
        "default_command": "polkadot",
        "default_image": "polkadot-debug:master",
        "chain": "paseo",
        "chain_spec_path": "INSERT_PATH_TO_CHAIN-SPEC.JSON",
        "default_args": ["--chain", "paseo"],
        "node_groups": [
            {
                "name": "group-1",
                "count": 2,
                "image": "polkadot-debug:master",
                "command": "polkadot",
                "args": ["--chain", "paseo"]
            }
        ],
        "...": {}
    },
    "...": {}
}

Parachain Configuration

The parachain keyword defines further parameters for the parachain. The available keys are:

• id ++"number"++: The id to assign to this parachain. Must be unique.

• chain? ++"string"++: The chain name.

• force_decorator? ++"string"++: Force the use of a specific decorator.

• genesis? ++"JSON"++: The genesis configuration.

• balance? ++"number"++: Balance to set in balances for parachain's account.

• delay_network_settings? ++"DelayNetworkSettings"++: Sets the expected configuration to delay the network.

  DelayNetworkSettings interface definition

  export interface DelayNetworkSettings {
    latency: string;
    correlation?: string; // should be parsable as float by k8s
    jitter?: string;
  }

• add_to_genesis? ++"boolean"++: Flag to add parachain to genesis or register in runtime. Defaults to true.

• register_para? ++"boolean"++: Flag to specify whether the para should be registered. The add_to_genesis flag must be set to false for this flag to have any effect. Defaults to true.

• onboard_as_parachain? ++"boolean"++: Flag to specify whether the para should be onboarded as a parachain, rather than remaining a parathread. Defaults to true.

• genesis_wasm_path? ++"string"++: Path to the Wasm file to use.

• genesis_wasm_generator? ++"string"++: Command to generate the Wasm file.

• genesis_state_path? ++"string"++: Path to the state file to use.

• genesis_state_generator? ++"string"++: Command to generate the state file.

• chain_spec_path? ++"string"++: Path to the chain spec file.

• chain_spec_command? ++"string"++: Command to generate the chain spec.

• cumulus_based? ++"boolean"++: Flag to use cumulus command generation. Defaults to true.

• bootnodes? ++"string[]"++: Array of bootnodes to use.

• prometheus_prefix? ++"string"++: Parameter for customizing the metric's prefix for all parachain nodes/collators. Defaults to substrate.

• collator? ++"Collator"++: Further defined in the Collator Configuration section.

• collator_groups? ++"CollatorGroup[]"++: An array of collator groups to spawn. It is further defined in the Collator Groups Configuration section.

For example, the following configuration file defines a minimal example for the parachain:

TOML

parachain-example.toml

[parachain]
id = 100
add_to_genesis = true
cumulus_based = true
genesis_wasm_path = "INSERT_PATH_TO_WASM"
genesis_state_path = "INSERT_PATH_TO_STATE"
# ...

JSON

parachain-example.json

{
    "parachain": {
        "id": 100,
        "add_to_genesis": true,
        "cumulus_based": true,
        "genesis_wasm_path": "INSERT_PATH_TO_WASM",
        "genesis_state_path": "INSERT_PATH_TO_STATE",
        "...": {}
    },
    "...": {}
}

Collator Configuration

One specific key capable of receiving more subkeys is the collator key. This key defines further parameters for the nodes. The available keys are:

• name ++"string"++: Name of the collator. Any whitespace will be replaced with a dash (for example, new alice will be converted to new-alice).

• image? ++"string"++: Image to use for the collator.

• command_with_args? ++"string"++: Overrides both command and arguments for the collator.

• validator ++"boolean"++: Pass the --validator flag to the command. Defaults to true.

• invulnerable ++"boolean"++: If true, add the collator to invulnerables in the chain spec. Defaults to false.

• balance ++"number"++: Balance to set in balances for collator's account. Defaults to 2000000000000.

• bootnodes? ++"string[]"++: Array of bootnodes to use.

• add_to_bootnodes? ++"boolean"++: Add this collator to the bootnode list. Defaults to false.

• ws_port? ++"number"++: WS port to use.

• rpc_port? ++"number"++: RPC port to use.

• prometheus_port? ++"number"++: Prometheus port to use.

• p2p_port? ++"number"++: P2P port to use.

• p2p_cert_hash? ++"string"++: Libp2p certhash to use with webRTC transport.

• delay_network_settings? ++"DelayNetworkSettings"++: Sets the expected configuration to delay the network.

  DelayNetworkSettings interface definition

  export interface DelayNetworkSettings {
    latency: string;
    correlation?: string; // should be parsable as float by k8s
    jitter?: string;
  }

• command? ++"string"++: Override default command to run.

• args? ++"string[]"++: Arguments to be passed to the command.

• env? ++"envVars[]"++: Environment variables to set in the container.

  envVars interface definition

  export interface EnvVars {
    name: string;
    value: string;
  }

• overrides? ++"Override[]"++: Array of overrides definitions.

  Override interface definition

  export interface Override {
    local_path: string;
    remote_name: string;
  }

• prometheus_prefix? ++"string"++: Customizes the metric's prefix for the specific node. Defaults to substrate.

• db_snapshot? ++"string"++: Database snapshot to use.

• substrate_cli_args_version? ++"SubstrateCliArgsVersion"++: Set the Substrate CLI arguments version directly to skip binary evaluation overhead.

  SubstrateCliArgsVersion enum definition

  export enum SubstrateCliArgsVersion {
    V0 = 0,
    V1 = 1,
    V2 = 2,
    V3 = 3,
  }

• resources? ++"Resources"++: Represent the resources limits/reservations needed by the node.

  Resources interface definition

  export interface Resources {
    resources: {
      requests?: {
        memory?: string;
        cpu?: string;
      };
      limits?: {
        memory?: string;
        cpu?: string;
      };
    };
  }

• keystore_key_types? ++"string[]"++: Defines which keystore keys should be created.

The configuration file below defines a minimal example for the collator:

TOML

collator-example.toml

[parachain]
id = 100
add_to_genesis = true
cumulus_based = true
genesis_wasm_path = "INSERT_PATH_TO_WASM"
genesis_state_path = "INSERT_PATH_TO_STATE"

[[parachain.collators]]
name = "alice"
image = "polkadot-parachain"
command = "polkadot-parachain"
# ...

JSON

collator-example.json

{
    "parachain": {
        "id": 100,
        "add_to_genesis": true,
        "cumulus_based": true,
        "genesis_wasm_path": "INSERT_PATH_TO_WASM",
        "genesis_state_path": "INSERT_PATH_TO_STATE",
        "collators": [
            {
                "name": "alice",
                "image": "polkadot-parachain",
                "command": "polkadot-parachain",
                "...": {}
            }
        ]
    },
    "...": {}
}

Collator Groups Configuration

The collator_groups key defines further parameters for the collator groups. The available keys are:

• name ++"string"++: Name of the node. Any whitespace will be replaced with a dash (for example, new alice will be converted to new-alice).

• image? ++"string"++: Override default Docker image to use for this node.

• command? ++"string"++: Override default command to run.

• args? ++"string[]"++: Arguments to be passed to the command.

• env? ++"envVars[]"++: Environment variables to set in the container.

  envVars interface definition

  export interface EnvVars {
    name: string;
    value: string;
  }

• overrides? ++"Override[]"++: Array of overrides definitions.

  Override interface definition

  export interface Override {
    local_path: string;
    remote_name: string;
  }

• prometheus_prefix? ++"string"++: Customizes the metric's prefix for the specific node. Defaults to substrate.

• db_snapshot? ++"string"++: Database snapshot to use.

• substrate_cli_args_version? ++"SubstrateCliArgsVersion"++: Set the Substrate CLI arguments version directly to skip binary evaluation overhead.

  SubstrateCliArgsVersion enum definition

  export enum SubstrateCliArgsVersion {
    V0 = 0,
    V1 = 1,
    V2 = 2,
    V3 = 3,
  }

• resources? ++"Resources"++: Represent the resources limits/reservations needed by the node.

  Resources interface definition

  export interface Resources {
    resources: {
      requests?: {
        memory?: string;
        cpu?: string;
      };
      limits?: {
        memory?: string;
        cpu?: string;
      };
    };
  }

• keystore_key_types? ++"string[]"++: Defines which keystore keys should be created.

• count ++"number | string"++: Number of nodes to launch for this group.

• delay_network_settings? ++"DelayNetworkSettings"++: Sets the expected configuration to delay the network.

  DelayNetworkSettings interface definition

  export interface DelayNetworkSettings {
    latency: string;
    correlation?: string; // should be parsable as float by k8s
    jitter?: string;
  }

For instance, the configuration file below defines a minimal example for the collator groups:

TOML

collator-groups-example.toml

[parachain]
id = 100
add_to_genesis = true
cumulus_based = true
genesis_wasm_path = "INSERT_PATH_TO_WASM"
genesis_state_path = "INSERT_PATH_TO_STATE"

[[parachain.collator_groups]]
name = "group-1"
count = 2
image = "polkadot-parachain"
command = "polkadot-parachain"
# ...

JSON

collator-groups-example.json

{
    "parachain": {
        "id": 100,
        "add_to_genesis": true,
        "cumulus_based": true,
        "genesis_wasm_path": "INSERT_PATH_TO_WASM",
        "genesis_state_path": "INSERT_PATH_TO_STATE",
        "collator_groups": [
            {
                "name": "group-1",
                "count": 2,
                "image": "polkadot-parachain",
                "command": "polkadot-parachain",
                "...": {}
            }
        ]
    },
    "...": {}
}

XCM Configuration

You can use the hrmp_channels keyword to define further parameters for the XCM channels at start-up. The available keys are:

• hrmp_channels ++"HrmpChannelsConfig[]"++: Array of Horizontal Relay-routed Message Passing (HRMP) channel configurations.

  HrmpChannelsConfig interface definition

  export interface HrmpChannelsConfig {
    sender: number;
    recipient: number;
    max_capacity: number;
    max_message_size: number;
  }

  Each of the HrmpChannelsConfig keys are defined as follows:

  • sender ++"number"++: Parachain ID of the sender.
  • recipient ++"number"++: Parachain ID of the recipient.
  • max_capacity ++"number"++: Maximum capacity of the HRMP channel.
  • max_message_size ++"number"++: Maximum message size allowed in the HRMP channel.

Spawn a Network

To spawn a network, create a configuration file and run:

zombienet spawn network.toml --provider native

Zombienet will:

1. Download or locate the required binaries.
2. Generate chain specifications.
3. Start relay chain validators.
4. Register and start parachain collators.
5. Display connection endpoints and logs.

Access the running nodes via the provided RPC endpoints (typically ws://127.0.0.1:9944 for the first node).

Write Tests

Zombienet provides a Domain Specific Language (DSL) for writing tests in .zndsl files. Tests can evaluate:

• Metrics from Prometheus
• Log patterns
• System events
• On-chain storage
• Custom JavaScript/TypeScript scripts

Test File Structure

Test files contain a header and body:

example-test.zndsl

Description: Example test suite
Network: ./network.toml
Creds: config

# Test assertions
alice: is up
bob: is up
alice: parachain 1000 is registered within 200 seconds
alice: parachain 1000 block height is at least 10 within 300 seconds

Run Tests

Execute tests using:

zombienet test example-test.zndsl --provider native

The test runner will execute each assertion and report pass/fail status.

Common Assertions

Some frequently used assertions include:

• Well-known functions: alice: is up, alice: parachain 100 is registered within 225 seconds
• Metrics: alice: reports node_roles is 4
• Logs: alice: log line matches glob "Imported #1" within 10 seconds
• System events: alice: system event matches ""paraId":[0-9]+" within 10 seconds
• Custom scripts: alice: js-script ./script.js return is greater than 1 within 200 seconds

Configuration Reference

For detailed configuration options, see:

• Configuration examples: Sample configurations for various scenarios.
• Testing DSL specification: Complete DSL syntax reference.
• Zombienet book: Comprehensive documentation.

Where to Go Next

• Zombienet Support

  ---

  For further support and information, refer to the official resources.

  → GitHub Repository

  → Element Channel