Repository navigation
feat(pq): EIP-8483 and PQ forks end to end for pq-devnet-0: STF, gossip, following, block production and validator duties - #847
Draft
MegaRedHand wants to merge 45 commits into
Draft
MegaRedHand wants to merge 45 commits into
MegaRedHand wants to merge 45 commits into
Conversation
3 tasks done
MegaRedHand
force-pushed
the
pq-devnet-0
branch
from
November 21, 2026 06:56
5af434e to
6661107
Compare
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.
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.
No published genesis tooling registers VRF roots under b5d422b2's leaf rule yet, so a network on this pin needs its own, and every root costs the whole 2^31-leaf tree. - ethlambda pq-keys writes a mnemonic's leanXMSS keys and VRF roots in the two formats ethPandaOps' tooling reads: <name>.bin (64 bytes per index, for eth-beacon-genesis' --xmss-pubkey-url/--xmss-pubkey-cache) and <name>.vrf (ethereum-package's vrf_state_url records: the root, four zero bytes, leaf 0's branch). Resumable, one validator at a time. Signing keys come from EIP-2333 at m/12381/3600/i/0/0 of the BIP-39 seed; validator 0 of the default mnemonic matches the package's published key and file name. - VrfTree restores from a compact state (root plus leaf 0's branch), checked by folding the seed's own leaf 0 to the root; a proof for a slot below 2^k hashes only the first 2^k leaves. The byte form keeps either shape. - The validator client takes --vrf-state-url (URL or path): a key with no stored tree loads its record by validator index, falls back to hashing on a missing or foreign record, and stores what it loaded. - The tree's hashes call keccak-f[1600] on one padded block instead of a streaming hasher: about 20% faster, same known answers.
PQ keeps gloas's data column sidecar and the bid's commitments, so a PQ
block may carry blobs like a gloas one:
- POST /eth/v1/validator/pq_blocks/{slot} checks the execution client's
blobs bundle as gloas's self-build does and keeps the blobs and cell
proofs by (slot, block root) instead of refusing the payload.
- publishExecutionPayloadEnvelope under the pq header builds the data
columns from those kept blobs, checks them against the bid's
commitments and gossips them with the envelope, as gloas's
Eth-Blob-Data-Included: false path does.
- Gossip judges a column of a PQ block against that block's bid rather
than ignoring it. EIP-8483 stays unfollowed.
The PQ fork keeps gloas's proposer_preferences topic with a leanXMSS signature at the proposal slot's LEAF_OFFSET_PROPOSER_PREFERENCES leaf, and that leaf takes one message: a proposer must not sign preferences for one slot under two dependent roots. - Validator client: at a PQ epoch the preferences service signs each owed preference once, with leanXMSS over gloas's signing root, and sends it as signed to every node until all hold it, then once a round. The leaf guard refuses a second dependent root, so a reorg leaves the slot without preferences rather than with two. New BeaconNodeApi::submit_pq_proposer_preferences. - Beacon node: POST /eth/v1/validator/proposer_preferences takes the pq header and PQ's container, judged by the same rules over the PQ builder market, which main now creates and shares with p2p (as the gloas one), and gossips them through PqGossipObject::ProposerPreferences.
Signing two messages at one leanXMSS leaf exposes the key at that leaf. Slashing protection already covers blocks and attestations, but the other per-slot leaves (payload attestations, aggregates, proposer preferences, envelopes) were guarded in memory only, so a client restarted within a slot could sign a second message at one of them. The record now lives in <validators-dir>/pq_signed_leaves.bin: a leaf's first claim is appended and flushed before its signature exists, a restart reloads it before any duty signs, and leaves of slots two epochs past are dropped as it is rewritten. A torn trailing record is dropped: it was never flushed, so nothing was signed at its leaf.
…es, blobs, preferences docs/beacon_pq.md linked three times to tooling/pq-devnet/README.md, outside the mdbook root, which failed the docs build. It also still said the node imports no PQ block and that no pool takes PQ messages, and pool.rs and block_contents.rs carried the same leftovers. The validator duties section now covers the VRF tree's sources (stored, --vrf-state-url, hashed), blobs and proposer preferences, and What remains drops what this branch now does.
The genesis's VRF roots and the validator clients' tree states come from ethlambda pq-keys, served from the host, since the published files follow the VRF rule b5d422b2 replaced. Records what the first run showed: gloas's compute_ptc needs an attester every slot, so the mainnet preset needs at least 32 validators, and the first slots after genesis are missed while the clients derive their keys.
build_payload, which gloas's and PQ's self-builds share, called
getPayload right after the forkchoiceUpdated that starts the build. Geth
then delivers the empty payload it starts from before its first build
with transactions completes: on a PQ devnet every ethlambda block carried
no transactions and no blobs while two funding transactions sat pending
in both mempools for nine minutes ("Starting work on payload" and
"Stopping work on payload reason=delivery" a millisecond apart, no
"Updated payload" between). Wait PAYLOAD_BUILD_WINDOW (500 ms) between
the two; it overlaps PQ's attestation packing. Preparing the payload
ahead of the slot would remove the wait, and is left for later.
leanXMSS signing parallelizes on rayon's global pool, and so did the VRF tree hashing `prepare_vrf_trees` falls back to for a key with no stored tree and no precomputed state. Rayon runs a job injected from outside a pool only once a worker's own queue is empty, and the tree's par_iter keeps every queue full until it is done: while a tree hashed (minutes per key), no attestation, aggregate or PTC vote was signed. Hash in a dedicated pool, one thread short of the cores, so the global pool's workers stay free for the signatures.
…sed aggregate The PQ block, envelope and aggregate paths logged each publish but never counted it, so blocks_proposed, envelopes_published and aggregates_published stayed at zero on a PQ chain. They now count as gloas's do, with envelope_failures for an envelope that was not signed or not published, and the signing histogram gains buckets in seconds, where a leanXMSS batch lands. An aggregator at a later seat whose committee an earlier aggregate already covers is answered 404 by the node, which is the specification's "publish nothing". The fallback reported that as every node failing, duty likely missed: every slot with a two-member committee warned once. When every node answers 404 the fallback now returns that 404, and the aggregation service logs it at info with the node's reason; any other failure among them still warns, since that node may have held the votes.
docs/beacon_pq.md still called the leaf record in-memory, and CLAUDE.md still said PQ blocks carry no blobs; both changed earlier on this branch. Also say where the VRF trees are hashed and why, and mention --vrf-state-url and the ethlambda-only devnet.
…l VRF patch Lighthouse's pq-devnet-0 image, ethPandaOps' genesis generator and ethereum-package's published VRF states follow consensus-specs pq at 4595f0fc, whose VRF leaf is keccak256(vrf_seed || le64(slot)), revealed as it is. This branch tracks b5d422b2, so a devnet with them needs ethlambda built with tooling/pq-devnet/vrf-4595f0fc.patch, which this branch does not carry. The params now name ethpandaops/lighthouse:pq-devnet-0, give ethlambda's validator client the package's published VRF states through --vrf-state-url (served from the host) and wait 300 s for genesis while the validator clients derive their keys. The package recipe moves to ethpandaops pq 87788250, and the ethlambda-only recipe says it builds without the VRF patch.
The patch switching ethlambda to the older VRF leaf was for a local check only: Lighthouse is to adopt b5d422b2's VRF function, so the branch does not carry it. The README again calls the Lighthouse devnets not runnable at this pin until it does, and says which two functions a local check against the older rule changes.
…, claims and lean_xmss pq-devnet-0 moves its signer, prover, verifier and sidecar to leanVM's bindings v0.15.0 release, all clients at once: proofs from the old pin (283686575c) do not verify under the new one. The client crates' API is unchanged; the Dockerfile's sidecar, the pinned LEANVM_REV the client reports and the docs move with them. leanVM's lean_xmss there signs the same bytes and adds cache_to_bytes/from_cache_bytes for its trees.
… leaves revealed pq-devnet-0 runs consensus-specs pq at 2f43bc0f. b5d422b2, two commits later, made each VRF leaf commit to a per-slot secret and revealed the secret; at 2f43bc0f the leaf is keccak256(vrf_seed || le64(slot)) and is revealed itself, which is what ethPandaOps' genesis tooling, its published VRF states and Lighthouse's pq-devnet-0 image use. Back to it: compute_vrf_leaf takes the seed, a proof starts with the leaf, and the fold starts from proof[0]. The Keccak-256 tree over all 2^31 leaves (2f43bc0f itself) stays, and so do the compact states and their loader. The known answers are now ethereum-package's published state for validator 0 of its default mnemonic, from eth-beacon-genesis. At this rule a proof also opens slot + 2^31, as the specification has it, so the test saying otherwise goes. The spec pin moves in the module docs, CLAUDE.md and docs; the PQ devnet README and params use the published keys and states again. The b5d422b2 work stays on pq-devnet-0-b5d422b2. The staggered aggregators of 4595f0fc are reverted separately.
…f has them pq-devnet-0's spec, 2f43bc0f, predates 4595f0fc, which staggered the aggregators of a committee by their seat in its aggregation committee and had a later one skip an aggregate an earlier one already covered. At 2f43bc0f every aggregator broadcasts at gloas's aggregate deadline (AGGREGATE_DUE_BPS_GLOAS). Back to that, as before the branch moved to b5d422b2: - Config loses AGGREGATION_CUTOFF_BPS, AGGREGATE_DUE_BPS_PQ and AGGREGATOR_DELAY_BPS, and fork choice get_aggregation_cutoff_ms and get_aggregate_due_ms(position). Its SSZ layout changes, so DB_VERSION is 9. - The node seals a slot's collected signatures halfway between the attestation and aggregate deadlines and proves every registered committee before the aggregate deadline, instead of per seat; attester duties lose aggregator_position, and aggregate_attestation no longer answers 404 for a covered aggregate (should_broadcast_aggregate). - The validator client publishes all its PQ aggregates at the aggregate deadline. A 404 now means the node proved nothing for the committee, so it is a warning again; the fallback still returns that 404 rather than calling it every node failing. Also the VRF proof's doc in PQ block production, missed by the VRF revert. The staggered aggregators stay on pq-devnet-0-b5d422b2.
…s v0.15.0) lean_xmss::verify, which the state transition and the reference proof check call, now goes through leanVM's own verifier at the pinned release, keeping the leaf-index check. The port stays for test keys (range_key) and is pinned against leanVM by a new test: consensus-specs' vector signs into the same bytes under both.
The validator client signed with ethlambda's own leanXMSS port. It made byte-identical signatures, but pq-devnet-0 asks for one leanXMSS throughout, so keys now come from leanVM's key_gen and signatures from its sign: - pq_keys::xmss_key returns leanVM's LeanXmssExpandedSecretKey, for the validator client and `ethlambda keygen` alike; the known public keys of ethereum-package's validator 0 and Lighthouse's vector still match. - leanVM derives a key on one thread (about 2.4 s), so the client spreads its keys over rayon's pool instead of one OS thread per validator. - leanVM's sign has no error path; a leaf past u32 is refused as LeafOutOfRange before it is claimed in the leaf record, not after. ethlambda_crypto re-exports leanvm_lean_xmss so a signer depends on the one pin. The port is left for verification's test keys (range_key).
ethereum-package publishes each validator's leanXMSS key cache as 14696-byte records indexed by validator index (leanVM's cache_to_bytes: the top tree's cached level, then two bottom trees). A key loads from its record in milliseconds instead of the 2.4 s a build takes. - Lookup: at PQ the registry names a validator by its XMSS key, which is what is being loaded, so its index is found by the public parameter alone (the request key's last 16 bytes, two hashes from the seed, pq_keys::xmss_public_param), scanning the whole registry (BeaconNodeApi::registry, GET .../states/head/validators). - Load: from_cache_bytes(seed, registered key, record), which checks the record against both. Best effort throughout: a registry not given within about two minutes, a source that fails, a record past the file's end or one refused, and that key (or every key) is built as before. The startup log counts keys cached, built and refused. - Fetch: pq::RecordFile, shared with --vrf-state-url, asks for each record by range; a server that ignores the range sends the whole file, which is kept and sliced, and a local file is read once rather than per key. One record is fetched alone before the rest go 16 at a time, so a whole-file answer is downloaded once. Checked against the published file: record 0 of b9dec4e1daa17dfe.xmss loads for ethereum-package's default mnemonic's validator 0 and signs the bytes a built key signs.
The per-slot leaves move to a new bottom tree at slot 4096 (about 13.6 h in at 12-second slots) and every 8192 slots after. Nothing built it ahead, so the first signature in it built it at the duty's deadline: about 2.5 s a key on leanVM, single-threaded. A background thread now looks 512 slots ahead once a minute and, when a duty leaf there falls in a bottom tree it has not built, builds it for every key (pq::prepare_bottom_tree) in a pool of half the cores, leaving the rest to the duties signing meanwhile. The trees key derivation built count as built, so the check is a no-op until the lookahead reaches the next tree. leanVM keeps four bottom trees a key: the attestation tree and the current and next per-slot ones fit.
Rebased onto main, the PQ commits stop compiling without a textual conflict: main now selects the preset at runtime (#851) and refactored the helpers they call. - Preset: a value the two presets disagree on is now an accessor (`preset::slots_per_epoch()`), and a container bounded by one takes a length marker. PQ's six such values (`MAX_COMMITTEES_PER_SLOT_PQ`, the two PQ gossip size bounds, `PREREGISTRATIONS_LIMIT`, `PREREGISTRATION_EXPIRY_SLOTS`, `AGGREGATION_COMMITTEE_WINDOW_LENGTH`) join `per_preset!`, the other nine join `shared!`, and `CommitteeBits` and the aggregation committee window take `MaxCommitteesPerSlotPq` and `AggregationCommitteeWindowLength`. Constants computed from per-preset values become functions. - State transition: EIP-8483's and PQ's `process_block` take `BlockCaches`, and PQ's slashings pass the active-balance cache `slash_validator` now takes. - Network and validator client: the wall slot comes from `wall_clock_slot`, the keystore from `ValidatorStore::signer`, and a test's `SigningContext` from `SigningContext::new`.
Nothing measured the beacon PQ aggregation path: no metric, and the logs timed a committee's proof only when it succeeded in time, and a block's merge without its size or budget. - A committee's proof logs prove_ms (the proof itself, the sidecar's cost) beside took_ms (the whole step), on success, when late and when it fails. - Each slot's proving pass ends with one line: committees and signatures sealed, how many were proved, failed, late or left unproved at the deadline, the time spent queued for a blocking thread, reading the head state and proving, and the budget. A head state that cannot be read is now logged instead of skipping the slot silently. - A block's merge logs its attestations, signatures and proof size and the budget it had, beside the time it took.
A PQ devnet node needs leanVM's prover sidecar next to it, and only tooling/pq-devnet/Dockerfile builds one: the root Dockerfile's image falls back to the reference proof encoding and refuses every Lighthouse block that carries attestations. The new optional `dockerfile` input (default ./Dockerfile, so every other dispatch builds what it did) publishes that image under the usual tags. It takes the same build args, so the shadow variant builds too.
The node took a sidecar's socket only, so something else had to start leanvm-sidecar beside it: the ethlambda-pq wrapper, inside an image only tooling/pq-devnet/Dockerfile built, which CI's image workflow could not publish. - --pq-prover-binary starts the sidecar through leanVM's own launcher (lean_pq::Sidecar::start, what Teku's Java bindings run): it waits for the warm-up, logs to <socket>.log, and the sidecar exits with the node however it exits, since it watches a stdin pipe from the node. The socket is --pq-prover-socket, or <data-dir>/pq-prover/sidecar.sock; --pq-prover-threads caps its proving threads (0: one per core). --pq-prover-socket alone still connects to a sidecar already running. - The root Dockerfile builds leanvm-sidecar at the pinned leanVM revision and ships it, so the regular image runs on a PQ network. - The ethlambda-pq wrapper and tooling/pq-devnet/Dockerfile go, and with them the workflow's dockerfile input; the ethereum-package launcher patch passes --pq-prover-binary=leanvm-sidecar instead. - lean-pq needs thiserror 2.0.21 (published 2026-09-23). MainnetOptions is boxed in Network, as LeanOptions is, now that it outgrew clippy's variant-size bound.
…duties Rebased onto main, two of its new paths meet the PQ forks: - The payload_attributes event (#852) answers no event for an EIP-8483 or PQ slot: PQ blocks are produced through pq_blocks/{slot}, which its preparation does not model, and EIP-8483 is not followed. - A doppelganger test's attester duty names no PQ aggregator role.
MegaRedHand
force-pushed
the
pq-devnet-0
branch
from
November 21, 2026 07:33
f9c3b4a to
e81e5d5
Compare
leanVM's .cargo/config.toml builds with `-C target-cpu=native`, so the sidecar the image shipped was tuned to whichever CI runner built it. The arm64 one is a Neoverse core with SVE, and its sidecar died with SIGILL on Apple silicon before listening, which stopped the node at startup. An amd64 runner with AVX-512 would do the same to hosts without it. The sidecar stage now builds with ethlambda's .cargo/config.toml in place of leanVM's: x86-64-v3 or neoverse-n1, plus the carryless-multiply features leanVM's binary-field prover needs.
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.Spec pin:
2f43bc0f989f47af81df390a90bc1f78e2436323, the pq-devnet-0 spec. ethPandaOps' genesis tooling, ethereum-package's published VRF states and Lighthouse'spq-devnet-0image all follow it. The branch went up tob5d422b2and came back down; see Since the last update. Theb5d422b2work (committed VRF secrets, staggered aggregators) is kept onpq-devnet-0-b5d422b2. The code and docs cite2f43bc0f, except the leanXMSS known-answer test, which citesee867e91, where its vector comes from.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. EIP-8483 stays unfollowed;docs/beacon_pq.mdlists what remains.Based on
main(rebased onto5caf010eon 2026-11-21; it used to be based onnightly). See Rebased ontomain.Rebased onto
mainmainnow has everything the oldnightlybase carried except feat(p2p): refuse execution payloads whose block hash is not their header's #770, which is still open. The PQ commits had extended feat(p2p): refuse execution payloads whose block hash is not their header's #770'spayload_hashto PQ envelopes, and those edits went with it. This branch therefore no longer refuses an envelope (gloas or PQ) whose block hash is not its payload header's, at gossip or in req/resp; the old branch did.main's code: the runtime preset (feat(beacon): select the preset at runtime from PRESET_BASE #851), Web3Signer remote signing (feat(validator): Web3Signer remote signing and the keymanager /eth/v1/remotekeys route #776),BlockCaches, and fix(p2p): queue a gloas block whose parent payload is unverified, rather than drop it #802's queueing of a block whose parent payload is unverified, which now covers PQ blocks too. In the validator client, PQ slots sign locally with leanXMSS insidemain's batched, concurrent signing. A validator behind Web3Signer gets no PQ key, since the key derives from a BLS secret a remote signer never hands over. "send committee subscriptions at PQ slots" is now a comment only, sincemainalready subscribes unconditionally.8a257098adapts the PQ code tomainwhere nothing conflicted textually.MAX_COMMITTEES_PER_SLOT_PQ, the two PQ gossip size bounds,PREREGISTRATIONS_LIMIT,PREREGISTRATION_EXPIRY_SLOTS,AGGREGATION_COMMITTEE_WINDOW_LENGTH) joinper_preset!, and the other nine joinshared!.CommitteeBitsand the aggregation committee window take length markers.process_blocktakeBlockCaches, and PQ's slashings pass the active-balance cache.5caf010e, over thepayload_attributesevent (feat(beacon): publish payload_attributes events #852) and doppelganger protection (feat(validator): doppelganger protection #807).e81e5d5bgives the event no PQ or EIP-8483 slot (PQ blocks are produced throughpq_blocks/{slot}, which its preparation does not model), and the PQ fork-tagged envelope is read throughas_gloasin the event's gloas preparation.8a257098do not compile on their own.Since the last update
2f43bc0f(beb567c9,e033029d).keccak256(vrf_seed || le64(slot))and is revealed as it is. The Keccak-256 tree over all2^31leaves (2f43bc0f itself) stays.AGGREGATE_DUE_BPS_GLOAS). The node seals a slot's collected signatures halfway between the attestation and aggregate deadlines and proves every registered committee before the aggregate deadline.ConfiglosesAGGREGATION_CUTOFF_BPS,AGGREGATE_DUE_BPS_PQandAGGREGATOR_DELAY_BPS, soDB_VERSIONis 9.c5ee9d239) for the sidecar, the claims and leanXMSS (f01290f3,8618fa0f,80223aaa). pq-devnet-0 moved its signer, prover, verifier and sidecar there at once; proofs from the old pin (283686575c) do not verify under it.lean_xmss.--vrf-state-urlloads them; ethereum-package publishes them asvrf_state_url.ethlambda pq-keyswrites a mnemonic's keys and VRF states in the formats ethPandaOps' tooling reads.--xmss-cache-urlloads ethereum-package's key cache records, in milliseconds instead of a 2.4 s build per key.POST /eth/v1/validator/pq_blocks/{slot}keeps the blobs of the payload it built, and publishing the envelope gossips their columns. Gossip judges a PQ block's columns against its bid.POST /eth/v1/validator/proposer_preferences(under thepqheader) to gossip.<validators-dir>/pq_signed_leaves.bin). Every per-slot leaf is claimed and flushed before its signature exists, so a restart within a slot cannot sign a second message at one leaf. That covers payload attestations, aggregates, preferences and envelopes; slashing protection covers blocks and attestations.PAYLOAD_BUILD_WINDOW) betweenforkchoiceUpdatedandgetPayload. This is shared with gloas's self-build: geth delivered the empty payload, and every ethlambda block on a devnet carried no transactions or blobs.60ab58cf).--pq-prover-binaryrunsleanvm-sidecarthrough leanVM's own launcher (lean_pq::Sidecar::start, what Teku's Java bindings run): it waits for the warm-up, logs to<socket>.log, and the sidecar exits with the node however it exits.--pq-prover-threadscaps its threads. The regularDockerfilenow builds and shipsleanvm-sidecar, so CI's ordinary image works on a PQ network; theethlambda-pqwrapper andtooling/pq-devnet/Dockerfileare gone.--pq-prover-socketalone still connects to a sidecar already running.prove_ms) next to the whole step's, each slot's proving pass ends with one summary line (proved, failed, late, unproved, budget), and a block's merge logs its size and budget.What Changed
Crypto (
ethlambda_crypto::{lean_xmss, stark, vrf, pq_keys})lean_xmssat bindings v0.15.0. It is distinct from the leanVM XMSS that lean consensus signs with. ethlambda's own port remains for test keys, pinned by consensus-specs'xmss_kat.jsonand by leanVM.2^31leaves, restorable from a compact state (the root and leaf 0's branch).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. 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; data columns their PQ block's bid. 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): attestation proofs are proved, merged and verified by leanVM's ownleanvm-sidecarprocess at leanVMc5ee9d239(bindings v0.15.0), which the node starts itself (--pq-prover-binary) or reaches on a socket (--pq-prover-socket), 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.aggregationcrate with its experimental prover, at the same pin, does resolve and compile next to this workspace's dependencies, so an in-process backend is possible. It still has to be tried and benchmarked against the sidecar (proof time, memory, CPU contention with block import) before choosing.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.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, with blobs.Store::pq_aggregate_pool), chosen greedily by uncredited participation weight and shaped ascompute_on_chain_aggregatedoes.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 blockprocess_starkrefuses is rebuilt empty.Validator client: leanXMSS keys come from leanVM's
key_gen(or--xmss-cache-url), and VRF trees come from storage,--vrf-state-url, or hashing.Aggregation: attester duties carry
is_aggregator. The node joins the committee's subnet under PQ digests and keeps the signatures of validated votes for registered committees (Store::pq_signature_pool). It proves every registered committee on the sidecar before the aggregate deadline, as Lighthouse does.aggregate_attestationanswers the proved aggregate, and the client signs theAggregateAndProof.Devnet tooling (
tooling/pq-devnet/): the ethereum-package launcher patch (passes--pq-prover-binary=leanvm-sidecaron a PQ network), and params for a following-only node and for one with 16 of 64 validators. There is also an ethlambda-only recipe.Docs:
docs/beacon_pq.md(new) anddocs/spec_deviations.md(five entries), plus updates toCLAUDE.md.Correctness / Behavior Guarantees
DB_VERSIONis 9. At 8,Config's SSZ encoding gained the new fork versions and epochs,UNREGISTERED_VALIDATOR_WITHDRAWABILITY_DELAYandATTESTATION_SUBNET_COUNT_PQ(checked against a compiled constant). At 9 it lost the staggered-aggregation keys. A directory written bymain(version 7) is refused and needs a checkpoint resync. This needs a decision before anything lands onmain. 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.e9139122. That has not been rerun since the rebase.Tests Added / Run
lean_xmss.#[ignore]d test).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.pq.yaml's type-specific SSZ bounds.make test reftests=true fork={eip8483,pq} preset=minimalat the pin (seedocs/beacon_pq.md), and fixes are expected once they run.a4d16c5b, next to Lighthouse's PQ branch (48 validators on Lighthouse, 16 on ethlambda): Lighthouse rejected nothing ethlambda sent, and ethlambda accepted everything Lighthouse sent. Both finalized every epoch through epoch 18 on the same roots. Those runs found the PQ subnet bug (4ccb69ea) and the missing committee subscriptions at PQ slots.b5d422b2on 2026-11-20:pq-devnet-0image, on a local VRF patch the branch does not carry, it finalized and Lighthouse rejected nothing ethlambda sent: blocks, envelopes, columns, aggregates, attestations, PTC votes, PQ preferences. A restarted validator client restored its stored trees and proposed again.2f43bc0f, bindings v0.15.0). It needs a Lighthousepq-devnet-0image built after its move to v0.15.0.e81e5d5b, after the second rebase):make fmt,make lintcargo check --all-targetson the workspace, and onethlambda-state-transitionandethlambda-blockchainwithbeacon-spec-testsonmake testandmake test-beacon-{mainnet,minimal}, left to CIe9139122: both halves ofmake test(3687 passed),make test-beacon-mainnet(7493 fixture cases) andmake test-beacon-minimal(50351 passed), 0 failed.50d9cc7d: both halves ofmake test(3708 passed, 0 failed).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.nightlybase carried. See Rebased ontomain.✅ Verification Checklist
make fmt— cleanmake lint(clippy with-D warnings) — cleanmake teston the rebased head — left to CI