Zombie-bite

A cli tool to easily fork live networks (e.g kusama/polkadot).

⚠️ 🚧 Under Active Development 🚧 ⚠️

zombie-bite is a CLI tool that allows you to spawn a new network based on a live one. It orchestrates the sync prior to bite and spawns a new network with the live state using doppelganger binaries. The tool supports overriding/injecting keys during block import.

Requirements

You need these binaries available in your PATH:

• Doppelganger binaries (doppelganger, doppelganger-parachain, workers)

Logical steps: Bite, Spawn, Post

zombie-bite is designed to create reusable artifacts at each step. The typical flow is:

• bite the desired network, this runs the biting process and generates artifacts to spawn the bited network multiple times.

• spawn a network reusing artifacts from bite. When running, you can signal zombie-bite to stop and pack the artifacts for the post step (e.g., run the AH migration during spawn).

• post is used to run post-migration tests or other logic using artifacts generated by the spawn step.

Concepts

• Base Path (base_path): zombie_bite encapsulate all the intermedia and generated files in this directory, using three main subdirectories (bite, spawn and post). If this directories are already used, zombie-bite will move the content to a new one with a numerical suffix (e.g something like spawn.0).

• Signal Stop: Ones the network is running, you can signal zombie-bite to stop it and pack the artifacts by placing a file called stop.txt in the base_path

Usage

Currently zombie-bite support a set of subcommands that allow you to reuse the artifacts from the different steps

❯ cargo run -- help
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.32s
     Running `target/debug/zombie-bite help`
Usage: zombie-bite <COMMAND>

Commands:
  bite                Bite the running network using 'doppelganger' binaries, and generate the artifacts for spawning
  spawn               Spawn a new instance of the network from the bite step
  generate-artifacts  [Helper] Generate artifacts to be used by the next step (only 'spawn' and 'post' allowed)
  clean-up-dir        [Helper] Clean up directory to only include the needed artifacts
  help                Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

AHM flow

zombie-bite was originally created to support the Asset-Hub Migration (AHM) workflow. The initial AHM-focused implementation is available in the archive-ahm. Now supports all system chains (asset-hub, coretime, people, colletives).

Base path

The order of resolution that zombie-bite use is:

• Iff the --base-path or -d option is provided use that path.
• If the option is not passed as cli args, use the env var 'ZOMBIE_BITE_BASE_PATH'.
• If the env var is not provided, fallback to use <cwd>_timestamp.

Bite usage

Compile any runtime WASM you want to override (optional), then start the bite process. Examples:

• Override the relay runtime:

zombie-bite bite -d /tmp/base_path -r polkadot --rc-override ./runtime_wasm/polkadot_runtime.compact.compressed.wasm

• Include only specific parachains (comma-separated):

zombie-bite bite -d /tmp/base_path -r polkadot --parachains people,bridge-hub,coretime,collectives

You can combine both options to override runtimes and select parachains in the same command. On success you'll have all artifacts needed to spawn the bitten network.

Spawn

Spawn a new instance of the bited network with the following cmd:

zombie-bite spawn -d /tmp/base_path

This will spawn the network and print direct links to connect to the nodes using both pjs or papi. Also, where the logs are stored and the command usage for spawn each node:

