Skip to content

feat(beacon): EIP-8483 and PQ forks in the state transition and fork choice - #847

Draft
MegaRedHand wants to merge 19 commits into
nightlyfrom
pq-devnet-0
Draft

MegaRedHand wants to merge 19 commits into
nightlyfrom
pq-devnet-0

Conversation

@MegaRedHand

@MegaRedHand MegaRedHand commented Nov 19, 2026 •

Copy link
Copy Markdown
Collaborator

Continues #806 on a renamed branch (pq-fork is now pq-devnet-0).

🗒️ Description / Motivation

Implements consensus-specs' pq branch as two feature forks after gloas.

Tracking commit: b5d422b255db80c9bbc48f515370655ecc8bf6e5 ("Commit to VRF secrets instead of revealing leaves", 2026-11-19), the head of pq at the last update. It was opened at a4d16c5b; see Update to b5d422b2. The code and docs cite this commit (docs/beacon_pq.md, the module docs of stf::{eip8483,pq}, helpers::pq and containers::{eip8483,pq}). The one exception is the leanXMSS known-answer test, which cites the earlier ee867e91 it took its vector from; the vector is unchanged since then.

The two forks:

  • EIP-8483: validators and builders register post-quantum material through two new execution-layer requests (64 bytes for a validator: an XMSS key and a VRF root; 32 bytes for a builder).
  • PQ: every validator and builder adopts the key it registered. BLS signatures become leanXMSS ones, sync committees go, RANDAO reveals become VRF proofs, attestations lose their signatures to one STARK proof per block, voluntary exits move to the execution layer, and deposits are guarded by preregistrations (EIP-8205).

Scope: the forks end to end on the node, minus EIP-8483 following. Crypto, types, the state transition, fork choice and PQ's gossip validation, and on top of them: the node follows PQ (ForkName::is_followed), builds PQ blocks with their attestations' proofs merged, and its validator client runs every PQ duty. It was run against Lighthouse's PQ branch on a local ethereum-package devnet, with validators on both sides, through finality (see Tests). EIP-8483 stays unfollowed; docs/beacon_pq.md lists what remains.

Based on nightly.

Update to b5d422b2

