isabella232 / eth2.0-ssz

Draft of SSZ specs repo

Eth 2.0 - Simple Serialize

Simple Serialize (SSZ) is a standard for the encoding and merkleization of structured data, designed for ETH 2.0.

Index

• General
• Types
  • Basic types
  • Bitfields
    • Bitvector
    • Bitlist
  • Complex
    • Vector
    • List
    • Container
  • Union
• Representation
  • Fixed and variable size
  • Sequences
• Merkleization
  • Hashing
  • Merkle proofs
  • Chunkify
  • Merkle mix-ins
  • Subtree Merkleization
  • Merkle proof backings
    • Classic
    • Tree offsets (WIP)
    • More (Turboproofs/Simple-token proofs/etc.)
• Navigation
  • Generalized indices
  • Paths
  • Summaries and expansions
• Partials

Design

Because of resource constraints (both space and speed) and a niche use-case for many interactions with merkleized data, existing encodings were abandoned in favor of SSZ on the ETH 2.0 stack.

The design choices for SSZ originate from the desire for:

• Efficiency and Elegance in proof structures with binary trees, and a design that separates opinionated sparse structures from merkleization, learning from issues in ETH 1.0.
• Consistency in a wide range of use-cases for minimal and efficient encoding and proofs in the core of ETH 2.0, as well as the layers being built on top.
• Flexibility and Transparency for tracing proofs through history, building shallow variants of types, or proofs to linked data such as between ETH 2.0 shards.
• Stability of proof data for stateless light clients and smart contracts. These can count on deterministic and stable locations of merkle tree leaves of interest.
• Fast data reads by making full deserialization optional, data can be retrieved with a very minimal amount of operations, largely pre-computable at compile time.

Minimalism and advanced use cases are almost orthogonal. To work around this, this SSZ specification maintains a strong separation of the different stack elements, and a feature introduction model with stages.

Feature stages

Features are introduced by progressing through stages, alike to the TC39 Process implemented by EcmaScript.

In summary, this translates to:

0. Strawperson Allow input into the specification
1. Proposal
   • Make the case for the addition
   • Describe the shape of a solution
   • Identify potential challenges
2. Draft Precisely describe the syntax and semantics.
3. Candidate Indicate that further refinement will require feedback from implementations and users.
4. Finished Indicate that the addition is ready for inclusion.

Implementations can build on the stable stage, and offer support for unfinished feature stages separately.

The proposals, drafts, candidates and finished documents are discussed through issues and PRs on GitHub, along with the relevant ETH 2.0 communication channels.

The Strawperson stage is only applicable to open PRs, and will need to become a rounded Proposal before being merged.

One difference with the regular process is that since SSZ is not widely running in production yet, and features have been modeled already, but not formally verified yet, the spec is more welcoming to some types of modifications:

• Language, cosmetics, examples and references in any spec document may still change
• Spec documents may be merged or split, to aid in the organization process of the SSZ spec as a whole.

Once finished however, the effective functionality does not change without an upgrade path for implementers.

Implementations

Language	Project	Maintainer	License	Status	Features / Notes	Implementation
Python	Eth 2.0	Ethereum Foundation	CC0	Spec	Spec
Go	ZRNT	Diederik Loerakker (@protolambda)	MIT	Active	Unsafe Go, fast, streaming	protolambda/zssz
Go	ZRNT	Diederik Loerakker (@protolambda)	MIT	Active	Generic, caching, datasharing	protolambda/ztyp
Go	Prysm	Ferran Borreguero (@ferranbt)	MIT	Active	Code-gen, fast	ferranbt/fastssz
Java	Teku	Consensys/PegaSys Eng.	Apache-2.0	Active	Caching, datasharing	PegaSysEng/teku/ssz
Nim	Nimbus	Status	MIT and Apache-2.0	Active	In-place decode, Caching	status-im/nim-beacon-chain/ssz.nim
Python	Trinity	Ethereum Foundation	MIT	Active	Pyrsistent, partial caching	ethereum/py-ssz
Python	Pyspec / Eth2.py	Diederik Loerakker (@protolambda)	MIT	Active	Datasharing, caching, streaming	protolambda/remerkleable
Rust	Lighthouse	Sigma Prime	Apache-2.0	Active	Partial caching, fast	sigp/lighthouse/ssz
Typescript	Lodestar	Chainsafe Systems	LGPL-v3.0	Active	Both Tree & structural, caching	ChainSafe/lodestar/ssz
C#	Cortex	Sly Gryphon (@sgryphon)	LGPL-v3.0	Under construction	Experimental	sgryphon/cortex-ssz
Go	Prysm	Prysmatic Labs	MIT	Deprecated	Generic, reflection, known bugs	prysmaticlabs/go-ssz
Java	Harmony	Harmony	Apache-2.0	Deprecated	Partially merged into Teku	harmony-dev/beacon-chain-java/ssz
TypeScript	Lodestar	ChainSafe Systems	Apache-2.0	Archived	See new Lodestar SSZ	ChainSafe/ssz-js
Rust	Shasper	ParityTech	GPL-3.0	Discontinued	No updates	paritytech/shasper/ssz
Swift	Yeeth	Dean Eigenmann (@decanus, @yeeth)	MIT	Discontinued	Incomplete	yeeth/SimpleSerialize.swift
Java	Cava	ConsenSys	Apache-2.0	Discontinued	Outdated, incomplete	ConsenSys/cava/ssz

License

CC0 1.0 Universal. See License file.