codegen

func NewCodeGenerator ¶

func NewCodeGenerator(typeCache *ssztypes.TypeCache) *CodeGenerator

NewCodeGenerator creates a new code generator instance.

The generator analyzes types on caches of its own, with spec resolution disabled: spec expressions are emitted for the generated code to resolve at runtime, so the caller's spec values play no part in the output. The cache argument is read-only; only its extended-types setting is taken, so a cache from an instance built with WithExtendedTypes widens the reflect path like the instance itself. Passing a live instance's cache is safe.

Parameters:

• typeCache: Cache whose extended-types setting is inherited; nil for the default.

Returns:

• *CodeGenerator: A new code generator ready to accept file generation requests

Example:

// Inherit the extended-types setting of an instance
cg := NewCodeGenerator(dynSsz.GetTypeCache())

// Create with default configuration
cg := NewCodeGenerator(nil)

func WithCreateDecoderFn ¶ added in v1.2.0

func WithCreateDecoderFn() CodeGeneratorOption

WithCreateDecoderFn creates an option to generate decoder functions.

When this option is enabled, the generator will generate decoder functions for the types.

Returns:

• CodeGeneratorOption: A functional option that enables decoder function generation

func WithCreateEncoderFn ¶ added in v1.2.0

func WithCreateEncoderFn() CodeGeneratorOption

WithCreateEncoderFn creates an option to generate encoder functions.

When this option is enabled, the generator will generate encoder functions for the types.

Returns:

• CodeGeneratorOption: A functional option that enables encoder function generation

func WithCreateLegacyFn ¶

func WithCreateLegacyFn() CodeGeneratorOption

WithCreateLegacyFn creates an option to generate legacy fastssz-compatible methods.

When this option is enabled, the generator creates additional methods that match the fastssz library interface, using a global DynSsz instance for compatibility. These methods include:

• MarshalSSZ() ([]byte, error)
• UnmarshalSSZ([]byte) error
• SizeSSZ() int
• HashTreeRoot() ([32]byte, error)

This option is essential for:

• Drop-in replacement for fastssz-generated code
• Gradual migration from fastssz to dynamic-ssz
• Interoperability with existing codebases expecting fastssz interfaces
• Maintaining backward compatibility in public APIs

The legacy methods delegate to the dynamic methods using the global DynSsz instance, so they inherit all dynamic sizing and expression capabilities.

Returns:

• CodeGeneratorOption: A functional option that enables legacy method generation

func WithExtendedTypes ¶ added in v1.2.2

func WithExtendedTypes() CodeGeneratorOption

WithExtendedTypes creates an option to generate code with extended types.

When this option is enabled, the generator will generate code with extended types.

Returns:

• CodeGeneratorOption: A functional option that enables extended type generation

func WithGoTypesType ¶

func WithGoTypesType(t types.Type, typeOpts ...CodeGeneratorOption) CodeGeneratorOption

WithGoTypesType creates an option to include a specific type using compile-time type analysis.

This function adds a type to the generation list using Go's types package for compile-time type analysis. This approach is more powerful than reflection as it can analyze types that may not be available at runtime and provides richer type information for complex scenarios.

This method is typically used in code analysis tools, compilers, or advanced code generation scenarios where you're working with the Go AST or type checker.

Parameters:

• t: The types.Type to include in code generation (from go/types package)
• typeOpts: Optional type-specific generation options that override base settings

Returns:

• CodeGeneratorOption: A functional option that adds the type to the generation list

Example:

// In a compiler or analysis tool context
var structType *types.Named = ... // obtained from type analysis
WithGoTypesType(structType,
    WithCreateLegacyFn(),
    WithoutDynamicExpressions(),
)

The type must be a declared named type; an alias cannot carry methods and is refused when go/types materialises it as one. Under Go 1.22, where go/types resolves an alias to its target before analysis, the caller has to make that distinction itself (dynssz-gen checks the declaration).

func WithGoTypesViewTypes ¶ added in v1.3.0

func WithGoTypesViewTypes(viewTypes ...types.Type) CodeGeneratorOption