The seven pq commits after a4d16c5b change no preset, no container and no gossip rule, and the branch's base did not move, so docs/spec_deviations.md's "newer gloas" lists still hold. What they change:

  • The VRF tree (2f43bc0f, 70b907fd, b5d422b2; new ethlambda_crypto::vrf). Hashed with Keccak-256 instead of SHA-256, and each leaf is now compute_vrf_leaf(secret, slot), a commitment to the slot's secret compute_vrf_secret(vrf_seed, slot); the reveal is the secret, not the leaf, so the branch no longer carries the neighbouring slot's reveal. is_valid_vrf_proof folds the branch itself rather than through is_valid_merkle_branch. The tree covers all 2^31 leaves, and since every leaf commits to its index nothing can be shared: a root is ~6.4 billion Keccak calls, ~100 s of all 14 cores of an M4 Max per key. The validator client therefore registers keys and attests at once and hashes the trees on a background thread, one key at a time, storing their upper nodes (1 MiB, commitments only) in <validators-dir>/pq_vrf_trees/ so it happens once per key. A proposal before its key's tree is ready is missed. Known answers come from an independent pure-Python transcription of the spec functions; one whole tree was hashed end to end (an #[ignore]d test).
  • Staggered aggregators (4595f0fc). New config keys AGGREGATION_CUTOFF_BPS (4000), AGGREGATE_DUE_BPS_PQ (6000), AGGREGATOR_DELAY_BPS (500) in Config (still DB_VERSION 8, which this PR already bumps), get_aggregation_cutoff_ms/get_aggregate_due_ms(position) in fork choice. Attester duties carry aggregator_position, the node proves each seat's committees at that seat's cutoff, the client publishes each seat at its broadcast time, and aggregate_attestation answers 404 when a broadcast aggregate (gossip's or our own) already covers every attester (should_broadcast_aggregate).
  • Test-only upstream changes (randomized PQ block tests, PQ in TESTGEN_FORKS, fast-confirmation skips) need nothing here.

Devnet interop is broken until the other tools catch up. ethPandaOps' genesis generator (ff42fce0, full Keccak tree) and Lighthouse's PQ branch (0c76c6e1, Keccak over the first 2^20 leaves) both still use the leaf = secret rule b5d422b2 replaced, so their registered roots fail our is_valid_vrf_proof and our reveals fail theirs. tooling/pq-devnet/README.md says so up front; the devnet results below are from a4d16c5b.

What Changed

  • Crypto (ethlambda_crypto::lean_xmss, ::stark)

    • A port of leanVM's leanXMSS: Keccak-256, 32-byte keys, 2404-byte signatures. It is distinct from the leanVM XMSS that lean consensus signs with. Pinned by consensus-specs' xmss_kat.json and by leanVM's own known answer.
    • The specification's reference STARK: a proof is the signatures concatenated.
  • Types

    • ForkName::{Eip8483, Pq}, on-disk selectors 8 and 9, with their config keys and presets.
    • The eip8483 and pq containers. PQ's removed fields are left as EIP-7495 progressive-container gaps.
    • The PQ registry holds each XMSS key in the 48-byte form a request names it by. The registry accessors therefore keep handing out the shared Validator, while SSZ and merkleization go through the spec's own records.
  • GloasFamily(Mut): one borrowed view of the fields that the gloas, EIP-8483 and PQ states share. gloas_state(_ref) now return it, so the gloas rules serve all three states.

  • State transition

    • Both fork upgrades and EIP-8483's two registration requests.
    • PQ block processing: XMSS signatures at their assigned leaves, VRF RANDAO, the block-wide STARK proof, preregistrations, voluntary-exit requests, legacy deposits, and the two-slot attestation inclusion delay.
    • PQ epoch processing: the aggregation-committee window, preregistration expiry and pending deposits.
    • Committee counts and the committee cache's ShufflingKey carry PQ's committee cap.
  • Fork choice: PQ attestations and attester slashings, no notify_ptc_messages for PQ blocks, and an XMSS-checked on_pq_payload_attestation_message.

  • Node crates: arms for the new variants. A PQ block that still reached BLS-only code is handled:

    • the block precheck verifies its XMSS signature against a PQ state, and leaves the fork boundary to the import;
    • the headers endpoint answers its XMSS signature.
  • Forks built on gloas: EIP-8483 builds on gloas and PQ on EIP-8483, as every fork builds on the one before. The state transition already worked that way, but seven Beacon API checks compared a slot's or head's fork to gloas exactly, so an EIP-8483 or PQ slot or head read as pre-gloas:

    • the attestation pool's header-to-slot match: a vote at such a slot under fulu's header was judged by electra's rules, and is now refused;
    • the payload flag of a submitted vote and of produced attestation data, the head's payload status, the PTC duties' head read, the aggregate_attestation container and a state's builders.

    Checks on which container a version header names stay exact.

  • PQ gossip (specs/_features/pq/p2p-interface.md; gossip::pq, ethlambda_p2p::beacon::pq)

    • Topics: a PQ digest holds gloas's set without voluntary_exit, bls_to_execution_change and the sync committee topics, and backbones its own ATTESTATION_SUBNET_COUNT_PQ (16) subnets, which attnets advertises while the digest is current. A validator client's aggregator and sync committee subnets (BLS duties) are never joined under one. Peer scoring parametrizes a PQ digest for its own topics.
    • Decode: every reshaped topic decodes by its digest into PQ's container, under the MAX_*_SIZE_PQ bounds. One that does not decode is ignored, as on every unfollowed fork's topic.
    • Rules: gloas's, with only the [Modified in PQ] and [New in PQ] lines applied. Aggregates check the aggregator's XMSS signature, aggregation-committee membership and the STARK proof; attestations the XMSS signature at the target epoch's leaf and one of 16 subnets; slashings, payload attestations and envelopes their XMSS signatures and proofs. Bids and preferences run gloas's own rules through BidRules/PreferencesRules over a separate PQ builder market (BuilderMarket is now generic over the signed containers), so block production never reads one.
    • A stateful rule whose state is not PQ ignores the message, which on a live node is every one. A vote block's state is advanced by at most two epochs, so a peer cannot make the node replay a stale head's whole gap.
    • One Validated::Pq wrapper, so the shared types the chain actor, pools and event stream read carry no PQ shape.
  • Proofs through leanVM (ethlambda_crypto::stark::sidecar): --pq-prover-socket proves, merges and verifies attestation proofs with a leanvm-sidecar process at leanVM 283686575c, the revision Lighthouse's PQ branch pins, mapping statements to claims as Lighthouse does. The reference encoding stays the default and what the fixtures use; the two do not verify each other's proofs.

  • Following PQ: the chain actor imports PQ blocks and envelopes from gossip and req/resp, applies accepted PQ aggregates (held a slot, as gloas's) and payload attestations to fork choice, and asks the engine about PQ payloads. Envelopes of every gloas-family fork travel as one fork-tagged containers::SignedExecutionPayloadEnvelope (storage decodes one by its slot's fork, req/resp by the chunk's context bytes, the engine gets each fork's typed requests list). A gloas-family genesis anchor accepts both bodies a generator may build (the spec helper's carries the state's bid).

  • Block production (pq_block_production, POST /eth/v1/validator/pq_blocks/{slot}): gloas's self-build in PQ's shapes, given the proposer's VRF proof. Attestations come from a pool of validated aggregates (Store::pq_aggregate_pool), chosen greedily by uncredited participation weight and shaped as compute_on_chain_aggregate does, with their proofs merged in process_stark's order on the sidecar while the payload builds, bounded by three quarters of the attestation deadline (Lighthouse's bound). A merge that misses it packs the most valuable single-committee attestation, whose proof needs no merge; a block process_stark refuses is rebuilt empty. No blobs yet.

  • Validator client: each validator's leanXMSS key and VRF seed are derived from its BLS signing key (ethlambda_crypto::pq_keys), as ethereum-package's generator and Lighthouse derive them; the VRF tree grows from the seed as the specification defines it (ethlambda_crypto::vrf). Attestations, PTC votes, proposals with their envelopes, and aggregates are signed at their leaves, with an in-memory guard against signing two roots at one leaf (slashing protection still covers attestations and proposals across restarts).

  • Aggregation: attester duties carry is_aggregator and aggregator_position (the aggregation-committee seat), and aggregators are staggered by seat. The node joins the committee's subnet under PQ digests, keeps the signatures of validated votes for registered committees (Store::pq_signature_pool), and proves each committee ahead on the sidecar, as Lighthouse does; aggregate_attestation answers the proved aggregate, and the client signs the AggregateAndProof.

  • Devnet tooling (tooling/pq-devnet/): the image (ethlambda plus the sidecar), the ethereum-package launcher patch, and params for a following-only node and for one with 16 of 64 validators.

  • Docs: docs/beacon_pq.md (new) and docs/spec_deviations.md (five entries), plus updates to CLAUDE.md.

Correctness / Behavior Guarantees

  • DB_VERSION is 8. Config's SSZ encoding gained the new fork keys, UNREGISTERED_VALIDATOR_WITHDRAWABILITY_DELAY and ATTESTATION_SUBNET_COUNT_PQ (checked against a compiled constant), so a version 7 directory is refused and needs a checkpoint resync. This needs a decision before anything lands on nightly. The alternative is to keep the new keys out of the persisted Config.
  • The pin is newer than the repo's. The pq branch sits on a consensus-specs master newer than this repository's v1.7.0-beta.2. The whole diff between the two was read:
    • Three newer gloas state-transition rules apply from EIP-8483 on.
    • Four newer fork-choice rules (unslashed committee fraction, rounded slot components, the node-tree viability filter, millisecond ticks) apply to no fork yet, because moving them changes every fork.
    • Gloas keeps its pinned rules.
  • Two other deliberate departures:
    • upgrade_to_pq reads a builder only for a payment with a nonzero amount. The spec indexes a possibly empty registry.
    • The spec-test binary turns XMSS verification off, as the spec's own generator does.
    • PQ gossip keeps gloas's own departures (the vote block's state rather than the head's, the signature before committees) and ignores where it cannot judge; see docs/spec_deviations.md.
  • Existing forks are unaffected: every pre-existing beacon fixture still passes on both presets.

Tests Added / Run

  • Added:

    • leanXMSS known-answer tests.
    • PQ STF tests that sign with real keys: block signature leaf, STARK proof order, VRF RANDAO, bids, preregistrations, exits, the aggregation-committee window, the inclusion delay.
    • Fork-upgrade tests, and precheck tests for PQ blocks.
    • process_slots crosses gloas, EIP-8483 and PQ in order, with both boundaries at one epoch and an epoch apart. upgrade_state walks every fork end to end to PQ, and each upgrade refuses any state but its predecessor's. The per-fork STF tests cover every beacon fork.
    • A vote at an EIP-8483 or PQ slot is refused under fulu's or gloas's header.
    • PQ gossip, signing with real leanXMSS keys: every signature rule accepts its own leaf and refuses the next (attestation, aggregate, proposer slashing, payload attestation, preferences, bid); the aggregate's STARK proof and aggregation committee; an attester slashing's proofs; the subnet; an envelope against its PQ block; a far-behind vote state is ignored unadvanced; a PQ bid is accepted against a PQ head. In p2p: decoding by digest and the size bounds, the PQ topic set and backbone, the rollover joining a PQ digest without duty subnets, PQ scoring, and triage.
    • get_latest_block_slot cases.
    • The largest aggregate, attester slashing and bid encode to pq.yaml's type-specific SSZ bounds.
  • Not run: no spec fixture exists for either fork yet. The runners route both forks' cases but have never seen one. Generating them takes make test reftests=true fork={eip8483,pq} preset=minimal at the pin (see docs/beacon_pq.md), and fixes are expected once they run. The new fork-choice paths have no tests of their own.

  • Devnet (ethpandaops ethereum-package pq merged with lambdaclass's add-ethlambda; Lighthouse ethdreamer/lighthouse:pq with 48 validators, ethlambda beacon node and validator client with 16; PQ at genesis):

    • Every Lighthouse message ethlambda received was accepted, and Lighthouse rejected nothing ethlambda sent: blocks, envelopes, attestations, PTC votes, aggregates and proposer preferences.
    • The last run: ethlambda published 118 blocks and envelopes (113 carrying attestations), 191 attestation batches, 187 PTC vote batches and 190 aggregates it proved itself. Both nodes finalized every epoch through epoch 18 on the same roots.
    • Earlier runs found and fixed a subnet bug (4ccb69ea: PQ attestations at slot 16 and later of an epoch were judged against 64 subnets) and a missing committee subscription at PQ slots (0020f033).
    • Measured there: a two-child merge takes the sidecar 2.6 to 4 s on Docker Desktop's VM, for Lighthouse too, past the ~2.25 s bound, hence the single-attestation fallback; proving one committee's aggregate takes 0.2 to 1 s.
  • Ran (on the PQ gossip commit, c1c2f80c):

    • make fmt, make lint
    • both halves of make test
    • make test-beacon-minimal, before the PQ gossip commit; the state-transition --lib tests under preset-minimal after it
    • make test-beacon-mainnet: 7493 fixture cases, including gloas's bid, preferences and payload-attestation gossip vectors, which run the rules this commit made generic
  • Ran on the head (e9139122):

    • make fmt, make lint
    • both halves of make test: 3687 passed, 0 failed
    • make test-beacon-mainnet: 7493 fixture cases and the state-transition --lib tests, 0 failed
    • make test-beacon-minimal: 50351 passed, 0 failed (it caught a mainnet-sized test, fixed in e9139122)
  • Ran on 50d9cc7d (the b5d422b2 update):

    • make fmt, make lint
    • both halves of make test: 3708 passed, 0 failed
    • the whole-tree VRF test (vrf::tests::the_whole_tree_..., --ignored): 104 s
    • not rerun: make test-beacon-{mainnet,minimal} (no fixture exists for either new fork, and the update touches no pre-PQ rule beyond new Config keys), and the devnet (see above)

Related Issues / PRs

✅ Verification Checklist

  • Ran make fmt — clean
  • Ran make lint (clippy with -D warnings) — clean
  • Ran make test (test-consensus plus test-node, at release-fast) — all passing

Port leanVM's Rust leanXMSS (Keccak-256, two layers of height-16 trees
over WOTS+C, 32-byte keys, 2404-byte signatures) from 4af2cddd, the
commit EthLib's README cites as the note's source, as
ethlambda_crypto::lean_xmss: the consensus-specs pq feature's xmss.Sign,
xmss.Verify and xmss.GetLeafIndex. Also the stark module, the pq
feature's reference concatenation for ProveAggregates, MergeProofs and
VerifyAggregates.

Pinned by consensus-specs' xmss_kat.json (verification, its four
negative cases, and signing from the seed byte for byte) and leanVM's
own known answer.
…choice

Implement consensus-specs' `pq` branch (pinned at a4d16c5b) as two
feature forks after gloas: EIP-8483, where validators and builders
register post-quantum material through two new execution-layer requests,
and PQ, which adopts that material and replaces BLS with leanXMSS.

- Types: ForkName::{Eip8483, Pq} (selectors 8 and 9), their config keys
  and presets, and the eip8483 and pq containers, with PQ's removed
  fields left as progressive-container gaps. The PQ registry holds each
  XMSS key in its 48-byte request form, so the registry accessors keep
  handing out the shared Validator; its SSZ and merkleization go through
  the specification's own records. The maximal aggregate, attester
  slashing and bid encode to pq.yaml's type-specific SSZ bounds.
- GloasFamily(Mut): one borrowed view of the fields gloas, EIP-8483 and
  PQ states share, which gloas_state(_ref) now return, so the gloas rules
  serve all three.
- State transition: both fork upgrades, EIP-8483's registration requests,
  and PQ's block and epoch processing (XMSS signatures at their leaves,
  VRF RANDAO, the block-wide STARK proof, preregistrations, voluntary exit
  requests, legacy deposits, aggregation committees, the two-slot
  attestation inclusion delay). Committee counts and the shuffling key
  carry PQ's cap.
