SSZ Specs

Simple Serialize (SSZ) is a serialization and hashing scheme used by Ethereum. This project is a reference implementation written in Python which serves as the official specifications.

Development

This project uses uv and just.

just check  # Run code quality checks
just fix    # Run code quality fixers
just test   # Run unit tests
just fill   # Generate reference tests

Tests

This project generates JSON reference tests, included in each release, that SSZ implementations can run to ensure compliance with the specifications.

Releases

Each release ships the eth-ssz-specs package on PyPI and the reference tests on the releases page, both built from the tagged commit.

pip install eth-ssz-specs

TAG=v0.1.0
curl -sSLO "https://github.com/ethereum/ssz-specs/releases/download/$TAG/ssz-test-vectors-$TAG.tar.gz"
curl -sSLO "https://github.com/ethereum/ssz-specs/releases/download/$TAG/ssz-test-vectors-$TAG.tar.gz.sha256"
sha256sum --check "ssz-test-vectors-$TAG.tar.gz.sha256"
tar -xzf "ssz-test-vectors-$TAG.tar.gz"   # extracts fixtures/

Types

Boolean

A true or false value.

Boolean(True)

Bit

A zero or one value.

Bit(1)

Byte

Eight bits of opaque data.

Byte(0xFF)

Uint8

An 8-bit unsigned integer.

Uint8(0xFF)

Uint16

A 16-bit unsigned integer.

Uint16(0xFFFF)

Uint32

A 32-bit unsigned integer.

Uint32(0xFFFFFFFF)

Uint64

A 64-bit unsigned integer.

Uint64(0xFFFFFFFFFFFFFFFF)

Uint128

A 128-bit unsigned integer.

Uint128(0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF)

Uint256

A 256-bit unsigned integer.

Uint256(0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF)

Vector

A fixed number of elements.

class Color(Vector[Uint8]):
    LENGTH = 3


Color(data=[255, 128, 0])

List

A variable number of elements up to a limit.

class Scores(List[Uint64]):
    LIMIT = 8


Scores(data=[10, 20, 30])

ByteVector

A fixed number of bytes.

class Serial(ByteVector):
    LENGTH = 4


Serial(b"\x01\x02\x03\x04")

ByteList

A variable number of bytes up to a limit.

class Message(ByteList):
    LIMIT = 32


Message(data=b"hello")

BitVector

A fixed number of bits.

class Weekdays(BitVector):
    LENGTH = 7


Weekdays(data=[1, 0, 0, 1, 0, 1, 0])

BitList

A variable number of bits up to a limit.

class Answers(BitList):
    LIMIT = 20


Answers(data=[1, 0, 1])

ProgressiveList

A variable number of elements with no limit.

class Temperatures(ProgressiveList[Uint16]):
    pass


Temperatures(data=[20, 21, 19])

ProgressiveBitList

A variable number of bits with no limit.

ProgressiveBitList(data=[1, 0, 1])

Container

A fixed set of named fields.

class Point(Container):
    x: Uint64
    y: Uint64


Point(x=1, y=2)

ProgressiveContainer

Named fields that keep their positions as the set changes.

class Square(ProgressiveContainer):
    ACTIVE_FIELDS = (1, 0, 1)

    side: Uint16  # position 0
    color: Uint8  # position 2


Square(side=0x1234, color=0x42)

Past a handful of positions, state the width and the gaps instead: ACTIVE_FIELDS = active_fields(width=46, gaps=(8, 9, 10, 28)).

CompatibleUnion

A choice between options that share one tree shape.

class Shape(CompatibleUnion):
    OPTIONS = {1: Square, 2: Circle}


Shape(selector=1, data=Square(side=0x1234, color=0x42))