WithGoTypesViewTypes creates an option to specify view types for data+views mode.

This option specifies view types that share the same SSZ schema as the data type. When code is generated, both regular data methods and view-compatible methods will be created, allowing the data type's methods to work with these view types.

Parameters:

• viewTypes: View types that share the same SSZ schema as the data type

Returns:

• CodeGeneratorOption: A functional option that sets view types

Example:

WithGoTypesType(dataType,
    WithGoTypesViewTypes(viewType1, viewType2),
)

func WithMaxSizeHints ¶

func WithMaxSizeHints(hints []ssztypes.SszMaxSizeHint) CodeGeneratorOption

WithMaxSizeHints creates an option to provide maximum size constraints for variable-length types.

Maximum size hints define upper bounds for variable-length types like slices and lists. These constraints are crucial for:

• Memory allocation optimization
• Security bounds checking
• SSZ encoding validation
• Buffer pre-allocation in performance-critical code

The hints help generate efficient code that can pre-allocate appropriate buffer sizes and validate data doesn't exceed specified limits during encoding/decoding.

Parameters:

• hints: Array of maximum size hints, typically corresponding to nested type levels

Returns:

• CodeGeneratorOption: A functional option that applies the provided maximum size hints

Example:

WithMaxSizeHints([]dynssz.SszMaxSizeHint{
    {Size: 1048576, Expr: "MAX_VALIDATORS_PER_COMMITTEE"},
})

func WithNoFastSsz ¶ added in v1.1.1

func WithNoFastSsz() CodeGeneratorOption

WithNoFastSsz creates an option to skip generating fast ssz generated methods.

When this option is enabled, the generator will not use any fast ssz generated methods for static types.

Returns:

• CodeGeneratorOption: A functional option that disables fast ssz generated method generation

func WithNoHashTreeRoot ¶

func WithNoHashTreeRoot() CodeGeneratorOption

WithNoHashTreeRoot creates an option to skip generating HashTreeRoot and HashTreeRootDyn methods.

When this option is applied, the code generator will not produce hash tree root calculation methods for the target types. This is useful when:

• Hash tree roots are not needed for the application
• Custom hashing logic is implemented elsewhere
• Optimizing for code size when cryptographic commitments aren't required

Note that hash tree roots are essential for many blockchain and cryptographic applications, particularly in Ethereum consensus where they're used for Merkle proofs and state roots.

Returns:

• CodeGeneratorOption: A functional option that disables hash tree root method generation

func WithNoMarshalSSZ ¶

func WithNoMarshalSSZ() CodeGeneratorOption

WithNoMarshalSSZ creates an option to skip generating MarshalSSZTo and MarshalSSZDyn methods.

When this option is applied, the code generator will not produce any marshaling methods for the target types. This is useful when:

• Types only need to be deserialized (read-only scenarios)
• Custom marshaling logic is implemented elsewhere
• Reducing generated code size for specific use cases

Note that skipping marshal methods may limit interoperability with some SSZ libraries that expect the full method interface to be present.

Returns:

• CodeGeneratorOption: A functional option that disables marshal method generation

func WithNoSizeSSZ ¶

func WithNoSizeSSZ() CodeGeneratorOption

WithNoSizeSSZ creates an option to skip generating SizeSSZ and SizeSSZDyn methods.

When this option is applied, the code generator will not produce size calculation methods for the target types. This is useful when:

• Size calculation is not needed for the application
• Custom size calculation logic is implemented elsewhere
• Optimizing for code size in constrained environments

Note that many SSZ operations benefit from accurate size pre-calculation for buffer allocation, so this option should be used carefully.

Returns:

• CodeGeneratorOption: A functional option that disables size method generation

func WithNoUnmarshalSSZ ¶

func WithNoUnmarshalSSZ() CodeGeneratorOption

WithNoUnmarshalSSZ creates an option to skip generating UnmarshalSSZ and UnmarshalSSZDyn methods.

When this option is applied, the code generator will not produce any unmarshaling methods for the target types. This is useful when:

• Types are only created programmatically (write-only scenarios)
• Custom unmarshaling logic is implemented elsewhere
• Reducing generated code size for specific use cases

Note that skipping unmarshal methods may limit interoperability with some SSZ libraries that expect the full method interface to be present.

Returns:

• CodeGeneratorOption: A functional option that disables unmarshal method generation

func WithRecursionDepth ¶ added in v1.4.0

func WithRecursionDepth(depth int) CodeGeneratorOption

WithRecursionDepth sets how deep a recursive type may nest before the generated methods fail with sszutils.ErrMaxDepthExceeded. A non-positive value selects defaultRecursionDepth.

The bound exists because stack exhaustion is fatal in Go: the runtime aborts the process and recover() cannot contain it, so a server could not isolate the failure to the request that caused it. Each level of a recursive type costs only a handful of wire bytes, so a small payload can otherwise declare nesting deep enough to exhaust the stack.

It applies to recursive cycles only: the count advances one level per cycle member entered — generated or inlined — so a trip around a cycle costs as many levels as the cycle has structural members, the same rule the reflection engine applies. A type that merely sits above a cycle threads the depth through unchanged; a type with no cycle beneath it is unaffected, as is the code emitted for it.

The value is baked into the generated code, so changing it requires regeneration. The reflection engine carries its own bound; see dynssz.WithMaxNestingDepth.

A recursive type reached through a view costs two stack frames per level rather than one: a view dispatcher returns a closure, which has nowhere to take a depth argument, so the closure supplies it and becomes a frame of its own. The bound still counts nesting levels, so the reachable depth is the same -- only the stack used getting there differs.

func WithReflectType ¶

func WithReflectType(t reflect.Type, typeOpts ...CodeGeneratorOption) CodeGeneratorOption

WithReflectType creates an option to include a specific type using runtime reflection.

This function adds a type to the generation list using Go's reflection system to analyze the type structure. It's the most common way to specify types for generation when you have access to the actual Go types at runtime.

The function accepts additional type-specific options that will be applied only to this type, allowing fine-grained control over generation behavior per type.

Parameters:

• t: The reflect.Type to include in code generation (typically obtained via reflect.TypeOf)
• typeOpts: Optional type-specific generation options that override base settings

Returns:

• CodeGeneratorOption: A functional option that adds the type to the generation list

Example:

// Add a type with default options
WithReflectType(reflect.TypeOf((*MyStruct)(nil)).Elem()),

// Add a type with specific options
WithReflectType(reflect.TypeOf((*AnotherStruct)(nil)).Elem(),
    WithNoHashTreeRoot(), // Skip hash tree root for this type only
    WithCreateLegacyFn(), // But include legacy methods
),

A referenced static type from another package that delegates to its own generated methods is sized with the type cache's specs at generation time; a width that depends on a spec value is baked for that preset. dynssz-gen reads such a width from the type's sizer at run time instead.

func WithReflectViewTypes ¶ added in v1.3.0

func WithReflectViewTypes(viewTypes ...reflect.Type) CodeGeneratorOption

WithReflectViewTypes creates an option to specify view types for data+views mode.

This option specifies view types that share the same SSZ schema as the data type. When code is generated, both regular data methods and view-compatible methods will be created, allowing the data type's methods to work with these view types.

Parameters:

• viewTypes: View types that share the same SSZ schema as the data type

Returns:

• CodeGeneratorOption: A functional option that sets view types

Example:

WithReflectType(dataType,
    WithReflectViewTypes(viewType1, viewType2),
)

func WithSizeHints ¶

func WithSizeHints(hints []ssztypes.SszSizeHint) CodeGeneratorOption

WithSizeHints creates an option to provide size constraints for dynamic types.

Size hints guide the code generator in handling types with variable or dynamic sizes. They can specify exact sizes, dynamic sizing expressions, or size calculation formulas that reference runtime specification values.

Common use cases:

• Fixed-size arrays where size depends on configuration: []Item with size "SLOTS_PER_EPOCH"
• Variable-size containers with known constraints
• Performance optimization by pre-calculating buffer sizes