- Fork choice: PQ attestations and slashings, no notify_ptc_messages for
  PQ blocks, and an XMSS-checked on_pq_payload_attestation_message.
- The pq branch sits on a consensus-specs master newer than this
  repository's pin. Its three newer gloas state-transition rules apply
  from EIP-8483 on; its four newer fork-choice rules (unslashed committee
  fraction, rounded slot components, the node-tree viability filter,
  millisecond ticks) apply to no fork yet (docs/spec_deviations.md).
- The node follows neither fork (is_followed is false); gossip, req/resp,
  the Beacon API and the validator client refuse both. Where a PQ block
  could still reach BLS-only code, it is handled: the block precheck
  checks its XMSS signature against a PQ state and leaves the fork
  boundary to the import, and the headers endpoint answers its XMSS
  signature.
- The spec-test runners route both forks' cases, with XMSS verification
  off as the specification's generator has it; no release ships the
  fixtures yet (docs/beacon_pq.md says how to generate them).

DB_VERSION is 8: Config's SSZ encoding gained the new keys.
…he STF

EIP-8483 builds on gloas and PQ on EIP-8483. The state transition and
fork choice already ran that way (the derived Ord, `next()` in the upgrade
loop, the gloas-family arms), but seven Beacon API checks compared a
slot's or head's fork to gloas exactly, so an EIP-8483 or PQ slot or head
read as pre-gloas:

