chainstate

Documentation

Overview

Package chainstate implements the protocol's chain state machine: structural validation, the head check, the commitment fold, and generation tracking. It is storage-agnostic — positions are logical entry indexes counted by the state itself — so every store implementation shares the one apply path, at ingest and at replay alike: the reference store composes it with an in-memory log, a production store with a replicated one.

A State is not safe for concurrent use; callers serialize access.

Index

• type Generation
• type State
  • func New(chainID uint64) *State
  • func NewAt(chainID uint64, head commitment.Head) *State
  • func (s *State) Apply(entry *pb.Entry) (commitment.Head, pb.AckStatus)
  • func (s *State) Generation(height uint64) (Generation, bool)
  • func (s *State) Head() commitment.Head
  • func (s *State) Restore(data []byte) error
  • func (s *State) Seed() commitment.Head
  • func (s *State) Snapshot() ([]byte, error)

Types

type Generation

type Generation struct {
	Positions []uint64
	Sealed    bool
}

Generation is one publication generation of a block height: the logical positions of its open, records, and seal among accepted entries. A re-anchor at the same height starts a new generation; block-addressed reads resolve to the latest.

type State

type State struct {
	// contains filtered or unexported fields
}

State holds one append-only chain guarded by the head check.

func New

func New(chainID uint64) *State

New returns an empty state whose head is the genesis seed for chainID.

func NewAt

func NewAt(chainID uint64, head commitment.Head) *State

NewAt returns a state resuming at head instead of the genesis seed, for replayers adopting a trusted mid-chain position: a cold replay of a partially retained log skips to its first BlockOpen and adopts that open's prefix commitment — trustworthy because it was head-checked when appended. Generations and known parents below the adopted point are unknown to the state, matching what the log below the retention floor no longer carries.

func (*State) Apply

func (s *State) Apply(entry *pb.Entry) (commitment.Head, pb.AckStatus)

Apply runs the one ingest path for an entry: structural validation, the head check, per-kind rules, fold. On OK the state has advanced and the entry's logical position is the pre-call applied count; on any other status the state is unchanged. The caller owns storing the entry — an accepted entry mutated afterwards corrupts every replayer.

func (*State) Generation

func (s *State) Generation(height uint64) (Generation, bool)

Generation returns a copy of the latest generation at height.

func (*State) Head

func (s *State) Head() commitment.Head

Head returns the current commitment head.

func (*State) Restore

func (s *State) Restore(data []byte) error

Restore replaces the state with a snapshot's contents. On error the state is unchanged.

func (*State) Seed

func (s *State) Seed() commitment.Head

Seed returns the genesis seed the chain starts from.

func (*State) Snapshot

func (s *State) Snapshot() ([]byte, error)

Snapshot serializes the full state. The result restores an equivalent State via Restore on any implementation of this package version.