justinpage / go-ssz

Simple Serialize (SSZ)

This package implements simple serialize algorithm specified in official Ethereum 2.0 spec.

API

Our simple serialize API is designed to match the popular JSON marshal/unmarshal API from the Go standard library

// Marshal val and output the result.
func Marshal(val interface{}) ([]byte, error)

// Unmarshal data from input and output it into the object pointed by pointer val.
func Unmarshal(input []byte, val interface{}) error

Tree Hashing

// HashTreeRoot SSZ marshals a value and packs its serialized bytes into leaves of a Merkle trie -
// then, it determines the Merkle root of the trie.
func HashTreeRoot(val interface{}) ([32]byte, error)

Usage

Say you have a struct like this

type exampleStruct1 struct {
    Field1 uint8
    Field2 []byte
}

Now you can encode this object like this

e1 := exampleStruct1{
    Field1: 10,
    Field2: []byte{1, 2, 3, 4},
}
encoded, err := Marshal(e1)
if err != nil {
    return fmt.Errorf("failed to marshal: %v", err)
}

One can also specify the specific size of a struct's field by using ssz-specific field tags as follows:

type exampleStruct struct {
    Field1 uint8
    Field2 []byte `ssz:"size=32"`
}

This will treat Field2 as as [32]byte array when marshaling. For unbounded fields or multidimensional slices, ssz size tags can also be used as follows:

type exampleStruct struct {
    Field1 uint8
    Field2 [][]byte `ssz:"size=?,32"`
}

This will treat Field2 as type [][32]byte when marshaling a struct of that type.

Similarly, you can unmarshal encoded bytes into its original form:

var e2 exampleStruct
if err = Unmarshal(encoded, &e2); err != nil {
    return fmt.Errorf("failed to unmarshal: %v", err)
}
reflect.DeepEqual(e1, e2) // Returns true as e2 now has the same content as e1.

To calculate tree-hash root of the object run:

root, err := HashTreeRoot(e1)
if err != nil {
    return fmt.Errorf("failed to compute Merkle root: %v", err)
}

Supported data types

• bool
• uint8
• uint16
• uint32
• uint64
• slice
• array
• struct
• pointer