Documentation
¶
Overview ¶
Package header contains all services related to generating, requesting, syncing and storing Headers.
There are 4 main components in the header package:
- p2p.Subscriber listens for new Headers from the P2P network (via the HeaderSub)
- p2p.Exchange request Headers from other nodes
- Syncer manages syncing of past and recent Headers from either the P2P network
- Store manages storing Headers and making them available for access by other dependent services.
Index ¶
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 ¶ added in v0.7.1
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 ¶
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 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 ¶
MarshalJSON serializes Hash into valid JSON.
func (*Hash) UnmarshalJSON ¶
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