104 lines
3.4 KiB
Markdown
104 lines
3.4 KiB
Markdown
|
---
|
||
|
|
eip: 6475
|
||
|
|
title: SSZ Optional
|
||
|
|
description: New SSZ type to represent optional values
|
||
|
|
author: Etan Kissling (@etan-status), Zahary Karadjov (@zah)
|
||
|
|
discussions-to: https://ethereum-magicians.org/t/eip-6475-ssz-optional/12891
|
||
|
|
status: Draft
|
||
|
|
type: Standards Track
|
||
|
|
category: Core
|
||
|
|
created: 2023-02-09
|
||
|
|
---
|
||
|
|
|
||
|
|
## Abstract
|
||
|
|
|
||
|
|
This EIP introduces a new [Simple Serialize (SSZ) type](https://github.com/ethereum/consensus-specs/blob/67c2f9ee9eb562f7cc02b2ff90d92c56137944e1/ssz/simple-serialize.md) 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 ideomatic 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`.
|
||
|
|
|
||
|
|
### Illegal types
|
||
|
|
|
||
|
|
`Optional[T]` with `T` that might serialize to empty data `[]` are illegal:
|
||
|
|
|
||
|
|
- `T` MUST NOT be `List[type, N]`
|
||
|
|
- `T` MUST NOT be a nested `Optional[type]`
|
||
|
|
|
||
|
|
### Serialization
|
||
|
|
|
||
|
|
```python
|
||
|
|
if value is None:
|
||
|
|
return b""
|
||
|
|
else:
|
||
|
|
return 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, deserialize the input as if it represents a value of type `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]`?
|
||
|
|
|
||
|
|
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 `Optional[T]`, the simpler `Optional[T]` type is sufficient, and support for general unions could be delayed until really needed.
|
||
|
|
|
||
|
|
`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 is less compact, due to the extra selector byte.
|
||
|
|
|
||
|
|
### 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](../assets/eip-6475/tests.py).
|
||
|
|
|
||
|
|
## Reference Implementation
|
||
|
|
|
||
|
|
- **Python:** See [EIP assets](../assets/eip-6475/optional.py), based on `protolambda/remerkleable`
|
||
|
|
- **Nim:** `status-im/nim-ssz-serialization`
|
||
|
|
|
||
|
|
## Security Considerations
|
||
|
|
|
||
|
|
None
|
||
|
|
|
||
|
|
## Copyright
|
||
|
|
|
||
|
|
Copyright and related rights waived via [CC0](../LICENSE.md).
|