Dynamic SSZ is a Go library for SSZ encoding/decoding with support for dynamic field sizes and code generation. It provides runtime flexibility while maintaining high performance through optional static code generation.
- 🔧 Dynamic Field Sizes - Support for runtime-determined field sizes based on configuration
- ⚡ Reflection-Based Processing - Works instantly with any SSZ-compatible types - no code generation required for prototyping
- 🏗️ Code Generation - Optional static code generation for maximum performance (2-3x faster than dynamic processing)
- 🚀 CLI Tool - Standalone
dynssz-gencommand for easy code generation from any Go package - 📡 Streaming Support - Memory-efficient streaming to/from
io.Reader/io.Writerfor large data - 🔄 Hybrid Approach - Seamlessly combines with fastssz for optimal efficiency
- 📦 Minimal Dependencies - Core library has minimal external dependencies
- ✅ Spec Compliant - Fully compliant with SSZ specification and Ethereum consensus tests
- 🧩 Extended Types - Optional support for signed integers, floats, big.Int, and optional types (non-standard)
- ✅ Reflection-based dynamic marshaling/unmarshaling/HTR: Production ready - battle-tested in various toolings and stable
- ✅ Code generator: Production ready - feature complete and functionally verified through extensive fuzz testing, though less battle-tested in production environments compared to the reflection code paths
go get github.com/pk910/dynamic-sszimport "github.com/pk910/dynamic-ssz"
// Define your types with SSZ tags
type MyStruct struct {
FixedArray [32]byte
DynamicList []uint64 `ssz-max:"1000"`
ConfigBased []byte `ssz-max:"1024" dynssz-max:"MAX_SIZE"`
}
// Create a DynSsz instance with your configuration
specs := map[string]any{
"MAX_SIZE": uint64(2048),
}
ds := dynssz.NewDynSsz(specs)
// Marshal
data, err := ds.MarshalSSZ(myObject)
// Unmarshal
err = ds.UnmarshalSSZ(&myObject, data)
// Hash Tree Root
root, err := ds.HashTreeRoot(myObject)For maximum performance, use code generation with the dynssz-gen CLI tool:
go install github.com/pk910/dynamic-ssz/dynssz-gen@latestGenerate SSZ methods:
# Generate for types in current package
dynssz-gen -package . -types "MyStruct,OtherType" -output generated.go
# Generate for types in external package
dynssz-gen -package github.com/example/types -types "Block" -output block_ssz.goGenerated code produces optimized SSZ methods that are faster than reflection-based encoding. See the Code Generation Guide for advanced usage including the programmatic API, cross-reference handling, and build system integration.
Dynamic SSZ is benchmarked against other SSZ libraries (including fastssz) in a dedicated benchmark repository: pk910/ssz-benchmark (view graphs).
The benchmarks compare encoding, decoding, and hash tree root performance across different SSZ libraries using common Ethereum consensus data structures.
View interactive benchmark results and historical trends at: https://pk910.github.io/ssz-benchmark/
The library includes comprehensive testing infrastructure:
- Unit Tests: Fast, isolated tests for core functionality
- Spec Tests: Ethereum consensus specification compliance tests
- Fuzz Testing: Continuous fuzzing via CI that generates random SSZ type structures and verifies correctness by comparing reflection and codegen implementations across marshal, unmarshal, hash tree root, and streaming operations
- Examples: Working examples that are automatically tested
- Performance Tests: Benchmarking and regression testing
- Getting Started Guide
- API Reference
- Supported Types
- Code Generation Guide
- Extended Types (non-standard)
- Streaming Support
- Struct Tags & Annotations
- Performance Guide
- Examples
Check out the examples directory for:
- Basic encoding/decoding
- Code generation setup
- Ethereum types integration
- Custom specifications
- Multi-dimensional arrays
We welcome contributions! Please see CONTRIBUTING.md for guidelines.
Dynamic SSZ is licensed under the Apache 2.0 License.