2025-08-02T00:26:33.286194Z  INFO zombienet_orchestrator::spawner: 🚀 alice, should be running now
2025-08-02T00:26:33.286215Z  INFO zombienet_orchestrator::spawner: 💻 alice: direct link (pjs) https://polkadot.js.org/apps/?rpc=ws://127.0.0.1:60568#/explorer
2025-08-02T00:26:33.286219Z  INFO zombienet_orchestrator::spawner: 💻 alice: direct link (papi) https://dev.papi.how/explorer#networkId=custom&endpoint=ws://127.0.0.1:60568
2025-08-02T00:26:33.286222Z  INFO zombienet_orchestrator::spawner: 📊 alice: metrics link http://127.0.0.1:56245/metrics
2025-08-02T00:26:33.286228Z  INFO zombienet_orchestrator::spawner: 📓 logs cmd: tail -f /parity/zombie-bite_1754046046/post/alice/alice.log
2025-08-02T00:26:33.457376Z  INFO zombienet_orchestrator::spawner: 🚀 bob, spawning.... with command: doppelganger --chain /parity/zombie-bite_1754046046/post/bob/cfg/polkadot.json --name bob --rpc-cors all --rpc-methods unsafe --node-key 81b637d8fcd2c6da6359e6963113a1170de795e4b725b84d1e0b4cfd9ec58ce9 --no-telemetry --prometheus-external --validator --insecure-validator-i-know-what-i-do --prometheus-port 56250 --rpc-port 56249 --listen-addr /ip4/0.0.0.0/tcp/56251/ws --base-path /parity/zombie-bite_1754046046/post/bob/data --bootnodes /ip4/127.0.0.1/tcp/56246/ws/p2p/12D3KooWQCkBm1BYtkHpocxCwMgR8yjitEeHGx8spzcDLGt2gkBm -l=babe=trace,grandpa=info,runtime=trace,consensus::common=trace,parachain=debug --discover-local --allow-private-ip --no-hardware-benchmarks
2025-08-02T00:26:59.339049Z  INFO zombienet_orchestrator::spawner: 🚀 bob, should be running now
2025-08-02T00:26:59.339072Z  INFO zombienet_orchestrator::spawner: 💻 bob: direct link (pjs) https://polkadot.js.org/apps/?rpc=ws://127.0.0.1:56249#/explorer
2025-08-02T00:26:59.339076Z  INFO zombienet_orchestrator::spawner: 💻 bob: direct link (papi) https://dev.papi.how/explorer#networkId=custom&endpoint=ws://127.0.0.1:56249
2025-08-02T00:26:59.339079Z  INFO zombienet_orchestrator::spawner: 📊 bob: metrics link http://127.0.0.1:56250/metrics
2025-08-02T00:26:59.339084Z  INFO zombienet_orchestrator::spawner: 📓 logs cmd: tail -f /parity/zombie-bite_1754046046/post/bob/bob.log
2025-08-02T00:26:59.343660Z  INFO zombienet_orchestrator::spawner: 🚀 collator, spawning.... with command: doppelganger-parachain --chain /parity/zombie-bite_1754046046/post/collator/cfg/1000.json --name collator --rpc-cors all --rpc-methods unsafe --node-key 53cf10627db4ce8abcddad56fc510cdfc58bfe587b0cbb6772f1f0727266e565 --prometheus-external --collator --prometheus-port 56255 --rpc-port 60569 --listen-addr /ip4/0.0.0.0/tcp/56256/ws --base-path /parity/zombie-bite_1754046046/post/collator/data --relay-chain-rpc-urls ws://127.0.0.1:60568 -l=aura=debug,runtime=debug,cumulus-consensus=trace,consensus::common=trace,parachain::collation-generation=trace,parachain::collator-protocol=trace,parachain=debug,xcm=trace --force-authoring --discover-local --allow-private-ip --no-hardware-benchmarks -- --base-path /parity/zombie-bite_1754046046/post/collator/relay-data --chain /parity/zombie-bite_1754046046/post/collator/cfg/polkadot.json --execution wasm --port 56252 --prometheus-port 56253
2025-08-02T00:27:30.223794Z  INFO zombienet_orchestrator::spawner: 🚀 collator, should be running now
2025-08-02T00:27:30.223819Z  INFO zombienet_orchestrator::spawner: 💻 collator: direct link (pjs) https://polkadot.js.org/apps/?rpc=ws://127.0.0.1:60569#/explorer
2025-08-02T00:27:30.223824Z  INFO zombienet_orchestrator::spawner: 💻 collator: direct link (papi) https://dev.papi.how/explorer#networkId=custom&endpoint=ws://127.0.0.1:60569
2025-08-02T00:27:30.223828Z  INFO zombienet_orchestrator::spawner: 📊 collator: metrics link http://127.0.0.1:56255/metrics
2025-08-02T00:27:30.223839Z  INFO zombienet_orchestrator::spawner: 📊 collator: collator full-node metrics link http://127.0.0.1:56253/metrics
2025-08-02T00:27:30.223844Z  INFO zombienet_orchestrator::spawner: 📓 logs cmd: tail -f /parity/zombie-bite_1754046046/post/collator/collator.log

Also, the spawn process have will wait until finalize a few blocks (3) to confirm the bootstrap of the network and a monitorin process will run and check the block production every 15 minutes. If this process detect that some node is stall will proceed to restart it.

For AHM, this is the moment to run the migration and ones is completed you can signal zombie-bite to teardown the current network and generate the artifacts for post migration test.

To signal the teardown, you should create a fila called stop.txt in the base_path

touch  /tmp/base_path/stop.txt

This will automatically teardown the network and generate the artifacts.

Post

The post step is mainly thought to run post migration test or any other logic you want to run from the previous state of the network. To spawn the network as part of the post step you can run

zombie-bite spawn -d /tmp/base_path -s post

Again, this will print network information and you can signal to teardown by creating the stop.txt file inside the base_path

touch /tmp/base_path/stop.txt

Log level:

By default the relaychain nodes are spawned with this log levels:

babe=trace,grandpa=trace,runtime=debug,consensus::common=trace,parachain=debug,sync=debug

but you can override those by setting the RUST_LOG_RC env, since the script will inject that env into the spawning logic.

And the parachain collators with this log levels:

aura=debug,runtime=debug,cumulus-consensus=trace,consensus::common=trace,parachain::collation-generation=trace,parachain::collator-protocol=trace,parachain=debug,xcm=trace

but you can override those by setting the RUST_LOG_COL env, since the script will inject that env into the spawning logic.

Override / Inject Keys:

Zombie-bite create a json file including two maps (overrides and injects), these two are simple key/values json that zombie-bite pass to the doppelganger nodes to override/inject those keys in the block import process. Those nodes override the key IFF the key exist in the state being imported and inject the ones sets at the end of the import process, so will be present in the resulting state even if there wasen't there originally.

You can check the keys we override/inject by default (for both relaychain / parachain) and at the moment if you want to include other key (or customize one) yo need to modify this file and rebuild the tool. Note: a process to dynamically set the overrides/injects map is planned.

Environment variables:

Zombie-bite reads a few env vars to allow users to customize th behavior:

• ZOMBIE_BITE_BASE_PATH: base_path to use.
• RUST_LOG_RC: log level to set in the relaychain nodes.
• RUST_LOG_COL: log level to set in the collator.
• ZOMBIE_BITE_RC_PORT: port to use for alice. (deprecated)
• ZOMBIE_BITE_ALICE_PORT: port to use for alice.
• ZOMBIE_BITE_BOB_PORT: port to use for bob.
• ZOMBIE_BITE_AH_PORT: port to use for the collator.
• ZOMBIE_SUDO: sudo key to set in sudo pallet (IFF present) and in RC manager.
• ZOMBIE_BITE_STATE_PRUNING: set the value of the flag --state-pruning (default value 28801)
• ZOMBIE_BITE_RC_EXTRA_ARGS: Comma separated list of args to add.
• ZOMBIE_BITE_AH_EXTRA_ARGS: Comma separated list of args to add. (e.g. "--db-cache=24000", --trie-cache-size=24000, --runtime-cache-size=255").