diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 27cdb84..d3c5c78 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -239,6 +239,15 @@ jobs: - name: List bin contents run: ls -la bin/ + # The CLI in the image reports the version these package.json files carry. + - name: Stamp the release version + env: + TAG: ${{ needs.prepare.outputs.tag }} + run: | + for pkg in . packages/network-config packages/cli; do + (cd "$pkg" && npm pkg set version="${TAG#v}") + done + - name: Set up Docker Buildx uses: docker/setup-buildx-action@v4 diff --git a/.github/workflows/zombienet-tests.yml b/.github/workflows/zombienet-tests.yml index ac9249b..4c6c149 100644 --- a/.github/workflows/zombienet-tests.yml +++ b/.github/workflows/zombienet-tests.yml @@ -113,6 +113,40 @@ jobs: grep -q "increase_attestation_allowance $PPN_ALLOWANCE_SS58 1000" /tmp/dot-calls.txt \ || { echo "allowance not granted to PPN_ALLOWANCE_SS58:"; cat /tmp/dot-calls.txt; exit 1; } + - name: DotnsGateway allowance script — deployable without PPN_ALLOWANCE_SS58 hard-fails + env: + PPN_PROFILE: deployable + run: | + if bash scripts/increase-dotns-attestation-allowance.sh 2>/dev/null; then + echo "expected non-zero exit when PPN_ALLOWANCE_SS58 missing"; exit 1 + fi + + - name: DotnsGateway allowance script — grants to PPN_ALLOWANCE_SS58, never Alice + env: + PPN_PROFILE: deployable + PPN_ALLOWANCE_SS58: 5ERKU2mm7E9o9mLcMGkPMNSPStFT51U5d1SS4YXCafe6riPA + ALLOWANCE_ACCOUNT: 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY + WAIT_SECONDS: 0 + run: | + # The stub reads the allowance back as 0 until a sudo call is made, then 1000, + # so the script's read-back loop ends. + mkdir -p /tmp/stub-dotns + cat > /tmp/stub-dotns/dot <<'STUB' + #!/usr/bin/env bash + echo "$@" >> /tmp/dotns-calls.txt + case "$1" in + *.query.DotnsGateway.AttestationAllowance) + if grep -q "Sudo.sudo" /tmp/dotns-calls.txt; then echo 1000; else echo 0; fi ;; + esac + STUB + sed -i 's/^ //' /tmp/stub-dotns/dot + chmod +x /tmp/stub-dotns/dot + PATH=/tmp/stub-dotns:$PATH bash scripts/increase-dotns-attestation-allowance.sh + grep -q "increase_attestation_allowance $PPN_ALLOWANCE_SS58 1000" /tmp/dotns-calls.txt \ + || { echo "allowance not granted to PPN_ALLOWANCE_SS58:"; cat /tmp/dotns-calls.txt; exit 1; } + ! grep -q 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY /tmp/dotns-calls.txt \ + || { echo "granted to Alice:"; cat /tmp/dotns-calls.txt; exit 1; } + # Smoke test: run the install magic link end-to-end, then start the network # Install the published packages the way a user would, into a workspace that is not a # checkout, and start a network from it. diff --git a/.gitignore b/.gitignore index 4cf5e87..d37bee2 100644 --- a/.gitignore +++ b/.gitignore @@ -19,6 +19,8 @@ fork-bundle*/ # A generated fork config normally lives inside the bundle; a manual # `ppn fork toml fork.toml` drops one wherever the shell stood. fork.toml +# What `ppn start` spawns: the config above with each custom process's environment (lib/spawn-env.ts) +*.spawn.toml # Working notes, kept locally rather than in the repo docs/issues-drafts/ diff --git a/CLAUDE.md b/CLAUDE.md index b42088a..08d318e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -64,8 +64,12 @@ make start FORK=1 NETWORK=devnet # Fork a different network (networks/*.json) make start FORK=1 FRESH_BITE=1 # Fork, biting production now instead of using a bundle make start FORK=1 CLEAN=1 # Fork, back at its bite block (a stopped fork otherwise resumes) make bite NETWORK=polkadot UPGRADES="people=" # Bite with a runtime authorized at import (no-sudo networks) +make start FORK=1 FRESH_BITE=1 CORES=people=3 COLLATORS=people=5 # Bite with People on 3 cores and 5 collators ``` +`CORES`/`COLLATORS` are bite-time: the authority sets and the core layout are state inside the +bundle, so they need a fresh bite, and the relay grows to one validator per core (max 10). + Fork mode continues from a real block rather than resetting to genesis, so contracts, registrations and balances are already present. A fork that is started again resumes where it stopped, as long as the data came from the bundle being spawned. See `docs/FORK.md`. @@ -131,6 +135,7 @@ docs/ ├── POLKADOT-FORK.md # Runbook: fork Polkadot with the fellowship runtimes on a dedicated machine ├── PROFILES.md # dev/prod profiles: funded accounts, sudo, signing keys ├── RUNTIME-UPGRADE.md # Upgrade the runtime of a running chain +├── TRINITY-STACK.md # The network's Trinity stack descriptor and light specs └── TURN.md # TURN/STUN relay (eturnal) behind DUB's turn-api bin/ # Output directory (gitignored except ppn.mjs) @@ -159,13 +164,15 @@ scripts/ # Shell launchers zombienet execs; the logic lives ├── pin-bulletin-products.sh # Launcher over `ppn service pin-bulletin-products` ├── force-open-hrmp.sh # Force-open HRMP channels ├── patch-bootnodes.sh # Patch bootnode addresses +├── trinity-stack.sh # Launcher over `ppn service trinity-stack`: descriptor and light specs ├── enact-upgrades.sh # Launcher over `ppn service enact-upgrades`: applies what a bite authorized ├── grant-invites.sh # Grants the backend's inviter account invites (both dims) ├── increase-people-lite-attestation-allowance.sh # Attestation allowance config +├── increase-dotns-attestation-allowance.sh # The same attester's DotnsGateway allowance on Asset Hub ├── docker-entrypoint.sh # Docker container entrypoint ├── ensure-dot-cli.sh # Installs dot CLI tool ├── install.sh # Installation script -├── kill-port.sh # Kill processes on specific ports +├── require-free-ports.sh # Refuse ports something already listens on (never kills) ├── validate-ports.sh # Port configuration validator ├── run-tests.sh # Integration test runner └── dub/ # device-uniqueness-backend (see docs/DEVICE-UNIQUENESS-BACKEND.md) diff --git a/Dockerfile b/Dockerfile index afcc102..37dbf53 100644 --- a/Dockerfile +++ b/Dockerfile @@ -101,5 +101,8 @@ HEALTHCHECK --interval=30s --timeout=10s --start-period=120s --retries=3 \ -d '{"jsonrpc":"2.0","method":"system_health","params":[],"id":1}' \ http://localhost:10000 || exit 1 +# The CLI reads its install type from this, because the image has no .git or dist manifest. +ENV PPN_INSTALL=docker + # Start network via entrypoint script (prints info, handles regenerate) ENTRYPOINT ["/ppn/scripts/docker-entrypoint.sh"] diff --git a/Makefile b/Makefile index daaf9ba..8d42e2d 100644 --- a/Makefile +++ b/Makefile @@ -85,6 +85,9 @@ FORK_TOML := $(FORK_DIR)/fork.toml # Runtimes a bite authorizes at import, for a network without sudo: UPGRADES="= ..." # becomes one `--upgrade` per entry on `ppn bite` (or `ppn start` when it bites). UPGRADE_FLAGS := $(foreach u,$(UPGRADES),--upgrade $(u)) +# How a bite lays the network out: CORES="= ..." COLLATORS="= ...". Fixed at +# bite time like UPGRADES, so a published bundle needs FRESH_BITE=1 to take them. +TOPOLOGY_FLAGS := $(foreach c,$(CORES),--cores $(c)) $(foreach c,$(COLLATORS),--collators $(c)) ifeq ($(FORK),1) TOML_FILE := $(FORK_TOML) @@ -153,7 +156,8 @@ start: build-spawner $(if $(filter 1,$(EPHEMERAL)),--ephemeral,) \ $(if $(filter 1,$(REGENERATE)),--regenerate,) \ $(if $(filter 1,$(FRESH_BITE)),--fresh-bite,) \ - $(UPGRADE_FLAGS) + $(if $(NODE_VERIFIER),--node-verifier $(NODE_VERIFIER),) \ + $(UPGRADE_FLAGS) $(TOPOLOGY_FLAGS) kill: @node $(CURDIR)/bin/ppn.mjs kill @@ -185,7 +189,7 @@ show-network: build-spawner # build: fork.toml is generated by @ppn/network-config, which shares its # ports and per-chain flags with the genesis config generator. bite: build-spawner ensure-binaries - @node $(CURDIR)/bin/ppn.mjs bite "$(FORK_DIR)" $(UPGRADE_FLAGS) + @node $(CURDIR)/bin/ppn.mjs bite "$(FORK_DIR)" $(UPGRADE_FLAGS) $(TOPOLOGY_FLAGS) @node $(CURDIR)/bin/ppn.mjs fork toml "$(FORK_DIR)" "$(FORK_TOML)" # Make sure a bundle + config exist before a FORK=1 start. @@ -351,6 +355,9 @@ help: @echo " Only previewnet starts from genesis; the rest are fork-only." @echo " FRESH_BITE=1 With FORK=1: bite the live network now, not a published bundle" @echo " UPGRADES=... With a bite: authorize runtimes at import, \"= ...\" (no-sudo networks)" + @echo " CORES=... With a bite: cores per parachain, \"= ...\" (validators grow to match)" + @echo " COLLATORS=... With a bite: collators per parachain, \"= ...\"" + @echo " NODE_VERIFIER= metric (zombie-cli's default) or none: none leaves node readiness to you" @echo "" @echo "Examples:" @echo " make start Start with persistence (default)" diff --git a/README.md b/README.md index aba6990..1915971 100644 --- a/README.md +++ b/README.md @@ -6,10 +6,11 @@ > 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 Paseo relay chain with six +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 Storage, plus the Ethereum RPC, IPFS, identity backend and storage provider those chains -expect, already wired together. +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. ## Start it @@ -36,21 +37,89 @@ Two things worth doing before the first start: ## What you would use it for -**Develop against the whole stack, not a mock.** Contracts on Asset Hub through -`eth-rpc` at `:8545`, identity on People, storage on Bulletin and Web3 Storage. Everything -speaks to everything, the way it does in production. +### Develop against the whole stack, not a mock -**Start from real state instead of genesis.** A fork continues from a live network's block, -so contracts, registrations and balances are already there. +Contracts on Asset Hub through `eth-rpc` at `:8545`, identity on People, storage on Bulletin +and Web3 Storage. Everything speaks to everything, the way it does in production, and `//Alice` +holds sudo and funds on every chain. ```bash -ppn start --fork # from the latest published snapshot -ppn start --fork paseo-next-v2 # a different network +ppn start # previewnet from genesis; state survives a restart +ppn start --ephemeral # throw the state away when it stops +ppn start --clean # wipe the state and start over ``` -**Test a build before it ships.** Any binary or runtime can be repointed without editing -anything, which is what makes this useful as a release gate. Run the full network against a -candidate and see what breaks. +### Start from real state instead of genesis + +A fork continues from a live network's block, so contracts, DotNS registrations, personhood +state and balances are already there. Which network decides where the state comes from and +what you can do with it afterwards: + +| Network | What it is | Sudo | A fork starts from | +| --- | --- | --- | --- | +| `previewnet` | Parity's preview network on its own relay. The only network that also starts from genesis | yes | a bundle published nightly | +| `paseo-next-v2` | the next runtimes as parachains on public Paseo | yes | a bundle published nightly | +| `devnet` | the Polkadot Products Devnet on public Paseo, system-chain para ids | yes | a bite of the live network | +| `kusama` | Kusama relay and Asset Hub | no | a bite, with the runtime under test authorized at import | +| `polkadot` | Polkadot relay, Asset Hub, People and Bulletin | no | a bite, with the runtime under test authorized at import | + +**Forking a testnet with sudo.** The bundle is bitten for you every night, so a start is a +download. Once the fork runs, sudo is `//Alice`, and anything that needs root works as it +does on genesis: runtime upgrades, HRMP, core assignment, the People grants. + +```bash +ppn start --fork # previewnet, from last night's bundle +ppn start paseo-next-v2 --fork # another network +ppn start --fork --fresh-bite # bite the live network right now instead +ppn start devnet --fork # no published bundle, so this bites (several minutes) +``` + +**Forking a mainnet without sudo.** Nothing on a fork of Kusama or Polkadot can dispatch root, +so a runtime upgrade cannot be authorized after the fact. Name the blob at bite time instead: +the bite writes the authorization into state, and once the chains author, the fork applies the +upgrade on its own, through the relay's PVF pre-check and go-ahead like a real one. This is +how a fellowship release is rehearsed against Polkadot's actual state before it ships. + +```bash +gh release download v2.5.0 -R polkadot-fellows/runtimes -D runtimes/ -p 'asset-hub-polkadot_*' -p 'people-polkadot_*' +ppn start polkadot --fork --fresh-bite \ + --upgrade asset-hub=runtimes/asset-hub-polkadot_runtime-v2005000.compact.compressed.wasm \ + --upgrade people=runtimes/people-polkadot_runtime-v2005000.compact.compressed.wasm +``` + +A `--upgrade` accepts any blob: a release asset, a PR's build artifact, a local build, and +`relay=` for the relay itself. The bite warp-syncs four chains, around 20 minutes, and a +parachain's upgrade goes live an hour after the spawn, because Polkadot's upgrade delay is 600 +relay blocks. The dashboard shows the spec version flip; the log of the process applying the +upgrades is under its logs tab. If that process gave up, or you want to redo one chain, submit +the apply step yourself with no blob, and the one the bite authorized is used: + +```bash +ppn upgrade people --enact-timeout 70 # apply what the bite authorized for People +``` + +Since the authorization is state inside the bundle, a different blob means a new bite. +[docs/POLKADOT-FORK.md](docs/POLKADOT-FORK.md) is the runbook for keeping such a fork running +on a dedicated machine. + +**Living with a fork.** A fork stopped and started again resumes where it was, with any +upgrade it enacted still in force. Every network keeps its own bundle and data directory, so +forks of different networks do not disturb one another. + +```bash +ppn kill && ppn start polkadot --fork # resume where it stopped +ppn start polkadot --fork --clean # back to the bite block +ppn start --fork --pin-products # import the DotNS products, to browse them on the fork +``` + +A fork has no block history before the bite: block numbers continue, but querying an earlier +block fails. Bulletin lists content it does not hold until `--pin-products` imports it. +[docs/FORK.md](docs/FORK.md) has the rest. + +### Test a build before it ships + +Any binary or runtime can be repointed without editing anything, which is what makes this +useful as a release gate. Run the full network against a candidate and see what breaks. ```bash ppn start --binary polkadot-omni-node=file:/path/to/your/build @@ -58,30 +127,64 @@ ppn start --runtime asset-hub=file:/path/to/runtime.wasm ppn start --binary polkadot-omni-node=paritytech/release-automation@polkadot-weekly2026w37-rc1 ``` -**Rehearse a runtime upgrade.** Authorize and apply one against a chain that is already -running, and watch it cross the boundary. +`--binary` works on a fork too (`ppn start --fork`), so it can run on the node binary under test. + +### Rehearse a runtime upgrade + +Authorize and apply one against a chain that is already running, genesis or fork, and watch it +cross the boundary. The command exits 0 only once the new code is enacted and five more blocks +have finalized, so it gates CI directly. ```bash ppn upgrade asset-hub ./asset_hub_runtime.wasm +ppn upgrade people --ws wss://my-host/people ./people_runtime.wasm # a remote instance +``` + +Sudo dispatches the authorization, so this is for genesis and for forks of a sudo network. On +a fork of Kusama or Polkadot the authorization comes from the bite, as described under +"Forking a mainnet without sudo" above. See +[docs/RUNTIME-UPGRADE.md](docs/RUNTIME-UPGRADE.md). + +### Produce a fork bundle without starting it + +A bite can be run on its own, for a CI job or to hand a snapshot to someone else, and it can be +pointed at your own instance of a network rather than the one the descriptor names. + +```bash +PPN_NETWORK=paseo-next-v2 ppn bite # into fork-bundle-paseo-next-v2/ +ppn bite --source https://my-previewnet.example.org # bite your own deployment of previewnet ``` -**Run a preview network for your team.** See -[docs/DEPLOYING-YOUR-OWN.md](docs/DEPLOYING-YOUR-OWN.md). +Spawning a bundle needs only the regular node binaries; the bite tooling is fetched when a bite +runs. Parity's nightly bites publish previewnet's and paseo-next-v2's bundles to the rolling +`bites` pre-release, which is what a `--fork` start of those two downloads. + +### Run a preview network for your team + +The engine ends at "a network is running and these are its ports". Parity's own preview +network at `previewnet.substrate.dev` is deployed from a separate repo that installs this +engine's release tarball. [docs/DEPLOYING-YOUR-OWN.md](docs/DEPLOYING-YOUR-OWN.md) describes +the contract to build yours against, and [docs/PROFILES.md](docs/PROFILES.md) the profile that +strips the dev keys from anything long-lived. A server's secrets file holds the keys in +[config/secrets.env.example](config/secrets.env.example); `ppn secrets check` validates it. ## The network | | Endpoint | | | --- | --- | --- | -| Relay (alice … ferdie) | `ws://127.0.0.1:10000` – `10005` | 6 validators, Paseo | +| Relay (alice … ferdie) | `ws://127.0.0.1:10000` – `10005` | 6 validators | | Asset Hub | `ws://127.0.0.1:10020` | **2-second blocks**, elastic scaling | | People | `ws://127.0.0.1:10010` | individuality | | Bulletin | `ws://127.0.0.1:10030` | transaction storage | -| Web3 Storage | `ws://127.0.0.1:10040` | storage parachain | +| Web3 Storage | `ws://127.0.0.1:10040` | storage parachain, previewnet only | | Dashboard | | status UI and API for all of the above | | Ethereum RPC | `http://127.0.0.1:8545` | JSON-RPC onto Asset Hub | | IPFS | `:8080` gateway, `:5001` API | | | Identity backend | `http://127.0.0.1:8092` | auth, usernames, tickets; `/docs` for the API | +The ports are the same whichever network runs. A fork runs the chains its network has, so a +Polkadot fork has no Web3 Storage and Kusama has only the relay and Asset Hub. + ## Docker ```bash @@ -97,7 +200,8 @@ a loopback bind. Set `DASHBOARD_ACTIONS_TOKEN` if you want them. ## Running a network of your own The networks above are descriptors, not code: `networks/.json` naming the binary, release -and runtime for every chain. Point `ppn` at your own set and it runs those instead. +and runtime for every chain, and the live endpoints a bite reads. Point `ppn` at your own set +and it runs those instead. ```bash export PPN_HOME=~/my-network # holds networks/my-net.json @@ -105,9 +209,10 @@ ppn networks # what it can see ppn show my-net # what that resolves to ``` -`$PPN_HOME` is also where state lives: `bin/` for downloaded binaries, `data/` for chain state. -Without it, `ppn` walks up from the working directory looking for a `networks/` folder, then -falls back to `~/.ppn`. See [`networks/README.md`](networks/README.md) for the schema. +`$PPN_HOME` is also where state lives: `bin/` for downloaded binaries, `data/` for chain state, +`fork-bundle-/` for bites. Without it, `ppn` walks up from the working directory +looking for a `networks/` folder, then falls back to `~/.ppn`. See +[`networks/README.md`](networks/README.md) for the schema. ## Working on PPN itself @@ -119,8 +224,10 @@ make start A clone is a workspace like any other, so the walk-up above finds its `networks/`. What a clone adds is `make`, a front door for the common things: every target delegates to `ppn`, so -`make start FORK=1 NETWORK=devnet` is `ppn start --fork devnet`. `make help` lists the targets, -`make doctor` checks your machine, and `ppn --help` lists the flags. +`make start FORK=1 NETWORK=devnet` is `ppn start devnet --fork`, `make bite NETWORK=polkadot +UPGRADES="people="` is a bite with `--upgrade`, and `make runtime-upgrade CHAIN=people +WASM=` is `ppn upgrade`. `make help` lists the targets, `make doctor` checks your +machine, and `ppn --help` lists the flags. `make test` runs the integration suite, which spawns a real network; `make test-unit` is the fast one. [ARCHITECTURE.md](docs/ARCHITECTURE.md) is the map. @@ -130,7 +237,9 @@ one. [ARCHITECTURE.md](docs/ARCHITECTURE.md) is the map. | | | | --- | --- | | [ARCHITECTURE.md](docs/ARCHITECTURE.md) | workspace layout, package boundaries, what a release contains | -| [FORK.md](docs/FORK.md) | how forking works, and what a bundle is | +| [FORK.md](docs/FORK.md) | how forking works, what a bundle is, upgrading a fork without sudo | +| [POLKADOT-FORK.md](docs/POLKADOT-FORK.md) | runbook: a Polkadot fork with the fellowship runtimes on a dedicated machine | +| [networks/README.md](networks/README.md) | the descriptor schema and the status of every network | | [DASHBOARD.md](docs/DASHBOARD.md) | the status UI, its API, and the action plane | | [PROFILES.md](docs/PROFILES.md) | `local` vs `deployable`: funded accounts, sudo, signing keys | | [RUNTIME-UPGRADE.md](docs/RUNTIME-UPGRADE.md) | upgrading a chain that is running | @@ -139,15 +248,11 @@ one. [ARCHITECTURE.md](docs/ARCHITECTURE.md) is the map. ## Security -> [!WARNING] -> The following is a prototype, reference implementation, and proof-of-concept. This open source -> code is provided for research, experimentation, and developer education only. This code has not -> been audited, is actively experimental, and may contain bugs, vulnerabilities, or incomplete -> features. Use at your own risk. - -Concretely: the default profile deliberately runs well-known development keys (`//Alice` and -friends) as funded sudo accounts, so do not point it at anything holding real value. Read -[PROFILES.md](docs/PROFILES.md) before running it anywhere long-lived or reachable by others. +The warning at the top of this file is the policy. Concretely: the default profile deliberately +runs well-known development keys (`//Alice` and friends) as funded sudo accounts, so do not +point it at anything holding real value. A fork of Kusama or Polkadot carries real accounts +and real balances, but its validators are the dev keys too: it is a sandbox, not the network. +Read [PROFILES.md](docs/PROFILES.md) before running anything long-lived or reachable by others. Before deploying this for real use cases, you are responsible for: @@ -159,12 +264,6 @@ Before deploying this for real use cases, you are responsible for: To report a vulnerability, follow the [Parity security policy](https://github.com/paritytech/.github/blob/main/SECURITY.md). -## Parity's deployment - -Parity runs a preview network from this engine at `previewnet.substrate.dev`. That deployment, -its server tooling and its release pipeline live in a separate repo; this one is the engine it -installs. - ## License Apache-2.0. See [LICENSE](LICENSE). diff --git a/config/ports.env b/config/ports.env index 37ef59c..787cba8 100644 --- a/config/ports.env +++ b/config/ports.env @@ -112,6 +112,26 @@ DASHBOARD_PORT=8090 # reverse proxy tells every browser to connect to 127.0.0.1. PPN_PUBLIC_URL= +# The Trinity stack descriptor `ppn service trinity-stack` writes (docs/TRINITY-STACK.md). Empty +# leaves each out. Here for the same reason as PPN_PUBLIC_URL; the signing key goes in the +# secrets file as PPN_STACK_SECRET. +# PPN_STACK_FAUCET_URL: the faucet's base URL, listed as a `faucet` service. +# PPN_STACK_WEB_GATEWAY_URL: the dotNS web gateway serving this instance's names, listed as a +# `web-gateway` service as written, such as https://testnet.li/?network=previewnet: the path +# ends in `/`, and a query may follow. Only the instance the gateway resolves against sets it. +# PPN_STACK_EXPIRES_AT: Unix seconds when the network is torn down, for spawner instances. +# PPN_STACK_VALID_FOR: seconds a reader may use a copy before fetching it again. +# PPN_STACK_REFRESH_SECONDS: how often the files are rewritten; default 6 hours. +PPN_STACK_FAUCET_URL= +PPN_STACK_WEB_GATEWAY_URL= +PPN_STACK_EXPIRES_AT= +PPN_STACK_VALID_FOR= +PPN_STACK_REFRESH_SECONDS= + +# This instance's name, replacing the network file's displayName in the dashboard and the +# Trinity stack descriptor, so instances of one network can be told apart: "Previewnet Staging". +PPN_DISPLAY_NAME= + # Where the dashboard binds. Loopback by default, which is also what leaves the sudo action # plane open (see docs/DASHBOARD.md): widen this and actions need DASHBOARD_ACTIONS_TOKEN. DASHBOARD_HOST= diff --git a/config/secrets.env.example b/config/secrets.env.example new file mode 100644 index 0000000..6a4e96d --- /dev/null +++ b/config/secrets.env.example @@ -0,0 +1,44 @@ +# Every key a server's secrets file (PPN_SECRETS_FILE) may hold. A laptop names no secrets file +# and needs none of this. `ppn secrets check ` fails when a required key is missing or +# empty, or when the file holds a key not listed here. A key the engine starts reading is added +# here, or no deployment knows to supply it. + +# ---- every server ---- + +# local: the dev accounts are sudo and funded. deployable: the keys below are. +PPN_PROFILE= +# Identity backend's token signing seed: echo 0x$(openssl rand -hex 32) +JWT_ED25519_SECRET= +# TURN relay password, shared with the backend: openssl rand -hex 24 | tr -d '\n' | base64 +TURN_SECRET= + +# ---- deployable servers ---- + +# Sudo account key: echo 0x$(openssl rand -hex 32) +PPN_SUDO_URI= +# Sudo account address: subkey inspect "$PPN_SUDO_URI" --output-type json | jq -r .ss58Address +PPN_SUDO_SS58= +# Faucet account address; its key lives with the faucet. +PPN_FAUCET_SS58= +# Identity backend's chain writer key: echo 0x$(openssl rand -hex 32) +PPN_DUB_ATTESTER_URI= +# Its address, which gets the attestation allowance: subkey inspect "$PPN_DUB_ATTESTER_URI" --output-type json | jq -r .ss58Address +PPN_ALLOWANCE_SS58= + +# ---- optional ---- + +# Invite ticket signer key, instead of //Bob: echo 0x$(openssl rand -hex 32) +PPN_INVITER_SURI= +# Its address: subkey inspect "$PPN_INVITER_SURI" --output-type json | jq -r .ss58Address +PPN_INVITER_SS58= +# Apple push notifications, read by the identity backend. +APNS_KEY_ID= +APNS_TEAM_ID= +APNS_TOPIC= +APNS_ENVIRONMENT= +APNS_PRIVATE_KEY= +APNS_PRIVATE_KEY_FILE= +# Android push notifications, read by the identity backend. +FCM_SERVICE_ACCOUNT_JSON= +# Trinity stack descriptor signing key; unset publishes it unsigned: echo 0x$(openssl rand -hex 32) +PPN_STACK_SECRET= diff --git a/config/versions.env b/config/versions.env index 46bcda1..e888f2b 100644 --- a/config/versions.env +++ b/config/versions.env @@ -97,9 +97,13 @@ KUBO_VERSION="v0.39.0" # ASSET_HUB_RPC_URL on the chain writer, which 0.5.0 read optionally. # # `INVITE_INVITER_*` in upstream's .env.example is compose's host-side naming; the key the -# binary reads is still INVITER_ADDRESS. +# binary reads is still INVITER_ADDRESS. v0.7.0 defaults turn-api to Cloudflare and refuses a +# TURN_SECRET without TURN_PROVIDER, so dub.ts names coturn, which needs a non-empty ICE_SERVERS. +# v0.8.0 signs the candidate and dotNS reservation signatures in the signing context the +# runtime publishes as the `SigningContext` pallet constant, and over the plain message on a +# runtime without it (paritytech/individuality-community#196). DUB_REPO="paritytech/device-uniqueness-backend-community" -DUB_TAG="${DUB_TAG:-v0.6.0}" +DUB_TAG="${DUB_TAG:-v0.8.0}" # Portable PostgreSQL for the backend services. Fetched straight from upstream # (public repo, no auth) because it is not a PPN build product. This is the @@ -126,7 +130,7 @@ ETURNAL_VERSION="1.12.3" # and a floating pin would change that under a rebuild with no commit to point at. # Override per-run with DOTNS_TAG=... to try another release. DOTNS_REPO="paritytech/dotns" -DOTNS_TAG="${DOTNS_TAG:-v0.8.0}" +DOTNS_TAG="${DOTNS_TAG:-v1.1.0}" # Which TLD's genesis to fetch is NOT pinned here: the network descriptor's # genesisConfig.networkSuffix is the namespace, and the DotNS TLD is the same value — # one knob, so the two cannot drift. The artifact stamps its own TLD and injection diff --git a/deploy/polkadot-test/apply.sh b/deploy/polkadot-test/apply.sh index a2cb1c6..2cd8cd2 100755 --- a/deploy/polkadot-test/apply.sh +++ b/deploy/polkadot-test/apply.sh @@ -95,6 +95,11 @@ if ! sudo test -f "$SECRETS_FILE"; then sudo chown "root:$RUN_USER" "$SECRETS_FILE" && sudo chmod 0640 "$SECRETS_FILE" say "created $SECRETS_FILE" fi +# `ppn start` rejects a secrets file without a profile; the fork runs with the dev accounts. +if ! sudo grep -q '^PPN_PROFILE=' "$SECRETS_FILE"; then + echo 'PPN_PROFILE=local' | sudo tee -a "$SECRETS_FILE" >/dev/null + say "$SECRETS_FILE: added PPN_PROFILE=local" +fi sed -i \ -e "s|^BOOTNODE_HOSTNAME=.*|BOOTNODE_HOSTNAME=$DOMAIN|" \ -e "s|^PPN_PUBLIC_URL=.*|PPN_PUBLIC_URL=https://$DOMAIN|" \ diff --git a/docs/DASHBOARD.md b/docs/DASHBOARD.md index e746a25..25c82ff 100644 --- a/docs/DASHBOARD.md +++ b/docs/DASHBOARD.md @@ -25,6 +25,7 @@ CONTRACT network.json (schemaVersion'd) │ SERVICE PLANE ppn service dashboard — one zombienet custom_process, like eth-rpc /api/network /api/provenance /api/addresses /api/health /api/logs/:id + /api/stack /.well-known/trinity-stack.json /chainspecs/* plus the UI's static assets, plus (locally) a path→port proxy │ UI PLANE static SPA = render(contract + health polling). Knows no domain, no port. @@ -45,6 +46,11 @@ The model emits one route table (`/relay/alice`, `/asset-hub`, `/eth-rpc`, …). included), so `ws://127.0.0.1:/asset-hub` mirrors `wss:///asset-hub`. Disabled on servers with `DASHBOARD_PROXY=0`. +The dashboard also serves the files `ppn service trinity-stack` writes: the descriptor at +`/.well-known/trinity-stack.json`, byte for byte, and each chain's light spec at +`/chainspecs/.smol.json`. The overview shows the stack's link and QR code from +`/api/stack`. See [TRINITY-STACK.md](TRINITY-STACK.md). + ### Provenance is stamped, not derived "What was this spawned from" is a historical fact. A `latest` pin re-resolved at query time may diff --git a/docs/DEPLOYING-YOUR-OWN.md b/docs/DEPLOYING-YOUR-OWN.md index 80d8dab..5b9d192 100644 --- a/docs/DEPLOYING-YOUR-OWN.md +++ b/docs/DEPLOYING-YOUR-OWN.md @@ -70,6 +70,12 @@ Run `PPN_PROFILE=deployable` on anything long-lived: it strips the well-known de requires you to supply sudo and faucet accounts. `local` (the default) keeps `//Alice` as a funded sudo and is right for laptops and CI only. See [PROFILES.md](PROFILES.md). +Every server names a secrets file with `PPN_SECRETS_FILE`, whatever its profile: without one, +the identity backend and the TURN relay run on public dev keys. Its keys, and how to make each, +are in [`config/secrets.env.example`](../config/secrets.env.example). Run +`ppn secrets check ` before you stop the running network; `ppn start` refuses a file that +fails it. + ## What you still have to build Honestly: the boring parts. Process supervision, TLS, a reverse proxy, log shipping, backups, diff --git a/docs/DEVICE-UNIQUENESS-BACKEND.md b/docs/DEVICE-UNIQUENESS-BACKEND.md index 167993f..56b3b55 100644 --- a/docs/DEVICE-UNIQUENESS-BACKEND.md +++ b/docs/DEVICE-UNIQUENESS-BACKEND.md @@ -258,6 +258,7 @@ INVITE_TICKETS_DATABASE_URL=postgres://…/invite_tickets # DATAB PEOPLE_RPC_URL=ws://127.0.0.1:$PEOPLE_PORT PEOPLE_NETWORK=paseo # westend2|paseo|polkadot ASSET_HUB_RPC_URL=ws://127.0.0.1:$ASSET_HUB_PORT +TURN_PROVIDER=coturn # our eturnal, not Cloudflare TURN_REALM=previewnet.local ``` @@ -277,13 +278,15 @@ request. ### Attester -`ATTESTER_ACCOUNT` needs no new chain-side setup: PPN's existing -`increase-people-lite-attestation-allowance` custom process already sudo-grants 1000 +`ATTESTER_ACCOUNT` needs no new chain-side setup: PPN's +`increase-people-lite-attestation-allowance` custom process sudo-grants 1000 allowance to `5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY`, the same account -upstream defaults to. `ATTESTER_ALLOWANCE_FLOOR` (default 100) sits comfortably under -that. Ordering between the allowance process and the chain writer still needs -checking — the writer polls allowance every `ATTESTER_RESOURCE_POLL_SECS` (60s), so a -late grant should self-heal, but that should be confirmed rather than assumed. +upstream defaults to, and `increase-dotns-attestation-allowance` grants that account +1000 on Asset Hub's DotnsGateway, which its dotNS reservations draw on. `ATTESTER_ALLOWANCE_FLOOR` (default 100) sits comfortably under +that. A grant that lands after the writer starts is still picked up: the writer +retries a rejected registration or reservation up to `CHAIN_WRITER_MAX_ATTEMPTS` (8) +times, backing off from 2s up to 64s, so it covers a grant a few minutes late. The +`ATTESTER_RESOURCE_POLL_SECS` (60s) poll only reports the allowance; it does not retry. ### Attester under the deployable profile @@ -309,7 +312,7 @@ it. The backend attests as that same account, so it needs the matching key along the keys #140 already defines: ```sh -PPN_IDENTITY_ATTESTER_URI="" +PPN_DUB_ATTESTER_URI="" ``` `scripts/dub/service.sh` reads both at exec time and overrides the Alice defaults @@ -320,7 +323,7 @@ the generated TOML carries. Two things are worth knowing about that: while generating the config would never reach a server. The public SS58 would otherwise belong in the TOML with the rest of the non-secret env. 2. **A missing key is fatal, deliberately.** With `PPN_ALLOWANCE_SS58` set and - `PPN_IDENTITY_ATTESTER_URI` absent, falling back to `//Alice` would leave the writer + `PPN_DUB_ATTESTER_URI` absent, falling back to `//Alice` would leave the writer signing as an account with no allowance: the API keeps returning `202` and every registration sits in the outbox failing `NoAttestationAllowance`. The services refuse to start instead, matching the allowance script's own hard-fail. diff --git a/docs/FORK.md b/docs/FORK.md index 0788cbc..7f8b390 100644 --- a/docs/FORK.md +++ b/docs/FORK.md @@ -245,7 +245,31 @@ its hex. 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. +2-second elastic scaling intact — unless the bite was asked for a different layout, below. + +### Cores and collators + +```bash +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==` lays a parachain out on that many cores (Asset Hub defaults to three, the +rest to one); `COLLATORS==` 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. +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 +People's. Extra collators are `Collator--2` … and restore the same snapshot as the first; +only the first holds the documented ports. + +What the parachain does with its cores is the runtime's business: People authors at 2 seconds on +three cores only if its runtime is built for that velocity. The bite provides the cores. **There is no block history before the bite point.** Warp sync delivers finality proofs plus the state at the target, not the chain. Block *numbers* continue from the bite block, but querying an @@ -346,10 +370,13 @@ adds (`--relay-chain-rpc-urls`, `--discover-local`, `--allow-private-ip`, `--sta keys its chains with the same names as the `Parachain` type, so a bundle manifest is checked against the descriptor with no mapping table in between. -**Relay nodes must be named `alice`…`eve`, collators `Collator-`.** zombienet maps the +**Relay nodes must be named `alice`…`ferdie`, collators `Collator-`.** zombienet maps the 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 `//`, +and the bite derives the same — `relayNodeName()`/`collatorNodeName()` in `toml-generator.ts` are +the one place both read the name from. **Every relay node needs `ZOMBIE_DISPUTE_CANDIDATE_LIFETIME_AFTER_FINALIZATION=1`.** A warp-synced database has no ancestry before the bite block, so the dispute scrape fails, @@ -449,9 +476,10 @@ because production's values are the ones we want: gives Asset Hub its 2-second blocks. Its `executor_params` holds `EnabledHostFunction(EccRfc163)`, without which the relay's validators reject People's PVFs. One key, two things depending on it, which is why overriding it wholesale costs both. -- `Hrmp::*` / `Dmp::*` — keeps the four HRMP channels (relay pallets). On a *shared* relay the - channels are kept too, but their queues are reset on both sides — see "Forking a shared relay" - in `networks/README.md` +- `Hrmp::*` / `Dmp::*` — keeps the four HRMP channels open (relay pallets), but resets their queues + on both sides on every bite: the parachains are snapshotted before the relay, and a message + delivered in between leaves the fork panicking `HRMP head mismatch` or `DMQ head mismatch`. + See "Forking a shared relay" in `networks/README.md` for what the reset writes. - `Paras::Parachains` — keeps all four parachains registered (relay pallet) Every override value is SCALE-decoded against the live metadata of the chain being bitten before it diff --git a/docs/PROFILES.md b/docs/PROFILES.md index 0ec2dcd..a9ba97c 100644 --- a/docs/PROFILES.md +++ b/docs/PROFILES.md @@ -12,9 +12,8 @@ PPN's chain specs and operational scripts run under one of two profiles, selecte The profile also selects which runtime the relay starts from: `local` uses `relay.fastRuntime` and `deployable` uses `relay.runtime`. **Which profile a host runs is a property of that host**, not a per-run choice: it comes -from `PPN_PROFILE` in the environment or from the secrets file below, so it cannot flip -with whoever triggered a deploy. How your deployment sets it is up to you — see -[DEPLOYING-YOUR-OWN.md](DEPLOYING-YOUR-OWN.md). +from `PPN_PROFILE` in the secrets file below, so it cannot flip with whoever triggered a +deploy. How your deployment sets it is up to you — see [DEPLOYING-YOUR-OWN.md](DEPLOYING-YOUR-OWN.md). ## How the switch is plumbed @@ -43,12 +42,22 @@ Four independent consumers read it directly: `ppn generate` your process scripts/{assign-cores,force-open-hrmp}.js (sources at top) supervisor (inline KEY=value loader) (EnvironmentFile) scripts/{set-dispatcher-address, - increase-people-lite-attestation-allowance}.sh + increase-people-lite-attestation-allowance, + increase-dotns-attestation-allowance}.sh (sources directly) ``` The reason every consumer reads the file directly is that `zombie-cli` does not forward env vars from its parent to `custom_process` children. So loading the file into the supervisor's environment covers `make generate` but does *not* reach the operational scripts that run during network boot — they have to read the file themselves. +## What the file must hold + +[`config/secrets.env.example`](../config/secrets.env.example) lists every key, with a line on +how to make each one, in three sections: every server, deployable servers on top under that +profile, and optional. A laptop names no secrets file and needs none of it. `ppn secrets check ` fails on a missing or empty required key, on a key the +example does not list, and on a deployable key in a local file; `ppn start` refuses such a file. +A key the engine starts reading goes into the example, and every deployment's check fails until +it supplies it. + With `PPN_SECRETS_FILE` unset, every consumer runs `local`. That is the developer ergonomic, and it is safe precisely because it is the *stated* absence of a deployment rather than a failed lookup. Anything that must not be guessed is gated on this instead of on a filesystem probe: the dashboard's sudo actions key off what the socket is bound to (see [DASHBOARD.md](DASHBOARD.md)), and the identity backend refuses to start on the public dev JWT seed once a secrets file is named. ## What deployable mode does NOT change diff --git a/docs/TRINITY-STACK.md b/docs/TRINITY-STACK.md new file mode 100644 index 0000000..38f1173 --- /dev/null +++ b/docs/TRINITY-STACK.md @@ -0,0 +1,108 @@ +# Trinity stack descriptor + +Every running network writes a [Trinity stack descriptor](https://github.com/paritytech/trinity-user-agents/blob/main/docs/rfcs/trinity-stack-descriptor.md): +one JSON document with its chains, genesis hashes, RPC endpoints, chain specs and services. +Hosts and tools import a network from it, by a link or a QR code, instead of keeping their own +copy of those facts. + +## What gets written + +`ppn service trinity-stack` runs as a zombienet custom process in genesis and fork spawns. +Once the chains answer, it writes into the data directory: + +| File | Served at | What it is | +| --- | --- | --- | +| `trinity-stack.json` | `/.well-known/trinity-stack.json` | The descriptor, signed when the deployment gives a key | +| `.smol.json` | `/chainspecs/.smol.json` | Each chain's light-client spec | +| `trinity-stack.state.json` | `/api/stack` | The publish state, the generation, and the pointer and link | + +It is a file rather than an API: a signature and a content hash cover exact bytes, and nginx, +CI and the dashboard can all serve the same file. The dashboard serves all three and shows the +link and its QR code on the overview. + +The service rewrites the files every `PPN_STACK_REFRESH_SECONDS` (6 hours by default), and at +least twice per `PPN_STACK_VALID_FOR`, so the relay's checkpoint stays recent and no reader +holds a copy past its `validUntil`. `sequence` rises only when the content changes. Until the +relay has finalized a block and eth-rpc answers, it publishes without the relay's light spec and +without eth-rpc, and tries again every 30 seconds. + +An `EPHEMERAL=1` run writes nothing: its chains live in a temp directory, so the data directory +holds an earlier run's files. + +## Fields + +The descriptor is built from the dashboard model, so its URLs are the ones the dashboard shows: + +- `id`, `name`: the network's, or `-fork` and `Fork of ` for a fork. A + deployment names its instance with `PPN_DISPLAY_NAME` in `config/ports.env`, such as + "Previewnet Staging", which replaces the display name here and in the dashboard. +- `network`: the relay's chain, such as `paseo`. +- `tld`: `stack.tld` in the network file, or `genesisConfig.networkSuffix`. A network with + neither writes no descriptor. +- `generation`: minted with the data directory, so it changes when the chains restart from + scratch: a wipe, or a fork started again from its bite. +- `chains`: each chain's genesis hash, its RPC URLs, and its full and light specs with their + SHA-256. +- `services`: the DUB, TURN and STUN, the IPFS gateway, Bulletin as `hop`, eth-rpc with its + chain id, the storage provider, and the faucet and web gateway a deployment configures. +- `assets` and `coinage`: `stack.assets` and `stack.coinage` in the network file, for a network + whose runtime has them. Previewnet pays in pUSD (asset 50000413 on Asset Hub) and runs Coinage + instance 0 on People. +- `dotns`: the dotNS contract addresses by `DotnsConstants` key, such as `storeFactory`, plus + `protocolRegistry` for the registry itself, so readers take them from the descriptor rather + than read them from Asset Hub. + - A genesis network takes them from `bin/dotns-addresses.json`, the address list `ppn fetch` + takes from the dotns release. Contracts with no key, such as the store beacons, are left out. + - A fork takes the keys from its source's descriptor, at `stack.pointer`, and each address from + its own registry's `get(key)`, since the bite copied the source's registry. When the source's + registry has no code on the fork, because dotNS reached the source after the bite and was + deployed on the fork separately, the registry is the one Asset Hub's + `DotnsGateway::DispatcherAddress` returns from `protocolRegistry()`. A key the registry does + not hold, such as a release's `multicall3`, keeps the source's address if that has code on + the fork, and is left out otherwise. While the source descriptor or eth-rpc does not answer, + the fork publishes no `dotns` and tries again in 30s. +- `fork` and each chain's `forkedAt`: on a fork whose spawn stamp records the bite and whose + network file names the source's descriptor in `stack.pointer`. `forkedAt` is the source's + block, whose hash `ppn bite` reads from the source and records as `biteHashes`: the fork's + own block at that height differs, because the bite imports its overrides into it. For a bundle + bitten before that was recorded, the service reads the hashes from the source chains, and + publishes no `fork` while they do not answer. `ppn start --fork` records the + bite itself. A deployment that spawns zombienet directly runs + `ppn stamp-spawn --fork-manifest /manifest.json`; without it the fork is still named + as one, but carries no `fork`. + +Once the live network signs its descriptor, its network file's `stack.pointer` needs the `key`, +so every fork of it names a signed source. + +## Light specs + +A light spec is the raw spec with its genesis storage replaced by the genesis state root, and +the relay's also carries a sync checkpoint from `sync_state_genSyncSpec`. Its bootnodes are +the network's own nodes: + +- the node's P2P WS port on `BOOTNODE_HOSTNAME`, which native smoldot dials; +- behind `https`, also nginx's TLS port for that chain (`*_P2P_WSS_PORT`), because a browser on + an https page may only dial `wss`. + +The relay's light spec names alice alone, because she is the only validator with a fixed P2P +port and a WSS port in front of it. While alice is down, light clients cannot reach the relay, +though the other validators keep it running. + +Before writing, the service checks that the spec implies the chain's genesis hash, and refuses +a raw spec that names a node on any host other than `BOOTNODE_HOSTNAME`. A fork keeps its +source's genesis hash, so a spec that still lists one of the source's nodes would join the +source network, and nothing on the chain would show it. + +## Settings + +All optional. zombienet hands custom processes no environment, so a deployment patches them +into `config/ports.env`, where each has an empty default. The key goes in the secrets file. + +| Setting | Effect | +| --- | --- | +| `PPN_STACK_SECRET` | `0x` and 64 hex digits, in the secrets file. Signs the descriptor, and the pointer carries its public key. Ignored on a fork, which is always published unsigned: a descriptor signed with its source's key would be the source. | +| `PPN_STACK_FAUCET_URL` | Adds a `faucet` service. | +| `PPN_STACK_WEB_GATEWAY_URL` | Adds a `web-gateway` service, published as written: its path ends in `/`, and a query may follow, as in `https://testnet.li/?network=previewnet`. Only the instance the gateway resolves names against sets it, so staging leaves it empty when the gateway serves production. | +| `PPN_STACK_EXPIRES_AT` | Unix seconds when the network is torn down, for spawner instances. | +| `PPN_STACK_VALID_FOR` | Seconds a reader may use a copy before fetching it again. | +| `PPN_STACK_REFRESH_SECONDS` | How often the files are rewritten. | diff --git a/networks/README.md b/networks/README.md index 67fe0b5..e0819b3 100644 --- a/networks/README.md +++ b/networks/README.md @@ -56,6 +56,10 @@ or `PPN_NETWORK=` in the environment of the scripts. | `parachains[].dotnsDeployer` | Ethereum wallet, or list of them, that deploys dotNS after the spawn. The bite endows each one's revive fallback account, because the deploy is signed by a wallet with no funds on a fork of a real chain. A signed transfer would work too, but only as a manual step repeated on every rebite. | | `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. | | `dotns.gateway` | IPFS gateway the product bytes are fetched from. Omitted → `bite.source`, which is right where the source network's front door is also its gateway (previewnet, devnet) and wrong where it is not: paseo-next-v2's `https://dot.li` is a single-page app that returns its own HTML for every path, 200 included. | +| `stack.tld` | The dotNS TLD the network's Trinity stack descriptor names. Omitted → `genesisConfig.networkSuffix`; still absent → no descriptor is written. See `docs/TRINITY-STACK.md`. | +| `stack.pointer` | `{ url, key? }` where the live network publishes its own descriptor. A fork names it as `fork.of` and takes its dotNS keys from it; omitted → the fork's descriptor carries no `fork` and no `dotns`. | +| `stack.assets` | `[{ role, chain, pallet, id }]`, published as the descriptor's `assets`, such as the asset a wallet pays in. `chain` is a chain role the network runs. | +| `stack.coinage` | `{ chain, instance }`, published as the descriptor's `coinage`: the chain role and instance of the Coinage pallet. | `_todo` fields (at any level) are blocking stubs: human notes about what still has to be confirmed. The loader ignores them; `make bite` refuses to bite a network @@ -88,9 +92,9 @@ dev validators, and all three are silent: | what | inherited state | why it breaks | what the bite writes | | --- | --- | --- | --- | | cores | ~18 registered parachains, so ~18 cores | the runtime splits 6 validators into 18 groups; 12 come out empty and ours sit on cores no group is assigned to, so nothing backs their blocks | ours on cores 0-N from `ParaScheduler::CoreDescriptors`, groups to match, `num_cores` cut to N (one byte of `Configuration::ActiveConfig`, so `EnabledHostFunction(EccRfc163)` survives) | +| HRMP / DMP | channel heads from a relay snapshot newer than the parachain ones | messages delivered in that window are pruned from the relay but counted in its `mqc_head`, so cumulus panics `HRMP head mismatch` and builds no block at all | every channel touching one of our paras (read off the relay's own indexes) keeps its `Hrmp::HrmpChannels` entry with `mqc_head` cleared and counters zeroed, its `HrmpChannelContents` emptied and the recipient's `HrmpChannelDigests` emptied; `Dmp::DownwardMessageQueueHeads` zeroed and `Dmp::DownwardMessageQueues` emptied per para; the parachain's own `ParachainSystem::LastDmqMqcHead` zeroed and `LastHrmpMqcHeads` emptied to match — both halves or neither. Channels stay open, which matters on a relay without sudo where nothing could reopen them | | upgrade timing | `validation_upgrade_delay` 600 and `validation_upgrade_cooldown` 14400 on Polkadot | a runtime under test goes live an hour after its apply, and the same parachain cannot be upgraded again for a day — the fork exists to do exactly that, several times | both patched in the same `ActiveConfig` rebuild, to 30 and 60 relay blocks (`FORK_VALIDATION_UPGRADE_DELAY`/`_COOLDOWN` in `shared-relay.ts`); the pre-check and go-ahead path is unchanged, only the timers | | dotNS dispatcher | `DotnsGateway::DispatcherAddress` unset, and the pallet itself absent until the upgrade lands | `set_dispatcher_address` takes `RootOrWhitelist`, so on a fork with no Sudo nothing can ever set it and `reserve_name` and `register_name` fail `DispatcherAddressNotSet` | the address the parachain's `dotnsDispatcher` names, written as an inject. Unverifiable (the live metadata has no such pallet) and guarded on the descriptor rather than `index.pallets.has`, which would be false at bite time; see `docs/FORK.md` | -| HRMP / DMP | channel heads from a relay snapshot newer than the parachain ones | messages delivered in that window are pruned from the relay but counted in its `mqc_head`, so cumulus panics `HRMP head mismatch` and builds no block at all | every channel touching one of our paras (read off the relay's own indexes) keeps its `Hrmp::HrmpChannels` entry with `mqc_head` cleared and counters zeroed, its `HrmpChannelContents` emptied and the recipient's `HrmpChannelDigests` emptied; `Dmp::DownwardMessageQueueHeads` zeroed per para; the parachain's own `ParachainSystem::LastDmqMqcHead` zeroed and `LastHrmpMqcHeads` emptied to match — both halves or neither. Channels stay open, which matters on a relay without sudo where nothing could reopen them | | stored-data proofs | Bulletin's `RetentionPeriod` of 201,600 against a chain at ~1.5M | `pallet-transaction-storage` asserts a periodic proof of historical data a bite does not carry, so no block can be built | `RetentionPeriod` pushed past any height we fork, applied only to a runtime that has the pallet | Two things that are *not* part of this, both established by trying them: `Paras::Parachains` is diff --git a/networks/devnet.json b/networks/devnet.json index f204453..31db5e7 100644 --- a/networks/devnet.json +++ b/networks/devnet.json @@ -109,5 +109,11 @@ "StoreFactory": "0xD81DC23FAa69B311C1FC553Ea63798772e7D253D", "Multicall3": "0x929EdB8d61461c29d07deC834ef747EbFDcf0B74" } + }, + "stack": { + "tld": "dot", + "pointer": { + "url": "https://stack.api.polkadotcommunity.foundation/.well-known/trinity-stack.json" + } } } diff --git a/networks/paseo-next-v2.json b/networks/paseo-next-v2.json index 011bd36..d16e603 100644 --- a/networks/paseo-next-v2.json +++ b/networks/paseo-next-v2.json @@ -83,5 +83,12 @@ "_note": "Same DotNS deployment as previewnet — the factory deployer key pins these addresses, so the resolver is at the same address on both. Verified 2026-08-19 by scanning it on paseo-asset-hub-next. The gateway is named explicitly because bite.source (https://dot.li) is the app, not an IPFS gateway.", "resolver": "0x7F74D7CD50f5a834270E2ad395a01b01891AB37d", "gateway": "https://paseo-bulletin-next-ipfs.polkadot.io" + }, + "stack": { + "tld": "paseo", + "pointer": { + "url": "https://stack-paseo-next.parity-testnet.parity.io/.well-known/trinity-stack.json", + "key": "0x2b89d8ca74aa2e11ab55f5af1168cd6929b88d1998aecd979b42cfc1078d5377" + } } } diff --git a/networks/polkadot.json b/networks/polkadot.json index 18d65de..6251370 100644 --- a/networks/polkadot.json +++ b/networks/polkadot.json @@ -111,5 +111,11 @@ "collection": "pop:polkadot.network/people-lite", "size": 1, "_note": "Onboard each lite person into a ring on their own, rather than holding the first two until a third registers. Unlike the other seeds this one replaces a value rather than supplying a missing one: live Polkadot People already carries the collection, created at LitePeopleOnboardingSize = 3, and the fork inherits that. set_onboarding_size takes ManagerOrigin, which is RootOrTechnicalMaintenance on people-polkadot, and a fork can raise neither arm. The people collection keeps the 10 it inherits; only the lite one was asked for." + }, + "stack": { + "tld": "dot", + "pointer": { + "url": "https://stack.api.pcf.network/.well-known/trinity-stack.json" + } } } diff --git a/networks/previewnet.json b/networks/previewnet.json index 9619ebc..c6c69b5 100644 --- a/networks/previewnet.json +++ b/networks/previewnet.json @@ -187,5 +187,12 @@ "_note": "Stated here like every other network's, though a genesis network could also derive it: `ppn fetch` writes the same address into bin/dotns-addresses.json from dotns's fresh-deploy address set (deployments/expected.json, what a genesis network actually carries), and the import refuses to run if the two disagree. No `gateway` on purpose: unlike paseo-next-v2, whose bite.source is an app rather than a gateway, previewnet's products live wherever it was bitten from — naming production here would make a fork of a staging previewnet fetch from the real one.", "resolver": "0x7F74D7CD50f5a834270E2ad395a01b01891AB37d", "pinProducts": true + }, + "stack": { + "pointer": { + "url": "https://previewnet.substrate.dev/.well-known/trinity-stack.json" + }, + "assets": [{ "role": "payment", "chain": "AssetHub", "pallet": "Assets", "id": 50000413 }], + "coinage": { "chain": "People", "instance": 0 } } } diff --git a/packages/cli/package.json b/packages/cli/package.json index 66f4367..b8075d4 100644 --- a/packages/cli/package.json +++ b/packages/cli/package.json @@ -8,12 +8,13 @@ }, "exports": { ".": "./dist/cli.js", - "./spawn-env": "./dist/lib/spawn-env.js" + "./spawn-env": "./dist/lib/spawn-env.js", + "./secrets": "./dist/lib/secrets-example.js" }, "scripts": { "build": "tsc -b", - "test": "tsx --test tests/*.test.ts", - "prepack": "pnpm --dir ../dashboard-ui build && rm -rf scripts config zombienet-configs networks && cp -R ../../scripts ../../config ../../zombienet-configs ../../networks . && rm -rf scripts/node_modules && find scripts config zombienet-configs -name \"*.test.*\" -delete && rm -f config/ports.local.env scripts/run-tests.sh scripts/validate-ports.sh && cp ../../LICENSE LICENSE", + "test": "PPN_PACKAGE_ROOT=../.. tsx --test tests/*.test.ts", + "prepack": "pnpm --dir ../dashboard-ui build && rm -rf scripts config zombienet-configs networks && cp -R ../../scripts ../../config ../../zombienet-configs ../../networks . && rm -rf scripts/node_modules && find scripts config zombienet-configs \\( -name \"*.test.*\" -o -name \"*.spawn.toml\" \\) -delete && rm -f config/ports.local.env scripts/run-tests.sh scripts/validate-ports.sh && cp ../../LICENSE LICENSE", "postpack": "rm -rf scripts config zombienet-configs networks && rm -f LICENSE" }, "dependencies": { @@ -24,6 +25,7 @@ "@polkadot/util": "13.5.9", "@polkadot/util-crypto": "^13.5.9", "@parity/ppn-network-config": "workspace:*", + "@parity/trinity-stack": "^0.2.0", "commander": "^15.0.0", "polkadot-api": "^1.23.3", "toml": "^4.2.0" diff --git a/packages/cli/src/cli.ts b/packages/cli/src/cli.ts index 4b08814..f0f05af 100644 --- a/packages/cli/src/cli.ts +++ b/packages/cli/src/cli.ts @@ -26,6 +26,7 @@ import { type NetworkDef, type OverrideSet, } from '@parity/ppn-network-config'; +import { shortVersion } from './lib/version.js'; function die(message: string): never { console.error(`ppn: ${message}`); @@ -233,6 +234,10 @@ export function buildProgram(): Command { 'Product Preview Network. Which network everything applies to comes from\n' + '$PPN_NETWORK (default previewnet) — see networks/README.md.' ) + .version(shortVersion(), '-V, --version', 'print the version and exit') + // Parse top-level options only before the subcommand, because `dist` has its own + // `--version `. + .enablePositionalOptions() .configureHelp({ sortSubcommands: true }) .showHelpAfterError('(run `ppn --help`)') // The one question every [network] argument raises. Resolved when the help is printed, @@ -245,6 +250,20 @@ export function buildProgram(): Command { } }); + program + .command('secrets') + .command('check') + .argument('[file]', 'secrets file; default $PPN_SECRETS_FILE') + .summary('check a secrets file against config/secrets.env.example') + .description( + 'Every key the profile requires is set, and nothing outside the example is there.\n' + + '`ppn start` refuses a file that fails this. The example says how to make each key.' + ) + .action(async (file: string | undefined) => { + const { check } = await import('./commands/secrets.js'); + check(file); + }); + program .command('nginx-conf') .argument('