This EIP defines the changes needed to adopt ProgressiveContainer from EIP-7495 and ProgressiveList from EIP-7916 in consensus data structures. Only merkleization changes; serialization of affected types is unchanged.
Ethereum's consensus data structures make heavy use of Simple Serialize (SSZ) Container, which defines how they are serialized and merkleized. The merkleization scheme allows application implementations to verify that neither individual fields nor partial fields have been tampered with. This is useful, for example, in smart contracts of decentralized staking pools that wish to verify that participating validators have not been slashed.
While SSZ Container defines how data structures are merkleized, the merkleization is prone to change across the different forks. When that happens, e.g., because new features are added or old features get removed, existing verifier implementations need to be updated to be able to continue processing proofs.
EIP-7495 ProgressiveContainer is a forward compatible alternative that guarantees a forward compatible merkleization scheme. By transitioning consensus data structures to use ProgressiveContainer, smart contracts that contain verifier logic no longer have to be maintained in lockstep with Ethereum's fork schedule as long as the underlying features that they verify don't change. For example, as long as the concept of slashing is represented using the boolean slashed field, existing verifiers will not break when unrelated features get added or removed. This is also true for off-chain verifiers, e.g., in hardware wallets or in operating systems for mobile devices that are on a different software update cadence than Ethereum.
Further, replacing static List and Bitlist capacities with their progressive equivalents decouples operational limits from the SSZ schema. Limits become runtime checks that future EIPs can tune without affecting data types or Merkle proofs. That includes cross-operation constraints such as an overall shared signature-check budget.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 and RFC 8174.
Container conversionContainer types that are expected to evolve over forks SHALL be redefined as ProgressiveContainer(active_fields=[1] * len(type.fields())).
For example, given a type in the old fork:
This type can be converted to support stable Merkleization in the new fork:
As part of the conversion, a stable generalized index (gindex) is assigned to each field that remains valid in future forks.
active_fields MUST be extended with a trailing 1.active_fields bit MUST be changed to 0.CompatibleUnion[fork_1.Foo, fork_2.Foo, fork_3.Foo, ...] type in the unit test framework.List[type, N] / Bitlist conversionList types frequently have excessively large capacities that are never reached in practice, or capacities that have shifted across forks.
List types with dynamic or unbounded capacity semantics SHALL be redefined as ProgressiveList[type]Bitlist types with dynamic or unbounded capacity semantics SHALL be redefined as ProgressiveBitlistThe application logic SHALL be updated to check for an appropriate limit at runtime.
As part of the conversion, a stable generalized index (gindex) is assigned to each list element that remains valid regardless of the number of added elements.
For each affected libp2p gossip topic and req/resp chunk type, a constant SHOULD be defined specifying its maximum uncompressed serialized message size, derived from the pre-conversion capacity of the corresponding type. Where no such constant is defined for variable-size messages, MAX_PAYLOAD_SIZE applies.
The following types SHALL be converted to ProgressiveContainer:
Attestation
aggregation_bits field is redefined to use ProgressiveBitlistIndexedAttestation
attesting_indices field is redefined to use ProgressiveListExecutionPayloadHeaderExecutionPayload
transactions and withdrawals fields are redefined to use ProgressiveListMAX_TRANSACTIONS_PER_PAYLOAD (1M) limit is no longer enforcedTransaction is redefined as ProgressiveByteList
MAX_BYTES_PER_TRANSACTION (1 GB) limit is no longer enforcedExecutionRequests
deposits, withdrawals and consolidations fields are redefined to use ProgressiveListBeaconBlockBody
proposer_slashings, attester_slashings, attestations, deposits, voluntary_exits and bls_to_execution_changes fields are redefined to use ProgressiveListBeaconState
validators, balances, previous_epoch_participation, current_epoch_participation, inactivity_scores, pending_deposits, pending_partial_withdrawals and pending_consolidations fields are redefined to use ProgressiveListblob_kzg_commitments, kzg_proofs and column fields are redefined to use ProgressiveListThese types are used as part of the ProgressiveContainer definitions. As they are not ProgressiveContainer themselves, they are considered to have immutable Merkleization. If a future fork requires changing these types in an incompatible way, a new type SHALL be defined and assigned a new field name.
| Type | Description |
|---|---|
Slot | Slot number on the beacon chain |
Epoch | Epoch number on the beacon chain, a group of slots |
CommitteeIndex | Index of a committee within a slot |
ValidatorIndex | Unique index of a beacon chain validator |
Gwei | Amount in Gwei (1 ETH = 10^9 Gwei = 10^18 Wei) |
Root | Byte vector containing an SSZ Merkle root |
Hash32 | Byte vector containing an opaque 32-byte hash |
Version | Consensus fork version number |
BLSPubkey | Cryptographic type representing a BLS12-381 public key |
BLSSignature | Cryptographic type representing a BLS12-381 signature |
Fork | Consensus fork information |
Checkpoint | Tuple referring to the most recent beacon block up through an epoch's start slot |
Validator | Information about a beacon chain validator |
AttestationData | Vote that attests to the availability and validity of a particular consensus block |
Eth1Data | Target tracker for importing deposits from transaction logs |
DepositData | Log data emitted as part of a transaction's receipt when depositing to the beacon chain |
BeaconBlockHeader | Consensus block header |
SignedBeaconBlockHeader | Tuple of beacon block header and its signature |
ProposerSlashing | Tuple of two equivocating consensus block headers |
Deposit | Tuple of deposit data and its inclusion proof |
VoluntaryExit | Consensus originated request to exit a validator from the beacon chain |
SignedVoluntaryExit | Tuple of voluntary exit request and its signature |
ParticipationFlags | Participation tracker of a beacon chain validator within an epoch |
SyncAggregate | Cryptographic type representing an aggregate sync committee signature |
SyncCommittee | Aggregated sync committee public keys |
ExecutionAddress | Byte vector containing an account address on the execution layer |
WithdrawalIndex | Unique index of a withdrawal from any validator's balance to the execution layer |
Withdrawal | Withdrawal from a beacon chain validator's balance to the execution layer |
BLSToExecutionChange | Request to register the withdrawal account address of a beacon chain validator |
SignedBLSToExecutionChange | Tuple of withdrawal account address registration request and its signature |
HistoricalSummary | Tuple combining a historical block root and historical state root |
KZGCommitment | G1 curve point for the KZG polynomial commitment scheme |
AttesterSlashing | Tuple of two slashable attestations |
DepositRequest | Tuple of flattened deposit data and its sequential index |
WithdrawalRequest | Execution originated request to withdraw from a validator to the execution layer |
ConsolidationRequest | Execution originated request to consolidate two beacon chain validators |
PendingDeposit | Pending operation for depositing to a beacon chain validator |
PendingPartialWithdrawal | Pending operation for withdrawing from a beacon chain validator |
PendingConsolidation | Pending operation for consolidating two beacon chain validators |
Once a field in a ProgressiveContainer has been published, its name can no longer be used to represent a different type in the future. This is in line with historical management of certain cases:
BeaconState contained previous_epoch_attestations / current_epoch_attestationsBeaconState replaced these fields with previous_epoch_participation / current_epoch_participationFurthermore, new fields have to be appended at the end of ProgressiveContainer. This is in line with historical management of other cases:
historical_summaries to BeaconState instead of squeezing the new field next to historical_rootsdeposit_requests_start_index to BeaconState rather than putting it next to the eth1_deposit_index mechanism that it replacedWith ProgressiveContainer, stable Merkleization requires these rules to become strict.
Validator is deliberately kept as Container:
Validator uses ProgressiveContainer, allowing the transition to restructure the type freely.ProgressiveContainer adds hashing overhead per validator, which scales to millions of additional hashes.historical_roots and historical_summaries are deliberately kept as List types. historical_roots has been frozen since Capella, and historical_summaries is actively used by verifiers proving against its hash_tree_root; converting either of them now would add churn or break verifiers without sufficient benefit. A future EIP can address both, potentially consolidating them into a single accumulator alongside related cleanups.
While ProgressiveContainer / ProgressiveList serialize in the same way as Container / List, the merkleization and hash_tree_root of affected data structures changes. Therefore, verifiers that process historical data predating this EIP still need to support the original merkleization scheme.
Existing Merkle proof verifiers need to be updated to support the new Merkle tree shape. This includes applicable verifiers in smart contracts on different blockchains and hardware wallets.
Serialization of affected types and libp2p network message size limits are unchanged by this EIP. Message rejection behavior previously derived from type-specific SSZ bounds is preserved by newly defined per-message bounds constants.
Copyright and related rights waived via CC0.