libssz

A fast, zkVM-friendly Simple Serialize (SSZ) library for Ethereum consensus.

no_std + alloc from day one. Up to 2.9x faster than Lighthouse on BeaconState encode and decode. Validated against 63,385 official Ethereum consensus spec test cases across all 9 forks (phase0 through heze). Fuzz-tested against both reference implementations.

Performance

Benchmarked against Lighthouse (ethereum_ssz + tree_hash) and ssz_rs v0.9, --release with thin LTO.

Apple M3 Max (ARM)

Encode

Decode

BeaconState (21 fields, variable-length)

Hash Tree Root

AMD Ryzen 9 9950X3D (x86_64)

Encode

Decode

BeaconState (21 fields, variable-length)

Hash Tree Root

libssz beats Lighthouse on both BeaconState encode and decode at every validator count, and dominates on primitives and vectors. Full results: cargo bench --bench differential.

• Direct-write ContainerEncoder — variable data writes directly to the output buffer with no intermediate allocation. Fixed fields are patched in-place into a pre-allocated region. Eliminates the double-write that a separate variable buffer would cause
• All-fixed containers bypass ContainerEncoder/ContainerDecoder entirely — the derive macro generates direct field-by-field append/decode, eliminating heap allocations and offset bookkeeping
• Inlined bulk encode/decode — the derive macro generates ssz_append_fixed_slice and ssz_decode_fixed_vec overrides that inline per-field operations directly into the loop body, skipping per-item struct-level length checks
• Bulk memcpy for [u8; N] and integers — both encode and decode use a single memcpy on little-endian platforms instead of per-element iteration
• Aggressive inlining — #[inline(always)] on all trait impls that cross crate boundaries

Getting Started

Adding dependencies

Add libssz to your project from crates.io:

cargo add libssz libssz-derive libssz-merkle libssz-types

For no_std environments (zkVMs, WASM, embedded), disable default features and enable alloc:

cargo add libssz --no-default-features --features alloc
cargo add libssz-types --no-default-features --features alloc
cargo add libssz-merkle --no-default-features --features alloc
cargo add libssz-derive

Encode and decode

use libssz::{SszEncode, SszDecode};

let value: u64 = 42;
let encoded = value.to_ssz();
let decoded = u64::from_ssz_bytes(&encoded).unwrap();
assert_eq!(decoded, 42);

Derive macros

use libssz_derive::{SszEncode, SszDecode, HashTreeRoot};
use libssz::{SszEncode, SszDecode};
use libssz_merkle::HashTreeRoot;

#[derive(SszEncode, SszDecode, HashTreeRoot)]
struct BeaconBlockHeader {
    slot: u64,
    proposer_index: u64,
    parent_root: [u8; 32],
    state_root: [u8; 32],
    body_root: [u8; 32],
}

let header = BeaconBlockHeader {
    slot: 1,
    proposer_index: 0,
    parent_root: [0u8; 32],
    state_root: [0u8; 32],
    body_root: [0u8; 32],
};

let bytes = header.to_ssz();
let decoded = BeaconBlockHeader::from_ssz_bytes(&bytes).unwrap();
let root = header.hash_tree_root();

Bounded collections

use libssz_types::{SszVector, SszList, SszBitvector, SszBitlist};

// Vector: exactly 4 elements
let v = SszVector::<u64, 4>::try_from(vec![1, 2, 3, 4]).unwrap();

// List: at most 1024 elements
let mut l = SszList::<u64, 1024>::default();
l.push(42).unwrap();

// Bitvector: exactly 8 bits
let bv = SszBitvector::<8>::default();

// Bitlist: at most 64 bits
let mut bl = SszBitlist::<64>::default();
bl.push(true).unwrap();

Union types

use libssz_derive::{SszEncode, SszDecode, HashTreeRoot};

#[derive(SszEncode, SszDecode, HashTreeRoot)]
#[ssz(enum_behaviour = "union")]
enum ExecutionPayload {
    Bellatrix(BellatrixPayload),
    Capella(CapellaPayload),
    Deneb(DenebPayload),
}

no_std usage

Every crate works without the standard library. CI verifies no_std compilation against thumbv7m-none-eabi on every commit.

#![no_std]
extern crate alloc;

use libssz::{SszEncode, SszDecode};

fn encode_slot(slot: u64) -> alloc::vec::Vec<u8> {
    slot.to_ssz()
}

fn decode_slot(bytes: &[u8]) -> Result<u64, libssz::DecodeError> {
    u64::from_ssz_bytes(bytes)
}

Crates

Dependency graph: libssz-derive → libssz-merkle → libssz ← libssz-types

Supported Types

active_fields defaults to every field active. For a container with inactive (deprecated) fields, pass the configuration explicitly — each 1 takes the next field in declaration order:

#[derive(SszEncode, SszDecode, HashTreeRoot)]
#[ssz(progressive_container, active_fields = [1, 0, 1, 0, 1])]
struct Foo {
    a: u8,                  // active_fields[0]
    b: SszList<u16, 123>,   // active_fields[2]
    c: ProgressiveBitlist,  // active_fields[4]
}

Testing

make test                  # unit + integration tests
make test-alloc            # no_std + alloc only
make download-spec-tests   # download consensus spec vectors (~1.25GB, cached)
make spec-tests            # run 63,385 spec test cases (downloads if needed)
make fuzz-quick            # 10s smoke fuzz per target (19 targets)
make bench                 # criterion benchmarks
make ci                    # full CI pipeline locally

Consensus Spec Tests

The library is validated against the official Ethereum consensus spec test vectors (v1.7.0-alpha.13). This covers:

• ssz_generic: all SSZ primitive types, vectors, lists, bitfields, containers, progressive types (EIP-7916), progressive containers (EIP-7495), and compatible unions — valid and invalid cases
• ssz_static mainnet: all Ethereum consensus types (BeaconState, BeaconBlock, Attestation, etc.) across 9 forks (phase0, altair, bellatrix, capella, deneb, electra, fulu, gloas, heze) at mainnet parameters
• ssz_static minimal: same types at minimal preset parameters

Each test case verifies decode, re-encode roundtrip, and hash tree root correctness.

Fuzzing

Differential fuzz-tested against Lighthouse and ssz_rs across 19 fuzz targets, run nightly in CI.

Documentation

• Architecture — crate layout, dependency graph, design rationale
• Technical Design — trait design, encoding/decoding algorithms
• SSZ Spec Summary — concise reference of the spec as implemented

License

Licensed under either of

• Apache License, Version 2.0
• MIT License

at your option.