header

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 WithMetrics[H Header](store Store[H]) error
• 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 Header
• type Store
• type Subscriber
• type Subscription
• type VerifyError
  • func (vr *VerifyError) Error() string

Constants

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")
)

Functions

func WithMetrics

func WithMetrics[H Header](store Store[H]) error

WithMetrics enables Otel metrics to monitor head and total amount of synced headers.

Types

type Broadcaster

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

Broadcaster broadcasts a Header to the network.

type ErrNonAdjacent

type ErrNonAdjacent struct {
	Head      int64
	Attempted int64
}

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] interface {
	Getter[H]
}

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

type Getter

type Getter[H Header] 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 returns the given range of Headers.
	GetRangeByHeight(ctx context.Context, from, amount uint64) ([]H, error)

	// GetVerifiedRange requests the header range from the provided Header and
	// verifies that the returned headers are adjacent to each other.
	GetVerifiedRange(ctx context.Context, from H, amount 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] interface {
	// Head returns the latest known header.
	Head(context.Context) (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 Header

type Header interface {
	// New creates new instance of a header.
	New() Header
	// IsZero reports whether Header is a zero value of it's concrete type.
	IsZero() bool
	// ChainID returns identifier of the chain (ChainID).
	ChainID() string
	// Hash returns hash of a header.
	Hash() Hash
	// Height returns the height of a header.
	Height() int64
	// 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(Header) error
	// Validate performs basic validation to check for missed/incorrect fields.
	Validate() error

	encoding.BinaryMarshaler
	encoding.BinaryUnmarshaler
}

Header abstracts all methods required to perform header sync.

type Store

type Store[H Header] interface {
	// Start starts the store.
	Start(context.Context) error

	// Stop stops the store by preventing further writes
	// and waiting till the ongoing ones are done.
	Stop(context.Context) error

	// 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
}

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

type Subscriber

type Subscriber[H Header] interface {
	// Subscribe creates long-living Subscription for validated Headers.
	// Multiple Subscriptions can be created.
	Subscribe() (Subscription[H], error)
	// AddValidator registers a Validator for all Subscriptions.
	// Registered Validators screen Headers for their validity
	// before they are sent through Subscriptions.
	// Multiple validators can be registered.
	AddValidator(func(context.Context, H) pubsub.ValidationResult) error
}

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

type Subscription

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

Subscription can retrieve the next Header from the network.

type VerifyError

type VerifyError struct {
	Reason error
}

VerifyError is thrown on during Verify if it fails.

func (*VerifyError) Error

func (vr *VerifyError) Error() string