Skip to content

perps: pinned, precomputed state-proof verifier keys for chain 22 (CON-601) - #195

Merged
dendisuhubdy merged 1 commit into
feat/cs11-revendorfrom
feat/perps-pinned-key
Nov 19, 2026
Merged

dendisuhubdy merged 1 commit into
feat/cs11-revendorfrom
feat/perps-pinned-key

Conversation

@dendisuhubdy

Copy link
Copy Markdown
Member

Summary

CON-601's consensus fix for chain 22. Validators load a pinned, precomputed verifier key for each perps state-proof shape from a shipped file. They never build one, so a block that carries a tier-18 state proof can no longer push a 2 GB validator into OOM.

  • Genesis field perps.state_proof_keys. Up to 8 entries of {tier, program_log_height, input_log_height, public_log_height, poseidon2_log_height, sha256}, where sha256 is lowercase hex of the file's raw bytes.

    • It is serde default + skip and is bound into the genesis hash only when set (state_proof_keys ‖ be32 n ‖ 5 height bytes ‖ 32-byte sha per key). The persisted section gets a new trailer tag, rand-perps-ext-3, written only when keys are set.
    • check() requires engine_program_log_height and accepts only canonical shapes of the chain, in strictly increasing order.
  • Consensus rule. When the list is non-empty:

    • an unpinned declared shape is refused before any key is touched, at validate and at apply (ledger verify_state_proof and the executor's perp_pre_key);
    • a pinned shape verifies only against the key loaded from its file;
    • the node never builds a pinned key.

    When the list is empty, chain 21's behaviour is unchanged (build on demand under PERP_KEY_BUILD_GATE).

  • Node. New perps_key.rs, modelled on msauth_key.rs.

    • At startup it loads every pinned file (--perps-key-dir / RAND_PERPS_KEY_DIR / beside the binary; the source-tree fallback works only in debug or with RAND_PERPS_KEY_DEV_FALLBACK=1). Each file is held to its genesis sha256, then to the build's own pin, profile and shape, before install_verifier_key_pinned.
    • If any file is missing or mismatched, the node refuses to start. verify loads the keys too.
    • rand_status.perps_keys = {source: loaded|absent, keys}; rand_getPerps.state_proof_keys serves the list.
  • CLI. rand-node keygen-perp-vk takes --print-pinned production, --check FILE, --genesis-json DIR, or --profile P --out-dir DIR [--public-log-height H].

  • Client. rand perp prove refuses a non-canonical shape (--smallest) on a pinned chain.

The admitted set: 4 shapes

Chain 22 runs max_tier 18, engine program height 14 and max_window_blocks 64. Under today's validity rules the admissible shapes run into the hundreds, so only the canonical shapes are pinned. These are what the engine prover makes by default on a pinned chain: input 16, poseidon2 20, no keccak/sha, and one key per public height for windows of 1..=64 blocks.

file sha256 bytes
perp-vk-production-t18-pg14-in16-pub7-p2h20.bin 4dc1f18bdd6d9104ba1622710cf2c146f71759676dbdcb70dad036152242e8b4 13 685
perp-vk-production-t18-pg14-in16-pub8-p2h20.bin 6392e5e9b7348f3729ba2031e0e3ec9788d6ed62a14521526482c92615f55106 13 685
perp-vk-production-t18-pg14-in16-pub9-p2h20.bin c31636aa281004163e6fe0debd81854f11d7bca6c8062a91b1501c7e593e5bf0 13 685
perp-vk-production-t18-pg14-in16-pub10-p2h20.bin ae3d0dc276061fd2a87b2e91b239f6dcccb746b49dedeecfdb2aab977c95c370 13 685

The files are committed in crates/randprotocol-zkvm/keys/, and their digests are compiled in as executor::perp_vk::CHAIN22_SHA256_PRODUCTION.

Key build cost, measured on the 16-vCPU droplet:

  • 20.6 s and 1.74 GB max RSS per key with parallel and RAYON_NUM_THREADS=16;
  • 20.8 s and 1.74 GB without parallel.

The build is deterministic. The ignored perp_vk test regenerated all four byte for byte, and a non-parallel build gave the same pub10 digest.

Shipping

  • Cut script. deploy/cut-chain22-genesis.sh:
    • perps_keys_step holds the files in PERPS_KEY_DIR to the cutting rand-node's --print-pinned output (via shasum and --check), sets the field from --genesis-json, and points the probe node at the files;
    • py_splice asserts the four shapes and that every digest matches its file and the pin;
    • the field probe gains 2 variants (37 → 39);
    • check-limits reads back rand_getPerps.state_proof_keys and rand_status.perps_keys = loaded/4.
  • release.yml. Ships the four files in SHA256SUMS and the attestation, and checks each one against the built rand-node's pin.
  • roll-all.sh. PERPS_VK_DIR checks every file on each host against the new rand-node's pins and installs it beside the binary. Without PERPS_VK_DIR, the roll is refused if a host's genesis names the field or cannot be read.
  • Docs. docs/deploy.md, docs/perps.md, CHANGELOG.md. sync-zkvm.sh excludes the node-local tests/perp_vk.rs.

Tests

  • Clippy (CI's set, -D warnings): clean.
  • randprotocol-core lib: 895 passed. invoke_wire_pin: 2 passed. beacon_gate_off_pin: 1 passed. Chain 21's pins and genesis hash have not moved.
    • New: con601_under_pinned_keys_an_unpinned_shape_is_refused_before_any_key (validate and apply, zero builds, ledger unchanged).
    • New: con601_state_proof_keys_are_checked_and_bound_only_when_set (commit bytes, JSON round trip, rules, ext-3 persistence).
    • Extended: the genesis perps test (hash moves when keys are set or a digest changes, the field is absent when unset, the file round-trips).
  • randprotocol-node lib: 881 passed after the rand_getPerps expectation fix (the first run failed only on the new field). The new perps_key tests:
    • an unpinned shape is refused with no build;
    • a pinned shape verifies from the loaded blob with no build;
    • a missing, flipped or swapped blob is refused;
    • a chain without pins builds on demand;
    • the committed chain-22 files are this build's pins;
    • there is no build path.
  • randprotocol-node integration: genesis_cli 15 passed, rpc_contract 11 passed.
  • randprotocol-zkvm: perp_vk 2 passed (1 ignored, the regenerate test, which was run and passed), guest_provenance 19, auth_msauth_vk 10.
  • randprotocol-client lib: 255 passed. wallet_flow builds.
  • Cut selftest: SELFTEST=1 bash deploy/cut-chain22-genesis.sh gives 467 passed, 0 failed. That includes 9 new py_splice refusals, 7 perps_keys_step cases, 7 check-limits mutations and the 39-variant probe.

Risks / open

  • Non-canonical shapes are invalid on chain 22. That covers --smallest, tiers below 18, and other input or poseidon2 heights. The durian perp-prover makes canonical shapes by default and never passes --smallest or --tier.
  • The cut script's ENGINE_HC_DECIDED is still the set-10 f286a611…. Set 11's engine is 482215a8…. The keys depend only on program height 14, not on the hc, but the hc still needs confirming separately.
  • A future constraint set needs new key files and a new cut, because the digests are pinned in genesis.
  • A pinned-but-not-loaded key is refused, not built. Startup prevents that state, since the node does not start without every file.

🤖 Generated with Claude Code

https://claude.ai/code/session_01YGaYNLS2uLR7w6m2JtejVo

…N-601)

A block carrying a tier-18 perps state proof made every validator build that
shape's verifier key (~1.7 GB with `parallel`, ~3.3-4 GB without), so a 2 GB
validator could OOM on a valid block. Chain 22 pins the keys instead.

- core: gated genesis field `perps.state_proof_keys` (serde default + skip,
  bound into the genesis hash only when set, `rand-perps-ext-3` persisted);
  check() admits only canonical shapes of the chain (<= 8, ordered, needs
  engine_program_log_height). When set, an unpinned declared shape is refused
  before any key is touched, at validate and at apply.
- zkvm (node-local executor.rs): `perp_vk` module (chain-22 shapes, compiled-in
  SHA-256 pins, file names, blob/check); pinned mode refuses unpinned shapes in
  perp_pre_key, verifies only against loaded keys and never builds one.
- node: `perps_key` loads every pinned file at startup (--perps-key-dir,
  RAND_PERPS_KEY_DIR, beside the binary), refuses to start on a missing or
  mismatched file, reports rand_status.perps_keys; rand_getPerps serves the
  list; `rand-node keygen-perp-vk` (--print-pinned, --check, --genesis-json,
  --profile --out-dir); `verify` loads them too.
- client: `rand perp prove` refuses non-canonical shapes on a pinned chain.
- keys: the four chain-22 Production files (tier 18, program 14, input 16,
  poseidon2 20, public 7/8/9/10), 13 685 bytes each, in
  crates/randprotocol-zkvm/keys/.
- deploy: the chain-22 cut sets the field from the shipped files held to the
  cutting rand-node's pins, asserts it, probes it in the hash and reads it
  back in check-limits (selftest 467 passed, 0 failed); release.yml ships,
  sums, attests and checks the files; roll-all.sh installs them (PERPS_VK_DIR).
- docs: deploy.md, perps.md, CHANGELOG.

Chain 21's genesis and pins are unchanged (the field is absent there).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01YGaYNLS2uLR7w6m2JtejVo
dendisuhubdy added a commit that referenced this pull request Nov 19, 2026
…is root a45d8fda…

Set 11's Grain Poseidon2 constants move the engine's hc and the perps genesis root;
neither the image nor the genesis words change (durian.market #2, measured on a5e08a9):

- ENGINE_HC_DECIDED = 482215a8df02dff341265c38212c47e23fc8bfb3c3297afe9c385d6a63e65073
  (chain 21's image, sha256 77dfc228...); chain 21's f286a611... is kept as
  ENGINE_HC_CHAIN21 for the check on chain 21's genesis. The finished file's engine_hc must
  be the set-11 hc and not chain 21's; check-limits wants it from rand_getPerps.
- PERP_GENESIS_ROOT_DECIDED = a45d8fdab8cf7dab972e76dd6a7a18d9e82fc8210afab672a161ee60021698b4
  (perp-prover genesis-state over BTC-PERP -> rand perp genesis-root; the 26 words are
  chain 21's, sha256 bb32f0c4...). The genesis_root check is now "equals the recorded
  set-11 root" (was "equals chain 21's da0e3a53..."); chain 21's root is refused. The
  derivation moves into perp_genesis_root_step, which refuses the set-9 root and any other
  before the section is written.
- Selftest: perp_genesis_root_step against a fake prover and rand (5 cases), and refusals
  of chain 21's root and engine hc in the finished file: 474 passed, 0 failed.
- crates/randprotocol-core/tests/vectors/perps-v1.json: the three perp_digest vectors
  regenerated under set 11 (PERPS_WRITE_VECTORS=1); randprotocol-zkvm's perps_vectors
  failed on the set-9 values on #194/#195. core's golden test still passes.
- docs/deploy.md, CHANGELOG.

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

codecov Bot commented Nov 19, 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 afb7f8f into feat/cs11-revendor Nov 19, 2026
22 of 23 checks passed
@dendisuhubdy
dendisuhubdy deleted the feat/perps-pinned-key branch November 19, 2026 19:57
dendisuhubdy added a commit that referenced this pull request Nov 19, 2026
…idon2 height, rate-¼ quotient layout, versioned rVM keys, cell-count gas) (#194)

* Re-vendor circuits: constraint set 11 (Grain constants, declared poseidon2 height, rate-1/4 quotient layout, versioned rVM keys, cell-count gas)

Issue #166 step 7, for the chain-22 cut and v0.8.7. CIRCUITS_PIN b3e21d9 -> 76a48dca
(circuits org/main), synced with deploy/sync-zkvm.sh; seven guests (evm-v1 added).

- BUILD_CONSTRAINT_SET 11; chain 21 joins CHAINS_THIS_BUILD_CANNOT_RUN. Set 11 moves every
  Poseidon2 output, so no chain 14-21 genesis file builds any more:
  constraint_set::build_genesis refuses them by chain id at init/run/verify, before any
  datadir is touched. Chain 22's CHAIN_CONSTRAINT_SETS row is owed at its cut.
- Guest digests: bundle v1 71eedbfb, v2 3aff6361, v3 00782b22, auth 8373994c, msauth
  41db73c5 (guest_provenance pins both these and the set-10 values chains 14-21's files carry).
- Gas mirror gas_max_declared(t,k,s,m,p2): bundle 22527, auth 1407, msauth 355775
  (MSAUTH_POSEIDON2_LOG_HEIGHT 16). poseidon2_log_height carried through ProofShape,
  MsauthShape, CallDryRun and the aggregate path; bundle/auth inner proofs and the canonical
  perp state proof declare the tier's full height.
- msauth key blobs: production 23851 B 168d79a8 (reproduced by keygen), test d30472df.
- Executor FRI mirror follows machine::LOG_BLOWUP (2): 92 queries / 24 pow bits.
- Recursion fixtures Test-0..2 re-proved and re-pinned; inner vk b9046f5d, interface digest
  517d13e4, production aggregate program digest 43e02700. msig signer-check fixtures
  regenerated.
- deploy/cut-chain22-genesis.sh: EXPECT_HC_BUNDLE, EXPECT_HC_AUTH, HC_AUTH_MULTISIG_DECIDED,
  BUNDLE_GAS_LIMIT to set 11's; chain 21's file asserted at its set-9 values. Perps engine
  pins left as chain 21's (durian must rebuild).
- Docs, CHANGELOG (Unreleased) and AGENTS.md.

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

* Cargo.lock: rand-zkvm-cuda at the CIRCUITS_PIN rev 76a48dca

The optional git dependency's rev moved with the re-vendor but the lock still named 71e1a04,
so every `--locked` job (clean-clone, wallet-e2e, release) refused to update it. `cargo update
-p rand-zkvm-cuda` under the pinned 1.98.1 toolchain: the cuda crate's new p3 deps, one
itertools dropped, range-compatible picks below it. Checked with --locked on the build
droplet in all three CI layouts: fullnode alone (metadata + check --workspace --tests),
beside circuits at the pin, and nested as wallet-e2e checks it out (release build of
rand-node and rand-prover).

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

* perps: pinned, precomputed state-proof verifier keys for chain 22 (CON-601)

A block carrying a tier-18 perps state proof made every validator build that
shape's verifier key (~1.7 GB with `parallel`, ~3.3-4 GB without), so a 2 GB
validator could OOM on a valid block. Chain 22 pins the keys instead.

- core: gated genesis field `perps.state_proof_keys` (serde default + skip,
  bound into the genesis hash only when set, `rand-perps-ext-3` persisted);
  check() admits only canonical shapes of the chain (<= 8, ordered, needs
  engine_program_log_height). When set, an unpinned declared shape is refused
  before any key is touched, at validate and at apply.
- zkvm (node-local executor.rs): `perp_vk` module (chain-22 shapes, compiled-in
  SHA-256 pins, file names, blob/check); pinned mode refuses unpinned shapes in
  perp_pre_key, verifies only against loaded keys and never builds one.
- node: `perps_key` loads every pinned file at startup (--perps-key-dir,
  RAND_PERPS_KEY_DIR, beside the binary), refuses to start on a missing or
  mismatched file, reports rand_status.perps_keys; rand_getPerps serves the
  list; `rand-node keygen-perp-vk` (--print-pinned, --check, --genesis-json,
  --profile --out-dir); `verify` loads them too.
- client: `rand perp prove` refuses non-canonical shapes on a pinned chain.
- keys: the four chain-22 Production files (tier 18, program 14, input 16,
  poseidon2 20, public 7/8/9/10), 13 685 bytes each, in
  crates/randprotocol-zkvm/keys/.
- deploy: the chain-22 cut sets the field from the shipped files held to the
  cutting rand-node's pins, asserts it, probes it in the hash and reads it
  back in check-limits (selftest 467 passed, 0 failed); release.yml ships,
  sums, attests and checks the files; roll-all.sh installs them (PERPS_VK_DIR).
- docs: deploy.md, perps.md, CHANGELOG.

Chain 21's genesis and pins are unchanged (the field is absent there).

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

* deploy: chain-22 perps on constraint set 11 — engine 482215a8…, genesis root a45d8fda…

Set 11's Grain Poseidon2 constants move the engine's hc and the perps genesis root;
neither the image nor the genesis words change (durian.market #2, measured on a5e08a9):

- ENGINE_HC_DECIDED = 482215a8df02dff341265c38212c47e23fc8bfb3c3297afe9c385d6a63e65073
  (chain 21's image, sha256 77dfc228...); chain 21's f286a611... is kept as
  ENGINE_HC_CHAIN21 for the check on chain 21's genesis. The finished file's engine_hc must
  be the set-11 hc and not chain 21's; check-limits wants it from rand_getPerps.
- PERP_GENESIS_ROOT_DECIDED = a45d8fdab8cf7dab972e76dd6a7a18d9e82fc8210afab672a161ee60021698b4
  (perp-prover genesis-state over BTC-PERP -> rand perp genesis-root; the 26 words are
  chain 21's, sha256 bb32f0c4...). The genesis_root check is now "equals the recorded
  set-11 root" (was "equals chain 21's da0e3a53..."); chain 21's root is refused. The
  derivation moves into perp_genesis_root_step, which refuses the set-9 root and any other
  before the section is written.
- Selftest: perp_genesis_root_step against a fake prover and rand (5 cases), and refusals
  of chain 21's root and engine hc in the finished file: 474 passed, 0 failed.
- crates/randprotocol-core/tests/vectors/perps-v1.json: the three perp_digest vectors
  regenerated under set 11 (PERPS_WRITE_VECTORS=1); randprotocol-zkvm's perps_vectors
  failed on the set-9 values on #194/#195. core's golden test still passes.
- docs/deploy.md, CHANGELOG.

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

* Re-vendor circuits 41d64acd: EVM guest block context v2 (circuits #27, issue #168)

CIRCUITS_PIN 76a48dca -> 41d64acd, and both rand-zkvm-cuda revs with it (Cargo.lock
updated with cargo update -p rand-zkvm-cuda). deploy/sync-zkvm.sh from circuits 41d64acd;
the recursion VM did not move (crates/randprotocol-rvm unchanged).

- evm.bin hc 3869b014...8920720d (program id 0eff0627...), evm-v1.bin 040c01c8...3454; the
  guests-compiled and vendor/circuits manifests and PROVENANCE.md re-synced. No hand-held
  evm hc pin existed elsewhere in fullnode (guest_provenance checks the manifests).
- evm_core::Host gained read_public: the vendored HostRef answers 0 (no context version,
  so the block opcodes trap as under a version-1 context), the new HostPublic reads a
  segment and panics past its end (no proof in the guest), and HostBox (ffi) forwards to
  READ_PUBLIC. No fullnode-owned Host impl exists.
- New crates/randprotocol-zkvm/tests/invoke_at_context.rs (excluded from the sync): the
  guest's CTX_* offsets equal the ledger's; the vendored interpreter over the segment the
  ledger builds (Transition::context_at over BlockFacts::context_words) pushes NUMBER,
  TIMESTAMP, CHAINID, BASEFEE, GASPRICE and PREVRANDAO from words 11-27, traps PREVRANDAO
  without a beacon and every block opcode under version 1; and a Test-profile InvokeAt
  proof of an RV32 program reading words 8+{0,11,12,13,16,17,19,27} verifies on its own
  block's segment and is refused on another time, another beacon value and a version-1
  context.
- docs/evm-block-context.md, CHANGELOG.md, AGENTS.md: the guest side is vendored.

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