ssztypes

func (SszType) IsBasic ¶ added in v1.4.0

func (t SszType) IsBasic() bool

IsBasic reports whether t is a basic type: a boolean or a fixed-width number. Basic values are packed into 32-byte chunks when a list or vector of them is merkleized.

func (*TypeCache) DisableSpecResolution ¶ added in v1.4.0

func (tc *TypeCache) DisableSpecResolution()

DisableSpecResolution switches the cache to building descriptors for code generation rather than for this process. Spec expressions are recorded as written instead of being resolved, because the generated code resolves them against whatever specs it runs under; resolving them here would bake the generator's own values into the output and would classify a dimension by whether a value happened to be loaded. The values are dropped rather than kept aside, so nothing can reach them by accident.

func (*TypeCache) GetAllTypes ¶

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

GetAllTypes returns a slice of all type keys 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 pairs of (runtime, schema) types in no particular order.

When runtime == schema (normal usage), these represent standard type descriptors. When they differ, the pair represents a view descriptor for fork-dependent SSZ.

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

Returns:

• [][2]reflect.Type: A slice of [runtime, schema] type pairs

Example:

cachedTypes := cache.GetAllTypes()
fmt.Printf("TypeCache contains %d type pairs\n", len(cachedTypes))
for _, pair := range cachedTypes {
    if pair[0] == pair[1] {
        fmt.Printf("  - %s\n", pair[0].String())
    } else {
        fmt.Printf("  - %s (view: %s)\n", pair[0].String(), pair[1].String())
    }
}

func (*TypeCache) GetTypeDescriptor ¶

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, nil)
if err != nil {
    log.Fatal("Failed to get type descriptor:", err)
}
fmt.Printf("Type size: %d bytes (dynamic: %v)\n", typeDesc.Size,
    typeDesc.SszTypeFlags&ssztypes.SszTypeFlagIsDynamic != 0)

func (*TypeCache) GetTypeDescriptorWithSchema ¶ added in v1.3.0

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

GetTypeDescriptorWithSchema returns a cached type descriptor for a (runtime, schema) type pair.

This method supports fork-dependent SSZ schemas (view descriptors) where the schema type defines the SSZ layout while the runtime type holds the actual data. This allows different SSZ serializations of the same runtime data based on the schema provided.

When runtimeType == schemaType, this behaves identically to GetTypeDescriptor. When they differ, the descriptor is built using schema's field definitions (names, tags, order) but accessing data from the runtime type's fields.

Parameters:

• runtimeType: The reflect.Type where actual data lives
• schemaType: The reflect.Type that defines SSZ layout (field order, tags, limits)
• sizeHints: Optional size hints from parent structures' tags
• maxSizeHints: Optional max size hints from parent structures' tags
• typeHints: Optional type hints from parent structures' tags

Returns:

• *TypeDescriptor: The type descriptor for the (runtime, schema) pair
• error: An error if types are incompatible or analysis fails

Example with view descriptor:

// Runtime type (superset)
type BeaconBlockBody struct { ... }
// Schema/view type for Altair fork
type BodyAltairView struct { ... }

desc, err := cache.GetTypeDescriptorWithSchema(
    reflect.TypeOf(BeaconBlockBody{}),
    reflect.TypeOf(BodyAltairView{}),
    nil, nil, nil,
)

func (*TypeCache) PromotedDelegationMethods ¶ added in v1.4.0

func (tc *TypeCache) PromotedDelegationMethods(targetType reflect.Type) map[string]bool

PromotedDelegationMethods returns the SSZ delegation methods a struct type only satisfies through a wrapper promoted from an embedded (anonymous) field, rather than a declaration of its own. Go promotes an embedded field's methods to the outer struct, so such a struct "implements" the interface even though the promoted method only knows how to serialize the embedded field — delegating through it silently drops the struct's sibling fields. Callers suppress delegation per interface: only the interfaces whose methods are promoted force the container walk, while an interface the struct declares itself (including a declaration shadowing an embedded method) keeps delegating.

A declared method is a real source-level function, whereas a promoted method is a compiler-generated wrapper the runtime attributes to a synthetic "<autogenerated>" file. That file distinction (see methodIsPromotedWrapper) tells the two apart.

The result is a pure function of the type and this sits on the per-call delegation hot path, so it is memoized per TypeCache. A nil map means no delegation method is promoted.

func (*TypeCache) RemoveAllTypes ¶

func (tc *TypeCache) RemoveAllTypes()

RemoveAllTypes clears all cached type descriptors from the cache, both the plain entries and the hint-carrying variants.

This method is useful for:

• 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. Spec values are resolved and memoized by the owning DynSsz instance, so a changed spec set needs a new DynSsz rather than a cleared cache.

Example:

cache.RemoveAllTypes()

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

func (*TypeCache) RemoveType ¶

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

RemoveType removes a specific type (with runtime == schema) from the cache, in both its value and pointer form.

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. Note: This only removes entries where runtime type equals schema type. Use RemoveTypeKey to remove view descriptor entries.

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

func (tc *TypeCache) RemoveTypeKey(runtimeType, schemaType reflect.Type)

RemoveTypeKey removes a specific (runtime, schema) type pair from the cache.

This method supports removing view descriptor entries where runtime differs from schema.

Parameters:

• runtimeType: The runtime type of the cache entry to remove
• schemaType: The schema type of the cache entry to remove

func (*TypeDescriptor) GetTypeHash ¶

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

GetTypeHash computes a SHA-256 hash of the TypeDescriptor's JSON representation. This hash uniquely identifies the type's SSZ layout and is used by the code generator to detect when a type's structure has changed and regeneration is needed.

Recursive types form a cyclic descriptor graph that standard JSON marshalling cannot represent; those fall back to a deterministic reference-based serialization so distinct recursive layouts hash to distinct values. Acyclic descriptors keep the plain JSON form.

The hash covers that encoding, not the wire format: encoding/json emits fields in declaration order, so reordering TypeDescriptor moves every hash without changing any serialization. It identifies a layout within one version of this package, not across versions.

func (*TypeDescriptor) SetMinSize ¶ added in v1.4.0

func (td *TypeDescriptor) SetMinSize()

SetMinSize records the smallest number of bytes a value of this type can serialize to. Decoders use it to reject an offset table that declares more elements than the region can hold, before that count sizes an allocation.

A type with no floor -- a list, an optional list -- keeps 0, which states no bound rather than a wrong one. A bit list holds its termination bit, a union its selector, an optional its presence byte and a big.Int its sign byte, so each holds at least one byte.

It is stored rather than derived at decode time because Len carries different meanings per type (bytes for a container's fixed section, elements for a vector), so the rule would otherwise be re-derived on every decode. Children are read from their own cached value, so a recursive type resolves without walking back into itself: a cycle's back edge simply contributes nothing.

Both front ends record it, so the descriptor hashes agree. The reflection cache resolves every size against the active spec; the code generator's go/types parser records the static tag values and emits the bound as a runtime expression instead (see minSizeExpr), since a preset may resolve them smaller than the static defaults.