header

README

Go Header

Go Header contains all services related to generating, requesting, syncing and storing Headers.

There are 4 main components in the header package:

1. p2p.Subscriber listens for new Headers from the P2P network (via the HeaderSub)
2. p2p.Exchange request Headers from other nodes
3. Syncer manages syncing of historical and new Headers from the P2P network
4. Store manages storing Headers and making them available for access by other dependent services.

Table of Contents

• Go Header
• Table of Contents
• Minimum requirements
• Installation
• Package-specific documentation
• Code of Conduct

Minimum requirements

Requirement	Notes
Go version	1.20 or higher

Installation

go get -u https://github.com/celestiaorg/go-header.git

For more information, go visit our docs at https://pkg.go.dev/github.com/celestiaorg/go-header.

Package-specific documentation

• P2P
• Sync
• Store

Code of Conduct

See our Code of Conduct here.

Documentation

Overview

Package header contains all services related to generating, requesting, syncing and storing Headers.

There are 4 main components in the header package:

1. p2p.Subscriber listens for new Headers from the P2P network (via the HeaderSub)
2. p2p.Exchange request Headers from other nodes
3. Syncer manages syncing of past and recent Headers from either the P2P network
4. Store manages storing Headers and making them available for access by other dependent services.

Index

• Constants
• Variables
• func New[H Header[H]]() (h H)
• func Verify[H Header[H]](trstd, untrstd H, heightThreshold uint64) error
• func WithTrustedHead[H Header[H]](verified H) func(opts *HeadParams[H])
• type Broadcaster
• type ErrNonAdjacent
  • func (ena *ErrNonAdjacent) Error() string
• type Exchange
• type Getter
• type Hash
  • func (h Hash) MarshalJSON() ([]byte, error)
  • func (h Hash) String() string
  • func (h *Hash) UnmarshalJSON(data []byte) error
• type Head
• type HeadOption
• type HeadParams
• type Header
• type Store
• type Subscriber
• type Subscription
• type VerifyError
  • func (vr *VerifyError) Error() string
  • func (vr *VerifyError) Unwrap() error

Constants

const DefaultHeightThreshold uint64 = 80000 // ~ 14 days of 15 second headers

DefaultHeightThreshold defines default height threshold beyond which headers are rejected NOTE: Compared against subjective head which is guaranteed to be non-expired

const (
	// MaxRangeRequestSize defines the max amount of headers that can be handled/requested at once.
	MaxRangeRequestSize uint64 = 512
)

Variables

var (
	// ErrNotFound is returned when there is no requested header.
	ErrNotFound = errors.New("header: not found")

	// ErrNoHead is returned when Store is empty (does not contain any known header).
	ErrNoHead = fmt.Errorf("header/store: no chain head")

	// ErrHeadersLimitExceeded is returned when ExchangeServer receives header request for more
	// than maxRequestSize headers.
	ErrHeadersLimitExceeded = errors.New("header/p2p: header limit per 1 request exceeded")
)

var (
	ErrZeroHeader       = errors.New("zero header")
	ErrWrongChainID     = errors.New("wrong chain id")
	ErrUnorderedTime    = errors.New("unordered headers")
	ErrFromFuture       = errors.New("header is from the future")
	ErrKnownHeader      = errors.New("known header")
	ErrHeightFromFuture = errors.New("header height is far from future")
)

Functions

func New

func New[H Header[H]]() (h H)

New is a generic Header constructor.

func Verify

func Verify[H Header[H]](trstd, untrstd H, heightThreshold uint64) error

Verify verifies untrusted Header against trusted following general Header checks and custom user-specific checks defined in Header.Verify

If heightThreshold is zero, uses DefaultHeightThreshold. Always returns VerifyError.

func WithTrustedHead

func WithTrustedHead[H Header[H]](verified H) func(opts *HeadParams[H])

WithTrustedHead sets the TrustedHead parameter to the given header.

Types

type Broadcaster

type Broadcaster[H Header[H]] interface {
	Broadcast(ctx context.Context, header H, opts ...pubsub.PubOpt) error
}

Broadcaster broadcasts a Header to the network.

type ErrNonAdjacent

type ErrNonAdjacent struct {
	Head      uint64
	Attempted uint64
}

ErrNonAdjacent is returned when Store is appended with a header not adjacent to the stored head.

func (*ErrNonAdjacent) Error

func (ena *ErrNonAdjacent) Error() string

type Exchange

type Exchange[H Header[H]] interface {
	Getter[H]
}

Exchange encompasses the behavior necessary to request Headers from the network.

type Getter

type Getter[H Header[H]] interface {
	Head[H]

	// Get returns the Header corresponding to the given hash.
	Get(context.Context, Hash) (H, error)

	// GetByHeight returns the Header corresponding to the given block height.
	GetByHeight(context.Context, uint64) (H, error)

	// GetRangeByHeight requests the header range from the provided Header and
	// verifies that the returned headers are adjacent to each other.
	// Expected to return the range [from.Height()+1:to).
	GetRangeByHeight(ctx context.Context, from H, to uint64) ([]H, error)
}

