Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 39 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,43 @@ invariants, and known traps.

## Project memory (state as of 2026-11-08)

### The chain-22 cut script carries block context and the beacon (2026-11-18, branch `feat/chain22-beacon-cut` stacked on `feat/randomness-beacon`, NOT pushed; deploy only)

The owner decided on 2026-11-18 that chain 22 launches with `program_state.reference_block_window`
(#168) and the beacon (#189). `deploy/cut-chain22-genesis.sh` now carries both; `docs/deploy.md`
"The next cut: chain 22" has the inputs and the operator seed procedure.

- **Inputs**: `REFERENCE_BLOCK_WINDOW` (default 256, 256..=4096, OPEN 9) and
`BEACON_COMMIT_DELAY_BLOCKS` (default 256, 1..=2^20, OPEN 10), both **owner values to
confirm**; `BEACON_TSV` (`<name> <64 hex>`, default `~/.rand-chain22/beacon-commitments.tsv`),
joined by validator name. Refused: a missing, extra or twice-listed name, a malformed (not 64
lowercase hex), shared or all-zero commitment, an empty window (the beacon needs it).
- **Addresses** in the section are the ones each public key derives (`rand-node admit sign
--candidate <pk>` under a throwaway key prints it, submits nothing); a VALIDATORS_TSV or
registration address that differs is refused. `FIXTURE_ADDRESSES_OK=1` (DRY_RUN's synthetic
register only) warns instead.
- **Spliced in Python**, like `perps`: `rand-node genesis` validates, and the base file has no
bridge or perps, so the window flag is refused there. The real cut gates on `genesis --help`
listing both flags; DRY_RUN skips both loudly (`BLOCK_CONTEXT_SKIPPED`).
- **Field probe**: 38 variants (the audit-v10 eight + window-and-beacon removed, window 257,
beacon removed, delay 257, each of the 26 commitments changed alone). Checked against the real
0.8.6 build: each moves the hash; removing both gives chain 21's `ca76c276…` back.
- **check-limits** reads back `rand_getLimits.program_state.{reference_block_window,
beacon_commit_delay_blocks}`, `rand_getBlockContext` (`-32001` before block 1 is accepted) and
`rand_getBeacon`: every commitment exactly at height 0; above it at most `height` may have moved
to their reveal (no BLAKE3 in the script to walk the link).
- **The seeds are never checked by the cut or check-limits**, which see no host's file.
`deploy/check-beacon-seed.sh` runs **on each validator host** (key address → genesis
commitment; `beacon commitment` names this address and chain; a chain in the file is that
commitment; mode 0600; with `--rpc`, `beacon status` exits 0). It belongs in the future
`cutover-fleet-chain22.sh` `start` gate, beside chain 21's msauth `vk_check`.
- **Cut record**: `reference-block-window:`, `beacon-commit-delay-blocks:`, one
`beacon-commitment: <name> <address> <hex>` per validator and the operator procedure (init on
its own host, send only the commitment, offline encrypted backup; total seed loss accepted
2026-11-18). The record must name both features.
- SELFTEST 309 → 403, all passing; shellcheck clean. Not exercised: DRY_RUN, the real cut, a
live `rand_getBeacon` / `rand_getBlockContext`, the cutover script (does not exist).

### The randomness beacon (2026-11-18, branch `feat/randomness-beacon` stacked on `feat/i168-reference-block`, NOT pushed; genesis-gated, on no chain)

Spec and operator notes: `docs/evm-block-context.md` §11. Stub executor only: nothing proved.
Expand Down Expand Up @@ -56,7 +93,6 @@ Spec and operator notes: `docs/evm-block-context.md` §11. Stub executor only: n
- **Pool**: `BeaconCommit` claims `(validator, nonce)` under role 11 and ranks with governance;
`admission::is_permanent` caches `RevealOutsideBlockHead` and `BadSignature`.
- **Not done**: circuits (`PREVRANDAO` reading words 19–27), a real-prover test,
`deploy/cut-chain22-genesis.sh` (it carries neither the window nor the beacon),
`deploy/fleet-watch.sh` alerts, entry removal for validators that left the register.

### Block context: the reference block (issue #168, ZKVM-203; 2026-11-18, branch `feat/i168-reference-block`, NOT pushed; genesis-gated, on no chain)
Expand Down Expand Up @@ -94,8 +130,8 @@ constraint set 10 and waits for the chain-22 cut. Spec: `docs/evm-block-context.
- **RPC**: `rand_getBlockContext` (public; `{"enabled": false}` when off);
`rand_getLimits.program_state.reference_block_window` only when set; `tx_json` kind `invoke_at`.
- **Not done**: circuits (READ_PUBLIC in evm-core/evm-rt/evm2rv, re-pin), wallet/CLI building an
`InvokeAt` (and its note scan learning `invoke_at`), a real-prover test,
`deploy/cut-chain22-genesis.sh` (see the branch's report). Stub executor only: no proof made.
`InvokeAt` (and its note scan learning `invoke_at`), a real-prover test. The chain-22
cut script now carries the window (above). Stub executor only: no proof made.

### Aggregation's memory docs re-anchored (issue #119, AGG-E2E-2; 2026-11-18, branch `docs/i119-aggregation-memory`, docs only)

Expand Down
11 changes: 10 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ change):
level as Ethereum's `PREVRANDAO` — one bit of withholding per slot — and a contract must pin
`target = NUMBER + k` at bet time or the prover re-rolls across the window: `docs/
evm-block-context.md` §11.4. The guest's `PREVRANDAO` read waits for the constraint-set-10
re-vendor; `deploy/cut-chain22-genesis.sh` does not carry the section yet.
re-vendor.

Core and node (issue #168, ZKVM-203; **genesis-gated, on no chain** — chain 21's genesis hash,
wire, storage and behaviour are unchanged):
Expand All @@ -53,6 +53,15 @@ wire, storage and behaviour are unchanged):
the block opcodes: reading these words is circuits work on constraint set 10, at the chain-22
cut. Spec: `docs/evm-block-context.md`.

Deploy (no node change):

- **The chain-22 cut carries `program_state.reference_block_window` and the beacon**
(`deploy/cut-chain22-genesis.sh`): `REFERENCE_BLOCK_WINDOW` (256, 256..=4096) and
`BEACON_COMMIT_DELAY_BLOCKS` (256), owner values to confirm; `BEACON_TSV` joined by validator
name, one distinct 64-hex commitment each; field-probed, read back by check-limits
(`rand_getBeacon`, `rand_getBlockContext`), written to the cut record with the operator seed
procedure. New `deploy/check-beacon-seed.sh`, run on each validator host before its node starts.

Node (issue #166, ZKVM-201; node-only, no wire, genesis or consensus change):

- **A build of one constraint set no longer starts on, or truncates, a datadir of another.** A
Expand Down
101 changes: 101 additions & 0 deletions deploy/check-beacon-seed.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,101 @@
#!/usr/bin/env bash
# Does THIS validator host's beacon seed open its genesis commitment? (The randomness beacon,
# genesis `beacon`, PR #189; docs/evm-block-context.md §11.5.) Run ON EACH VALIDATOR HOST, as
# root, before its node first starts on a beacon chain — the chain-22 cutover's `start` gate,
# beside the msauth key check — and again after the start with --rpc. A host whose seed does not
# open its commitment starts and votes, but can never propose (every one of its slots costs the
# chain a view timeout): this catches it before launch.
#
# deploy/check-beacon-seed.sh --genesis <genesis.json> --datadir <datadir> --key <node key>
# [--rpc <url>] [--node <rand-node>]
#
# Offline (always):
# 1. the node key's address (`rand-node address --key`) has a commitment C in the genesis
# `beacon` section;
# 2. `rand-node beacon commitment --datadir` succeeds — it re-derives every chain in
# <datadir>/beacon.seed.json from its seed, so a file that is not this validator's, or that
# was edited, is refused there — and names THIS key's address and the genesis chain id (a
# seed file copied from another host names that host's validator: refused);
# 3. some chain in the file has commitment C (the newest, normally; an older one is accepted
# with a warning — the node walks every chain in the file);
# 4. the file is mode 0600 or stricter (it is secret).
# With --rpc (the node running on this genesis): `rand-node beacon status` exits 0 — the
# commitment the chain holds in force for this validator is opened by the file — and at height 0
# that commitment is C.
#
# Reads the commitments of the seed file, never prints a seed. Needs rand-node and python3.
# Exit 0 and one line `beacon seed OK: …` on success; non-zero and the reason otherwise.
set -euo pipefail

NODE=${NODE:-rand-node}
GENESIS='' DATADIR='' KEY='' RPC=''
while [ $# -gt 0 ]; do
case "$1" in
--genesis) GENESIS=${2:?}; shift 2;;
--datadir) DATADIR=${2:?}; shift 2;;
--key) KEY=${2:?}; shift 2;;
--rpc) RPC=${2:?}; shift 2;;
--node) NODE=${2:?}; shift 2;;
*) echo "check-beacon-seed: unknown argument $1 (--genesis --datadir --key [--rpc] [--node])" >&2; exit 2;;
esac
done
fail() { echo "check-beacon-seed: $(hostname 2>/dev/null || echo host): $*" >&2; exit 1; }
[ -n "$GENESIS" ] && [ -n "$DATADIR" ] && [ -n "$KEY" ] || { echo "check-beacon-seed: --genesis, --datadir and --key are required" >&2; exit 2; }
[ -f "$GENESIS" ] || fail "no genesis file $GENESIS"
[ -f "$KEY" ] || fail "no node key $KEY"
SEED=$DATADIR/beacon.seed.json
[ -f "$SEED" ] || fail "no $SEED — run \`rand-node beacon init --datadir $DATADIR --key $KEY --chain-id <chain id>\` on this host (or restore THIS validator's own offline backup) and send only the commitment"

# 1. this key's address and its genesis commitment
ADDR=$("$NODE" address --key "$KEY" | sed -n 's/^address: \(.*\)$/\1/p' | head -1)
[ -n "$ADDR" ] || fail "\`$NODE address --key $KEY\` printed no address"
read -r CHAIN_ID WANT < <(python3 - "$GENESIS" "$ADDR" <<'PY'
import json, sys
g = json.load(open(sys.argv[1]))
b = g.get("beacon")
if not b:
sys.exit(f"check-beacon-seed: {sys.argv[1]} has no beacon section — nothing to check")
c = [x["commitment"] for x in b["commitments"] if x["validator"] == sys.argv[2]]
if len(c) != 1:
sys.exit(f"check-beacon-seed: the genesis beacon lists no commitment for this key's address {sys.argv[2]} — not a genesis validator's key?")
print(g["chain_id"], c[0])
PY
) || exit 1
[ -n "${WANT:-}" ] || fail "could not read the genesis commitment"

# 2. the file is this validator's, on this chain, and every chain in it re-derives
ERR=$(mktemp); trap 'rm -f "$ERR"' EXIT
NEWEST=$("$NODE" beacon commitment --datadir "$DATADIR" 2>"$ERR") || fail "\`rand-node beacon commitment\` refused $SEED: $(tail -1 "$ERR")"
read -r FCHAIN FVAL < <(sed -n 's/^chain \([0-9][0-9]*\), validator \([^,]*\), .*/\1 \2/p' "$ERR" | head -1) || true
[ -n "${FVAL:-}" ] || fail "\`rand-node beacon commitment\` did not name the file's chain and validator ($(tail -1 "$ERR"))"
[ "$FVAL" = "$ADDR" ] || fail "$SEED is validator $FVAL's, and this host's key is $ADDR's — a seed file copied from another host (never copy beacon.seed.json); run \`rand-node beacon init\` here"
[ "$FCHAIN" = "$CHAIN_ID" ] || fail "$SEED is for chain $FCHAIN, the genesis is chain $CHAIN_ID's"

# 3. a chain in the file is the genesis commitment; 4. the mode
read -r HAS MODE < <(python3 - "$SEED" "$WANT" <<'PY'
import json, os, stat, sys
f = json.load(open(sys.argv[1]))
cs = [s.get("commitment", "").lower() for s in f.get("seeds", [])] # commitments only — never a seed
print("newest" if cs and cs[-1] == sys.argv[2] else ("older" if sys.argv[2] in cs else "none"), oct(stat.S_IMODE(os.stat(sys.argv[1]).st_mode)))
PY
) || fail "could not read the commitments of $SEED"
case "$HAS" in
newest) ;;
older) echo "check-beacon-seed: ⚠ the genesis commitment is an OLDER chain in $SEED, not its newest ($NEWEST) — a recommit since? the node still opens it" >&2;;
*) fail "no seed in $SEED opens this validator's genesis commitment $WANT (its newest is $NEWEST) — the commitment sent for the genesis is not this file's; this validator would miss every slot";;
esac
case "$MODE" in 0o600|0o400) ;; *) fail "$SEED is mode $MODE, not 0600 — it is secret (chmod 600 it)";; esac
OK="validator $ADDR, chain $CHAIN_ID, genesis commitment ${WANT:0:12}… opened by $SEED (offline)"

# With --rpc: what the running node holds in force for this validator, opened by the file.
if [ -n "$RPC" ]; then
OUT=$("$NODE" beacon status --datadir "$DATADIR" --rpc "$RPC" 2>&1) || fail "\`rand-node beacon status\` failed: $(printf '%s\n' "$OUT" | tail -1)"
H=$(printf '%s\n' "$OUT" | sed -n 's/^validator .* at height \([0-9][0-9]*\);.*/\1/p' | head -1)
INFORCE=$(printf '%s\n' "$OUT" | sed -n 's/^commitment in force \([0-9a-f]\{64\}\): the seed file opens it; remaining reveals: \([0-9]*\)$/\1 \2/p' | head -1)
[ -n "$INFORCE" ] || fail "\`rand-node beacon status\` exited 0 but printed no opened commitment in force: $(printf '%s\n' "$OUT" | tail -1)"
if [ "${H:-}" = 0 ] && [ "${INFORCE%% *}" != "$WANT" ]; then
fail "at height 0 the node holds ${INFORCE%% *} in force for $ADDR, not the genesis commitment $WANT — the node runs another genesis?"
fi
OK="$OK; the node at height ${H:-?} holds ${INFORCE%% *} in force, opened, ${INFORCE#* } reveals left"
fi
echo "beacon seed OK: $OK"
Loading
Loading