- POST /eth/v2/beacon/pool/attestations accepted a vote at such a slot
  under electra's or fulu's header and judged it by electra's rules. A
  slot from gloas on now needs its own fork's header, and since
  submission_fork refuses EIP-8483's and PQ's, the vote is refused.
- The payload flag of a submitted vote and of produced attestation data,
  the head's payload status, the PTC duties' read of the head state, the
  aggregate_attestation container and a state's builders now hold from
  gloas on.

Checks on which container a version header names stay exact. EIP-8483's
attestations, aggregates, attester slashings and bids are gloas's own
(gossip already decodes the first three as such), but the Beacon API
refuses the `eip8483` header because the node does not follow the fork.
Gossip's bid rules still judge only gloas states: they read the parent's
envelope, whose shape EIP-8483 changes.

Tests: process_slots crosses gloas, EIP-8483 and PQ with both boundaries
at one epoch and an epoch apart; upgrade_state walks to PQ end to end;
each upgrade takes only its predecessor's state; the per-fork STF tests
cover every beacon fork; a vote at an EIP-8483 or PQ slot is refused under
fulu's or gloas's header. The ForkName docs and docs/beacon_pq.md state
the chain, and two comments that said the node never joins an unfollowed
fork's digest are corrected: the rollover joins it.
Implement `specs/_features/pq/p2p-interface.md` (consensus-specs' `pq`
branch at a4d16c5b) for a PQ fork digest's topics. The node still does not
follow PQ: every reshaped topic is decoded, judged and relayed, and nothing
past gossip consumes what it accepts.

