EIP-8310 A quantum-resistant keystore for stateful keys (Post-Quantum Keystore for Stateful Keys)
No call decision · Security & privacy · EIP status Draft · created 2026-06-19
Defines keystore version 5, which holds quantum-resistant XMSS signing keys. Given the property that a key is consumed with every signature, it also specifies where signing position is managed and how the key is safely moved.
Why it is needed
Validator keys today are BLS keys held in an ERC-2335 keystore. This key never changes no matter how many times it signs, so the key itself stays safe even if the file is copied or restored from a backup. But Lean Ethereum switches validator keys to XMSS, a hash-based signature scheme, to prepare for quantum computers. XMSS consumes one one-time signing slot, called a leaf, per signature, and signing two different messages with the same leaf makes forgery possible, effectively destroying the key. This single property makes all three behaviors that were previously taken for granted - the file never changes, copying is harmless, and restoring from any backup is safe - dangerous. Because the existing keystore spec never assumed this kind of consumable key, merely changing the encrypted container is not enough; a new format is needed that also defines where signing state is managed and in what order it is stored.
What changes
Today
- A keystore file never changes once created
- Copying a BLS key to two machines and running both does not corrupt the key itself
- A key can be used to sign immediately after restoring from any backup
- Having just a single keystore file is enough to start signing
After EIP-8310
- With an XMSS key, state advances with every signature, and that state is managed by an authoritative store outside the file
- For multiple signers to use the same key, each must be assigned a non-overlapping leaf range
- If restored to an old state, the client detects the high-water-mark regression and refuses to sign
- A keystore file alone allows only key recovery and verification; resuming signing requires the latest authoritative state
Who is affected
- Validator operator: Backup and restore procedures change. A seed backup can recover the key, but resuming signing directly from an old state snapshot is forbidden; signing is allowed only after reconciling with the latest authoritative state.
- Client teams: Implementations must support version 5 keystores, the commit-then-sign ordering, and atomic import/export that moves the XMSS key together with its slashing-protection history as a single unit.
- Builders and signing services: Out-of-protocol signatures not tied to a slot (such as builder bids) use counter mode and reserved leaf ranges so that a single global counter does not become a bottleneck.
- Key management tool developers: Starting to sign after importing a key without its state must be blocked as a hard error, not a warning.
In depth
Version 5 file format and cryptographic hardening
This EIP defines keystore version 5. v5 is v4 (ERC-2335) plus changes. crypto.cipher.function must be AEAD or a 256-bit construction (MUST), aes-256-gcm is recommended, and v4's aes-128-ctr is forbidden in v5 (MUST NOT). crypto.kdf.function may use argon2id in addition to the existing scrypt and pbkdf2, with parameters following current memory-hardness guidance. This cryptographic hardening is only a precaution against the Grover algorithm, and the original text states explicitly that this EIP's essence is not cryptography but the state management of a consumable key. crypto.cipher.message holds an encrypted XMSS seed instead of an extended private key, and the file stores only the material needed to recover the key, not the live signing state.
scheme object: signature scheme parameters
The newly added scheme object records the signature scheme and its parameters. scheme.name identifies the scheme, as with leanxmss, and a reader that does not recognize it must refuse to use the keystore (MUST). scheme.params must contain all parameters needed to regenerate the public key and verify signatures, and cannot be changed after creation. The recommended production parameters are tree_height 32, hypertree_layers 1 (a single-tree Generalized XMSS), encoding target_sum, winternitz_w 8, dimension 46, target_sum 200, giving lifetime_leaves = 2^(tree_height x hypertree_layers) = 4294967296, i.e. a lifetime of 2^32. This matches leanSig's SIGAbortingTargetSumLifetime32Dim46Base8 instance. The format is hash-agnostic, with a Poseidon1 hash over the KoalaBear field being evaluated as the recommended instance; the concrete choice is recorded in the hash field. index_mode must be either synchronized or counter.
The state snapshot is reference only
The state object is a snapshot included so operators can see capacity at a glance. state.authoritative must be false within the keystore file, and this file must not be referenced as the high-water mark at signing time (MUST NOT). state.authority must be one of slashing-protection, external, or embedded, and must match index_mode: slashing-protection for synchronized, external (a dedicated state store) for counter. embedded is reserved, intended only for self-contained single-signer tools, and should not be used for production validator keys (SHOULD NOT), since doing so breaks the file's immutability. capacity and high_water are informational only; consumers must treat the authoritative store, not these fields, as the binding reference. Because putting a mutable field in a portable file becomes a reuse trap, the design is to show it for visibility while denying it any role at signing time.
State authority: coupling with the slashing-protection DB
A signer must reference and advance a single authoritative state when producing a signature (MUST). In synchronized mode, the authoritative state is the EIP-3076 slashing-protection database. Because the leaf consumed is determined by f(epoch) or f(slot), refusing to sign the same slot twice is identical to refusing to reuse the same leaf. The original text explains that this identity is made normative rather than coincidental, and justifies it by noting that building a separate state mechanism would create two sources of truth that could diverge, which would be the worst outcome. Implementations must bind the XMSS key and its slashing-protection history as an inseparable unit, so that the history moves atomically together with the key whenever it is moved, imported, or exported. In counter mode, a dedicated store keyed by the keystore uuid holds the current counter and must provide the same durability and atomicity guarantees.
Commit-then-sign: an ordering that avoids reusing a leaf even after a crash
For every signature, an implementation must follow this order: (1) determine the candidate leaf index, (2) verify it is strictly greater than the authoritative high-water mark (in synchronized mode, confirm the slot/epoch has not already been signed), (3) write and flush the advanced high-water mark (fsync or a platform equivalent) and commit it via an atomic rename or an equivalent atomic transaction, (4) compute the signature, (5) return the signature to the caller. Exporting the signature before the state advance is durably committed is a violation, because a crash between return and persistence would cause the index to be reused on restart. Step 3 must complete before step 5, and steps 3 and 4 may be reordered relative to each other, but neither may precede step 2. The original Rationale states that this is the only ordering rule that prevents crash-induced reuse, and that the rest of the spec is bookkeeping around it.
Reserved leaf ranges: supporting concurrent signers
For concurrent or high-throughput signers, a keystore may partition the leaf space into non-overlapping reserved ranges (MAY). Each range has an id, start, end, and high_water; a signer assigned a range must consume only indices within [start, end] and must maintain its own authoritative high-water mark for that range per the ordering rule in section 4. A single range must not be assigned to two signer instances at once (MUST NOT), and once a range is exhausted, the signer must refuse to sign rather than borrow another range or wrap back to the start (MUST). The original text recommends this mechanism for the case of exhaustion in builder-bid signing, where a single global counter would face heavy contention. The Security Considerations also warn that running the same key on two hosts without separate reserved ranges guarantees reuse.
Distinguishing recovery from resuming signing
This EIP separates two operations that existing tools conflated. Recovery regenerates the hypertree from the encrypted seed and derives the public key, and is always safe with just the keystore file. Resuming signing requires the latest authoritative state and is not safe with the file alone. Therefore signing must not begin from a keystore lacking authoritative state, and importing with empty state must be a hard error, not a warning. Exporting a consumable key must include or reference the authoritative state, and when exporting the file alone, it must be marked as recovery/verification only so that no consumer signs with it. The most catastrophic case is restoring together with an old state snapshot; implementations must detect a regression in the high-water mark and refuse to sign until reconciled with the latest authoritative state. The Security Considerations stress that leaf reuse can silently and completely compromise a key with no immediate on-chain penalty, and that restoring from stale state is the dominant operational risk.
Still in draft stage
This EIP's status is Draft, and its contents may change. Test cases and a reference implementation are planned for addition later; the original text lists as tests at minimum a seed encrypt/decrypt round trip, refusing to sign on high-water-mark regression, crash injection between signature computation and state persistence, and checks for the separation and exclusive assignment of reserved ranges. Whether to mandate synchronized mode only for protocol keys and restrict counter mode to dedicated signing services remains an open discussion item. On backward compatibility, v5 is not compatible with v4 consumers, and a v5-aware client must refuse to treat a consumable key as if it were a reusable v4-style key, while existing v4 BLS keystores remain valid under their own standard. There is no core developer call decision yet on fork inclusion.