Repository navigation
Implement EIP-8450 post-quantum validator key registry - #31
Open
kevaundray wants to merge 28 commits into
Open
kevaundray wants to merge 28 commits into
kevaundray wants to merge 28 commits into
Conversation
lean-pq pulls in leanVM, whose `keccak_gkr` crate uses `cfg_select!`, which is stable from rustc 1.95. Bump `rust-version`, the builder images of `Dockerfile` and `lcli/Dockerfile`, and the pinned per-platform digests of the reproducible build (`Dockerfile.reproducible`, `Makefile` and `docker-reproducible.yml`).
Add the `Eip8450` fork after Heze (`EIP8450_FORK_EPOCH`,
`EIP8450_FORK_VERSION`). It reuses Heze's execution payload, bid and
engine API methods, and adds:
- `PqPublicKeys`, `PqKeyRegistration`, `PqKeyPossession` and
`SignedPqKeyRegistration`, the `pq_public_keys` and
`pq_key_change_epochs` state lists, and the `pq_key_registrations`
block body field.
- `process_pq_key_registrations`, with BLS authorization under
`DOMAIN_PQ_KEY_REGISTRATION` and a leanXMSS proof of possession at leaf
index 0 under `DOMAIN_PQ_KEY_POSSESSION`, both on the genesis fork
version. Proofs are verified on every block signature path, including
`BlockSignatureVerifier`. A `PqPubkeyCache` on the state enforces key
uniqueness.
- `upgrade_to_eip8450`, and default entries for new validators.
- The `pq_key_registration` gossip topic with the EIP's checks, a capped
op pool that packs only sequentially valid registrations, pool
persistence (schema v33), and `POST/GET
/eth/v1/beacon/pool/pq_key_registrations`,
`GET /eth/v1/beacon/states/{state_id}/pq_public_keys` and the
`pq_key_registration` SSE event.
- `lcli pq-key-registration` to create and submit registrations.
- Presets: `MAX_PQ_KEY_REGISTRATIONS = 8`; `MIN_PQ_KEY_CHANGE_DELAY` is
256 epochs (8 on minimal).
Heze payload envelopes are now sent with `engine_newPayloadV6` instead of
V5, and the mock EL requires V6 after Heze. Without this a devnet's EL
stops at the Heze fork.
leanXMSS comes from lean-pq v0.8.0, checked against EIP-CRYPTO v1 by a
known-answer test whose vectors come from an independent reference.
Follow the spec change: `pq_key_change_epochs` starts at `FAR_FUTURE_EPOCH` instead of `GENESIS_EPOCH`, in `upgrade_to_eip8450` and `add_validator_to_registry`. A registration applied in the genesis epoch stored the value it named, so it could be replayed once after `MIN_PQ_KEY_CHANGE_DELAY`. Every change now moves the stored epoch. The delay check (block processing and gossip) only runs for registered validators and uses saturating addition. The stored value now goes from `FAR_FUTURE_EPOCH` down to the first change epoch, so change epochs no longer order numerically. Add `cmp_pq_change_epochs` and `is_pq_registration_superseded`, which order `FAR_FUTURE_EPOCH` before every epoch, and use them in the op pool's replacement rule, its finalization prune and the gossip duplicate filter's prune. With numeric comparisons, a pooled first registration superseded by different keys was never pruned, a first registration could replace a pooled change, and pairs naming a change made in a non-finalized block were forgotten too early. Tests name the stored value for first registrations, and new tests cover a genesis-epoch registration that cannot be replayed and a first registration naming `GENESIS_EPOCH`.
- `PqKeyPossession` names the validator by its BLS public key (`validator_pubkey`) instead of its index, as in consensus-specs and the EIP. Block processing, `BlockSignatureVerifier`, gossip and `lcli pq-key-registration` sign and verify the proof over the validator's pubkey from the state. The known-answer vectors are regenerated from the independent Python reference. - Gossip's fork gate and change-delay check allow for `MAXIMUM_GOSSIP_CLOCK_DISPARITY`, as the spec's gossip rules do. - Finalization pruning (op pool and the gossip duplicate filter) also drops registrations naming a change epoch that only exists on an orphaned fork: a real epoch before the finalized epoch that differs from the finalized state's entry. These could never be included, and their observed pair made the node ignore the validator's valid registration on gossip.
Follow EIP-8450 at ethereum/EIPs#12592 (b91ea8e0): - `PqPublicKeys` is `{ xmss_public_key, vrf_root }` (64 bytes), so a `SignedPqKeyRegistration` is 2580 bytes. Remove `PQ_KEYS_VERSION_*`, the version check in block processing, and the version gossip rule. The HTTP API's `PqPublicKeysData` drops `version`. - A validator is registered when its `pq_key_change_epochs` entry is not `FAR_FUTURE_EPOCH`. The key-in-use check, the uncached scan and the `PqPubkeyCache` rebuild all use one helper based on that, so an unregistered validator's all-zero entry never owns a key. - `VrfRoot` is `Hash256` (SSZ, tree hash and JSON match `Bytes32`), and references to the removed EIP-CRYPTO are reworded. - Gossip checks that the head state is past the fork before validating the validator, in the EIP's rule order.
EIP-8450 (ethereum/EIPs#12592 at 6e69f9c8) no longer assumes leanXMSS signing is deterministic: signing twice at a leaf index, even the same message, is a reuse. Leaf 0 signs the key's `PQKeyPossession` once, and the signer resubmits those bytes in every later registration of the key. `lcli pq-key-registration` now signs the proof only when it creates a key, over the validator's on-chain BLS public key, and stores it in the seed file (`seed`, `validator_index`, `validator_pubkey`, `possession`) before the registration is output or submitted. Reusing a key loads the stored proof, checks it against the validator and the seed's key, and cannot reach a signing call: `sign_possession` is separate from `build_signed_registration`, which takes the proof as input. Seed files without a stored proof are refused rather than re-signed. Test comments no longer rely on deterministic signing.
Follow EIP-8450 at ethereum/EIPs#12592 (a8a412e4): the key-in-use check no longer excludes the registering validator. A registration is invalid if any registered validator, including itself, holds its leanXMSS key, in block processing and in the gossip REJECT. A VRF-root-only change is therefore rejected; a change needs a new key. A key freed by its holder's change can be registered again. `pq_public_key_owner(state, xmss_public_key)` returns any registered holder. The op pool's finalization prune treats any finalized holder of a pooled registration's key, including its own validator, as making it dead. That subsumes the separate "already applied" rule. `lcli pq-key-registration` creates a new key on every run: the `--xmss-seed-file` reuse path and the stored proof are removed, and the seed file holds `seed`, `validator_index` and `validator_pubkey`. A registration that was not included is resubmitted by POSTing its `--output` file unchanged; it is never re-signed.
The key rule prunes registrations that are invalid against the finalized state, not only those no descendant can include: a holder that later changes away from the key would make it valid again. Say so, and why this is intended (EIP-8450 lets nodes clear a first-seen registration that is no longer valid against the finalized state, and the pair is forgotten so a resubmission is accepted).
Follow EIP-8450 at ethereum/EIPs#12592 (2344c589), mirrored in consensus-specs kw/8450 at 4357a7a53: - Rename `PqKeyRegistration.validator_index` to `index` and `PqKeyPossession.validator_pubkey` to `pubkey` (SSZ unchanged, JSON field names change). - Builders register through the same operation and gossip topic, under their index with `BUILDER_INDEX_FLAG` set. They must be active, register a zero VRF root, and sign the registration and the proof of possession with the builder's BLS key. Key uniqueness spans validators and builders. - `BeaconStateEip8450` gains `builder_pq_public_keys` and `builder_pq_key_change_epochs`, parallel to `builders`. The upgrade and `add_builder_to_registry` store the empty key and the builder's deposit epoch, also at a reused index, and the PQ pubkey cache releases a reused index's old key. - An index has registered keys when its stored leanXMSS key is not all-zero. A registration of the all-zero key is rejected explicitly, and the change delay is gated on the stored key. - Gossip follows the EIP's rule order: index (validator not exiting, or active builder), builder zero VRF root, first seen, change epoch, delay, key (non-zero and not in use), BLS signature, possession. - Block production does not pack a registration for a builder whose exit request is in the block's parent execution requests. - The PQ state endpoint accepts flagged builder indices, and `lcli pq-key-registration --builder-index` registers builders.
Remove Eth1 data and legacy deposits from Heze block bodies and states using progressive container masks. Skip obsolete processing and production paths, require the deposit migration indices to match at the fork, and cover the boundary and proof behavior in tests.
EIP-8015 removes `deposits` from Heze block bodies, so `invalid_signature_deposit` cannot add one: return early when the test fork is Heze or later. Also describe the Gloas and Heze `BeaconBlockBody` active-field masks separately.
Carry the EIP-8015 gaps into Eip8450: the state is active_fields(width=50, gaps=(8, 9, 10, 28)) with the PQ key lists at 46-49, and the body is active_fields(width=14, gaps=(1, 6)) with pq_key_registrations at 13. `upgrade_to_eip8450` no longer carries the removed Heze fields; Eip8450 bodies have no eth1_data/deposits in empty blocks, block production and blinded conversions; proof selection and tests use the Eip8450 masks. Co-authored-by: hopinheimer <knmanas6@gmail.com> Co-authored-by: Eitan Seri- Levi <eserilev@gmail.com>
# Conflicts: # consensus/types/src/block/beacon_block_body.rs
`apply_deposit` read `eth1_deposit_index` up front only to label errors, so it failed on Heze states, which EIP-8015 leaves without that field. Fall back to index 0 for the label; proofs and the index increment still require it.
Follow EIP-8450 at ethereum/EIPs#12592 (71c5ab47) and consensus-specs kw/8450 (9da0d0bbe): the gossip rule for builders is split in two. - A builder that has initiated an exit (`withdrawable_epoch` set) is REJECTed, as `BuilderExiting`. - A builder whose deposit epoch is not before the head state's finalized epoch is IGNOREd, as `BuilderDepositNotFinalized`, since finality can differ between nodes and a peer that has seen it advance forwards the registration honestly. The exit check comes before the finality check, and both before the builder zero VRF root rule. Block processing is unchanged: it still requires `is_active_builder`.
Follow EIP-8450 at ethereum/EIPs#12592 (55e79510), a pure rename with no SSZ or hash-root change: - `PqPublicKeys` -> `PqKeyMaterial` - state fields `pq_public_keys` -> `pq_key_material` and `builder_pq_public_keys` -> `builder_pq_key_material` - `PqKeyRegistration.public_keys` -> `key_material` - helpers `get/set/registered_pq_public_keys` -> `*_pq_key_material` The JSON field names change with them. The Lighthouse-defined state endpoint moves to `/eth/v1/beacon/states/{state_id}/pq_key_material`, with `PqKeyMaterialData` and `get_beacon_states_pq_key_material`. `xmss_public_key`, `XmssPublicKey`, `pq_public_key_owner` and BLS public keys keep their names.
Follow EIP-8450 at ethereum/EIPs#12592 (95861ee8) and consensus-specs kw/8450 (91c59ff0d), a pure rename with no SSZ or hash-root change: - `pq_key_material` -> `post_quantum_key_material` - `pq_key_change_epochs` -> `post_quantum_key_change_epochs` - `builder_pq_key_material` -> `builder_post_quantum_key_material` - `builder_pq_key_change_epochs` -> `builder_post_quantum_key_change_epochs` The state's JSON field names change with them. Types, helpers, the block body field `pq_key_registrations` and the `/eth/v1/beacon/states/{state_id}/pq_key_material` route are unchanged. Both EIP-8450 domains already use the genesis fork version explicitly.
Fixes RUSTSEC-2026-0418 (the libz-sys build script leaks environment variables into the build directory), which fails `cargo audit` in check-code. Upstream made the same bump in sigp#10499.
Gloas gossip `beacon_block` validation REJECTs a block whose parent is not full when `bid.parent_block_hash != parent_state.latest_block_hash`. Lighthouse only enforced this at import, so it accepted and forwarded such blocks on gossip. The consensus-spec-tests vector `gossip_beacon_block__reject_bid_not_on_parent_execution_head` (Heze) exposed this. A Gloas block's `process_execution_payload_bid` asserts `bid.parent_block_hash == state.latest_block_hash`, so the parent's execution head is the parent bid's `parent_block_hash`, which fork choice already stores. The check needs no state load. Pre-Gloas parents carry no bid hashes and are skipped.
Remove the blanket Heze skip in the EF test handler and the `heze/` exclusion in `check_all_files_accessed.py`, then make the v1.7.0-beta.4 Heze vectors pass: - Build state caches before advancing in transition tests. Post-Gloas epoch processing reads the slashings cache to compute the proposer lookahead, and Heze transition tests start from a Gloas pre-state. - Stop running `eth1_data_reset` on Heze (EIP-8015 removes it). - Run the Heze light client `single_merkle_proof` tests, and the Heze `InclusionList`, `SignedInclusionList` and `ExecutionRequests` SSZ tests. - In the gossip harness, REJECT beacon blocks that fail SSZ decoding, as the network service does, instead of failing to load the case. The Gloas "too many <operation>" vectors rely on this. - Accept the Gloas `payload` field on gossip setup blocks and skip cases that need it, since the harness cannot import payload envelopes. Narrow skips that remain, each with a comment: - EIP-8365 (unimplemented): three Heze `pending_deposits` cases. - Heze light client types (unimplemented): Heze `LightClient*` SSZ vectors. - Gossip suites without a handler: Heze `gossip_inclusion_list` (FOCIL) and the Gloas ePBS suites Heze inherits; the latest-stable-only gossip suites now also list Heze. - Fork choice compliance: beta.4 ships no Heze comptests. Also run locally generated EIP-8450 vectors (consensus-specs `kw/8450`) where they exist: add the `pq_key_registration` operation, the PQ SSZ types and `BeaconBlockBodyEip8450`, and extend the Heze-typed SSZ tests to EIP-8450. Without those vectors nothing changes, since no released vectors cover EIP-8450.
Remove `--mnemonic` and `--bls-secret-key` from `lcli pq-key-registration`: secrets on the command line are visible in /proc and shell history. The BLS key comes from `--mnemonic-file`, `--keystore` or `--bls-secret-key-file`. Secret bytes (the leanXMSS seed and its hex, the seed file contents, mnemonic and BLS key files) are held in pre-sized zeroized buffers that never reallocate, and errors no longer quote secret input. The `--xmss-seed-out` help notes that lean-pq does not zeroize the leanXMSS secret key it holds in memory.
Follow consensus-specs kw/8450 (b1b194cb1) and ethereum/EIPs#12599: a registration for an index not yet in the head state, one naming another stored change epoch, and one whose key is held in the head state are IGNOREd instead of REJECTed. Each depends on the node's head, so an honest peer could otherwise be penalised for forwarding. They fail before the registration is marked seen. Also: - The op pool's persisted layout is chosen by its first SSZ offset, so a decode failure reports the stored layout's error. A V33 pool whose registrations no longer decode starts with an empty PQ pool and logs a warning, keeping the rest of the pool. - Range sync is tested over segments with validator and builder registrations, and rejects a segment with a bad proof of possession. - The Heze-boundary payload preparation tests schedule EIP-8450 after Heze. - Correct the comment in `BeaconBlock::any_from_ssz_bytes`: since EIP-8015, Heze and Gloas blocks do not encode identically.
Run the Heze EF tests (consensus-spec-tests v1.7.0-beta.4) with narrow skips for unimplemented EIP-8365, payload-envelope gossip cases and the Heze light client, and fix what they found: forwarding of Gloas/Heze gossip blocks whose bid is not on the parent's execution head, missing state caches in transition tests, and eth1 data reset on Heze.
A registration taking a key that its finalized holder changed away from in a not-yet-finalized block is valid at the head, and was accepted over HTTP and gossip, but was pruned at the next finalization because the finalized state still showed the old holder. The submitter only found out by resubmitting after finality. A key held in the finalized state now prunes a registration only if the registration is also invalid at the head: the key is held there too, or it fails verification for a reason other than the change delay. Block packing already checks every candidate against the block's pre-state. Found on a kurtosis devnet.
Adding lean-pq re-resolved data-encoding-macro-internal (via multiaddr) to syn 1.0.109, which deny.toml bans. Re-resolve it to syn 2, so `make deny-CI` passes again.
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.
Issue Addressed
A post-quantum fork needs validators and builders to already hold registered hash-based keys when it activates; registering them all at the fork is not feasible. EIP-8450 (Post-Quantum Consensus Key Registry) adds a registry to the beacon state: each validator and builder registers a leanXMSS public key and a VRF tree root, which stay dormant until a later fork switches duties to them. This PR implements it, following consensus-specs
kw/8450(b1b194cb1) and ethereum/EIPs#12599. The hash-based primitives are EIP-CRYPTO v1 via lean-pq-bindings v0.8.0.Proposed Changes
Fork. A new
Eip8450fork after Heze (EIP8450_FORK_EPOCH,EIP8450_FORK_VERSION, following the consensus-specs_featuresconvention). It reuses Heze's execution payload, bid and engine API methods, and includes the EIP-8015 Heze port (#32), so its states and blocks match the spec's.Consensus
PqKeyMaterial(xmss_public_key,vrf_root),PqKeyPossession,PqKeyRegistration,SignedPqKeyRegistration.post_quantum_key_materialandpost_quantum_key_change_epochsfor validators, andbuilder_post_quantum_key_materialandbuilder_post_quantum_key_change_epochsfor builders, as progressive lists. An all-zero key means unregistered; a never-changed entry recordsFAR_FUTURE_EPOCH, or a builder's deposit epoch.pq_key_registrations(at mostMAX_PQ_KEY_REGISTRATIONS= 8).process_pq_key_registration, run after every other operation:previous_change_epoch, carry a new key that no validator or builder holds, and come at leastMIN_PQ_KEY_CHANGE_DELAYafter the last change.DOMAIN_PQ_KEY_REGISTRATION, and a leanXMSS proof of possession at leaf index 0 underDOMAIN_PQ_KEY_POSSESSION, bound to the BLS pubkey. Both domains use the genesis fork version.BlockSignatureVerifier(VerifyBulk, gossip import and range sync).PqPubkeyCacheon the state. It covers validators and builders, is cloned with the state, built lazily, and kept exact across builder index reuse.MIN_PQ_KEY_CHANGE_DELAYis 256 epochs on mainnet and gnosis, and 8 on minimal so devnets can exercise key changes.Node
pq_key_registration, with the EIP's checks in its order:previous_change_epoch, a key already held, a builder deposit not yet finalized, the change delay, and a duplicate(index, previous_change_epoch).MAX_PQ_KEY_REGISTRATIONS * SLOTS_PER_EPOCH * 64entries.POST/GET /eth/v1/beacon/pool/pq_key_registrations,GET /eth/v1/beacon/states/{state_id}/pq_key_material?id=, and the SSE eventpq_key_registration. POST checks the registration against the head first, so a stale one gets a 400.Tooling.
lcli pq-key-registrationbuilds, signs and optionally submits a validator or builder registration.Also in this PR
engine_newPayloadV6instead of V5, and the mock EL requires V6 after Heze. Without this, a devnet's EL rejects every Heze payload while the CL keeps finalizing.cfg_select!.libz-sysis bumped to 1.1.31 (RUSTSEC-2026-0418), anddata-encoding-macro-internalresolves to syn 2 again forcargo deny.Additional Info
Testing
state_processing: every case in the EIP's test list, including builders, plus block-levelVerifyIndividual/VerifyBulk.beacon_chainharness tests: valid import, an invalid proof rejected on gossip import, a lost key race recovered after finalization, a key freed before finality surviving finalization, and range sync over segments with validator and builder registrations (one with a bad proof is rejected).kw/8450):process_pq_key_registration: 33.4M operations, 0 disagreements.make lintandcargo denyare clean.make run-ef-tests, mainnet and minimal, with and withoutfake_crypto) pass, Heze included.FORK_NAME=eip8450, the only failures are the same onesFORK_NAME=hezeshows. The bid,envelope_apiand network ones also fail onunstable:payload_bid_verificationtests.envelope_api.prepare_payloadand 1 block-production test in the spec-minimal suite.basic-simulatorpasses locally (2/2 runs). In CI it can fail with "Sync aggregate … was partial", which is a known upstream flake: 11 of the last 47 runs on sigp/lighthouse failed with the same error.Kurtosis campaign (local, minimal preset; ethrex
heze-devnet-3; Gloas at epoch 0, Heze at 2, Eip8450 at 4; 4 genesis builders)4e4c51eec: the prune fix was checked on chain, along with a regression pass.state_root, and the key material matched entry for entry.Known gaps / follow-ups
lcli. No EIP-8310 keystores, and builder registration needs a BLS key file (no builder mnemonic derivation).unstable): after Gloas checkpoint sync, the anchor's fork-choice node haspayload_received: false(proto_array_fork_choice.rs:628). Its children then fail withParentUnknown, and peers are penalised for about 3 minutes before the node recovers.