Skip to content

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
mainfrom
pq-devnet-0
Draft

MegaRedHand wants to merge 45 commits into
mainfrom
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.

Spec pin: 2f43bc0f989f47af81df390a90bc1f78e2436323, the pq-devnet-0 spec. ethPandaOps' genesis tooling, ethereum-package's published VRF states and Lighthouse's pq-devnet-0 image all follow it. The branch went up to b5d422b2 and came back down; see Since the last update. The b5d422b2 work (committed VRF secrets, staggered aggregators) is kept on pq-devnet-0-b5d422b2. The code and docs cite 2f43bc0f, except the leanXMSS known-answer test, which cites ee867e91, where its vector comes from.

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. EIP-8483 stays unfollowed; docs/beacon_pq.md lists what remains.

Based on main (rebased onto 5caf010e on 2026-11-21; it used to be based on nightly). See Rebased onto main.

Rebased onto main

Since the last update

  • Back to 2f43bc0f (beb567c9, e033029d).
    • The VRF leaf is keccak256(vrf_seed || le64(slot)) and is revealed as it is. The Keccak-256 tree over all 2^31 leaves (2f43bc0f itself) stays.
    • The known answers are ethereum-package's published state for validator 0 of its default mnemonic.
    • Aggregators are unstaggered again: every aggregator broadcasts at gloas's aggregate deadline (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.
    • Config loses AGGREGATION_CUTOFF_BPS, AGGREGATE_DUE_BPS_PQ and AGGREGATOR_DELAY_BPS, so DB_VERSION is 9.
  • leanVM bindings v0.15.0 (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.
    • Signing and verification now go through leanVM's own lean_xmss.
    • The port stays for test keys and is pinned against leanVM: consensus-specs' vector signs to the same bytes under both.
  • Keys and VRF trees for the validator client:
    • Precomputed VRF tree states: --vrf-state-url loads them; ethereum-package publishes them as vrf_state_url.
    • ethlambda pq-keys writes a mnemonic's keys and VRF states in the formats ethPandaOps' tooling reads.
    • Precomputed leanXMSS keys: --xmss-cache-url loads ethereum-package's key cache records, in milliseconds instead of a 2.4 s build per key.
    • Bottom trees built ahead: a background thread builds each key's next leanXMSS bottom tree before a duty needs it (the first one at slot 4096).
    • Hashing: a VRF tree that has to be hashed runs in a rayon pool of its own, so it no longer starves the signatures.
  • Blobs in PQ blocks. PQ keeps gloas's data column sidecar, so 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.
  • PQ proposer preferences, signed with leanXMSS at the proposal slot's leaf, from the validator client through POST /eth/v1/validator/proposer_preferences (under the pq header) to gossip.
  • A durable leaf record (<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.
  • A self-built payload gets 500 ms to fill (PAYLOAD_BUILD_WINDOW) between forkchoiceUpdated and getPayload. 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.
  • PQ blocks, envelopes and aggregates are counted in the validator client's metrics.
  • The node starts the sidecar itself, as Teku does (60ab58cf). --pq-prover-binary runs leanvm-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. --pq-prover-threads caps its threads. The regular Dockerfile now builds and ships leanvm-sidecar, so CI's ordinary image works on a PQ network; the ethlambda-pq wrapper and tooling/pq-devnet/Dockerfile are gone. --pq-prover-socket alone still connects to a sidecar already running.
  • Timing logs for PQ aggregation: each committee's proof logs the STARK's time (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})

    • leanXMSS (Keccak-256, 32-byte keys, 2404-byte signatures) signs and verifies through leanVM's lean_xmss at 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.json and by leanVM.
    • The specification's reference STARK: a proof is the signatures concatenated.
    • The VRF tree: Keccak-256 over all 2^31 leaves, restorable from a compact state (the root and leaf 0's branch).
    • PQ key material (leanXMSS key, VRF seed) is derived from a BLS signing key, as ethereum-package's generator and Lighthouse derive it.
  • 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. 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; data columns their PQ block's bid. 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. 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): attestation proofs are proved, merged and verified by leanVM's own leanvm-sidecar process at leanVM c5ee9d239 (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.

    • Still to try: proving in-process. The sidecar keeps the prover's memory, crashes and thread pool out of the node, and is what every other client runs. leanVM's aggregation crate 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.

    • 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.
    • Their proofs are 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.
  • 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.

    • Attestations, PTC votes, proposals with their envelopes, aggregates and proposer preferences are signed at their leaves.
    • Every leaf is claimed in a durable record before signing. Slashing protection still covers attestations and proposals.
  • 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_attestation answers the proved aggregate, and the client signs the AggregateAndProof.

  • Devnet tooling (tooling/pq-devnet/): the ethereum-package launcher patch (passes --pq-prover-binary=leanvm-sidecar on 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) and docs/spec_deviations.md (five entries), plus updates to CLAUDE.md.

Correctness / Behavior Guarantees

  • DB_VERSION is 9. At 8, Config's SSZ encoding gained the new fork versions and epochs, UNREGISTERED_VALIDATOR_WITHDRAWABILITY_DELAY and ATTESTATION_SUBNET_COUNT_PQ (checked against a compiled constant). At 9 it lost the staggered-aggregation keys. A directory written by main (version 7) is refused and needs a checkpoint resync. This needs a decision before anything lands on main. 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.
  • 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.
  • Gloas behavior changes outside PQ:
  • Existing forks: every pre-existing beacon fixture passed on both presets at e9139122. That has not been rerun since the rebase.

Tests Added / Run

  • Added:
    • leanXMSS known-answer tests, and the port pinned against leanVM's lean_xmss.
    • VRF known answers: ethereum-package's published state for validator 0. One whole tree was hashed end to end (an #[ignore]d test).
    • 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.
    • 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. In p2p: decoding by digest and the size bounds, the PQ topic set and backbone, the rollover, PQ scoring, and triage.
    • The validator client's PQ duties, the durable leaf record (including a torn trailing record), the key cache loader and PQ preferences.
    • 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 (ethereum-package with ethlambda added; PQ at genesis):
    • At 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.
    • At b5d422b2 on 2026-11-20:
      • An ethlambda-only devnet finalized with blobs.
      • Next to Lighthouse's pq-devnet-0 image, 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.
    • Not yet run at this head (2f43bc0f, bindings v0.15.0). It needs a Lighthouse pq-devnet-0 image built after its move to v0.15.0.
    • Measured earlier: 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 head (e81e5d5b, after the second rebase):
    • make fmt, make lint
    • cargo check --all-targets on the workspace, and on ethlambda-state-transition and ethlambda-blockchain with beacon-spec-tests on
    • not run: make test and make test-beacon-{mainnet,minimal}, left to CI
  • Earlier runs, before the rebase:
    • At e9139122: both halves of make test (3687 passed), make test-beacon-mainnet (7493 fixture cases) and make test-beacon-minimal (50351 passed), 0 failed.
    • At 50d9cc7d: both halves of make test (3708 passed, 0 failed).

Related Issues / PRs

✅ Verification Checklist

  • Ran make fmt — clean
  • Ran make lint (clippy with -D warnings) — clean
  • Ran make test on the rebased head — left to CI

@MegaRedHand
MegaRedHand changed the base branch from nightly to main November 21, 2026 07:00
@MegaRedHand MegaRedHand changed the title feat(beacon): EIP-8483 and PQ forks in the state transition and fork choice feat(pq): EIP-8483 and PQ forks end to end for pq-devnet-0: STF, gossip, following, block production and validator duties Nov 21, 2026
MegaRedHand and others added 26 commits November 21, 2026 04:30
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.
MegaRedHand and others added 18 commits November 21, 2026 04:31
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.
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

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