dynssz

func (*CompatibleUnion[T]) GetDescriptorType ¶ added in v1.0.2

func (u *CompatibleUnion[T]) GetDescriptorType() reflect.Type

GetDescriptorType returns the reflect.Type of the descriptor struct T. This allows external code to access the descriptor type information.

func (*DynSsz) GetTree ¶ added in v1.1.1

func (d *DynSsz) GetTree(source any, opts ...CallOption) (*treeproof.Node, error)

GetTree builds and returns the complete Merkle tree for the given value.

This method constructs a full Merkle tree representation of the SSZ-encoded structure, which is useful for proof generation, debugging, and understanding the internal tree structure. The returned tree can be used to generate Merkle proofs for any field or value within the structure.

The tree construction follows the same SSZ merkleization rules as HashTreeRoot, but instead of returning just the root hash, it provides access to the complete tree with all intermediate nodes. This enables:

• Generating Merkle proofs for specific fields using tree.Prove(index)
• Debugging tree structure with tree.Show(maxDepth)
• Understanding how different fields map to generalized indices
• Analyzing the progressive vs binary tree structures

Parameters:

• source: Any Go value to be converted to a Merkle tree. Must be SSZ-compatible.

Returns:

• *treeproof.Node: The root node of the complete Merkle tree
• error: An error if tree construction fails due to unsupported types or encoding errors

The returned tree supports:

• Navigation: Use Get(index) to fetch nodes by generalized index
• Proof generation: Use Prove(index) to generate Merkle proofs
• Debugging: Use Show(maxDepth) to visualize the tree structure
• Multi-proofs: Use ProveMulti(indices) for efficient batch proofs

Example:

// Build tree for a beacon block
tree, err := ds.GetTree(beaconBlock)
if err != nil {
    log.Fatal("Failed to build tree:", err)
}

// Show tree structure (limited to 3 levels deep)
tree.Show(3)

// Generate proof for a specific field at generalized index 25
proof, err := tree.Prove(25)
if err != nil {
    log.Fatal("Failed to generate proof:", err)
}

// Verify the proof against the tree root
isValid, err := treeproof.VerifyProof(tree.Hash(), proof)

Note: For progressive containers (with ssz-index tags), the tree structure will be progressive rather than binary, which affects the generalized indices of fields.

On success the returned tree is fully hashed: every branch node already holds its cached hash, so the tree is read-only and safe to share across goroutines for concurrent Prove/ProveMulti/Hash/Value calls. On error the tree is returned alongside it but may be only partially finalized: every hash cached in it is valid, and a later Finalize resumes from those caches, but it must not be shared across goroutines until one succeeds.

func (*DynSsz) GetTypeCache ¶ added in v1.0.0

func (d *DynSsz) GetTypeCache() *ssztypes.TypeCache

GetTypeCache returns the type cache for the DynSsz instance.

The type cache stores computed type descriptors for types used in encoding/decoding operations. Type descriptors contain optimized information about how to serialize/deserialize specific types, including field offsets, size information, and whether fastssz can be used.

This method is primarily useful for debugging, performance analysis, or advanced use cases where you need to inspect or manage the cached type information.

Returns:

• *TypeCache: The type cache instance containing all cached type descriptors

Example:

ds := dynssz.NewDynSsz(specs)
cache := ds.GetTypeCache()

// Inspect cached types
types := cache.GetAllTypes()
fmt.Printf("Cache contains %d types\n", len(types))

func (*DynSsz) HashTreeRoot ¶ added in v0.0.6

func (d *DynSsz) HashTreeRoot(source any, opts ...CallOption) ([32]byte, error)

HashTreeRoot computes the hash tree root of the given source object according to SSZ specifications.

The hash tree root is a cryptographic commitment to the entire data structure, used extensively in Ethereum's consensus layer for creating Merkle proofs and maintaining state roots. This method implements the SSZ hash tree root algorithm, which recursively hashes all fields and combines them using binary Merkle trees.

For optimal performance, the method uses a hasher pool to reuse hasher instances across calls. When NoFastHash is false (default), it uses the optimized gohashtree implementation. For types without dynamic fields, it automatically delegates to fastssz's HashTreeRoot method when available.

