ssz_rs ✂️️

An implementation of the SSZ serialization scheme defined in the consensus-specs repo.

This repo aims to remain lightweight and relatively free-standing, rather than coupled to other ethereum consensus code/dependencies.

🚧 WARNING 🚧

This implementation has not been audited for security and is primarily intended for R&D use cases.

If you need a battle-tested implementation (e.g. for consensus-critical work), refer to the Lighthouse implementation.

Features

To conform to the SSZ spec, a given Rust type should implement the SimpleSerialize trait. Types implementing this trait then obtain:

Encoding / decoding

This library provides routines to serialize from and deserialize into a Rust type to/from the corresponding SSZ data via the Serialize and Deserialize traits.

Merkleization

This library provides the hash tree root computation for types implementing Merkleized.

• NOTE: more sophisticated hashing strategies are possible, users may run into memory or performance issues with the current implementation.

Multiproofs

This library provides the ability to reason about generalized indices for a given SSZ definition, along with the ability to generate and verify proofs of data at those indices.

• NOTE: still under construction

no-std feature

This library is no-std compatible. To build without the standard library, disable the crate's default features.

For example, in Cargo.toml:

ssz_rs = { version = "...", default-features = false }

Custom types

This library attempts to provide as minimal an interface over the native Rust types as possible when implementing SSZ types. For example, the uint64 type from the SSZ spec is represented by Rust's native u64 type.

The library also provides custom types for List, Vector, Bitlist and Bitvector following the SSZ spec. Each of these custom types should behave approximately like Rust's Vec type. A notable exception is deferring to the underlying type's iteration capabilities; e.g. to iterate a List you must explicitly call .iter().

For safety, there are only a few ways to construct an instance of each of these custom types:

• Default::default

• TryFrom::try_from

• ssz_rs::Deserialize

Moreover, the ssz_rs_derive package provides macros to derive the encoding and decoding routines for SSZ containers and unions (represented as Rust structs and enums, respectively).

Examples

See the examples for example usage of the facilities of this library.

Testing

This repo includes a copy of the ssz_generic consensus spec tests as integration tests for the ssz_rs package, along with hand-written unit tests. The integration tests are generated via a utility under ssz-rs-test-gen package. See the README there for further details.