From 481b17f4f50f2f37e57efc246bc0d12a2b244d11 Mon Sep 17 00:00:00 2001 From: Dendi Suhubdy <4477337+dendisuhubdy@users.noreply.github.com> Date: Fri, 20 Nov 2026 06:39:58 +0800 Subject: [PATCH 1/2] v0.8.7: version, changelog and release notes (chain 22, constraint set 11) - Workspace version 0.8.7: Cargo.toml, the seven workspace crates in Cargo.lock (cargo update -w on the build droplet; offline failed on the rand-zkvm-cuda git dependency), the rand_getVersion test. - CHANGELOG: Unreleased becomes v0.8.7 (tag date a PLACEHOLDER), with a row for #197's cutover-fleet-chain22.sh and the asset list. - docs/releases/v0.8.7.md: the set-11 gas change as a governance record (bundle 20 479 -> 22 527, auth 1 279 -> 1 407, msauth 436 159 -> 355 775; the per-row weights), the chain-22 cut, the operator upgrade steps and the rollback. The chain-22 genesis hash and the CHAIN_CONSTRAINT_SETS row are PLACEHOLDER-... until the cut. - README release table: v0.8.7. AGENTS.md: #194 is merged. Not tagged, not signed, not published. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01YGaYNLS2uLR7w6m2JtejVo --- AGENTS.md | 7 +- CHANGELOG.md | 26 +++ Cargo.lock | 14 +- Cargo.toml | 2 +- README.md | 1 + crates/randprotocol-node/src/rpc.rs | 2 +- docs/releases/v0.8.7.md | 267 ++++++++++++++++++++++++++++ 7 files changed, 309 insertions(+), 10 deletions(-) create mode 100644 docs/releases/v0.8.7.md diff --git a/AGENTS.md b/AGENTS.md index d2387316..4682c090 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,7 +6,12 @@ invariants, and known traps. ## Project memory (state as of 2026-11-08) -### Constraint set 11 re-vendored (issue #166 step 7; 2026-11-20, branch `feat/cs11-revendor`, PR open, NOT merged) +### Constraint set 11 re-vendored (issue #166 step 7; 2026-11-20, #194 merged as `94b2c15c`; v0.8.7) + +**v0.8.7** is this build: version bump on `release/v0.8.7` (from main `e79070a7`, after #197's +`cutover-fleet-chain22.sh`), release notes `docs/releases/v0.8.7.md`. Not tagged, signed or +rolled as of 2026-11-20; the chain-22 genesis hash and its `CHAIN_CONSTRAINT_SETS` row are +`PLACEHOLDER-…` there until the cut. `CIRCUITS_PIN` **`41d64acd`** (circuits main: set 11 landed at `76a48dca`, "Constraint set 11: Grain constants, declared poseidon2 height, quotient layout, versioned rVM key"; then #27, the EVM diff --git a/CHANGELOG.md b/CHANGELOG.md index 5d2c8538..bfcc883c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,32 @@ stopped at v0.4 until 2026-09-30, when the entries v0.5 to v0.6.7 were written f ## Unreleased +Nothing yet. + +## v0.8.7 — PLACEHOLDER-TAG-DATE (chain 22, **a chain cut**: constraint set 11; a set-11 node refuses every chain 14–21 genesis, so this release is never rolled onto chain 21) + +The release notes — the set-11 gas change as a governance record, the chain-22 cut, the operator +upgrade steps and the rollback — are [`docs/releases/v0.8.7.md`](docs/releases/v0.8.7.md). +Assets: `rand-node`, `rand`, `rand-prover`, `msauth-vk-production.bin` (set 11, `168d79a8…71b3`) +and the four `perp-vk-production-t18-*.bin` state-proof keys, with `SHA256SUMS` (eight lines; +seven of them are the files the fleet installs) and the owner's `SHA256SUMS.sig`. + +Release (no node change beyond the version): + +- **The fleet switch from chain 21 to chain 22: `deploy/cutover-fleet-chain22.sh`** (#197), + derived from chain 21's cutover. The build is v0.8.7 at constraint set 11, so `switch` keeps + v0.8.6's `rand-node`, `rand` and chain 21's msauth blob as `*.pre-c22` and `rollback` restores + all three. Seven signed files are staged and checked on every host (`rand-node`, `rand`, the + set-11 msauth blob, the four perps keys). New phases `beacon-init` (each validator makes its own + seed on its own host; the seed never leaves it) and `beacon-collect` (`BEACON_TSV`); + `check-beacon-seed.sh` runs at `stop`, `switch`, `start` and `wait`. 25 validators (archive2 + dropped), quorum 17. `stop` refuses without `CONFIRM_HALT_CHAIN21=halt-chain-21-for-`. `verify` needs the `CHAIN_CONSTRAINT_SETS` row. Every changing + phase appends to `deploy/roll-records/v0.8.7-chain22-cutover.record`. `SELFTEST=1` rehearses + the whole cutover against 26 fake hosts (`deploy/rehearse-cutover-fleet-chain22.sh`). +- **Workspace version 0.8.7** (`Cargo.toml`, the seven workspace crates in `Cargo.lock`, the + `rand_getVersion` test). + Perps (**a chain cut, chain 22**; chain 21 unchanged): - **Chain 22's perps on constraint set 11.** The cut pins the engine at `482215a8…5073` (chain diff --git a/Cargo.lock b/Cargo.lock index a75cd77c..38e9327c 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1108,7 +1108,7 @@ dependencies = [ [[package]] name = "bridge-codec" -version = "0.8.6" +version = "0.8.7" [[package]] name = "bs58" @@ -5463,7 +5463,7 @@ dependencies = [ [[package]] name = "randprotocol-client" -version = "0.8.6" +version = "0.8.7" dependencies = [ "anyhow", "base64 0.22.1", @@ -5490,7 +5490,7 @@ dependencies = [ [[package]] name = "randprotocol-core" -version = "0.8.6" +version = "0.8.7" dependencies = [ "bincode", "blake3", @@ -5510,7 +5510,7 @@ dependencies = [ [[package]] name = "randprotocol-msig" -version = "0.8.6" +version = "0.8.7" dependencies = [ "chacha20poly1305 0.11.0", "getrandom 0.2.17", @@ -5527,7 +5527,7 @@ dependencies = [ [[package]] name = "randprotocol-node" -version = "0.8.6" +version = "0.8.7" dependencies = [ "anyhow", "async-trait", @@ -5566,7 +5566,7 @@ dependencies = [ [[package]] name = "randprotocol-prover" -version = "0.8.6" +version = "0.8.7" dependencies = [ "anyhow", "axum", @@ -5631,7 +5631,7 @@ dependencies = [ [[package]] name = "randprotocol-zkvm" -version = "0.8.6" +version = "0.8.7" dependencies = [ "chacha20 0.10.2", "chacha20poly1305 0.11.0", diff --git a/Cargo.toml b/Cargo.toml index fe5b3234..d0ee84ba 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -9,7 +9,7 @@ members = ["crates/randprotocol-core", "crates/randprotocol-zkvm", "crates/randp exclude = ["vendor/circuits/evm-core", "vendor/circuits/sbpf-core", "vendor/circuits/dilithium-core"] [workspace.package] -version = "0.8.6" +version = "0.8.7" edition = "2021" license = "GPL-3.0-only" authors = ["RandProtocol Contributors"] diff --git a/README.md b/README.md index 1f58ffef..110b03df 100644 --- a/README.md +++ b/README.md @@ -359,6 +359,7 @@ a time. | v0.7.0 | node-only: the audit v7 addendum (bounded by-hash deferral, header pages capped by reply size, a prover timeout, the wallet's resumable first sync hardened) and the last audit v6 rows (a clean-clone build, an incremental token root, the key-separation schedule); the first workflow-built, signed release | 20 | | v0.8.0 | chain 21's cut build: constraint set 9 (rVM phase 4's Merkle spans, the MODQ chip), tree aggregation, scan heads, compact blocks, the `fees` section, RPL-3 perps, public and private multisig | 21 | | v0.8.2 | node-only on chain 21: the audit v10 node, perps and prover-pool fixes (the prover memory gate, the two-member pool pin, threshold release signatures); its consensus rules are genesis-gated to the next cut | 21 | +| v0.8.7 | chain 22's cut build: constraint set 11 (Grain Poseidon2 constants, declared poseidon2 height, rate-¼ quotient layout, versioned rVM keys, cell-count gas: bundle 22 527, auth 1 407, msauth 355 775), EVM block context and the randomness beacon, pinned perps state-proof keys, the 5-of-6 treasury; refuses chains 14–21 ([release notes](docs/releases/v0.8.7.md)) | 22 | ## v0.5: RPL, zUSD and bridge hardening diff --git a/crates/randprotocol-node/src/rpc.rs b/crates/randprotocol-node/src/rpc.rs index 58522cd6..418a6cd0 100644 --- a/crates/randprotocol-node/src/rpc.rs +++ b/crates/randprotocol-node/src/rpc.rs @@ -10287,7 +10287,7 @@ pub(crate) mod tests { // passed happily through v0.2, v0.3 and v0.4 while the field reported 0.1.0 (audit v3, // PROC-3). The workspace version is bumped with each tag, and this is what notices when it // is not. - assert_eq!(v["version"], "0.8.6", "bump the workspace version in Cargo.toml with the tag"); + assert_eq!(v["version"], "0.8.7", "bump the workspace version in Cargo.toml with the tag"); // The full 40-hex commit, `-dirty` when tracked files differed at build time, or // "unknown" when neither git nor a `.git-rev` could say — never a short or stale form. let sha = v["git_sha"].as_str().unwrap(); diff --git a/docs/releases/v0.8.7.md b/docs/releases/v0.8.7.md new file mode 100644 index 00000000..2a9a4270 --- /dev/null +++ b/docs/releases/v0.8.7.md @@ -0,0 +1,267 @@ +# v0.8.7 — chain 22 on constraint set 11 (release notes) + +Written 2026-11-20 on `release/v0.8.7`, from fullnode main `e79070a7`. **Nothing here has been +tagged, signed, published or run against a host.** The owner tags and signs on a real TTY. The +cut, `stop` (the halt of chain 21) and every fleet phase run only on the owner's go, typed in the +executing session, one phase at a time. + +v0.8.7 is **the chain-22 release, a chain cut**. It is never rolled onto chain 21. A set-11 +`rand-node` refuses every chain 14–21 genesis by chain id (`constraint_set::build_genesis`) before +it touches a datadir. So the fleet switches from v0.8.6 to v0.8.7 in one all-stop cutover +(`deploy/cutover-fleet-chain22.sh`), and a host cannot run both chains on one binary. Chain 21's +datadirs are never touched, and chain 21 stays the rollback target on v0.8.6. + +The row-by-row list is the `CHANGELOG.md` entry for v0.8.7. The full record (pins, measured runs, +traps) is `AGENTS.md`. This page covers the four things an operator or a reviewer needs from the +release: + +1. the fee change, as a governance record; +2. the chain-22 cut; +3. the upgrade steps; +4. the rollback. + +## Placeholders filled at the tag and at the cut + +These values do not exist yet. Each placeholder below is written `PLACEHOLDER-…` so a grep finds +every one. Fill them in the commit that lands `deploy/genesis-chain22.json`. + +| what | value | filled when | +|---|---|---| +| tag commit | `PLACEHOLDER-TAG-COMMIT` (this branch's merge commit on main) | at the tag | +| tag date (UTC; also the CHANGELOG heading) | `PLACEHOLDER-TAG-DATE` | at the tag | +| green `ci` run named in the tag annotation | `PLACEHOLDER-CI-RUN` | at the tag | +| `rand-node` / `rand` / `rand-prover` sha256 | `PLACEHOLDER-SHA256SUMS` (the release workflow's `SHA256SUMS`) | when `release.yml` finishes | +| **chain-22 genesis hash** | `PLACEHOLDER-CHAIN22-GENESIS-HASH` | at the cut (`deploy/cut-chain22-genesis.sh`, re-derived by the second operator) | +| **`CHAIN_CONSTRAINT_SETS` row** | `(22, "PLACEHOLDER-CHAIN22-GENESIS-HASH", 11),` | at the cut: the cut prints it as `constraint-set-row:` in the cut record | +| chain-22 launch time | `PLACEHOLDER-LAUNCH-UTC` | at `start` | + +**The row is not in the v0.8.7 binary, and does not need to be.** The genesis hash cannot exist +before the cut, and the cut needs the v0.8.7 release: `stage` and `beacon-init` run the staged +v0.8.7 binary before the snapshot. A v0.8.7 node runs chain 22 by the `constraint-set` marker +(`11`) that `init` writes into each new datadir. The row lands on main with +`deploy/genesis-chain22.json`, in the same commit, after the cut and before `push` (see below). +The cutover's `verify` and the cut script's `check-limits` both refuse until it is committed. The +same order held at chain 21: tag v0.8.0 (`c0878c3f`) has no `genesis-chain21.json`, which landed +afterwards in `58c7afd2`. + +> **Note for the owner (a doc conflict, not resolved here).** `docs/deploy.md` ("The +> constraint-set row") says "A release for chain 22 is tagged only from a tree on which +> `check-limits` passes". No tree can satisfy that for v0.8.7, because the release has to exist +> before the cut. This page reads the sentence as applying to the first release *after* the cut +> (v0.8.8 or later), which will carry the row in its binary. Say if you read it otherwise. + +## 1. The fee change: constraint set 11's gas weights (governance record) + +| | | +|---|---| +| **decision** | Adopt the cell-count gas weights at constraint set 11: Keccak and SHA-256 priced lower, MODQ priced per op, the Poseidon2 absorb raised (fullnode issue #167, ZKVM-202; circuits set 11) | +| **decided by** | the owner, 2026-11-18 (the set-11 scope decision: "everything staged", weights included) | +| **source** | circuits `76a48dca` (set 11), pinned here at `41d64acd`; fullnode #194 (`94b2c15c`); `crates/randprotocol-core/src/gas.rs`; `docs/fees.md` | +| **takes effect** | chain 22's genesis, block 0. Chain 21 is unchanged and keeps set 9's weights on v0.8.6 | +| **not changed** | the gas price (default `--gas-price` 100 units = 10⁻⁷ RAND), the byte price (800 units per KiB), `BUNDLE_BASE` (1 000 000), the call fee schedule, the fee burn and subsidy rules (`fees` is carried from chain 21) | +| **owner sign-off of this record** | `PLACEHOLDER-OWNER-SIGNOFF` (name, date) | + +**The declared gas ceilings, old → new.** Every bundle and auth proof must declare exactly these +values, or it is refused permanently (`TxError::BundleGasLimit`, `TxError::AuthGasLimit`). The +bundle value is chain 22's genesis `gas.bundle_gas_limit`. + +| proof | chain 21 (set 9) | chain 22 (set 11) | change | +|---|---|---|---| +| bundle, tier 14 (`gas_max(14, 0, 0)`, genesis `bundle_gas_limit`) | 20 479 | **22 527** | +2 048 (+10.0 %) | +| auth, tier 10 (`gas_max(10, 0, 0)`) | 1 279 | **1 407** | +128 (+10.0 %) | +| msauth (private multisig auth; poseidon2 height 16) | 436 159 | **355 775** | −80 384 (−18.4 %) | + +**The per-row weights behind them** (`gas.rs`, mirrored against the vendored zkVM): + +| row | set 9 | set 11 | +|---|---|---| +| cpu cycle | 1 | 1 | +| `KECCAK` | 192 | **134** | +| `SHA256` | 64 | **49** | +| `POSEIDON2` absorb / digest prefix | 3 | **4** | +| `MODQ` | 168, flat | **per op**: NTT/INTT 193, DOT4 264, MSUB4 304 (the header ceiling uses 304) | + +**What a user pays.** At the default gas price of 100 units per gas, the gas term of a bundle's +fee goes from 2 047 900 units (0.0020479 RAND) to 2 252 700 units (0.0022527 RAND). That is ++204 800 units, about 0.0002 RAND per bundle. The auth proof's ceiling moves by +12 800 units. +The msauth ceiling falls by 8 038 400 units (about 0.008 RAND). A call's fee is still priced at +the full-height poseidon2 ceiling, which over-charges a proof that declares a shorter table and +never under-charges one. Wallets declare the ceilings by default, so no user action is needed +beyond a chain-22 wallet build. Issue #167 stays open for what set 11 does not address. + +## 2. The chain-22 cut + +The full field list, the owner's decisions and the checks are in `docs/deploy.md`, "The next cut: +chain 22". In brief: + +- **Constraint set 11.** Grain-derived Poseidon2 round constants. Every guest hc, note + commitment, nullifier, Merkle and state root and verifier key moves. Proofs also declare their + poseidon2 height, use the rate-¼ quotient layout (FRI blowup 2, 92 queries, 24 pow bits) and + versioned rVM keys. Guests: bundle v3 `00782b22…141e`, auth `8373994c…6078`, msauth + `41db73c5…9cd1`. The production msauth key blob is `168d79a8…71b3` (23 851 bytes). +- **EVM block context** (circuits `41d64acd`, issue #168). Under `InvokeAt` (wire tag 45), the + EVM guest's `NUMBER`, `TIMESTAMP`, `CHAINID`, `BASEFEE`, `GASPRICE` and `PREVRANDAO` read + public words 11–27. `program_state.reference_block_window` is 256. +- **The randomness beacon.** Hash-chain commit–reveal (`BeaconReveal` tag 46, `BeaconCommit` tag + 47) with `commit_delay_blocks` 256. There is one commitment per validator, made on its own + host. Total seed loss halts the chain for good. The owner accepted that risk on 2026-11-18, to + be covered by each operator's offline encrypted backup. +- **Perps.** BTC-PERP on zUSD, tier 18, 24 inputs, as on chain 21. The engine image keeps the + same bytes, now at the set-11 hc `482215a8…5073`, and the set-11 `genesis_root` is + `a45d8fda…98b4`. `perps.state_proof_keys` pins four tier-18 shapes (CON-601), and validators + load those keys instead of building them. Chain 21's exchange is carried, and it is empty. +- **The treasury.** 5 of 6 with six new signers. Its 100 000 RAND is carried from chain 21's + `multisig_rand_held`, not issued again. +- **Validators.** 25 (18 genesis + 7 bonded), quorum 17. archive2 is dropped and its 1 000 RAND + chain-21 stake is not recreated (named on the record's `drops:` line). +- **History.** Chain 21's history on record starts at height 187 556 (e, obs1). The carry scan + runs with `PRUNED_SCAN_OK=1` and the record's `scan-floor: 187556`. +- **Program vaults are dropped.** durian.market's AMM is redeployed on chain 22 with a fresh + pool. +- **Other genesis-gated rules switched on at the cut:** + - `program_state.refuse_panics` (PST-1); + - `perps.bound_payouts` (PERP-6); + - `perps.sparse_windows` with `max_window_heights` 256 (PERP-101); + - `perps.max_pending_digests` 65 536 (PERP-5); + - `multisig.max_accounts` 65 536 (MSA-4); + - `tokens.incremental_root`. +- **Chain-22 genesis hash:** `PLACEHOLDER-CHAIN22-GENESIS-HASH`. + +## 3. Upgrade steps + +### a. The tag, the release, the signature + +The owner runs these; the exact sequence is in the v0.8.7 release PR. In outline: + +1. Tag `v0.8.7` (annotated, naming the green `ci` run) on fullnode main. +2. `release.yml` builds and attests the release. It publishes `rand-node`, `rand`, + `rand-prover`, `msauth-vk-production.bin`, the four `perp-vk-production-t18-*.bin` files and + `SHA256SUMS`. +3. The owner signs `SHA256SUMS` off the build host with `deploy/sign-release.sh` and uploads + `SHA256SUMS.sig`. +4. Verify all of the following before any host is touched: + - the signature, with `verify_release_sums`; + - each file against the signed sums, with `verify_binary`; + - each file's attestation, with `gh attestation verify`; + - the msauth blob is `168d79a8…71b3` and 23 851 bytes; + - `rand-node keygen-perp-vk --print-pinned production` names the four sha256s in + `docs/deploy.md`. + +`SHA256SUMS` has eight lines. Seven of them are the files `cutover-fleet-chain22.sh` stages and +re-checks on every host: `rand-node`, `rand`, `msauth-vk-production.bin` and the four perps keys. +The eighth is `rand-prover`, which the cutover does not stage (the prover hosts take it +separately). The cutover refuses a +signed file that does not list all seven at their decided values. + +### b. The fleet (all 25 hosts): `deploy/cutover-fleet-chain22.sh` + +Run each phase **alone**, never piped or chained, and read `echo $?` before the next (the chain-16 +trap). `INVENTORY=…/configuration/fleet/inventory.tsv` is needed by every phase. +`RELEASE_SUMS` is the signed v0.8.7 `SHA256SUMS`, `OLD_RELEASE_SUMS` v0.8.6's (chain 21: rand-node +`61c2a8bb…`, msauth blob `68facb06…cd30`). Chain 21 keeps committing until `stop`. + +1. `preflight` (read-only): all 25 hosts reachable on v0.8.6 and chain 21, disk, keys, and the + signed v0.8.7 sums and files. +2. `stage`: the seven files and `check-beacon-seed.sh` go to `/root/stage-c22` on every host, + sha-checked. +3. `beacon-init`: each validator makes **its own** seed with the staged v0.8.7 binary. **Each + validator operator** then keeps an offline, encrypted backup of `beacon-c22/beacon.seed.json`. + The seed never leaves its host. +4. `beacon-collect` (read-only): the 25 commitments are written to `BEACON_TSV`. +5. `bridge-stop`: rand-guardian on the six guardian hosts, and rand-relayer on `RELAYER_HOST`. +6. `snapshot ` and `balances `, against a tunnel to e or obs1 (`CHAIN21_RPC`), with + chain 21's v0.8.6 `rand` as `WALLET`. +7. `cut`, with these inputs: + - `EXPECT_NODE_VERSION=0.8.7`; + - `PERPS_MAX_WINDOW_HEIGHTS=256`; + - `MULTISIG_MAX_ACCOUNTS=65536`; + - `TREASURY=~/.rand-chain22/treasury.txt`; + - `PROGRAM_VAULTS_DROPPED_OK=1`, `PRUNED_SCAN_OK=1`; + - the collected `BEACON_TSV`. + + The cut writes `deploy/genesis-chain22.json` and the cut record, and prints the genesis hash + and the `constraint-set-row:`. **→ fill `PLACEHOLDER-CHAIN22-GENESIS-HASH`.** +8. The second operator re-derives the hash and writes `second-hash:` into the record. +9. **Commit** `deploy/genesis-chain22.json`, the cut record, and the row + `(22, "", 11),` in `crates/randprotocol-node/src/constraint_set.rs`. Raise the array + length to 9. In the same commit, replace this page's placeholders. Then run + `cargo test -p randprotocol-node --lib constraint_set` on the build droplet, never on the Mac. +10. `push `: the genesis goes to every host. Chain 21 is **still running**. +11. **The owner's go**, typed in the executing session. +12. `CONFIRM_HALT_CHAIN21=halt-chain-21-for- stop `. This stops + all 25 hosts and halts chain 21. +13. `switch `: the v0.8.6 files become `*.pre-c22`, then the v0.8.7 files are installed, + the new datadirs created (marker `11`) and each seed copied into its host's own datadir. +14. `start`: bootstraps C and D first, then the other 21 validators. +15. `check-limits `: the cut script's read-back against C, run **before the first deposit + and state proof**. +16. `start-archives`: e and obs1. +17. `wait `: all 25 on chain 22, keys loaded, `check-beacon-seed.sh --rpc` passing. +18. `BRIDGE_ON_CHAIN22=yes bridge-start`, once the bridge session has switched the daemons' + configs (chain id, cursor). +19. `verify `: the `CHAIN_CONSTRAINT_SETS` row and the roll record + (`deploy/roll-records/v0.8.7-chain22-cutover.record`). + +`SELFTEST=1 deploy/cutover-fleet-chain22.sh` rehearses all of this against 26 fake hosts, and +`DRY_RUN=1` prints every remote command. + +### c. A node outside the fleet (an RPC node, an archive, a developer's node) + +1. Install v0.8.7's `rand-node` and `rand` and, **beside the binary**, `msauth-vk-production.bin` + (set 11) and the four `perp-vk-production-t18-*.bin`. Without them a chain-22 node refuses to + start. To keep them elsewhere, use `--msauth-vk` / `RAND_MSAUTH_VK` and `--perps-key-dir` / + `RAND_PERPS_KEY_DIR`. +2. Make a **new** datadir: `rand-node init --datadir --genesis genesis-chain22.json`. + This writes `constraint-set` = `11`. Copy `constraint-set` with `genesis.json` and `db/` if a + datadir is ever moved. Do not point v0.8.7 at a chain-21 datadir: it is refused, and left + byte-identical. +3. A validator only: create the seed with `rand-node beacon init --datadir --key + --chain-id 22` on that host, before the cut. Back it up offline and encrypted, and never copy + it to another host. Before the first start, run `deploy/check-beacon-seed.sh --genesis + genesis-chain22.json --datadir --key `. +4. Start the node. + - Check `rand_getVersion` reports 0.8.7. + - Check `rand_status.msauth_key` and `rand_status.perps_keys` report the keys loaded. + - Check `rand_getBeacon` is `enabled`. + +### d. Downstream, at the cut (each in its own repository) + +- **Wallets.** Wallets need a set-11 core: clients `2f80ad5e` (#14) is chain-22-only. A wallet + that still proves for set 9 cannot transact on chain 22. Mobile still has to migrate a saved + chain 21 to 22. +- **randscan, durian.market, randbridge.org, randprotocol.org.** Each moves its chain pin and + expected genesis to chain 22. +- **The bridge.** The relayer and guardians mint against set-11 commitments on chain 22. +- **clients CI.** `FULLNODE_TAG` becomes `v0.8.7` only after the tag exists. + +## 4. Rollback + +Rollback is possible **only while chain 22 has burned and minted nothing**. Once a bridge burn, +deposit or mint has committed on chain 22, going back loses it. From then on, problems are fixed +forward. Stop the bridge first (`bridge-stop`). + +1. `quiet ` (read-only): confirms nothing was burned or minted on chain 22. +2. `halt`: stops a fleet that does not run chain 21. It refuses a fleet that does. +3. `OLD_RELEASE_SUMS= rollback`: restores chain 21's units, + `/root/rand-node.pre-c22`, `/root/rand.pre-c22` and + `/root/msauth-vk-production.bin.pre-c22`. v0.8.6 reads chain 21's set-9 blob, so restoring it + is required. The four perps key files may stay, because chain 21's genesis pins none. +4. `start`: the rollback marker licenses it, with C and D first. +5. `wait21`: waits until all 25 serve chain 21 and C's height moves. Chain 21 resumes from the + height where it stopped, because its datadirs were never touched. + +**By hand**, if `rollback` itself cannot run: + +- restore the three `*.pre-c22` files into `/usr/local/bin`; +- on a node host, restore `/root/rand-node.service..bak` over the unit; +- on a guardian host, move `/root/chain21.conf.c21` back into + `/etc/systemd/system/rand-node.service.d/` and delete `chain22.conf`; +- then `daemon-reload` and start. + +**A re-cut after a switch** runs `halt`, `rollback`, `start` and `wait21`, then `push`, `stop` and +`switch` on the new genesis. The beacon seeds stay in each host's staging dir and are reused, so +`BEACON_TSV` is unchanged. Each re-cut has a new genesis hash, so the `CHAIN_CONSTRAINT_SETS` row +and this page's placeholders follow it. + +**Not a rollback.** Never install v0.8.6 over a chain-22 datadir, or v0.8.7 over a chain-21 one. +Each build refuses the other's datadir by its marker and writes nothing. From ee67a75c57ff076bcf3d3cdc18a552bfc30d4f4b Mon Sep 17 00:00:00 2001 From: Dendi Suhubdy <4477337+dendisuhubdy@users.noreply.github.com> Date: Fri, 20 Nov 2026 09:16:06 +0800 Subject: [PATCH 2/2] v0.8.7 notes: the set-11 address re-derivation (#199) and WALLET22 Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01YGaYNLS2uLR7w6m2JtejVo --- CHANGELOG.md | 6 ++++++ docs/releases/v0.8.7.md | 7 ++++++- 2 files changed, 12 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index bfcc883c..0f6c92ea 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -24,6 +24,12 @@ seven of them are the files the fleet installs) and the owner's `SHA256SUMS.sig` Release (no node change beyond the version): +- **The chain-22 cut re-derives every shielded address under set 11** (#199). The same spend + key has a different `rand1…` address under set 11 (`pk = H_PK(nk)` is a Poseidon2 output). + `cut-chain22-genesis.sh` now takes `WALLET22` (the v0.8.7 `rand`) next to chain 21's + `WALLET`, and tells them apart by a probe key. It re-derives every alloc, zUSD carry, faucet + recipient and validator payout from a held key file (or a recorded `given=` address and + fingerprint), and refuses any address chain 21 knew. The fee recipient has no chain-21 default. - **The fleet switch from chain 21 to chain 22: `deploy/cutover-fleet-chain22.sh`** (#197), derived from chain 21's cutover. The build is v0.8.7 at constraint set 11, so `switch` keeps v0.8.6's `rand-node`, `rand` and chain 21's msauth blob as `*.pre-c22` and `rollback` restores diff --git a/docs/releases/v0.8.7.md b/docs/releases/v0.8.7.md index 2a9a4270..3c15298d 100644 --- a/docs/releases/v0.8.7.md +++ b/docs/releases/v0.8.7.md @@ -170,7 +170,12 @@ trap). `INVENTORY=…/configuration/fleet/inventory.tsv` is needed by every phas 4. `beacon-collect` (read-only): the 25 commitments are written to `BEACON_TSV`. 5. `bridge-stop`: rand-guardian on the six guardian hosts, and rand-relayer on `RELAYER_HOST`. 6. `snapshot ` and `balances `, against a tunnel to e or obs1 (`CHAIN21_RPC`), with - chain 21's v0.8.6 `rand` as `WALLET`. + chain 21's v0.8.6 `rand` as `WALLET` (it reads chain 21) and the signed v0.8.7 `rand` as + `WALLET22` (it derives every chain-22 address). **Set 11 changes every shielded address for + the same key** (#199). Every carried line, the faucet allowlist and the validator payouts are + re-derived from held key files. The owner supplies a set-11 fee-recipient address and + fingerprint (`rand address` with the v0.8.7 wallet), because chain 21's `89DS-4Q4X…` is + refused. 7. `cut`, with these inputs: - `EXPECT_NODE_VERSION=0.8.7`; - `PERPS_MAX_WINDOW_HEIGHTS=256`;