Parameters:

• source: Any Go value for which to compute the hash tree root

Returns:

• [32]byte: The computed hash tree root
• error: An error if the computation fails due to unsupported types or hashing errors

The method handles all SSZ-supported types including:

• Basic types (bool, uint8, uint16, uint32, uint64)
• Fixed-size and variable-size arrays
• Structs with nested fields
• Slices with proper limit handling
• Bitlists with maximum size constraints

Example:

block := &phase0.BeaconBlock{
    Slot:          12345,
    ProposerIndex: 42,
    // ... other fields
}

root, err := ds.HashTreeRoot(block)
if err != nil {
    log.Fatal("Failed to compute root:", err)
}
fmt.Printf("Block root: %x\n", root)

func (*DynSsz) HashTreeRootWith ¶ added in v1.1.1

func (d *DynSsz) HashTreeRootWith(source any, hh sszutils.HashWalker, opts ...CallOption) error

HashTreeRootWith computes the hash tree root of the given source object according to SSZ specifications.

This method is similar to HashTreeRoot, but allows for custom hasher instances to be used. It dynamically handles hashing for types with both static and dynamic field sizes, automatically using fastssz for optimal performance when applicable.

Parameters:

• source: Any Go value for which to compute the hash tree root
• hh: The HashWalker instance to use for hashing. It may be a clean walker or an in-progress one; the source is merkleized as a subtree at the walker's current position. On a non-nil error the walker is left in an indeterminate state (unbalanced scopes / partial buffer); the caller must reset or discard it before reusing it, otherwise a subsequent root is corrupted. (The pooled HashTreeRoot entry point handles this automatically.)

Returns:

• error: An error if the computation fails due to unsupported types or hashing errors

The method handles all SSZ-supported types including:

• Basic types (bool, uint8, uint16, uint32, uint64)
• Fixed-size and variable-size arrays
• Structs with nested fields
• Slices with proper limit handling
• Bitlists with maximum size constraints

Example:

block := &phase0.BeaconBlock{
    Slot:          12345,
    ProposerIndex: 42,
    // ... other fields
}

hh := &hasher.Hasher{}
err := ds.HashTreeRootWith(block, hh)
if err != nil {
    log.Fatal("Failed to compute root:", err)
}
fmt.Printf("Block root: %x\n", hh.HashRoot())

func (*DynSsz) LoadSpecSet ¶ added in v1.4.0

func (d *DynSsz) LoadSpecSet(key reflect.Type) []uint64

LoadSpecSet returns the spec set cached for the generated type key, or nil when no method of that type has resolved one under this instance yet.

func (*DynSsz) MarshalSSZ ¶

func (d *DynSsz) MarshalSSZ(source any, opts ...CallOption) ([]byte, error)

MarshalSSZ serializes the given source into its SSZ (Simple Serialize) representation.

This method dynamically handles the serialization of Go types to SSZ format, supporting both static and dynamic field sizes. For types without dynamic specifications, it automatically uses fastssz for optimal performance. For types with dynamic field sizes (based on runtime specifications), it uses reflection-based processing.

The method allocates a new byte slice for the result. For high-performance scenarios with frequent allocations, consider using MarshalSSZTo with a pre-allocated buffer.

Parameters:

• source: Any Go value to be serialized. Must be a type supported by SSZ encoding.

Returns:

• []byte: The SSZ-encoded data as a new byte slice
• error: An error if serialization fails due to unsupported types, encoding errors, or size mismatches

Supported types include:

• Basic types: bool, uint8, uint16, uint32, uint64
• Arrays and slices of supported types
• Structs with appropriate SSZ tags
• Pointers to supported types
• Types implementing any of the fastssz marshalling interfaces

Example:

header := &phase0.BeaconBlockHeader{
    Slot:          12345,
    ProposerIndex: 42,
    // ... other fields
}

data, err := ds.MarshalSSZ(header)
if err != nil {
    log.Fatal("Failed to marshal:", err)
}
fmt.Printf("Encoded %d bytes\n", len(data))

