Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
14 changes: 8 additions & 6 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,10 +10,10 @@ Do not add `Co-Authored-By: Claude` (or any other AI attribution) lines to commi

Product Preview Network (PPN) is infrastructure tooling for spinning up a local Polkadot ecosystem with Zombienet. It provides pre-built binaries, WASM runtimes, and configuration for:

- **Relay Chain**: Paseo (6 validators: alice, bob, charlie, dave, eve, ferdie)
- **Relay Chain**: Paseo (8 validators: alice, bob, charlie, dave, eve, ferdie, one, two)
- **Parachains**:
- Asset Hub (ID 1500) - port 10020 - **2-second blocks** via elastic scaling
- People/Individuality Chain (ID 1502) - port 10010
- People/Individuality Chain (ID 1502) - port 10010 - **2-second blocks** via elastic scaling
- Bulletin Chain (ID 1501) - port 10030
- Web3 Storage Chain (ID 1600) - port 10040

Expand Down Expand Up @@ -235,11 +235,13 @@ zombienet-configs/
| DUB API Reference | `http://127.0.0.1:8092/docs` | Generated OpenAPI reference |
| TURN/STUN (eturnal) | `stun:127.0.0.1:3478`, `turn:127.0.0.1:3478` | Relay for p2p clients; credentials from DUB `/api/v1/turn/issue` (see `docs/TURN.md`) |

## Elastic Scaling (Asset Hub)
## Elastic Scaling (Asset Hub, People)

Asset Hub runs with 2-second block times using elastic scaling:
- 6 validators required for 5 cores (3 parachains + 2 extra for Asset Hub)
- Core assignment via `scripts/assign-cores.sh` (runs automatically as custom_process)
Asset Hub and People run with 2-second block times on three cores each (`parachains[].cores` in
the descriptor):
- 8 validators for 8 cores (one per core, or a core has no group to back its blocks)
- The genesis TOML adds the extra cores; `ppn service assign-cores` (a custom process) hands
them out, and on a kept chain assigns only cores that have a validator group and no assignment

## Testing

Expand Down
8 changes: 4 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,8 @@
> been audited, is actively experimental, and may contain bugs, vulnerabilities, or incomplete
> features. Use at your own risk.

A complete Polkadot ecosystem on your machine, in one command: a relay chain with six
validators, plus Asset Hub (2-second blocks via elastic scaling), People, Bulletin and Web3
A complete Polkadot ecosystem on your machine, in one command: a relay chain with eight
validators, plus Asset Hub and People (2-second blocks via elastic scaling), Bulletin and Web3
Storage, plus the Ethereum RPC, IPFS, identity backend and storage provider those chains
expect, already wired together. The same tool forks a live network, Polkadot included, so the
chains come up carrying real state instead of an empty genesis.
Expand Down Expand Up @@ -175,9 +175,9 @@ strips the dev keys from anything long-lived. A server's secrets file holds the

| | Endpoint | |
| --- | --- | --- |
| Relay (alice … ferdie) | `ws://127.0.0.1:10000` – `10005` | 6 validators |
| Relay (alice … ferdie) | `ws://127.0.0.1:10000` – `10005` | 8 validators; `one` and `two` on `10006`, `10007` |
| Asset Hub | `ws://127.0.0.1:10020` | **2-second blocks**, elastic scaling |
| People | `ws://127.0.0.1:10010` | individuality |
| People | `ws://127.0.0.1:10010` | individuality, **2-second blocks**, elastic scaling |
| Bulletin | `ws://127.0.0.1:10030` | transaction storage |
| Web3 Storage | `ws://127.0.0.1:10040` | storage parachain, previewnet only |
| Dashboard | <http://127.0.0.1:8090> | status UI and API for all of the above |
Expand Down
5 changes: 4 additions & 1 deletion config/ports.env
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,9 @@ RELAY_CHARLIE_PORT=10002
RELAY_DAVE_PORT=10003
RELAY_EVE_PORT=10004
RELAY_FERDIE_PORT=10005
# The keyring's One and Two, which a genesis spawn runs past the six, one validator per core.
RELAY_ONE_PORT=10006
RELAY_TWO_PORT=10007

