commitment

Documentation

Overview

Package commitment defines the sequence store's commitment chain: a running keccak256 hash over the entry sequence, advanced by a per-item fold

head' = keccak256(head ‖ tag ‖ item)

where an item is an open record's context fields, one transaction, or a sealed block hash, and tag is the item's entry-class domain tag. The fold operates over the canonical byte encodings defined here — never over serialized protobuf, which is not canonical across implementations. Producers, the store ingress, and consumers must compute bit-identical heads; this package is the normative definition for all three.

Index

• Constants
• Variables
• func SealedHash(header []byte) [32]byte
• type Head
  • func Fold(head Head, tag byte, item []byte) Head
  • func FoldOpen(head Head, open OpenContext) (Head, error)
  • func FoldSeal(head Head, sealedHash [32]byte) Head
  • func FoldTx(head Head, rawTx []byte) Head
  • func FoldTxs(head Head, rawTxs [][]byte) Head
  • func Seed(chainID uint64) Head
  • func (h Head) Bytes() []byte
• type OpenContext

Constants

const (
	TagOpen byte = 0x01
	TagTx   byte = 0x02
	TagSeal byte = 0x03
)

Entry-class domain-separation tags. One per entry class, so no folded item can collide across types. Normative.

const Domain = "polygon-pos/sequence-store"

Domain seeds the chain's genesis head; it never varies at runtime.

const FormatVersion uint32 = 1

FormatVersion is folded into the genesis seed; bump it on any change to the wire format or to the canonical encodings below, so streams from different revisions fail structurally at the first head check.

Variables

var ErrInvalidBaseFee = errors.New("base fee must be a non-negative integer of at most 256 bits")

ErrInvalidBaseFee reports an open context whose base fee is nil, negative, or wider than 256 bits.

Functions

func SealedHash

func SealedHash(header []byte) [32]byte

SealedHash returns keccak256 of a sealed RLP header — the block hash a seal record commits to and the item FoldSeal folds.

Types

type Head

type Head [32]byte

Head is a commitment-chain head — the post-fold state after some prefix of the sequence.

func Fold

func Fold(head Head, tag byte, item []byte) Head

Fold advances a head by one item: keccak256(head ‖ tag ‖ item).

func FoldOpen

func FoldOpen(head Head, open OpenContext) (Head, error)

FoldOpen folds a block-open record's context, producing C_open(N). The canonical encoding is fixed-width so concatenation is unambiguous: number and timestamp as 8-byte big-endian, the parent hash as 32 bytes, gas limit as 8-byte big-endian, base fee as 32-byte big-endian. It errors if the base fee is nil, negative, or wider than 256 bits.

func FoldSeal

func FoldSeal(head Head, sealedHash [32]byte) Head

FoldSeal folds a block's sealed hash (keccak256 of its sealed header), producing C_seal(N) — the head the next block's open record extends on the normal path.

func FoldTx

func FoldTx(head Head, rawTx []byte) Head

FoldTx folds one raw signed transaction. Folding per transaction — not per record — is normative: it makes the chain independent of how transactions are batched into records.

func FoldTxs

func FoldTxs(head Head, rawTxs [][]byte) Head

FoldTxs folds transactions in order, one at a time; after a block's last transaction the head is C_block(N).

func Seed

func Seed(chainID uint64) Head

Seed returns head_0 = keccak256(Domain ‖ chain_id ‖ format_version), the head of the empty sequence. The first entry ever appended must carry it as prefix_commitment. Encoding: Domain bytes, then chainID as 8-byte big-endian, then FormatVersion as 4-byte big-endian.

func (Head) Bytes

func (h Head) Bytes() []byte

Bytes returns a copy of the head. Use it to fill a prefix_commitment field from a variable that keeps advancing: h[:] aliases the variable's storage, so the field would silently change on the next fold.

type OpenContext

type OpenContext struct {
	Number     uint64
	Timestamp  uint64
	ParentHash [32]byte
	GasLimit   uint64
	BaseFee    *big.Int
}

OpenContext is the header context fixed by a block-open record — every header field execution depends on.