func (*DynSsz) MarshalSSZTo ¶

func (d *DynSsz) MarshalSSZTo(source any, buf []byte, opts ...CallOption) ([]byte, error)

MarshalSSZTo serializes the given source into its SSZ (Simple Serialize) representation and writes the output to the provided buffer.

This method provides direct control over the output buffer, enabling performance optimizations such as buffer reuse across multiple serialization operations. Like MarshalSSZ, it dynamically handles serialization for types with both static and dynamic field sizes, automatically using fastssz when possible for optimal performance.

The method appends the serialized data to the provided buffer, which allows for efficient concatenation of multiple serialized objects without additional allocations.

Parameters:

• source: Any Go value to be serialized. Must be a type supported by SSZ encoding.
• buf: Pre-allocated byte slice where the serialized data will be appended. Can be nil or empty.

Returns:

• []byte: The updated buffer containing the original data plus the newly serialized data
• error: An error if serialization fails due to unsupported types, encoding errors, or size mismatches

Example:

buf := make([]byte, 0, 1024) // Pre-allocate with expected capacity
for _, block := range blocks {
    buf, err = ds.MarshalSSZTo(block, buf)
    if err != nil {
        log.Fatal("Failed to marshal block:", err)
    }
}
fmt.Printf("Serialized %d blocks into %d bytes\n", len(blocks), len(buf))

func (*DynSsz) MarshalSSZWriter ¶ added in v1.2.0

func (d *DynSsz) MarshalSSZWriter(source any, w io.Writer, opts ...CallOption) error

MarshalSSZWriter serializes the given source into its SSZ representation and writes it directly to an io.Writer.

This method provides memory-efficient streaming serialization for SSZ encoding, particularly beneficial for large data structures that would be expensive to buffer entirely in memory. Unlike MarshalSSZ which returns a complete byte slice, this method writes data incrementally to the provided writer, enabling direct output to files, network connections, or other I/O destinations.

The implementation employs several optimizations:

• Internal buffering (default 1KB) to reduce system call overhead for small writes
• Automatic delegation to regular MarshalSSZ for structures smaller than the buffer size
• Seamless integration with fastssz for types without dynamic fields

A stream cannot be seeked to patch offsets in, so the offsets of a value's dynamic children are computed from their sizes before the children are written. Each nesting level sizes its own children, so a deeply nested value is sized once per level it is nested in; on consensus-shaped values the cost is on par with MarshalSSZ.

Parameters:

• source: Any Go value to be serialized. Must be a type supported by SSZ encoding.
• w: The io.Writer destination for the SSZ-encoded output. Common writers include:
• os.File for file output
• net.Conn for network transmission
• bytes.Buffer for in-memory buffering
• Any custom io.Writer implementation

Returns:

• error: An error if serialization fails due to:
• Type validation errors
• I/O write failures
• Size calculation errors for dynamic fields
• Unsupported type structures

On error the writer may already hold part of the encoding. Bytes are written as they are produced, so whatever was encoded before the failure is gone -- and how much that is depends on the value, the buffer size and whether the type has generated code, which reaches the writer sooner. A write failure leaves a partial encoding regardless of any of that.

So a failed call leaves the stream in an unusable state: discard it, or reset it to where it was, rather than writing anything further. A peer reading it has no way to tell a truncated encoding from a complete one. When the reader must see all of it or none, encode with MarshalSSZ and write the result.

Example usage:

// Write directly to a file
file, err := os.Create("beacon_state.ssz")
if err != nil {
    log.Fatal(err)
}
defer file.Close()

err = ds.MarshalSSZWriter(state, file)
if err != nil {
    log.Fatal("Failed to write state:", err)
}

// Stream over network
conn, err := net.Dial("tcp", "localhost:8080")
if err != nil {
    log.Fatal(err)
}
defer conn.Close()

err = ds.MarshalSSZWriter(block, conn)

func (*DynSsz) ResolveSpecValue ¶ added in v1.0.2

func (d *DynSsz) ResolveSpecValue(name string) (bool, uint64, error)