- Topics: a PQ digest holds `PQ_TOPIC_KINDS`, gloas's set without
  `voluntary_exit`, `bls_to_execution_change` and the sync committee
  topics, and backbones its own `ATTESTATION_SUBNET_COUNT_PQ` (16)
  subnets (`compute_subscribed_subnets_pq`), which `attnets` advertises
  while the current digest is PQ's. A validator client's aggregator and
  sync committee subnets, both from BLS duties, are never joined under a
  PQ digest. Peer scoring parametrizes a PQ digest for its own topics.
  `ATTESTATION_SUBNET_COUNT_PQ` is a `Config` key checked against the
  compiled constant.
- Decode: every topic PQ reshapes decodes by the topic's digest into PQ's
  container (`decode_pq_gossip`), with the `MAX_*_SIZE_PQ` bounds; one
  that does not decode is ignored, as on every unfollowed fork's topic.
- Rules (`gossip::pq`): gloas's with only the `[Modified in PQ]` and
  `[New in PQ]` lines applied. Aggregates: the aggregator's XMSS signature
  at its aggregate leaf, membership of the aggregation committee, and the
  STARK proof of the attesters' signatures. Attestations: the XMSS
  signature at the target epoch's leaf, one of 16 subnets. Proposer and
  attester slashings, payload attestation messages and envelopes: their
  XMSS signatures and proofs. Bids and preferences run gloas's own rules
  through new `BidRules`/`PreferencesRules` traits over a PQ builder
  market of their own (`BuilderMarket` is generic over the signed
  containers), so block production never reads one; the bid rule's head
  view now reads any gloas-family head. The PQ block's operation and
  request limits sit behind the existing `is_followed` gate. A stateful
  rule whose state is not a PQ one ignores the message, and a vote
  block's (or a preference's dependent block's) state is advanced by at
  most two epochs, so a peer cannot make the node replay a stale head's
  whole gap.
