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) (*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.

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

func (d *DynSsz) GetTypeCache() *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) ([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) 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

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) MarshalSSZ ¶

func (d *DynSsz) MarshalSSZ(source any) ([]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 fastssz.Marshaler interface

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) ([]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) ResolveSpecValue ¶ added in v1.0.2

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

func (*DynSsz) SizeSSZ ¶

func (d *DynSsz) SizeSSZ(source any) (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

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) UnmarshalSSZ ¶

func (d *DynSsz) UnmarshalSSZ(target any, ssz []byte) 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) ValidateType ¶ added in v1.0.2

func (d *DynSsz) ValidateType(t reflect.Type) 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 (strings, maps, channels, signed integers, floats, etc.)

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

Parameters:

• t: The reflect.Type to validate for SSZ compatibility

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.

Example usage:

type MyStruct struct {
    ValidField   uint64
    InvalidField string  // This will cause validation to fail
}

err := ds.ValidateType(reflect.TypeOf(MyStruct{}))
if err != nil {
    log.Fatal("Type validation failed:", err)
    // Output: Type validation failed: field 'InvalidField': unsupported type 'string'
}

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 (*TypeCache) GetAllTypes ¶ added in v1.0.1

func (tc *TypeCache) GetAllTypes() []reflect.Type

GetAllTypes returns a slice of all types currently cached in the TypeCache.

This method is useful for cache inspection, debugging, and understanding which types have been processed and cached during the application's lifetime. The returned slice contains the reflect.Type values in no particular order.

The method acquires a read lock to ensure thread-safe access to the cache.

Returns:

• []reflect.Type: A slice containing all cached types

Example:

cachedTypes := cache.GetAllTypes()
fmt.Printf("TypeCache contains %d types\n", len(cachedTypes))
for _, t := range cachedTypes {
    fmt.Printf("  - %s\n", t.String())
}

func (*TypeCache) GetTypeDescriptor ¶ added in v1.0.0

func (tc *TypeCache) GetTypeDescriptor(t reflect.Type, sizeHints []SszSizeHint, maxSizeHints []SszMaxSizeHint, typeHints []SszTypeHint) (*TypeDescriptor, error)

GetTypeDescriptor returns a cached type descriptor for the given type, computing it if necessary.

This method is the primary interface for obtaining type descriptors, which contain optimized metadata about how to serialize, deserialize, and hash types according to SSZ specifications. Type descriptors are cached for performance, avoiding repeated reflection and analysis of the same types.

The method is thread-safe and ensures sequential processing to prevent duplicate computation of type descriptors when called concurrently for the same type.

Parameters:

• t: The reflect.Type for which to obtain a descriptor
• sizeHints: Optional size hints from parent structures' tags. Pass nil for top-level types.
• maxSizeHints: Optional max size hints from parent structures' tags. Pass nil for top-level types.
• typeHints: Optional type hints from parent structures' tags. Pass nil for top-level types.

Returns:

• *TypeDescriptor: The type descriptor containing metadata for SSZ operations
• error: An error if the type cannot be analyzed or contains unsupported features

Type descriptors are only cached when no size hints are provided (i.e., for root types). When size hints are present, the descriptor is computed dynamically to accommodate the specific constraints.

Example:

typeDesc, err := cache.GetTypeDescriptor(reflect.TypeOf(myStruct), nil, nil)
if err != nil {
    log.Fatal("Failed to get type descriptor:", err)
}
fmt.Printf("Type size: %d bytes (dynamic: %v)\n", typeDesc.Size, typeDesc.Size < 0)

func (*TypeCache) RemoveAllTypes ¶ added in v1.0.1

func (tc *TypeCache) RemoveAllTypes()

RemoveAllTypes clears all cached type descriptors from the cache.

This method is useful for:

• Resetting the cache after configuration changes
• Memory management in long-running applications
• Testing scenarios requiring a clean cache state

The method acquires a write lock to ensure thread-safe clearing. After calling this method, all subsequent type descriptor requests will trigger recomputation.

Example:

// Clear cache after updating specifications
ds.UpdateSpecs(newSpecs)
cache.RemoveAllTypes()

// All types will be recomputed with new specs
desc, err := cache.GetTypeDescriptor(reflect.TypeOf(MyStruct{}), nil, nil)

func (*TypeCache) RemoveType ¶ added in v1.0.1

func (tc *TypeCache) RemoveType(t reflect.Type)

RemoveType removes a specific type from the cache.

This method is useful for cache management scenarios where you need to force recomputation of a type descriptor, such as after configuration changes or when testing different type configurations.

The method acquires a write lock to ensure thread-safe removal.

Parameters:

• t: The reflect.Type to remove from the cache

Example:

// Remove a type to force recomputation
cache.RemoveType(reflect.TypeOf(MyStruct{}))

// Next call to GetTypeDescriptor will rebuild the descriptor
desc, err := cache.GetTypeDescriptor(reflect.TypeOf(MyStruct{}), nil, nil)

func (*TypeDescriptor) GetTypeHash ¶ added in v1.1.0

func (td *TypeDescriptor) GetTypeHash() ([32]byte, error)

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.