Parameters:

• hints: Array of size hints, typically corresponding to nested type levels

Returns:

• CodeGeneratorOption: A functional option that applies the provided size hints

Example:

WithSizeHints([]dynssz.SszSizeHint{
    {Size: 8192, Expr: "SLOTS_PER_HISTORICAL_ROOT"},
})

func WithTypeHints ¶

func WithTypeHints(hints []ssztypes.SszTypeHint) CodeGeneratorOption

WithTypeHints creates an option to provide explicit SSZ type mappings for ambiguous Go types.

Type hints resolve ambiguity when Go types can be mapped to multiple SSZ types. This is particularly important for:

• Generic types that could be containers, lists, or vectors
• Interface types that need concrete SSZ representations
• Custom types that implement multiple SSZ-compatible interfaces
• Ensuring consistent type interpretation across different contexts

The hints allow precise control over how the generator interprets and encodes complex type hierarchies, ensuring compatibility with dynamic expressions and runtime specifications.

Parameters:

• hints: Array of type hints mapping Go types to specific SSZ type interpretations

Returns:

• CodeGeneratorOption: A functional option that applies the provided type hints

Example:

WithTypeHints([]dynssz.SszTypeHint{
    {Type: dynssz.SszListType}, // Force slice to be treated as list not vector
    {Type: dynssz.SszContainerType}, // Force struct to be treated as container
})

func WithViewOnly ¶ added in v1.3.0

func WithViewOnly() CodeGeneratorOption

WithViewOnly creates an option to generate only view methods, not data methods.

When this option is set, the generator will only produce view-compatible methods (like MarshalSSZToView, UnmarshalSSZView, etc.) and skip generating standard data methods (MarshalSSZTo, UnmarshalSSZ, etc.).

This is useful when you have a type that is only used as a view for another data type and doesn't need its own data serialization methods.

Returns:

• CodeGeneratorOption: A functional option that enables view-only mode

Example:

WithGoTypesType(viewType,
    WithViewOnly(),
    WithGoTypesViewTypes(otherViewType), // additional views
)

func WithoutDynamicExpressions ¶

func WithoutDynamicExpressions() CodeGeneratorOption

WithoutDynamicExpressions creates an option to generate static-only code that ignores dynamic expressions.

When this option is enabled, the generator produces highly optimized code that uses only static, compile-time known sizes and completely ignores any dynamic size expressions. This results in:

• Maximum performance characteristics for the default/known preset
• Smaller generated code size
• No runtime expression evaluation overhead
• Compile-time size validation

Trade-offs:

• Loss of flexibility for different presets/specifications
• Cannot handle runtime size variations
• Falls back to slower reflection-based methods for dynamic cases
• Not compatible with types that require dynamic expression evaluation

This option is ideal for production deployments where:

• The specification preset is known at compile time
• Maximum performance is prioritized over flexibility
• Code size optimization is important

Returns:

• CodeGeneratorOption: A functional option that enables static-only code generation

func NewParser ¶

func NewParser() *Parser

NewParser creates a new compile-time type parser for code generation.

The parser is initialized with an empty cache and is ready to analyze types using the go/types package. The parser can be reused across multiple type analysis operations to benefit from caching.

Returns:

• *Parser: A new parser instance ready for type analysis

Example:

parser := NewParser()
desc, err := parser.GetTypeDescriptor(myGoType, nil, nil, nil)
if err != nil {
    log.Fatal("Type analysis failed:", err)
}

func NewTypePrinter ¶

func NewTypePrinter(currentPkg string) *TypePrinter

NewTypePrinter creates a new type printer for the specified package.

The type printer is configured to generate type names relative to the specified current package. Types from the current package will be unqualified, while types from other packages will be properly qualified with import aliases.

Parameters:

• currentPkg: The Go package path of the code being generated

Returns:

• *TypePrinter: A new type printer ready for type formatting and import tracking

Example:

printer := NewTypePrinter("github.com/example/mypackage")
typeName := printer.TypeString(myTypeDescriptor) // Will qualify external types