EIP-8016 SSZ CompatibleUnion
No call decision · Scaling & data · EIP status Draft · created 2025-08-28
Defines a new SSZ type, CompatibleUnion, that holds one of several variants. It guarantees that, regardless of which variant is chosen, common fields always occupy the same position (gindex) in the Merkle tree.
Why it is needed
In Ethereum, there are cases, such as transactions, where one kind of data exists as several variants with slightly different functionality. In these cases it is desirable for the common fields shared across variants to be provable and verifiable in the same way. However, in the current SSZ (Simple Serialize), when several versions of a container exist at once, the generalized index (gindex), the position number within the Merkle tree, can differ between versions even for the same field. This means that whoever verifies a proof must separately maintain a mapping between fields and gindexes for each version, and update that mapping every time a new version appears. This adds unnecessary complexity for verifiers and accumulates maintenance burden. CompatibleUnion restricts merkleization to only group type options that are mutually compatible, so that no matter which option is chosen, the same field always sits at the same gindex. In addition, thanks to the selector tag, a parser can learn the tree shape of the data early, making deserialization efficient.
What changes
Today
- Even for the same field, the gindex can differ between container versions
- Proof verifiers must continually maintain a mapping of fields to gindexes for each version
- The existing SSZ union proposal was only used in a deprecated specification
After EIP-8016
- Common fields keep the same gindex across all type options
- Verifiers can verify common fields without a per-version mapping table
- A 1-byte selector immediately identifies which variant it is, enabling deserialization
Who is affected
- Client teams: Must implement serialization, deserialization, and merkleization logic for the new SSZ type, and add defenses against invalid input
- SSZ library developers: Must add the CompatibleUnion type and tests to libraries such as remerkleable
- Proof verification logic developers: Verification code no longer needs to be revised per version even as variants grow
- Portal Network: The existing union concept used for network types can be switched over to this proposal in a new networking version
In depth
Type definition and illegal type rules
CompatibleUnion({selector: type}) is a new SSZ composite type that holds one of the given subtypes. The notation pairs selector numbers with types, as in CompatibleUnion({1: Square, 2: Circle}). Even if every type option has the same fixed length, this type is always treated as variable-size. There is no defined default value; using one is an error. The following are illegal types: a CompatibleUnion({}) with no type options at all, one whose selector falls outside the range uint8(1) to uint8(127), and one where some type option is not merkleization-compatible with another option.
Rules for determining merkleization compatibility
Which type options can be grouped together is defined by explicit rules. A type is compatible with itself. byte and uint8 are compatible with each other. Bitlist[N] and Bitvector[N] are compatible if they have the same capacity N. List[type, N] and Vector[type, N] are compatible if their element types are compatible and N is the same. ProgressiveList[type] is compatible if its element type is compatible. A Container is compatible if the field names and order match and all field types are compatible. ProgressiveContainer(active_fields) is compatible if every field corresponding to a 1 entry in active_fields on both sides has the same name and a compatible type, and no field name outside that set overlaps between the two. Two CompatibleUnions are compatible if all of their type options are mutually compatible with each other. All other types are incompatible.
Serialization, deserialization, and JSON mapping
A value has value.data, the contained data, and value.selector, which indicates the chosen type option. Serialization is value.selector.to_bytes(1, "little") + serialize(value.data). Deserialization reads the first byte of the range as the type selector and deserializes the remainder as the selected type. Implementations must guard against four kinds of invalid input: a selector out of range, incomplete data lacking even one selector byte, corrupted or malformed serialized data, and invalid serialization of the inner type (delegated to that type's own deserialization). In JSON it is represented as an object of the form { "selector": string, "data": type }, where the contents of data depend on the selector.
mix_in_selector and root uniqueness
A helper function, mix_in_selector, is added to the merkleization specification. It takes a Merkle root root and a selector serialized as uint8, and returns hash(root, selector). The hash tree root of a CompatibleUnion value is mix_in_selector(hash_tree_root(value.data), value.selector). This selector mixing guarantees a distinct, unique hash_tree_root when multiple type options share the same Merkle tree shape, or when options differ only in the element type of a List[type, N] or ProgressiveList[type] field (since the hash tree root of an empty list does not depend on the element type). Without the selector, such cases would have to be defined as illegal types, or handled in application logic by mixing into the signing root or placing the element type in a separate field.
Selector range and rationale for the design choices
Selector 0 is reserved to prevent problems arising from incomplete initialization, and may be used in a future EIP to mark field optionality. Values above 127 (those with the top bit set) are reserved for future backwards-compatible extensions. The range 1 through 127 is sufficient for current needs. An alternative design that exports the active_fields bitvector directly for field collections was also considered, but when ProgressiveContainers are nested, the parser cannot determine the full tree shape up front, making parsing very inefficient, and the bitvector forces every nesting level to be variable-size, adding significant overhead to the serialized format. CompatibleUnion exports a tag so the parser can know in advance what to expect even in nested fields. Note that wrapping an existing field in a CompatibleUnion is not a backwards-compatible change. However, since adding a new option or removing an existing option does not break verifiers, CompatibleUnion should be adopted from the start, even with only a single type option, wherever future expansion is expected.
Relationship to the existing union proposal
CompatibleUnion is an alternative to the earlier union proposal that was in the SSZ specification. That earlier proposal was only used in the now-abandoned sharding specification. The Portal Network also uses a union concept for its network types, but does not apply hash_tree_root to it there, so it could switch to this CompatibleUnion proposal in a new networking version. Testing includes static tests in test_impl.py and test_typing.py in ethereum/remerkleable, as well as randomized tests included in tests/general/phase0/ssz_generic in ethereum/consensus-specs releases. The reference implementation is ethereum/remerkleable.
Current status: Draft
This EIP was created on August 28, 2025 and is currently in Draft status. Since the specification is not yet finalized, details such as the selector range, compatibility rules, and JSON mapping may still change. The provided core developer call records contain no fork-inclusion decision for this EIP.