Repository navigation
feat(beacon): EIP-8483 and PQ forks in the state transition and fork choice - #847
Draft
MegaRedHand wants to merge 19 commits into
Draft
MegaRedHand wants to merge 19 commits into
MegaRedHand wants to merge 19 commits into
Conversation
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.
3 tasks done
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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Continues #806 on a renamed branch (
pq-forkis nowpq-devnet-0).🗒️ Description / Motivation
Implements consensus-specs'
pqbranch as two feature forks after gloas.Tracking commit:
b5d422b255db80c9bbc48f515370655ecc8bf6e5("Commit to VRF secrets instead of revealing leaves", 2026-11-19), the head ofpqat the last update. It was opened ata4d16c5b; see Update tob5d422b2. The code and docs cite this commit (docs/beacon_pq.md, the module docs ofstf::{eip8483,pq},helpers::pqandcontainers::{eip8483,pq}). The one exception is the leanXMSS known-answer test, which cites the earlieree867e91it took its vector from; the vector is unchanged since then.The two forks:
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.mdlists what remains.Based on
nightly.Update to
b5d422b2The seven
pqcommits aftera4d16c5bchange no preset, no container and no gossip rule, and the branch's base did not move, sodocs/spec_deviations.md's "newer gloas" lists still hold. What they change:2f43bc0f,70b907fd,b5d422b2; newethlambda_crypto::vrf). Hashed with Keccak-256 instead of SHA-256, and each leaf is nowcompute_vrf_leaf(secret, slot), a commitment to the slot's secretcompute_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_prooffolds the branch itself rather than throughis_valid_merkle_branch. The tree covers all2^31leaves, 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).4595f0fc). New config keysAGGREGATION_CUTOFF_BPS(4000),AGGREGATE_DUE_BPS_PQ(6000),AGGREGATOR_DELAY_BPS(500) inConfig(stillDB_VERSION8, which this PR already bumps),get_aggregation_cutoff_ms/get_aggregate_due_ms(position)in fork choice. Attester duties carryaggregator_position, the node proves each seat's committees at that seat's cutoff, the client publishes each seat at its broadcast time, andaggregate_attestationanswers 404 when a broadcast aggregate (gossip's or our own) already covers every attester (should_broadcast_aggregate).PQinTESTGEN_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 first2^20leaves) both still use the leaf = secret ruleb5d422b2replaced, so their registered roots fail ouris_valid_vrf_proofand our reveals fail theirs.tooling/pq-devnet/README.mdsays so up front; the devnet results below are froma4d16c5b.What Changed
Crypto (
ethlambda_crypto::lean_xmss,::stark)xmss_kat.jsonand by leanVM's own known answer.Types
ForkName::{Eip8483, Pq}, on-disk selectors 8 and 9, with their config keys and presets.eip8483andpqcontainers. PQ's removed fields are left as EIP-7495 progressive-container gaps.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
ShufflingKeycarry PQ's committee cap.Fork choice: PQ attestations and attester slashings, no
notify_ptc_messagesfor PQ blocks, and an XMSS-checkedon_pq_payload_attestation_message.Node crates: arms for the new variants. A PQ block that still reached BLS-only code is handled:
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:
aggregate_attestationcontainer 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)voluntary_exit,bls_to_execution_changeand the sync committee topics, and backbones its ownATTESTATION_SUBNET_COUNT_PQ(16) subnets, whichattnetsadvertises 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.MAX_*_SIZE_PQbounds. One that does not decode is ignored, as on every unfollowed fork's topic.[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 throughBidRules/PreferencesRulesover a separate PQ builder market (BuilderMarketis now generic over the signed containers), so block production never reads one.Validated::Pqwrapper, 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-socketproves, merges and verifies attestation proofs with aleanvm-sidecarprocess at leanVM283686575c, 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 ascompute_on_chain_aggregatedoes, with their proofs merged inprocess_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 blockprocess_starkrefuses 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_aggregatorandaggregator_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_attestationanswers the proved aggregate, and the client signs theAggregateAndProof.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) anddocs/spec_deviations.md(five entries), plus updates toCLAUDE.md.Correctness / Behavior Guarantees
DB_VERSIONis 8.Config's SSZ encoding gained the new fork keys,UNREGISTERED_VALIDATOR_WITHDRAWABILITY_DELAYandATTESTATION_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 onnightly. The alternative is to keep the new keys out of the persistedConfig.pqbranch sits on a consensus-specsmasternewer than this repository'sv1.7.0-beta.2. The whole diff between the two was read:upgrade_to_pqreads a builder only for a payment with a nonzero amount. The spec indexes a possibly empty registry.docs/spec_deviations.md.Tests Added / Run
Added:
process_slotscrosses gloas, EIP-8483 and PQ in order, with both boundaries at one epoch and an epoch apart.upgrade_statewalks 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.get_latest_block_slotcases.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=minimalat the pin (seedocs/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
pqmerged with lambdaclass'sadd-ethlambda; Lighthouseethdreamer/lighthouse:pqwith 48 validators, ethlambda beacon node and validator client with 16; PQ at genesis):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).Ran (on the PQ gossip commit,
c1c2f80c):make fmt,make lintmake testmake test-beacon-minimal, before the PQ gossip commit; the state-transition--libtests underpreset-minimalafter itmake test-beacon-mainnet: 7493 fixture cases, including gloas's bid, preferences and payload-attestation gossip vectors, which run the rules this commit made genericRan on the head (
e9139122):make fmt,make lintmake test: 3687 passed, 0 failedmake test-beacon-mainnet: 7493 fixture cases and the state-transition--libtests, 0 failedmake test-beacon-minimal: 50351 passed, 0 failed (it caught a mainnet-sized test, fixed ine9139122)Ran on
50d9cc7d(theb5d422b2update):make fmt,make lintmake test: 3708 passed, 0 failedvrf::tests::the_whole_tree_...,--ignored): 104 smake test-beacon-{mainnet,minimal}(no fixture exists for either new fork, and the update touches no pre-PQ rule beyond newConfigkeys), and the devnet (see above)Related Issues / PRs
heze-devnet-3(Add PQ registration requests (EIP-8483) ethereum/consensus-specs#5809). Here EIP-8483 comes after gloas, as thepqbranch orders it.✅ Verification Checklist
make fmt— cleanmake lint(clippy with-D warnings) — cleanmake test(test-consensusplustest-node, atrelease-fast) — all passing