ResolveSpecValue resolves a dynamic specification value by name. The name can be a simple identifier (e.g., "MAX_VALIDATORS_PER_COMMITTEE") or an integer arithmetic expression referencing spec values. Results are cached for subsequent lookups.

Expressions support + - * / % and parentheses over unsigned integer literals and spec identifiers. They are evaluated as exact rationals (full precision across the whole uint64 range, independent of evaluation order) and rounded up to the next whole unit once at the end, since partial bytes/bits cannot be serialized. Modulo requires integer operands. A negative or out-of-range result, division/modulo by zero, or anything beyond this subset is an error.

An identifier or parenthesized group followed by :N resolves on its own the way a size tag resolves against its static fallback: it takes its value rounded up to a whole unit, or N when it is undefined or zero (with :0 it is simply zero then). It binds tighter than the arithmetic operators, so "(A/8):4*8+B:2" is ((A/8):4)*8+(B:2).

Returns whether the value was resolved, the uint64 value, and any parse error. If the name references undefined spec values, resolved will be false with no error.

func (*DynSsz) SizeSSZ ¶

func (d *DynSsz) SizeSSZ(source any, opts ...CallOption) (int, error)

SizeSSZ calculates the size of the given source object when serialized using SSZ encoding.

This method is useful for pre-allocating buffers with the exact size needed for serialization, avoiding unnecessary allocations and resizing. It dynamically evaluates the size based on the actual values in the source object, accurately handling variable-length fields such as slices and dynamic arrays.

For types without dynamic fields, the size is calculated using the optimized fastssz SizeSSZ method when available. For types with dynamic fields, it traverses the entire structure to compute the exact serialized size.

Parameters:

• source: Any Go value whose SSZ-encoded size needs to be calculated

Returns:

• int: The exact number of bytes that would be produced by MarshalSSZ for this source
• error: An error if the size calculation fails due to unsupported types or invalid data

For a value that encodes, the size is exact: it is the length MarshalSSZ produces, and both engines agree on it.

For a value that does not encode -- a union holding data that does not match its selector, or a list past its limit, say -- the number means nothing, and what comes back depends on which engine ran. A type with generated code sizes itself through DynamicSizer, which returns a bare int and so cannot report the problem: it answers with whatever the shape adds up to, a plausible number that no encoding of the value will ever match, or with 0 where the shape itself is refused. The reflection engine returns an error instead.

So use this to size a buffer, not to decide whether a value is encodable. MarshalSSZ rejects such a value in either engine.

Example:

state := &phase0.BeaconState{
    // ... populated state fields
}

size, err := ds.SizeSSZ(state)
if err != nil {
    log.Fatal("Failed to calculate size:", err)
}

// Pre-allocate buffer with exact size
buf := make([]byte, 0, size)
buf, err = ds.MarshalSSZTo(state, buf)

func (*DynSsz) StoreSpecSet ¶ added in v1.4.0

func (d *DynSsz) StoreSpecSet(key reflect.Type, set []uint64) []uint64

StoreSpecSet caches set for the generated type key. The spec values of an instance never change, so two callers that resolved the set at the same time hold equal sets; the first one stored is the one every caller shares.

func (*DynSsz) UnmarshalSSZ ¶

func (d *DynSsz) UnmarshalSSZ(target any, ssz []byte, opts ...CallOption) error

UnmarshalSSZ decodes the given SSZ-encoded data into the target object.

This method is the counterpart to MarshalSSZ, reconstructing Go values from their SSZ representation. It dynamically handles decoding for types with both static and dynamic field sizes, automatically using fastssz for optimal performance when applicable.

The target must be a pointer to a value of the appropriate type. The method will allocate memory for slices and initialize pointer fields as needed during decoding.

Parameters:

• target: A pointer to the Go value where the decoded data will be stored. Must be a pointer.
• ssz: The SSZ-encoded data to decode

Returns:

• error: An error if decoding fails due to:
• Invalid SSZ format
• Type mismatches between the data and target
• Insufficient or excess data
• Unsupported types

The method ensures that all bytes in the ssz parameter are consumed during decoding. If there are leftover bytes, an error is returned indicating incomplete consumption.

Example:

var header phase0.BeaconBlockHeader
err := ds.UnmarshalSSZ(&header, encodedData)
if err != nil {
    log.Fatal("Failed to unmarshal:", err)
}
fmt.Printf("Decoded header for slot %d\n", header.Slot)

func (*DynSsz) UnmarshalSSZReader ¶ added in v1.2.0

func (d *DynSsz) UnmarshalSSZReader(target any, r io.Reader, size int, opts ...CallOption) error

UnmarshalSSZReader decodes SSZ-encoded data from an io.Reader directly into the target object.

This method implements memory-efficient streaming deserialization for SSZ data, reading incrementally from any io.Reader source. Unlike UnmarshalSSZ which requires the complete data in memory as a byte slice, this method processes data in chunks, making it ideal for large files, network streams, or memory-constrained environments.

The implementation handles SSZ's offset-based encoding for dynamic fields by:

• Reading offsets to determine field boundaries for variable-length data
• Using limited readers to enforce exact byte consumption per field
• Processing static fields directly from the stream
• Dynamically allocating slices based on discovered sizes

Parameters:

• target: A pointer to the Go value where decoded data will be stored. Must be a pointer to a type compatible with SSZ decoding. The method will allocate memory for slices and initialize pointer fields as needed during decoding.
• r: An io.Reader source containing the SSZ-encoded data. Common readers include:
• os.File for file input
• net.Conn for network reception
• bytes.Reader for in-memory data
• Any custom io.Reader implementation
• size: The expected total size of the SSZ data in bytes. A negative size enables "unknown size" mode: the payload is consumed to EOF without being materialised, so the memory savings of streaming still apply.

A non-negative size is trusted input. It is the extent every region is measured against and the most that is read from r, and the decoder sizes its allocations from it before the bytes arrive; it is not subject to WithMaxStreamSize. It must therefore come from a source you control, such as the stat() result of a local file or a length your own protocol has already validated, never from an untrusted remote peer. A size taken from untrusted framing lets the peer choose how much memory the decode commits before sending anything: the heap reserved for a list is the declared element count times the Go element size, so a few bytes carrying a declared 64 MiB list of pointer elements reserve 512 MiB up front and hold it for as long as the peer keeps the connection open. For input that cannot be trusted pass a negative size and bound the decode with WithMaxStreamSize or WithStreamSizeLimit instead.

Unknown-size mode is possible because SSZ is self-delimiting for every region except the trailing one, so the missing length only ever affects the last dynamic child at each nesting level. It is bounded by WithMaxStreamSize, or by WithStreamSizeLimit when the call passes one. That is a wire-byte allowance, not a deadline, cancellation mechanism, or decoded-object heap limit. Use the smallest application-specific cap your schema permits.

EOF is the message boundary in unknown-size mode. A raw connection is safe only when it carries one SSZ payload and EOF unambiguously ends that payload. Long-lived network readers need protocol framing instead; every network reader also needs a deadline or cancellation mechanism, since a peer can stay below the byte allowance while withholding EOF forever. io.Reader itself has no context support, so cancellation usually closes the reader/connection.

Two caveats apply to unknown-size mode:

• Errors are less precise. Checks that a known length would catch up front — a truncated fixed section, an offset past the end, a misaligned list — instead surface as ErrUnexpectedEOF when the read runs out. The accept/reject decision is unchanged; only the diagnostic differs.
• Types whose SSZ methods were produced by dynamic-ssz v1.3.2 or earlier must be regenerated before decoding without a size. Older generated decoders size the trailing region from the remaining-length estimate, so they reject valid input or allocate up to WithMaxStreamSize before failing. Passing an explicit size keeps working with them.

Returns:

• error: An error if decoding fails due to:
• I/O read failures
• Invalid SSZ format or structure
• Type mismatches between data and target
• Unexpected EOF or excess data
• Size constraint violations

The method ensures strict compliance with SSZ specifications, validating that:

• All expected bytes are consumed (when size is specified)
• Dynamic field offsets are valid and properly ordered
• Field boundaries are respected
• No data is left unread

Example usage:

