HomeEIPs
EIPsEIP-6475
EIP-6475

SSZ Optional

New SSZ type to represent optional values
DraftStandards Track: Core
Created: 2023-02-09
Etan Kissling (@etan-status), Zahary Karadjov (@zah)
DiscussionsOriginal linkEdit
1 min read

EIP-6475, titled "SSZ Optional," introduces a new Simple Serialize (SSZ) type to represent Optional[T] values. Currently, optional values can only be represented in SSZ using workarounds. This proposal aims to improve readability and compact serialization. The proposal introduces a new type definition, Optional[T], which can represent a value of SSZ type T or the absence of a value, indicated by None. The default value of Optional[T] is None. The serialization and deserialization of an Optional[T] depend on whether the value is None or not. If the value is None, the list length is 0 during Merkleization. Otherwise, the list length is 1, and the first list element contains the underlying value. The document also discusses the rationale behind not using Union[None, T] and List[T, 1] as alternatives. Union[None, T] leaves ambiguity about the intention whether the type may be extended in the future, i.e., Union[None, T, U]. The serialization of List[T, 1] is less compact for variable-length T due to the extra offset table at the beginning of the list to indicate the list length. The document mentions that there are no known backward compatibility issues or security considerations associated with this proposal. The test cases and reference implementation are yet to be determined.

Video
Anyone may contribute to propose contents.
Go propose
Original

Abstract

This EIP introduces a new Simple Serialize (SSZ) type to represent Optional[T] values.

Motivation

Optional values are currently only representable in SSZ using workarounds. Adding proper support provides these benefits:

  1. Better readability: SSZ structures with optional values can be represented with idiomatic types of the underlying programming language, e.g., Optional[T] in Python, making them easier to interact with.

  2. Compact serialization: SSZ serialization can rely on the binary nature of optional values; they either exist or they don't. This allows more compact serialization than using alternative approaches based on workarounds.

Specification

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.

Type definition

Optional[T] is defined as a type that can represent:

  • A value of SSZ type T
  • Absence of a value, indicated by None

Default value

The default value of Optional[T] is None.

Serialization

if value is None: return b"" else: return b"\x01" + serialize(value)

Deserialization

The deserialization of an Optional[T] depends on the input length:

  • If the input length is 0, the value is None.
  • Otherwise, the first byte of the deserialization scope must be checked to be 0x01, the remainder of the scope is deserialized same as T.

Merkleization

An Optional[T] is merkleized as a List[T, 1].

  • If the value is None, the list length is 0.
  • Otherwise, the list length is 1, and the first list element contains the underlying value.

Rationale

Why not Union[None, T]?

Union[None, T] leaves ambiguity about the intention whether the type may be extended in the future, i.e., Union[None, T, U].

Furthermore, SSZ Union types are currently not used in any final Ethereum specification and do not have a finalized design themselves. If the only use case is a workaround for lack of Optional[T], the simpler Optional[T] type is sufficient, and support for general unions could be delayed until really needed. Note that the design of Optional[T] could be used as basis for a more general Union.

Why not List[T, 1]?

The serialization is less compact for variable-length T, due to the extra offset table at the beginning of the list to indicate the list length.

Backwards Compatibility

Union[None, T] and List[T, 1] workarounds are not used at this time to represent Optional[T].

Test Cases

See EIP assets.

Reference Implementation

  • Python: See EIP assets, based on protolambda/remerkleable
  • Nim: status-im/nim-ssz-serialization

Security Considerations

None

Copyright and related rights waived via CC0.

Further reading
Anyone may contribute to propose contents.
Go propose
Adopted by projects
Anyone may contribute to propose contents.
Go propose

Not miss a beat of EIPs' update?

Subscribe EIPs Fun to receive the latest updates of EIPs Good for Buidlers to follow up.

View all
Serve Ethereum Builders, Scale the Community.
Resources
GitHub
Supported by