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

After EIP-8016

Who is affected

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.

Original EIP · ← EIPs