// Read from file
file, err := os.Open("beacon_state.ssz")
if err != nil {
    log.Fatal(err)
}
defer file.Close()

// Get file size for exact reading
info, _ := file.Stat()
var state phase0.BeaconState
err = ds.UnmarshalSSZReader(&state, file, info.Size())
if err != nil {
    log.Fatal("Failed to read state:", err)
}

// Read one EOF-framed payload from a connection. A deadline is required:
// WithMaxStreamSize limits bytes, not how long the peer may withhold EOF.
conn, _ := net.Dial("tcp", "localhost:8080")
defer conn.Close()
_ = conn.SetReadDeadline(time.Now().Add(15 * time.Second))
var block phase0.BeaconBlock
err = ds.UnmarshalSSZReader(&block, conn, -1)

func (*DynSsz) ValidateType ¶ added in v1.0.2

func (d *DynSsz) ValidateType(t reflect.Type, opts ...CallOption) error

ValidateType validates whether a given type is compatible with SSZ encoding/decoding.

This method performs a comprehensive analysis of the provided type to determine if it can be successfully serialized and deserialized according to SSZ specifications. It recursively validates all nested types within structs, arrays, and slices, ensuring complete compatibility throughout the type hierarchy.

The validation process checks for:

• Supported primitive types (bool, uint8, uint16, uint32, uint64)
• Valid composite types (arrays, slices, structs)
• Proper SSZ tags on slice fields (ssz-size, ssz-max, dynssz-size, dynssz-max)
• Correct tag syntax and values
• No unsupported types (maps, channels, functions, multi-level pointers; signed integers and floats need WithExtendedTypes)

When a view descriptor is provided via WithViewDescriptor option, the method validates:

• The schema type (view descriptor) is compatible with SSZ
• Schema fields can be mapped to corresponding runtime fields by name
• Field type compatibility between schema and runtime types

This method is particularly useful for:

• Pre-validation before attempting marshalling/unmarshalling operations
• Development-time type checking to catch errors early
• Runtime validation of dynamically constructed types
• Ensuring type compatibility when integrating with external systems
• Validating view descriptor compatibility with runtime types

Parameters:

• t: The reflect.Type to validate for SSZ compatibility
• opts: Optional CallOptions, including WithViewDescriptor for fork-dependent validation

Returns:

• error: nil if the type is valid for SSZ encoding/decoding, or a descriptive error explaining why the type is incompatible. The error message includes details about the specific field or type that caused the validation failure.

A type can be valid for encoding yet refuse a hash tree root: a list or bitlist without an ssz-max limit encodes, but has no standard SSZ hash tree root unless extended types hash it as an unbounded list. ValidateType answers the encoding question.

Example usage:

type MyStruct struct {
    ValidField   uint64
    InvalidField map[string]int  // maps cannot be serialized
}

err := ds.ValidateType(reflect.TypeOf(MyStruct{}))
if err != nil {
    log.Fatal("Type validation failed:", err)
}

// With view descriptor validation:
err = ds.ValidateType(reflect.TypeOf(RuntimeBody{}), WithViewDescriptor(&AltairBodyView{}))

The method validates at the type level without requiring an instance of the type, making it suitable for early validation scenarios. For performance-critical paths, validation results can be cached as type compatibility doesn't change at runtime.

func (*TypeWrapper[D, T]) Get ¶ added in v1.0.2

func (w *TypeWrapper[D, T]) Get() T

Get returns the wrapped value.

func (*TypeWrapper[D, T]) GetDescriptorType ¶ added in v1.0.2

func (w *TypeWrapper[D, T]) GetDescriptorType() reflect.Type

GetDescriptorType returns the reflect.Type of the descriptor struct D. This allows external code to access the descriptor type information.

func (*TypeWrapper[D, T]) Set ¶ added in v1.0.2

func (w *TypeWrapper[D, T]) Set(value T)

Set sets the wrapped value.

func (*Union[T]) GetDescriptorType ¶ added in v1.4.0

func (u *Union[T]) GetDescriptorType() reflect.Type

GetDescriptorType returns the reflect.Type of the descriptor struct T. This allows external code to access the descriptor type information.