ferranbt / 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

• 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.

Conceptual dependency graph

The SSZ specification has the following general architecture:

Note that for Types and Merkle proof backings, different options exist, and the specifications building for each of the options may not all be complete, or in the same standardization stage.

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 using formal spec language
3. Candidate Indicate that further refinement will require feedback from implementations and users
4. Finished Indicate that the addition is ready for inclusion in the formal ECMAScript standard

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.

Implementations

Language	Project	Maintainer	License	Status	Implementation
Python	Eth 2.0	Ethereum Foundation	CC0	Spec
Go	Prysm	Prysmatic Labs	MIT	Active	prysmaticlabs/go-ssz
Go	ZRNT	Diederik Loerakker (@protolambda)	MIT	Active	protolambda/zssz
Go	-	Ferran Borreguero (@ferranbt)	MIT	Active	ferranbt/fastssz
Java	Artemis	Consensys/PegaSys Eng.	Apache-2.0	Active	PegaSysEng/artemis/util
Java	Harmony	Harmony	Apache-2.0	Active	harmony-dev/beacon-chain-java/ssz
Nim	Nimbus	Status	MIT and Apache-2.0	Active	status-im/nim-beacon-chain/ssz.nim
Python	Trinity	Ethereum Foundation	MIT	Active	ethereum/py-ssz
Rust	Lighthouse	Sigma Prime	Apache-2.0	Active	sigp/lighthouse/ssz
Rust	Shasper	ParityTech	GPL-3.0	Active	paritytech/shasper/ssz
Typescript	Lodestar	Chainsafe Systems	LGPL-v3.0	Active	ChainSafe/lodestar/ssz
C#	Cortex	Sly Gryphon (@sgryphon)	LGPL-v3.0	Under construction	sgryphon/cortex-ssz
TypeScript	Lodestar	ChainSafe Systems	Apache-2.0	Archived	ChainSafe/ssz-js
Java	Cava	ConsenSys	Apache-2.0	Archived	ConsenSys/cava/ssz
Swift	Yeeth	Dean Eigenmann (@decanus, @yeeth)	MIT	Incomplete	yeeth/SimpleSerialize.swift
C#	-	Jordan Andrews (@codingupastorm)	MIT	Discontinued	codingupastorm/csharp-ssz
C++	-	Jiyun Kim (@NAKsir-melody)	-	Discontinued	NAKsir-melody/cpp_ssz

License

CC0 1.0 Universal. See License file.