- p2p: one `Validated::Pq` wrapper with its own enum, so the shared
  variants the chain actor, pools and event stream read carry no PQ
  shape. Its seen records go to the caches the other forks share.

Tests sign with real leanXMSS keys: every signature rule accepts its own
leaf and refuses the next one, and the aggregate's STARK proof, the
aggregation committee and the subnet are checked. Docs: beacon_pq.md,
spec_deviations.md, CLAUDE.md.
The PQ devnet's clients (Lighthouse's pq branch) prove attestation
aggregates with leanVM through a leanvm-sidecar process, not with the
specification's reference concatenation, so a node on the reference
backend verifies none of their blocks. ethlambda_crypto::stark now
dispatches prove_aggregates, merge_proofs and verify_aggregates to one of
two backends chosen once per process: the reference (default, what the
spec fixtures use) or the sidecar (install_sidecar).

The sidecar backend is leanVM's own client crate at 283686575c, the
revision Lighthouse and its leanvm-sidecar binary pin, and maps statements
to claims as Lighthouse does: sorted, deduplicated (pubkey, message)
pairs, the empty proof for no claims, merges folded 16 children at a time.
leanVM proofs do not attest leaf indices, so verification under the
sidecar checks that each key signed the message at some leaf.

merge_proofs now takes each child's statements, which the sidecar needs.

Also pins validator 0 of ethereum-package's default mnemonic: its leanXMSS
key from sha256("leanxmss-seed" || sk) is the one the PQ genesis tooling
precomputes.
The node now follows a chain past gloas into EIP-8483 and PQ
(ForkName::is_followed is true for both), and was checked against a
Lighthouse PQ devnet: ethpandaops' ethereum-package `pq` branch, PQ at
genesis, ethdreamer/lighthouse:pq proposing.

- Envelopes: a fork-tagged SignedExecutionPayloadEnvelope (gloas,
  EIP-8483, PQ) replaces the gloas-only type in gossip, req/resp (decoded
  by the chunk's context bytes), storage (decoded by the fork of its slot),
  the chain actor's envelope pipeline, fork choice and the Beacon API.
  verify_execution_payload_envelope checks each fork's signature (PQ's
  with leanXMSS) and its own requests root; engine_newPayload gets each
  fork's typed requests list, and the payload hash check covers them too.
- Gossip consumers: an accepted PQ aggregate hands its vote and the
  attesting indices validation resolved to the chain actor, which applies
  them to fork choice a slot later as for every fork; PQ payload
  attestation messages and envelopes reach the actor as gloas's do. Block
  gossip runs the bid and parent-payload rules on every gloas-family
  block.
- Genesis: from gloas on the genesis block's body carries the state's
  latest_execution_payload_bid, as the specification's genesis helper
  and ethpandaops' generator build it, so a gloas-family genesis anchors.
- --pq-prover-socket installs the leanVM sidecar backend at startup, and
  bin/ethlambda/pq/ethlambda-pq starts a leanvm-sidecar before the node,
  as Lighthouse's lighthouse-pq-bn does.
- The anchor's envelope fetch decodes by the anchor block's fork.
…odies

