8 breaking releases
0.9.0 | Jul 8, 2023 |
---|---|
0.7.0 | Nov 5, 2021 |
#3 in #ssz
131,637 downloads per month
Used in 19 crates
(via snowbridge-beacon-primiti…)
475KB
3K
SLoC
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 struct
s and enum
s, 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.
Dependencies
~2–2.8MB
~66K SLoC