header

Documentation

Overview

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

An ExtendedHeader is similar to a regular block header from celestia-core, but "extended" by adding the DataAvailabilityHeader (DAH), ValidatorSet and Commit in order to allow for light and full nodes to reconstruct block data by referencing the DAH.

ExtendedHeaders are generated by bridge nodes that listen to the celestia-core network for blocks, validate and extend the block data in order to generate the DAH, and request both the ValidatorSet and Commit for that block height from the celestia-core network. Bridge nodes then package that data up into an ExtendedHeader and broadcast it to the 'header-sub' GossipSub topic (HeaderSub). All nodes subscribed to HeaderSub will receive and validate the ExtendedHeader, and store it, making it available to all other dependent services (such as the DataAvailabilitySampler, or DASer) to access.

There are 5 main components in the header package:

1. core.Listener listens for new blocks from the celestia-core network (run by bridge nodes only), extends them, generates a new ExtendedHeader, and publishes it to the HeaderSub.
2. p2p.Subscriber listens for new ExtendedHeaders from the Celestia Data Availability (DA) network (via the HeaderSub)
3. p2p.Exchange or core.Exchange request ExtendedHeaders from other celestia DA nodes (default for full and light nodes) or from a celestia-core node connection (bridge nodes only)
4. Syncer manages syncing of past and recent ExtendedHeaders from either the DA network or a celestia-core connection (bridge nodes only).
5. Store manages storing ExtendedHeaders and making them available for access by other dependent services.

For bridge nodes, the general flow of the header Service is as follows:

1. core.Listener listens for new blocks from the celestia-core connection
2. core.Listener validates the block and generates the ExtendedHeader, simultaneously storing the extended block shares to disk
3. core.Listener publishes the new ExtendedHeader to HeaderSub, notifying all subscribed peers of the new ExtendedHeader
4. Syncer is already subscribed to the HeaderSub, so it receives new ExtendedHeaders locally from the core.Listener and stores them to disk via Store. 4a. If the celestia-core connection is started simultaneously with the bridge node, then the celestia-core connection will handle the syncing component, piping every synced block to the core.Listener 4b. If the celestia-core connection is already synced to the network, the Syncer handles requesting past headers up to the network head from the celestia-core connection (using core.Exchange rather than p2p.Exchange).

For full and light nodes, the general flow of the header Service is as follows:

1. Syncer listens for new ExtendedHeaders from HeaderSub
2. If there is a gap between the local head of chain and the new, validated network head, the Syncer kicks off a sync routine to request all ExtendedHeaders between local head and network head.
3. While the Syncer requests headers between the local head and network head in batches, it appends them to the subjective chain via Store with the last batched header as the new local head.

Index

• type Service
  • func NewHeaderService(syncer *sync.Syncer, sub header.Subscriber, p2pServer *p2p.ExchangeServer, ...) *Service
  • func (s *Service) GetByHeight(ctx context.Context, height uint64) (*header.ExtendedHeader, error)
  • func (s *Service) Head(ctx context.Context) (*header.ExtendedHeader, error)
  • func (s *Service) IsSyncing() bool
  • func (s *Service) Start(context.Context) error
  • func (s *Service) Stop(context.Context) error

Types

type Service

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

Service represents the header service that can be started / stopped on a node. Service's main function is to manage its sub-services. Service can contain several sub-services, such as Exchange, ExchangeServer, Syncer, and so forth.

func NewHeaderService

func NewHeaderService(
	syncer *sync.Syncer,
	sub header.Subscriber,
	p2pServer *p2p.ExchangeServer,
	ex header.Exchange,
	store header.Store) *Service

NewHeaderService creates a new instance of header Service.

func (*Service) GetByHeight

func (s *Service) GetByHeight(ctx context.Context, height uint64) (*header.ExtendedHeader, error)

GetByHeight returns the ExtendedHeader at the given height, blocking until header has been processed by the store or context deadline is exceeded.

func (*Service) Head

func (s *Service) Head(ctx context.Context) (*header.ExtendedHeader, error)

Head returns the ExtendedHeader of the chain head.

func (*Service) IsSyncing

func (s *Service) IsSyncing() bool

IsSyncing returns the status of sync

func (*Service) Start

func (s *Service) Start(context.Context) error

Start starts the header Service.

func (*Service) Stop

func (s *Service) Stop(context.Context) error

Stop stops the header Service.