Skip to content

chore(readme): reflect current code (CLI flags, archive-ahm reference, parachain examples) #106

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pepoviola merged 1 commit into from
Apr 24, 2026
Merged

chore(readme): reflect current code (CLI flags, archive-ahm reference, parachain examples) #106

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 27 additions & 27 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,28 +6,23 @@

## :warning: :construction: Under Active Development :construction: :warning:

> Currently this tool is focused in the AH migration project and isn't ready to use as general purpouse tool without customization.
`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

`zombie-bite` is a simple _cli_ tool that allow you to spawn a new network based on a live one (e.g kusama/polkadot/ paseo). Under the hood we orchestrate the `sync` prior to _bite_ and spawn a new network with the _live state_ using `doppelganger` (based on https://github.com/paritytech/polkadot-sdk/issues/4230) as family of binaries that allow us to _inject_ some _keys_ using a custom `block_import` on top of the regular one.
You need these binaries available in your `PATH`:


### Requerimients

In order to use this tool you will need this binaries available in your `PATH`

- [Doppelganger binaries](https://github.com/paritytech/doppelganger-wrapper) (doppelganger, doppelganger-parachain, workers)
- [Doppelganger binaries](https://github.com/paritytech/doppelganger-wrapper) (doppelganger, doppelganger-parachain, workers)

### Logical steps: Bite, Spawn, Post

`zombie-bite` was designed focused on creating reusble artifacts on each step, the expected flow of usage is:
`zombie-bite` is designed to create reusable artifacts at each step. The typical flow is:

- `bite` the desired network, this will run the _biting_ process and generate the _artifacts_ to `spawn` the _bited_ network as many times you want.
- `bite` the desired network, this runs the _biting_ process and generates _artifacts_ to `spawn` the _bited_ network multiple times.

- `spawn` the network, reutilizing the _artifacts_ from the _bitting_ process. Ones the network is running you can [signal](#signal-stop) `zombie-bite` to stop it and generate the _artifacts_ for the `post` state.
(e.g: Is expected to run the AH migration as part of this step).
- `spawn` a network reusing artifacts from `bite`. When running, you can [signal](#signal-stop) `zombie-bite` to stop and pack the artifacts for the `post` step (e.g., run the AH migration during spawn).

- `post` step it utilized when you want to reuse a network from the _artifacts_ generated by the `spawn` step. (e.g: Is expected to run the _post_ migration test using this step)
- `post` is used to run post-migration tests or other logic using artifacts generated by the `spawn` step.

#### Concepts
- <a id="base_path"></a> __Base Path__ (base_path): `zombie_bite` encapsulate all the intermedia and generated files in this directory, using three main subdirectories (`bite`, `spawn` and `post`).
Expand Down Expand Up @@ -60,7 +55,8 @@ Options:

### AHM flow

As this tool is primarily for the AHM project, we will focus in this section on how to use it to bite a live network (e.g: polakadot) with asset-hub. Then spawn a new instance of the network, run the migration and _stop_ the network to later spawn for running the _post_ migration test.
`zombie-bite` was originally created to support the Asset-Hub Migration (AHM) workflow. The initial AHM-focused implementation is available in the [archive-ahm](https://github.com/paritytech/zombie-bite/tree/archive-ahm).
Now supports all system chains (asset-hub, coretime, people, colletives).

#### Base path

Expand All @@ -69,24 +65,30 @@ The order of resolution that `zombie-bite` use is:
- 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 (with override runtimes):
#### Bite usage

First we need to have compiled the runtimes we want to override for the rc and ah, then we can start the `bite` process by running.
Compile any runtime WASM you want to override (optional), then start the `bite` process. Examples:

- Override the relay runtime:

```sh
zombie-bite bite -d /tmp/ahm-migration -r polkadot --rc-override ./runtime_wasm/polkadot_runtime.compact.compressed.wasm --ah-override ./runtime_wasm/asset_hub_polkadot_runtime.compact.compressed.wasm
zombie-bite bite -d /tmp/base_path -r polkadot --rc-override ./runtime_wasm/polkadot_runtime.compact.compressed.wasm
```

_Note_: We will using this path `/tmp/ahm-migration` for the whole flow.
- Include only specific parachains (comma-separated):

Ones this process completed, we will have all the needed _artifacts_ to spawn a new instance of the _bited_ network
```sh
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

The next step is to _spawn_ the network, and _run the runtime migration_. We can `spawn` a new instance of the _bited_ network with the following cmd:
Spawn a new instance of the _bited_ network with the following cmd:

```bash
zombie-bite spawn -d /tmp/ahm-migration
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:
Expand Down Expand Up @@ -120,7 +122,7 @@ For __AHM__, this is the moment to run the migration and ones is completed you c
To __signal__ the teardown, you should create a fila called __stop.txt__ in the _base_path_

```bash
touch /parity/zombie-bite_1754046046/stop.txt
touch /tmp/base_path/stop.txt
```

This will automatically teardown the network and generate the artifacts.
Expand All @@ -131,20 +133,18 @@ The `post` step is mainly thought to run _post migration_ test or any other logi
To _spawn_ the network as part of the `post` step you can run

```bash
zombie-bite spawn -d /tmp/ahm-migration -s post
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_

```bash
touch /parity/zombie-bite_1754046046/stop.txt
touch /tmp/base_path/stop.txt
```



##### Log level:

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

```sh
babe=trace,grandpa=trace,runtime=debug,consensus::common=trace,parachain=debug,sync=debug
Expand Down