# Parachain collator RPC ports. A chain's RPC nodes (rpcNodes in the descriptor or the
# network overlay) take the next ports up: 10011, 10012, ... for People.
Expand Down Expand Up @@ -172,6 +175,6 @@ DUB_POSTGRES_DATA_DIR=


# Aggregate lists
RELAY_PORTS="$RELAY_ALICE_PORT $RELAY_BOB_PORT $RELAY_CHARLIE_PORT $RELAY_DAVE_PORT $RELAY_EVE_PORT $RELAY_FERDIE_PORT"
RELAY_PORTS="$RELAY_ALICE_PORT $RELAY_BOB_PORT $RELAY_CHARLIE_PORT $RELAY_DAVE_PORT $RELAY_EVE_PORT $RELAY_FERDIE_PORT $RELAY_ONE_PORT $RELAY_TWO_PORT"
PARACHAIN_PORTS="$PEOPLE_PORT $ASSET_HUB_PORT $BULLETIN_PORT $WEB3_STORAGE_PORT"
ALL_PORTS="$RELAY_PORTS $PARACHAIN_PORTS"
24 changes: 14 additions & 10 deletions docs/FORK.md
Original file line number Diff line number Diff line change
Expand Up @@ -90,8 +90,10 @@ instead of driving doppelganger itself ([#120](https://github.com/paritytech/zom
## What you get, and what you don't

The fork resumes at the bite block and diverges from there — it is a real fork, not a mirror. It
runs six relay validators and one collator per parachain, on PPN's normal ports, with Asset Hub's
2-second elastic scaling intact — unless the bite was asked for a different layout, below.
runs one collator per parachain, on PPN's normal ports. A previewnet fork keeps the core layout it
bit, with the descriptor's six validators; a fork of a shared relay lays the parachains out on the
descriptor's `cores` (Asset Hub and People three each) — unless the bite was asked for a different
layout, below.

### Cores and collators

Expand All @@ -100,17 +102,19 @@ make start FORK=1 FRESH_BITE=1 CORES=people=3 COLLATORS=people=5
make bite CORES="people=3 asset-hub=1" COLLATORS=people=5
```

`CORES=<chain>=<n>` lays a parachain out on that many cores (Asset Hub defaults to three, the
rest to one); `COLLATORS=<chain>=<n>` installs that many collators as its authorities. Both are
`CORES=<chain>=<n>` lays a parachain out on that many cores (the descriptor's `cores` otherwise);
`COLLATORS=<chain>=<n>` installs that many collators as its authorities. Both are
**bite-time** settings: the collator authority sets and the relay's core layout are state inside
the snapshots, so a published bundle — bitten with the defaults — cannot take them. `ppn start`
refuses a bundle whose recorded layout differs from what it was asked for and says how to re-bite.
refuses a bundle bitten with other `--cores`/`--collators` than it was asked for and says how to
re-bite.
The bundle's `manifest.json` carries the layout under `topology`, and the fork TOML follows it.

The relay grows to one validator per core, because a core with no validator group backs nothing:
previewnet with `people=3` is 3 + 3 + 1 + 1 = 8 cores, so 8 validators. Past the well-known six
they are named `Validator-7`, `Validator-8`, … and their keys derived from those names, the same
way zombienet does it; the cap is 10, where the relay RPC ports (`10000 + i`) would run into
The relay grows to one validator per core it lays out, because a core with no validator group
backs nothing: paseo-next-v2 is 3 + 3 + 1 = 7 cores, so 7 validators, and previewnet with
`--cores people=3` is 8. Past the well-known six they are the keyring's `one` and `two`, then
`Validator-9`, `Validator-10`, with keys derived from those names the same way zombienet does it;
the cap is 10, where the relay RPC ports (`10000 + i`) would run into
People's. Extra collators are `Collator-<paraId>-2` … and restore the same snapshot as the first;
only the first holds the documented ports.

Expand Down Expand Up @@ -217,7 +221,7 @@ against the descriptor with no mapping table in between.
well-known names to the well-known dev keys, which is exactly the authority set the bite installs.
PPN's genesis-mode names (`alice-paseo-validator`, …) get generated keys instead, and the network
cannot author. This is why fork mode has its own config rather than overlaying `local-dev.toml`.
Any node past those (`Validator-7`, `Collator-1502-2`) gets keys zombienet derives from `//<Name>`,
Any node past those (`one`, `Collator-1502-2`) gets keys zombienet derives from `//<Name>`,
and the bite derives the same — `relayNodeName()`/`collatorNodeName()` in `toml-generator.ts` are
the one place both read the name from.

Expand Down
3 changes: 2 additions & 1 deletion networks/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,9 +50,10 @@ or `PPN_NETWORK=<name>` in the environment of the scripts.
| `relay.rpc`, `parachains[].rpc` | RPC endpoint: an absolute `ws(s)://`/`http(s)://` URL, or a path resolved against `bite.source`. |
| `rpcAlternates` | Informational: other public providers for the same chain, for when the primary is re-homed. Not consumed by tooling (yet). |
| `relay.specSource`, `parachains[].specSource` | Explicit location of the chain spec the bite warp-syncs from (it must carry the live network's bootnodes): an absolute URL, a path resolved against `bite.source` (previewnet uses `chainspecs/<spec>-local.json`, so biting a different instance follows the base-URL override), or `"builtin"` (generated with `build-spec --chain <relay.chain> --raw`, relay only). |
| `relay.validators` | Number of dev-key validators the fork runs with (max 6: alice…ferdie). |
| `relay.validators` | Number of dev-key validators the fork runs with (max 6: alice…ferdie). A bite that lays the cores out (a shared relay, or `--cores`) and a genesis spawn run one per core where that is more: the keyring's `one` and `two`, then `Validator-9`…, with keys derived from those names. The parachains' total `cores` can be at most 10. |
| `parachains[].key` | One of `asset-hub`, `people`, `bulletin`, `web3-storage` — the keys PPN's port table and per-chain flags are defined for. |
| `parachains[].paraId` | The network's real para id. Previewnet/paseo-next-v2 use the 1500 band; devnet and real networks the 1000 band. |
| `parachains[].cores` | Relay cores the chain runs on, 1 when absent. More than one is elastic scaling, and shortens block time only when the runtime is built for that many blocks per relay block (Asset Hub and People: 3, so 2-second blocks). Genesis adds the extra cores and `assign-cores` hands them out. A fork of a shared relay lays its parachains out with these counts and `--cores` overrides them; a previewnet fork keeps the layout it bit. |
| `parachains[].spec` | Basename of the parachain spec inside the bundle. |
| `services` | Optional `{ "<process>": false }` map to disable custom processes that would otherwise run for the present parachains (e.g. eth-rpc for asset-hub, ipfs for bulletin). |
| `dotns.resolver` | DotnsContentResolver address for `pin-bulletin-products` — per network, since every DotNS deployment has its own. Omitted → read from `bin/dotns-addresses.json` (previewnet's release artifact); still absent → the import is skipped. |
Expand Down
2 changes: 2 additions & 0 deletions networks/devnet.json
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,7 @@
{
"key": "asset-hub",
"paraId": 1000,
"cores": 3,
"spec": "asset-hub",
"rpc": "wss://asset-hub-paseo-rpc.n.dwellir.com",
"rpcAlternates": [
Expand All @@ -55,6 +56,7 @@
{
"key": "people",
"paraId": 1004,
"cores": 3,
"spec": "people",
"rpc": "wss://people-paseo.rotko.net",
"rpcAlternates": [
Expand Down
1 change: 1 addition & 0 deletions networks/kusama.json
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@
{
"key": "asset-hub",
"paraId": 1000,
"cores": 3,
"spec": "asset-hub",
"rpc": "wss://kusama-asset-hub-rpc.polkadot.io",
"specSource": "builtin:asset-hub-kusama",
Expand Down
2 changes: 2 additions & 0 deletions networks/paseo-next-v2.json
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@
{
"key": "asset-hub",
"paraId": 1500,
"cores": 3,
"spec": "asset-hub",
"rpc": "wss://paseo-asset-hub-next-rpc.polkadot.io",
"specSource": "https://raw.githubusercontent.com/paritytech/chainspecs/main/paseo/parachain/asset-hub-next/raw.json",
Expand All @@ -50,6 +51,7 @@
{
"key": "people",
"paraId": 1502,
"cores": 3,
"spec": "people",
"rpc": "wss://paseo-people-next-system-rpc.polkadot.io",
"specSource": "https://raw.githubusercontent.com/paritytech/chainspecs/main/paseo/parachain/people-next-system/raw.json",
Expand Down
2 changes: 2 additions & 0 deletions networks/polkadot.json
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@
{
"key": "asset-hub",
"paraId": 1000,
"cores": 3,
"spec": "asset-hub",
"rpc": "wss://polkadot-asset-hub-rpc.polkadot.io",
"specSource": "builtin:asset-hub-polkadot",
Expand All @@ -48,6 +49,7 @@
{
"key": "people",
"paraId": 1004,
"cores": 3,
"spec": "people",
"rpc": "wss://polkadot-people-rpc.polkadot.io",
"specSource": "builtin:people-polkadot",
Expand Down
2 changes: 2 additions & 0 deletions networks/previewnet.json
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,7 @@
{
"key": "asset-hub",
"paraId": 1500,
"cores": 3,
"spec": "asset-hub",
"rpc": "asset-hub",
"specSource": "chainspecs/asset-hub-local.json",
Expand All @@ -97,6 +98,7 @@
{
"key": "people",
"paraId": 1502,
"cores": 3,
"spec": "individuality",
"rpc": "people",
"specSource": "chainspecs/individuality-local.json",
Expand Down
2 changes: 2 additions & 0 deletions networks/westend.json
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,7 @@
{
"key": "asset-hub",
"paraId": 1000,
"cores": 3,
"spec": "asset-hub",
"rpc": "wss://westend-asset-hub-rpc.polkadot.io",
"specSource": "builtin:asset-hub-westend",
Expand All @@ -45,6 +46,7 @@
{
"key": "people",
"paraId": 1004,
"cores": 3,
"spec": "people",
"rpc": "wss://westend-people-rpc.polkadot.io",
"specSource": "builtin:people-westend",
Expand Down
2 changes: 1 addition & 1 deletion packages/cli/src/commands/bite.ts
Original file line number Diff line number Diff line change
Expand Up @@ -529,7 +529,7 @@ export async function run(args: string[], opts: BiteOptions = {}): Promise<void>
// after minutes of syncing.
const staged = stageUpgrades(opts.upgrades, chains, out, opts.upgradeCheckVersion ?? true);
const topology = resolveTopology(opts, net);
if (topology) console.log(` topology: ${topologyFlags(topology)} → ${topology.validators} validators`);
if (topology) console.log(` topology: ${topologyFlags(topology) || 'the defaults'} → ${topology.validators} validators`);

console.log(`=== 1/6 collecting chain specs (network: ${net.name}) ===`);
for (const chain of chains) await collectSpec(chain, net, out, baseUrl, dgDir);
Expand Down
2 changes: 1 addition & 1 deletion packages/cli/src/commands/fork.ts
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ export async function run(args: string[]): Promise<void> {
endpointOf(relay, NETWORK, baseUrl),
`${outDir}/rc_overrides.json`,
{
paras: PARACHAINS.map((p) => ({ key: p.key, paraId: p.paraId })),
paras: NETWORK.parachains,
validators: topology?.validators ?? NETWORK.relay.validators,
cores: topology?.cores,
sharedRelay: NETWORK.bite.sharedRelay === true,
Expand Down
Loading
Loading