EIP-8483 goes back to unfollowed: its block's cheap gossip rules, its
envelope topic's decode and rules, and its fetched envelopes' checks still
take gloas's shapes, and nothing schedules it (the PQ devnet starts on PQ).

A gloas-family genesis anchor now tries the empty body when the bid form
does not match the state's header, for a generator built against an older
gloas release.
- docs/beacon_pq.md, CLAUDE.md: the node follows PQ (blocks, envelopes,
  aggregates and payload attestations), and EIP-8483 not yet; the two proof
  backends and how the sidecar maps statements to leanVM claims.
- docs/spec_deviations.md: leanVM proofs attest no leaf index, and the
  gloas-family genesis body carries the state's bid.
- docs/cli.md: --pq-prover-socket.
- tooling/pq-devnet: a Dockerfile that adds leanvm-sidecar (built from the
  pinned leanVM revision) and ethlambda-pq to the image, the ethereum-package
  launcher patch and network params for a PQ-at-genesis devnet with
  Lighthouse, and a README with what to check and the known limits
  (Lighthouse serves no PQ envelopes over req/resp; sidecar memory).
- ethlambda_crypto::pq_keys derives a validator's leanXMSS key and VRF
  tree the way ethPandaOps' PQ genesis tooling and Lighthouse do:
  sha256("leanxmss-seed" || sk) and sha256("vrf-seed" || sk). The VRF tree
  keeps the roots of its 2^10-leaf subtrees and rebuilds one per proof.
  Pinned by ethereum-package's precomputed root for validator 0 of its
  default mnemonic and Lighthouse's known answer.
- A leanXMSS key keeps its two most recently used bottom trees built: a PQ
  validator signs attestations in one and its per-slot messages in
  another, and rebuilding one costs about a second and a half.
The validator client and the beacon node's validator API on the PQ fork,
with leanXMSS keys derived from each keystore's BLS key
(ethlambda_crypto::pq_keys).

Validator client (`crate::pq`):
- With PQ scheduled, every validator's leanXMSS key and VRF tree are
  derived at startup, before any duty, and the two bottom trees its next
  attestation and per-slot signatures fall in are built.
- The PQ registry names a validator by its XMSS key's 48-byte request form;
  parse_pubkey maps one of this client's back to the BLS key that owns it,
  and index lookup asks for both forms, so duties still match local keys.
- Attestations are signed at the target epoch's leaf, payload attestations
  at the slot's PTC leaf, a block at its proposer leaf with its VRF proof as
  RANDAO reveal, and its self-built envelope at the envelope leaf.
  Slashing protection guards blocks and attestations; the other per-slot
  leaves are guarded in memory (one signing root per leaf).
- Aggregation, proposer preferences, sync committees and committee
  subscriptions are not run at PQ yet.

Beacon node:
- POST /eth/v1/validator/pq_blocks/{slot}: the proposer's VRF proof in, a
  self-built PQ block and its envelope out (SSZ pq::BlockContents), from
  pq_block_production (PQ's requests list, the empty self-build bid
  signature, no attestations yet).
- Block publish, envelope publish, the attestation pool and the payload
  attestation pool take PQ's containers under the `pq` header and judge
  them with PQ's rules; proposer duties read a PQ head's lookahead, and
  payload attestation data answers for a PQ block.
- RpcToP2P::publish_pq_gossip gossips a validator client's PQ attestation,
  aggregate or payload attestation on its PQ topic and hands fork choice
  its part.
The pool endpoint judged a submitted PQ attestation against the subnet electra's formula gives, modulo ATTESTATION_SUBNET_COUNT (64), while PQ gossip expects ATTESTATION_SUBNET_COUNT_PQ (16). The two agree only below slot 16 of an epoch, so from there on the node refused its own validator client's votes as Reject(WrongSubnet). Committee subscriptions for a PQ slot used the same formula and joined the wrong subnet.
Accepted PQ network aggregates are held in a new PqAggregatePool on Store, the one per (AttestationData, committee) covering the most attesters, with the attesting indices gossip validated it with. PQ block production selects from it what process_attestation accepts at the slot and whose committee still names those attesters, greedily by uncredited participation weight, up to MAX_ATTESTATIONS_PQ, as compute_on_chain_aggregate shapes them. The proofs are merged in process_stark's order on the proving sidecar, concurrently with the payload build and bounded by three quarters of the attestation deadline, one merge at a time. A merge that misses the deadline or fails, or a block process_stark refuses, falls back to a block without attestations.
Merging two or more aggregate proofs takes the proving sidecar seconds (about 4 s for two children on the devnet VM, for Lighthouse too), more than the three quarters of the attestation deadline a proposal can spend. Instead of dropping every attestation when the merge misses its budget or fails, pack the most valuable single-committee attestation alone: its aggregate's proof is the block's proof as it is. A single child skips the merge altogether, and every merge logs what it took when it ends.
A PQ aggregator is a member of its committee's aggregation committee and proves its committee's signatures with a STARK instead of aggregating them. Proving takes the sidecar seconds, so the node proves ahead, as Lighthouse's PQ branch does:

