Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
93d3f38
feat(crypto): leanXMSS and the reference STARK for the beacon PQ fork
MegaRedHand Nov 18, 2026
dae68d7
feat(beacon): EIP-8483 and PQ forks in the state transition and fork …
MegaRedHand Nov 18, 2026
8994d6b
feat(beacon): treat EIP-8483 and PQ as forks built on gloas outside t…
MegaRedHand Nov 18, 2026
c1c2f80
feat(p2p): PQ gossip validation
MegaRedHand Nov 18, 2026
afdfb45
feat(crypto): leanVM sidecar backend for PQ attestation proofs
MegaRedHand Nov 19, 2026
5b6382c
feat(beacon): follow the EIP-8483 and PQ forks
MegaRedHand Nov 19, 2026
3a17c8e
fix(beacon): keep EIP-8483 unfollowed and accept both gloas genesis b…
MegaRedHand Nov 19, 2026
741c7f1
docs(beacon): the node follows PQ; add the PQ devnet tooling
MegaRedHand Nov 19, 2026
11b0f92
feat(crypto): PQ validator key material from a BLS signing key
MegaRedHand Nov 19, 2026
51c8735
feat(validator): PQ validator duties: attest, vote and propose
MegaRedHand Nov 19, 2026
4ccb69e
fix(rpc): compute PQ attestation subnets among PQ's 16
MegaRedHand Nov 19, 2026
49d4399
feat(beacon): pack attestations into PQ blocks
MegaRedHand Nov 19, 2026
f425789
feat(beacon): pack one PQ attestation when the merge cannot finish
MegaRedHand Nov 19, 2026
3ec3db2
feat(validator): PQ aggregation duty
MegaRedHand Nov 19, 2026
0020f03
fix(validator): send committee subscriptions at PQ slots
MegaRedHand Nov 19, 2026
3d4b07b
docs(beacon): PQ block production and validator duties
MegaRedHand Nov 19, 2026
e913912
test(beacon): size the PQ packing tests' registry by the preset
MegaRedHand Nov 19, 2026
5d8ccdb
fix: propagate graffiti when building blocks
MegaRedHand Nov 19, 2026
50d9cc7
feat(beacon): track consensus-specs pq at b5d422b2
pablodeymo Nov 20, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 56 additions & 5 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -284,6 +284,17 @@ actual_slot = finalized_slot + 1 + relative_index

