willow25

Documentation

Overview

Package willow25 is the Willow'25 specialisation of the generic datamodel and meadowcap layers. It fixes path limits to 4096 / 4096 / 4096 bytes-per-component / components-per-path / total-path-bytes (per https://willowprotocol.org/specs/willow25/), pins NamespaceID and SubspaceID to 32-byte Ed25519 public keys, pins PayloadDigest to a 32-byte BLAKE3 hash, and provides convenience constructors that bundle these choices together.

Application code that does not need to swap parameters should depend on this package and only drop down to datamodel / meadowcap / encoding for advanced cases.

Index

• Constants
• func EntrySpec() datamodel.EntrySpec
• func HashPayload(payload []byte) [PayloadDigestWidth]byte
• func Limits() datamodel.Limits
• func NewEntry(namespaceID, subspaceID []byte, path datamodel.Path, timestamp uint64, ...) (datamodel.Entry, error)
• func NewPath(components [][]byte) (datamodel.Path, error)
• func William3Sum(input []byte) [32]byte

Constants

const (
	// MaxComponentLength is the per-component byte cap.
	MaxComponentLength = 4096
	// MaxComponentCount is the maximum number of components in any single path.
	MaxComponentCount = 4096
	// MaxPathLength is the maximum total path length in bytes.
	MaxPathLength = 4096
)

Standard path parameters per the Willow'25 specification.

const (
	NamespaceIDWidth   = 32
	SubspaceIDWidth    = 32
	PayloadDigestWidth = 32
)

Fixed widths for the Willow'25 id and digest types.

Functions

func EntrySpec

func EntrySpec() datamodel.EntrySpec

EntrySpec returns the Willow'25 datamodel.EntrySpec used when decoding Entry encodings (32-byte ids and digest, plus the standard path limits).

func HashPayload

func HashPayload(payload []byte) [PayloadDigestWidth]byte

HashPayload returns the 32-byte WILLIAM3 digest of payload — the payload-digest function defined by willow25 (https://willowprotocol.org/specs/willow25/index.html#willow25_data_model). WILLIAM3 is the BLAKE3 compression function with a substituted IV, so payloads produce DIFFERENT digests under WILLIAM3 vs vanilla BLAKE3. Implementation lives in william3.go; verified byte-identical against upstream bab_rs v0.5.0 on the testdata/william3/ fixtures.

func Limits

func Limits() datamodel.Limits

Limits returns the Willow'25 datamodel.Limits.

func NewEntry

func NewEntry(
	namespaceID, subspaceID []byte,
	path datamodel.Path,
	timestamp uint64,
	payload []byte,
) (datamodel.Entry, error)

NewEntry returns a fully populated datamodel.Entry for a Willow'25 payload. It hashes the payload to derive PayloadDigest and sets PayloadLength to len(payload). NamespaceID and SubspaceID must be 32 bytes each.

func NewPath

func NewPath(components [][]byte) (datamodel.Path, error)

NewPath is a thin wrapper around datamodel.FromSlices that uses the Willow'25 Limits, suitable for building paths without sprinkling willow25.Limits() at every call site.

func William3Sum

func William3Sum(input []byte) [32]byte

William3Sum returns the 32-byte WILLIAM3 digest of input.