1. Cl-SSZ
   1. Overview
   2. Features
   3. Requirements
   4. Installation
   5. Usage
   6. Testing
   7. Project Layout
   8. Contributing
   9. Author
   10. Copyright
   11. License

Cl-SSZ is a Common Lisp implementation of the Simple Serialize (SSZ) protocol used throughout the Ethereum consensus specifications. The library focuses on providing type definitions, serialization and deserialization routines, and the Merkle tree utilities required to compute SSZ hash tree roots.

• Implements core SSZ basic and composite types (boolean, uint, byte, list, vector, container, union, bitlist, bitvector).
• Supports SSZ serialization and deserialization with structured error conditions for precise failure reporting.
• Provides Merkleization helpers, including chunk packing, mix-in utilities, and `hash-tree-root` implementations for all supported types.
• Supplies test scaffolding that can ingest the official consensus-spec tests (phase0 / ssz_generic) for verification.

• Common Lisp implementation (SBCL is used during development).
• Quicklisp with the following systems available: `imnisen/iutils`, `flexi-streams`, `rove`, `str`, `alexandria`, `uiop`, `thnappy`.

1. Clone this repository and ensure it is visible to ASDF, for example by placing it in `~/quicklisp/local-projects/` or adding the path via `asdf:initialize-source-registry`.
2. Evaluate `(ql:quickload :cl-ssz)` to load the system and its dependencies.

Simple serialization and merkleization examples:

(ql:quickload :cl-ssz)

;; Create a uint32 type and value
(defparameter *uint32* (make-instance 'cl-ssz:typ-uint :n 32))
(defparameter *value* (make-instance 'cl-ssz:val-uint :n 32 :value 42))

;; Serialize / deserialize
(defparameter *serialized* (cl-ssz:serialize *value*))
(defparameter *roundtrip* (cl-ssz:deserialize *uint32* *serialized*))

;; Compute a hash tree root for a composite value
(defparameter *vector-typ*
  (make-instance 'cl-ssz:typ-vector
                 :element-typ cl-ssz:*typ-boolean*
                 :n 4))
(defparameter *vector-val*
  (make-instance 'cl-ssz:val-vector
                 :element-typ cl-ssz:*typ-boolean*
                 :n 4
                 :value (list (make-instance 'cl-ssz:val-boolean :value t)
                               (make-instance 'cl-ssz:val-boolean :value nil)
                               (make-instance 'cl-ssz:val-boolean :value t)
                               (make-instance 'cl-ssz:val-boolean :value nil))))
(defparameter *root* (cl-ssz:hash-tree-root *vector-val*))

The project uses Rove. To run the full regression suite:

1. Clone the official fixtures from https://github.com/ethereum/consensus-spec-tests/tree/master/tests/general/phase0/ssz_generic (or download that subtree) so that the SSZ test cases are available locally.

2. Set the `CL<sub>SSZTESTPATH</sub>` environment variable to the directory that contains those fixtures.

3. After loading the project, execute:

   (asdf:test-system :cl-ssz)

• `src/` contains the library source code, organised by SSZ type and support modules.
• `tests/` provides Rove-based regression tests and helpers for parsing the Ethereum fixtures.
• `README.md` is a minimal Markdown variant of this document.

Issues and pull requests are welcome. Please include tests or fixtures that demonstrate the behaviour being added or fixed when possible.

imnisen ([email protected])

Copyright (c) 2025 imnisen ([email protected])

This project is released under the MIT License.