Getter contains the behavior necessary for a component to retrieve headers that have been processed during header sync.

type Hash

type Hash []byte

Hash represents cryptographic hash and provides basic serialization functions.

func (Hash) MarshalJSON

func (h Hash) MarshalJSON() ([]byte, error)

MarshalJSON serializes Hash into valid JSON.

func (Hash) String

func (h Hash) String() string

String implements fmt.Stringer interface.

func (*Hash) UnmarshalJSON

func (h *Hash) UnmarshalJSON(data []byte) error

UnmarshalJSON deserializes JSON representation of a Hash into object.

type Head

type Head[H Header[H]] interface {
	// Head returns the latest known header.
	Head(context.Context, ...HeadOption[H]) (H, error)
}

Head contains the behavior necessary for a component to retrieve the chain head. Note that "chain head" is subjective to the component reporting it.

type HeadOption

type HeadOption[H Header[H]] func(opts *HeadParams[H])

type HeadParams

type HeadParams[H Header[H]] struct {
	// TrustedHead allows the caller of Head to specify a trusted header
	// against which the underlying implementation of Head can verify against.
	TrustedHead H
}

HeadParams contains options to be used for Head interface methods

type Header

type Header[H any] interface {
	// New creates new instance of a header.
	// It exists to overcome limitation of Go's type system.
	// See:
	//https://go.googlesource.com/proposal/+/refs/heads/master/design/43651-type-parameters.md#pointer-method-example
	New() H
	// IsZero reports whether Header is a zero value of it's concrete type.
	IsZero() bool
	// ChainID returns identifier of the chain.
	ChainID() string
	// Hash returns hash of a header.
	Hash() Hash
	// Height returns the height of a header.
	Height() uint64
	// LastHeader returns the hash of last header before this header (aka. previous header hash).
	LastHeader() Hash
	// Time returns time when header was created.
	Time() time.Time
	// Verify validates given untrusted Header against trusted Header.
	Verify(H) error
	// Validate performs stateless validation to check for missed/incorrect fields.
	Validate() error

	encoding.BinaryMarshaler
	encoding.BinaryUnmarshaler
}

Header abstracts all methods required to perform header sync. TODO: Ideally, this should be Header[H Header[H]], but GO does not support recursive type definitions (yet?)

type Store

type Store[H Header[H]] interface {
	// Getter encompasses all getter methods for headers.
	Getter[H]

	// Init initializes Store with the given head, meaning it is initialized with the genesis header.
	Init(context.Context, H) error

	// Height reports current height of the chain head.
	Height() uint64

	// Has checks whether Header is already stored.
	Has(context.Context, Hash) (bool, error)

	// HasAt checks whether Header at the given height is already stored.
	HasAt(context.Context, uint64) bool

	// Append stores and verifies the given Header(s).
	// It requires them to be adjacent and in ascending order,
	// as it applies them contiguously on top of the current head height.
	// It returns the amount of successfully applied headers,
	// so caller can understand what given header was invalid, if any.
	Append(context.Context, ...H) error

	// GetRange returns the range [from:to).
	GetRange(context.Context, uint64, uint64) ([]H, error)
}

Store encompasses the behavior necessary to store and retrieve Headers from a node's local storage.

type Subscriber

type Subscriber[H Header[H]] interface {
	// Subscribe creates long-living Subscription for validated Headers.
	// Multiple Subscriptions can be created.
	Subscribe() (Subscription[H], error)
	// SetVerifier registers verification func for all Subscriptions.
	// Registered func screens incoming headers
	// before they are forwarded to Subscriptions.
	// Only one func can be set.
	SetVerifier(func(context.Context, H) error) error
}

Subscriber encompasses the behavior necessary to subscribe/unsubscribe from new Header events from the network.

type Subscription

type Subscription[H Header[H]] interface {
	// NextHeader returns the newest verified and valid Header
	// in the network.
	NextHeader(ctx context.Context) (H, error)
	// Cancel cancels the subscription.
	Cancel()
}

Subscription listens for new Headers.

type VerifyError

type VerifyError struct {
	// Reason why verification failed as inner error.
	Reason error
	// SoftFailure means verification did not have enough information to definitively conclude a
	// Header was correct or not.
	// May happen with recent Headers during unfinished historical sync or because of local errors.
	// TODO(@Wondertan): Better be part of signature Header.Verify() (bool, error), but kept here
	//  not to break
	SoftFailure bool
}

VerifyError is thrown if a Header failed verification.

func (*VerifyError) Error

func (vr *VerifyError) Error() string

func (*VerifyError) Unwrap

func (vr *VerifyError) Unwrap() error