**XMSS (eXtended Merkle Signature Scheme):**
- Post-quantum signature scheme
- Two schemes share the name. Lean consensus signs with leanVM's XMSS
(BLAKE2s, below). The Beacon Chain's PQ fork signs with leanXMSS over
Keccak-256 (`ethlambda_crypto::lean_xmss`, 32-byte keys, 2404-byte
signatures, a port of leanVM `4af2cddd`'s Rust implementation pinned by
consensus-specs' and leanVM's known answers), and proves many signatures at
once through `ethlambda_crypto::stark`: the specification's reference (the
signatures concatenated) by default, or real leanVM proofs from a
`leanvm-sidecar` process (`--pq-prover-socket`, leanVM `283686575c`, the
revision Lighthouse's PQ branch pins), which is what the PQ devnet runs.
The two encodings do not verify each other's proofs. Never pass one
scheme's key to the other
- Wire sizes: `PUBLIC_KEY_SIZE` (`common/types/src/state.rs`) and `SIGNATURE_SIZE`
(`common/types/src/attestation.rs`), static-asserted against leanVM's scheme
constants in `common/crypto/src/signature.rs`
Expand Down Expand Up @@ -633,7 +644,7 @@ existing once per chain.
silent wrong answer.
- **`ForkName::Lean` is deliberately absent from `ForkName::ALL`.** `ALL` is
what `parse`, `previous` and `next` search, so its absence keeps
`parse("lean")` at `None` and `Gloas.next()` at `None`, meaning a fork upgrade
`parse("lean")` at `None` and `Pq.next()` at `None`, meaning a fork upgrade
cannot walk off the end into lean. Lean is not a point on the Beacon Chain's
fork timeline. `Lean` is declared *last* so the derived `Ord` puts it after
every beacon fork, which is what `fork >= ForkName::X` gating reads.
Expand Down Expand Up @@ -812,6 +823,42 @@ transitions are in `ethlambda-types`, per the section above. Nothing above
Fork choice is fixture-verified too, including bellatrix's terminal-PoW
validation, deneb's and fulu's data availability, and gloas's payload-aware
suites.
- **EIP-8483 and PQ** (consensus-specs' `pq` branch feature forks, pinned at
`b5d422b2`) are `ForkName::Eip8483` and `ForkName::Pq` after gloas, selectors
8 and 9, implemented in the state transition and fork choice
(`stf/{eip8483,pq}.rs`, `stf/epoch/pq.rs`, `helpers/pq.rs`, `upgrade_to_*`)
and PQ's gossip rules (`gossip/pq.rs`, `p2p/src/beacon/pq.rs`: a PQ digest's
reshaped topics decode by the digest and are judged with XMSS signatures
and STARK proofs). **The node follows PQ** (`ForkName::is_followed`): PQ
blocks and envelopes import from gossip and req/resp, accepted PQ
aggregates and payload attestations reach fork choice, and envelopes of
every fork travel as the 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). It was run next to
Lighthouse's PQ client on a PQ-at-genesis devnet (`tooling/pq-devnet/`),
with its own validators (before `b5d422b2` changed the VRF tree, which no
other client's tooling follows yet): the validator client derives each
validator's leanXMSS key and VRF seed from its BLS key
(`ethlambda_crypto::pq_keys`) and attests, aggregates (staggered by its seat
in the aggregation committee), casts PTC votes and proposes, each signature
at its leaf. The VRF tree (`ethlambda_crypto::vrf`, Keccak-256 over all
`2^31` leaves, each committing to its slot's secret) takes about 100 s of
every core per key, so a background thread hashes it after startup and
stores its upper nodes in `<validators-dir>/pq_vrf_trees/`; a proposal
before its key's tree is ready is missed. The beacon node builds PQ blocks through `POST
/eth/v1/validator/pq_blocks/{slot}` (`rpc/src/beacon/pq_proposal.rs`,
`pq_block_production.rs`), packing attestations from the validated
aggregates in `Store::pq_aggregate_pool` with their proofs merged on the
sidecar under a deadline (one unmerged attestation when it misses), and
proves its aggregators' committees ahead (`rpc/src/beacon/pq_aggregation.rs`,
`Store::pq_signature_pool`). EIP-8483 is not followed yet, and PQ blocks
carry no blobs. The
gloas rules run on all three gloas-family states through `GloasFamily(Mut)`
(`containers/gloas_family.rs`, returned by `helpers::gloas::gloas_state(_ref)`),
and the PQ registry holds each XMSS key in its 48-byte request form so the
registry accessors keep handing out the shared `Validator`. No release ships
their fixtures; see [`docs/beacon_pq.md`](docs/beacon_pq.md) for the design,
how to generate them, and what remains.
- **Gloas** lives in `stf/gloas.rs`, `stf/epoch/gloas.rs`, `helpers/gloas.rs`,
the gloas section of `fork_choice.rs`, and `containers/gloas.rs` in
`ethlambda-types`. **The live follower follows gloas.** The chain actor's
Expand Down Expand Up @@ -1061,10 +1108,14 @@ behavior.
in-memory map stays as a write-through cache in front of the table. Pruned
on finalization to the same horizon as `LiveChain` (the finalized block's
own slot, keeping that block's own entry).
- `DB_VERSION` is 7: `States` and `StateDiffs` moved from root keys to
slot||root keys (the block's slot, looked up from `BlockHeaders` by readers)
so `Store::prune_finalized_states` can range-delete finalized states; a
directory written by an earlier version holds rows no lookup finds. (6 was
- `DB_VERSION` is 8: `Config` gained the EIP-8483 and PQ fork versions and
epochs, `UNREGISTERED_VALIDATOR_WITHDRAWABILITY_DELAY`, PQ's aggregation
timing (`AGGREGATION_CUTOFF_BPS`, `AGGREGATE_DUE_BPS_PQ`,
`AGGREGATOR_DELAY_BPS`) and `ATTESTATION_SUBNET_COUNT_PQ`, so a version 7
directory's stored config decodes into the wrong fields. (7 moved `States`
and `StateDiffs` from root keys to slot||root keys, the block's slot looked
up from `BlockHeaders` by readers, so `Store::prune_finalized_states` can
range-delete finalized states; 6 was
the gloas schedule, timing and churn keys in `Config`, which is SSZ-encoded
under `KEY_CONFIG`; 5 was the unrealized-justifications table, since a
directory written before it has no row there for any block it already
Expand Down
53 changes: 53 additions & 0 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

18 changes: 18 additions & 0 deletions Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -116,6 +116,24 @@ secp256k1 = { version = "0.30.0", default-features = false, features = ["global-
# build remains portable to hardware lacking the extensions.
sha2 = { version = "0.10.9", features = ["asm"] }

# Keccak-256 (Ethereum's, with Keccak's original padding), the hash of leanXMSS,
# the post-quantum signature scheme of the Beacon Chain's PQ fork
# (`ethlambda_crypto::lean_xmss`). Not leanVM's XMSS: that one hashes with
# BLAKE2s and signs lean consensus messages only.
sha3 = "0.10.9"

# The client of leanVM's `leanvm-sidecar` (`crates/sidecar` without its
# `server` feature, which builds no prover) and its claim encoding: the PQ
# fork's attestation proofs as the PQ devnet makes them, real leanVM STARKs
# over leanXMSS signatures rather than the specification's concatenation
# (`ethlambda_crypto::stark`). Pinned to the revision Lighthouse's PQ branch
# and its `leanvm-sidecar` use: nothing on the wire detects a mismatch, a proof
# from another revision just fails to verify. Not the `leanvm` revision below,
# which lean consensus proves with.
leanvm_sidecar = { package = "sidecar", git = "https://github.com/leanEthereum/leanVM.git", rev = "283686575c4e81790591d2c6e3ed21c69c0e3bbe" }
leanvm_claims = { package = "claims", git = "https://github.com/leanEthereum/leanVM.git", rev = "283686575c4e81790591d2c6e3ed21c69c0e3bbe" }
leanvm_lean_xmss = { package = "lean_xmss", git = "https://github.com/leanEthereum/leanVM.git", rev = "283686575c4e81790591d2c6e3ed21c69c0e3bbe" }

# XMSS signatures + recursive aggregation, through leanVM's own facade crate:
# it re-exports the aggregation API, the `xmss` module (keys, signing, and the
# SSZ codec for the two wire types) and the `rand` that signing draws from, so
Expand Down
64 changes: 64 additions & 0 deletions bin/ethlambda/pq/ethlambda-pq
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
#!/bin/bash
# Runs `ethlambda` with a leanVM prover sidecar beside it, for a network that
# schedules the PQ fork: `ethlambda-pq beacon <flags>` starts `leanvm-sidecar`
# on a private socket, waits for it to listen, then starts
# `ethlambda <flags> --pq-prover-socket <socket>`. Either exiting stops the
# other. The sidecar must be built from the leanVM revision ethlambda pins
# (`ethlambda_crypto::stark::sidecar::LEANVM_REV`). `LEANVM_THREADS` caps its
# threads (0, the default, is one per core).
set -eu

socket_dir=$(mktemp -d "${TMPDIR:-/tmp}/leanvm.XXXXXXXX")
socket_path="$socket_dir/prover.sock"
prover_pid=
node_pid=

cleanup() {
if [[ -n "$node_pid" ]]; then
kill "$node_pid" 2>/dev/null || true
wait "$node_pid" 2>/dev/null || true
fi
if [[ -n "$prover_pid" ]]; then
kill "$prover_pid" 2>/dev/null || true
wait "$prover_pid" 2>/dev/null || true
fi
rm -f -- "$socket_path" "$socket_path.lock"
rmdir -- "$socket_dir" 2>/dev/null || true
}

trap cleanup EXIT
trap 'exit 143' TERM
trap 'exit 130' INT

leanvm-sidecar --socket "$socket_path" --threads "${LEANVM_THREADS:-0}" &
prover_pid=$!
ready_deadline=$((SECONDS + 120))
until [[ -S "$socket_path" ]]; do
if ! kill -0 "$prover_pid" 2>/dev/null; then
echo 'leanvm-sidecar exited before creating its socket' >&2
exit 1
fi
if (( SECONDS >= ready_deadline )); then
echo 'leanvm-sidecar did not create its socket within 120 seconds' >&2
exit 1
fi
sleep 0.1
done

ethlambda "$@" --pq-prover-socket "$socket_path" &
node_pid=$!

while kill -0 "$prover_pid" 2>/dev/null && kill -0 "$node_pid" 2>/dev/null; do
sleep 0.2
done

if kill -0 "$prover_pid" 2>/dev/null; then
status=0
wait "$node_pid" || status=$?
node_pid=
exit "$status"
fi

prover_pid=
echo 'leanvm-sidecar exited while ethlambda was running' >&2
exit 1
10 changes: 8 additions & 2 deletions bin/ethlambda/src/beacon.rs
Original file line number Diff line number Diff line change
Expand Up @@ -177,8 +177,8 @@ pub fn wire_params(
//
// A fork the node does not follow keeps its own warning: crossing its
// digest works like any other, but the node stops tracking the chain
// there regardless. No fork is in that state today, since gloas is
// followed, so the warning is the guard for the next one.
// there regardless. EIP-8483 and PQ are in that state, though no built-in
// network schedules either.
let schedule = ForkSchedule::new(&chain, genesis.genesis_validators_root);
match schedule.next_boundary_after(epoch) {
Some(next) if !next.fork.is_followed() => warn!(
Expand Down Expand Up @@ -227,6 +227,11 @@ pub fn wire_params(
let attestation_subnets =
ethlambda_p2p::beacon::subnets::compute_subscribed_subnets(node_id, epoch, &chain)
.map_err(|err| eyre::eyre!("computing the attestation subnet backbone: {err:?}"))?;
// A PQ digest's backbone, the same function over `ATTESTATION_SUBNET_COUNT_PQ`:
// held only while a PQ digest is.
let attestation_subnets_pq =
ethlambda_p2p::beacon::subnets::compute_subscribed_subnets_pq(node_id, epoch, &chain)
.map_err(|err| eyre::eyre!("computing the PQ attestation subnet backbone: {err:?}"))?;
info!(
subnets_per_node = chain.subnets_per_node,
subnets = ?attestation_subnets,
Expand All @@ -250,6 +255,7 @@ pub fn wire_params(
genesis_validators_root: genesis.genesis_validators_root,
custody_columns,
attestation_subnets,
attestation_subnets_pq,
},
fork_id,
})
Expand Down
Loading
Loading