- Attester duties at a PQ slot carry is_aggregator (the aggregation-committee seat), which the validator client subscribes with instead of a BLS selection proof.
- beacon_committee_subscriptions for a PQ slot join the committee's subnet among PQ's 16 under PQ digests (new aggregator_subnets_pq bookkeeping in p2p, carried across digest switches and left on expiry), and register the committee with a new PqSignaturePool on Store.
- Validated single attestations for registered committees, the validator client's own and gossip's, leave their signatures in that pool. Once a slot a task seals them halfway between the attestation and aggregate deadlines and proves each committee before the aggregate deadline, largest first.
- GET aggregate_attestation at a PQ slot answers the proved aggregate and its proof (pq::ProvenAggregate, Lighthouse's PqAggregate shape), waiting briefly for a proof in progress. POST aggregate_and_proofs takes PQ aggregates, judges them by PQ's gossip rules and gossips them.
- The validator client signs each AggregateAndProof with leanXMSS at the slot's aggregate leaf.
- A node's own published aggregate, and each one it proves, go into the pool block production packs from.
They were skipped from the PQ fork on because they carried BLS selection proofs. A PQ duty's aggregator role now comes from the node's is_aggregator, and without the subscription the node never collects the committee's signatures, so every PQ aggregation found nothing to publish.
beacon_pq.md, CLAUDE.md and the PQ devnet README still said the node neither produced PQ blocks nor ran PQ duties. Describe the key derivation, each duty's leaf, attestation packing with its merge deadline and single-attestation fallback, and the aggregation flow; list the PQ endpoints in rpc.md; add network_params_validators.yaml, which gives ethlambda 16 of the 64 validators.
They built 8192 validators, two committees per slot only under the mainnet preset; the minimal preset makes four, and the committee-order test failed there. Size the registry as 2 * SLOTS_PER_EPOCH * TARGET_COMMITTEE_SIZE instead.
MegaRedHand and others added 2 commits November 19, 2026 18:25
Move the PQ fork from a4d16c5b to b5d422b2, the head of consensus-specs'
pq branch. The seven commits in between change no preset, container or
gossip rule, and the branch's base did not move.

- VRF tree (2f43bc0f, 70b907fd, b5d422b2): hashed with Keccak-256, and
  each leaf is compute_vrf_leaf(secret, slot), a commitment to the slot's
  secret compute_vrf_secret(vrf_seed, slot). The reveal is the secret, so
  a branch no longer carries the neighbouring slot's reveal.
  is_valid_vrf_proof folds the branch itself. New ethlambda_crypto::vrf,
  pinned by known answers from an independent transcription of the spec.
- The tree covers all 2^31 leaves and no subtree repeats, so a root takes
  about 100 s of 14 cores. The validator client attests at once and hashes
  each key's tree on a background thread, storing its upper nodes under
  <validators-dir>/pq_vrf_trees/ so it happens once per key; a proposal
  before its key's tree is ready is missed.
- Staggered aggregators (4595f0fc): AGGREGATION_CUTOFF_BPS,
  AGGREGATE_DUE_BPS_PQ and AGGREGATOR_DELAY_BPS in Config,
  get_aggregation_cutoff_ms and get_aggregate_due_ms(position). Attester
  duties carry aggregator_position; the node proves each seat's
  committees at its cutoff, the client publishes each seat at its time,
  and aggregate_attestation answers 404 when a broadcast aggregate
  already covers every attester (should_broadcast_aggregate).

Neither ethPandaOps' genesis generator nor Lighthouse's PQ branch uses
b5d422b2's VRF leaves yet, so the PQ devnet cannot run until they do;
tooling/pq-devnet/README.md says so.

This branch has not been deployed

No deployments
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.

2 participants