Skip to content

deploy: chain-22 cut re-derives every shielded address under constraint set 11 (cut-blocking) - #199

Merged
dendisuhubdy merged 1 commit into
mainfrom
fix/cut22-set11-addresses
Nov 20, 2026
Merged

dendisuhubdy merged 1 commit into
mainfrom
fix/cut22-set11-addresses

Conversation

@dendisuhubdy

Copy link
Copy Markdown
Member

Why (cut-blocking)

Constraint set 11 changes the Poseidon2 constants, so pk = H_PK(nk) and the rand1… address change for the same spend key. On the test key, v0.8.0 gives PNKR-0783-FNHS-K5AY and set 11 gives KWTC-Y3MQ-XX7S-JVXP. deploy/cut-chain22-genesis.sh took every carried rand1 from chain-21 tooling:

  • balances / ALLOC_ADDRESSES
  • ZUSD_CARRY
  • the fee recipient (89DS-4Q4X-HXSX-MBYW)
  • chain 21's faucet allowlist
  • the validator payouts

As a result, chain 22's genesis would have sealed funds to set-9 addresses that no set-11 wallet can spend, and nothing would have reported it.

Design

  • Two wallets.
    • WALLET (chain 21's rand, set 9) only reads chain 21 and proves a key file's chain-21 address.
    • WALLET22 (v0.8.7 from the signed release, set 11, no default) derives every chain-22 address, fingerprints addresses, and runs perp image-hc / perp genesis-root.
    • Each binary is identified by the fingerprint it gives for a public, never-funded probe key (01×32): set 9 gives XCGM-G4XD-CQQA-753X and set 11 gives S3VP-7C0T-GGSA-BJJY. I checked both against the build droplet's set-11 rand with throwaway keys only.
    • The cut refuses, by name, a set-9 WALLET22 (the same address as WALLET), a set-11 WALLET, or a binary of an unknown set.
  • Carry lines (ALLOC_ADDRESSES, ZUSD_CARRY, FAUCET_RECIPIENTS) have the form <label> <set-11 rand1…> [<amount>] key=<key file>|given=<fingerprint> [c21=<chain-21 rand1…>].
    • balances writes alloc lines in this form and prints suggested zUSD key= lines.
    • The cut re-derives every key= file with both binaries. It refuses a line whose address is not WALLET22's derivation, is the key's set-9 address, or has a c21= that does not match.
    • Every alloc line must come from a held key (key= + c21=).
    • given= (a holder such as Anish sends their set-11 address and fingerprint) is allowed only in zUSD/faucet lines, only for labels in SET11_GIVEN that also appear on the cut record's set11-given: line, and only when the fingerprint checks out.
  • Faucet: FAUCET_RECIPIENTS is now required. It must be chain 21's allowlist at set-11 addresses, in order, unless FAUCET_RECIPIENTS_CHANGED=1.
  • Validator payouts: re-derived from PAYOUT_KEYS_DIRS/<name>.key.json, using the key whose set-9 address equals the chain-21 payout.
  • Fee recipient: needs a chain-22 FEE_RECIPIENT_FILE and FEE_RECIPIENT_FINGERPRINT, with no default. WALLET22 checks the fingerprint. 89DS-4Q4X-HXSX-MBYW and chain 21's address are refused by name, with instructions to run rand address with the v0.8.7 wallet.
  • Backstop: before writing the genesis, the cut refuses any rand1 that chain 21 knew and any alloc note sealed to a chain-21 pk.
  • Record: adds the line address-derivation: set 11 via WALLET22 sha256 … (probe …), chain 21 via WALLET sha256 …; n key file(s) re-derived; given: ….
  • Not affected: validator, faucet-minter and beacon addresses are Address::from_public_key = blake3("rand-address" ‖ Dilithium2 pk). They contain no Poseidon2, so set 11 does not move them. Treasury signers and guardians are public keys.
  • DRY_RUN: uses throwaway WALLET22 keys for the synthetic wallets and the faucet. When there is no fee file it also uses a throwaway fee recipient, and it says so loudly.
  • deploy/cutover-fleet-chain22.sh: balances and cut refuse to run without both wallets, or with the same binary as both. The roll record gets WALLET22's sha256.
  • Docs: docs/deploy.md (chain-22 section) and AGENTS.md (project memory + workflow traps).

What the owner supplies at the cut

  • WALLET22: the v0.8.7 rand from the signed release. WALLET stays v0.8.6.
  • Their set-11 fee-recipient address in ~/.rand-chain22/fee-recipient-address.txt and FEE_RECIPIENT_FINGERPRINT, both from rand address --key <their key> with the v0.8.7 wallet.
  • ~/.rand-chain22/faucet-recipients.txt.
  • A payout key for each of the 25 validators under PAYOUT_KEYS_DIRS.
  • For any holder whose key is not on the Mac: their set-11 address and fingerprint (given=), listed in SET11_GIVEN and on the record's set11-given: line.

Tests (Mac)

  • SELFTEST=1 bash deploy/cut-chain22-genesis.sh: 547 passed, 0 failed. Fake set-9, set-10 and set-11 wallets cover each refusal and the happy path.
  • SELFTEST=1 bash deploy/cutover-fleet-chain22.sh: 215 passed, 0 failed.
  • shellcheck -x: no new findings. The only notes left are two that were already on main (SC2001, SC2016).

Not merged.

🤖 Generated with Claude Code

https://claude.ai/code/session_01YGaYNLS2uLR7w6m2JtejVo

…nt set 11

Set 11 changes the Poseidon2 constants, so pk = H_PK(nk) and the rand1
address move for the same spend key (test key: PNKR-0783-FNHS-K5AY under
v0.8.0, KWTC-Y3MQ-XX7S-JVXP under set 11). The cut took every carried
rand1 from chain-21 tooling (balances, ZUSD_CARRY, the fee recipient
89DS-4Q4X-HXSX-MBYW, chain 21's faucet allowlist, validator payouts), so
chain 22's genesis would have sealed funds to set-9 addresses no set-11
wallet can spend.

- Two wallets: WALLET (chain 21's rand, set 9) reads chain 21; WALLET22
  (v0.8.7, set 11, no default) derives every chain-22 address and runs
  perp image-hc / genesis-root. Each is identified by a public probe
  key's fingerprint (set 9 XCGM-G4XD-CQQA-753X, set 11
  S3VP-7C0T-GGSA-BJJY, checked on the build droplet's set-11 rand); a
  set-9 WALLET22, a set-11 WALLET or an unknown set is refused by name.
- Carry lines: <label> <set-11 rand1> [<amount>] key=<file>|given=<fp>
  [c21=<rand1>]. balances writes ALLOC_ADDRESSES in this form; the cut
  re-derives every key= file with both binaries and refuses any address
  not WALLET22's derivation. given= only for ZUSD_CARRY /
  FAUCET_RECIPIENTS, only under SET11_GIVEN plus a set11-given: record
  line, fingerprint-checked.
- Validator payouts: re-derived from PAYOUT_KEYS_DIRS (the key whose
  set-9 address is the chain-21 payout).
- Fee recipient: chain-22 FEE_RECIPIENT_FILE + FEE_RECIPIENT_FINGERPRINT,
  no default, checked with WALLET22; 89DS-... and chain 21's address
  refused by name.
- FAUCET_RECIPIENTS is required (chain 21's allowlist is set 9).
- Backstop: no rand1 or note pk chain 21 knew in the finished file.
- Record: address-derivation: set 11 via WALLET22 sha256 ... line.
- Validator, minter and beacon addresses are blake3 of a Dilithium2 key:
  unaffected, documented.
- cutover-fleet-chain22.sh balances/cut require both wallets and record
  WALLET22's sha256; docs/deploy.md and AGENTS.md updated.

SELFTEST=1 deploy/cut-chain22-genesis.sh: 547 passed, 0 failed.
SELFTEST=1 deploy/cutover-fleet-chain22.sh: 215 passed, 0 failed.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01YGaYNLS2uLR7w6m2JtejVo
@codecov

codecov Bot commented Nov 20, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@dendisuhubdy
dendisuhubdy merged commit 680db7f into main Nov 20, 2026
23 checks passed
@dendisuhubdy
dendisuhubdy deleted the fix/cut22-set11-addresses branch November 20, 2026 01:15
dendisuhubdy added a commit that referenced this pull request Nov 20, 2026
…t 11) (#198)

* 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 <[email protected]>
Claude-Session: https://claude.ai/code/session_01YGaYNLS2uLR7w6m2JtejVo

* v0.8.7 notes: the set-11 address re-derivation (#199) and WALLET22

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01YGaYNLS2uLR7w6m2JtejVo

---------

Co-authored-by: Claude Opus 5.5 <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant