This EIP introduces a new Simple Serialize (SSZ) type to represent containers with forward-compatible Merkleization: A given field is always assigned the same stable generalized index (gindex) even when different container versions append new fields or drop existing fields.
SSZ containers are frequently versioned, for example across fork boundaries. When the number of fields reaches a new power of two, or a field is removed or replaced with one of a different type, the shape of the underlying Merkle tree changes, breaking verifiers of Merkle proofs for these containers. Deploying a new verifier may involve security councils to upgrade smart contract logic, or require firmware updates for embedded devices. This effort is needed even when no semantic changes apply to the fields that the verifier is interested in.
Progressive containers address these shortcomings by:
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.
ProgressiveContainer(active_fields)A new SSZ composite types is defined:
progressive container: ordered heterogeneous collection of values with stable Merkleization
The default value is defined as:
| Type | Default Value |
|---|---|
ProgressiveContainer(active_fields) | [default(type) for type in progressive_container] |
The following types are considered illegal:
ProgressiveContainer with no fields are illegal.ProgressiveContainer with an active_fields configuration of more than 256 entries are illegal.ProgressiveContainer with an active_fields configuration ending in 0 are illegal.ProgressiveContainer with an active_fields configuration with a different count of 1 than fields are illegal.Serialization of ProgressiveContainer(active_fields) is identical to Container.
Deserialization of ProgressiveContainer(active_fields) is identical to Container.
The canonical JSON mapping is updated:
| SSZ | JSON | Example |
|---|---|---|
ProgressiveContainer(active_fields) | object | { "field": ... } |
The SSZ Merkleization specification is extended with two helper functions:
get_active_fields(value), where value is of type ProgressiveContainer(active_fields): return active_fields.mix_in_active_fields: Given a Merkle root root and an active_fields configuration return hash(root, pack_bits(active_fields)). Note that active_fields is restricted to ≤ 256 bits.The Merkleization definitions are extended.
mix_in_active_fields(merkleize_progressive([hash_tree_root(element) for element in value]), get_active_fields(value)) if value is a progressive container.active_fields limited to 256 bits?256 bits (1 word) allows the mix-in to be simple, consistent with the length mix-in for lists, and is practically sufficient. An alternate design with a ProgressiveBitlist mix-in was explored, however deemed too over-engineered as it would effectively require introducing caches to pre-compute the mix-in's hash_tree_root to avoid repeated computations, and also makes verifier logic more complex than necessary.
Even though the 256 field limit includes all fields (including deprecated ones), it is unlikely that many progressive containers come close to reach 256 fields (BeaconState currently reaches around 40 fields). If that happens, one can add a more field with a nested ProgressiveContainer.
ProgressiveContainer an illegal type?It would result in 0-length serialization, meaning that the length of a list of such a container cannot be determined from the serialization.
Optional[type]?Introducing Optional is not required by any current functionality and is deferred to a future EIP.
The active_fields bitvector can be updated to also indicate optionality. Further, serialization for sparse lists should be explored.
ProgressiveContainer(active_fields) is a new SSZ type and does not conflict with existing types.
ethereum/remerkleable contains static tests in test_impl.py and test_typing.py.ethereum/consensus-specs releases contain random tests in tests/general/phase0/ssz_generic, generated according to a format defined in tests/format/ssz_generic.See ethereum/remerkleable.
Light client based verifiers and smart contracts (e.g., based on EIP-4788) do not update at the same cadence as Ethereum. If a future fork removes a field from a ProgressiveContainer(active_fields), the active_fields mix-in enables such verifiers to distinguish absent fields from 0 values. Without active_fields, the hash_tree_root for these cases would collide.
Copyright and related rights waived via CC0.