header

package
v0.5.0-rc3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 15, 2022 License: Apache-2.0 Imports: 30 Imported by: 6

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. - 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 - 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

Constants

This section is empty.

Variables

View Source 
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")
)
View Source 
var EmptyDAH = da.MinDataAvailabilityHeader

EmptyDAH provides DAH of the empty block.

View Source 
var TrustingPeriod = 168 * time.Hour

TrustingPeriod is period through which we can trust a header's validators set.

Should be significantly less than the unbonding period (e.g. unbonding period = 3 weeks, trusting period = 2 weeks).

More specifically, trusting period + time needed to check headers + time needed to report and punish misbehavior should be less than the unbonding period.

Functions

func ExtendedHeaderToProto 

func ExtendedHeaderToProto(eh *ExtendedHeader) (*header_pb.ExtendedHeader, error)

func MarshalExtendedHeader 

func MarshalExtendedHeader(in *ExtendedHeader) (_ []byte, err error)

MarshalExtendedHeader serializes given ExtendedHeader to bytes using protobuf. Paired with UnmarshalExtendedHeader.

func RandBlockID 

func RandBlockID(t *testing.T) types.BlockID

RandBlockID provides a BlockID fixture.

func WithMetrics added in v0.4.0 

func WithMetrics(store Store)

WithMetrics enables Otel metrics to monitor head.

Types

type Broadcaster 

type Broadcaster interface {
	Broadcast(ctx context.Context, header *ExtendedHeader, opts ...pubsub.PubOpt) error
}

Broadcaster broadcasts an ExtendedHeader to the network.

type ConstructFn 

type ConstructFn = func(
	context.Context,
	*core.Block,
	*core.Commit,
	*core.ValidatorSet,
	blockservice.BlockService,
) (*ExtendedHeader, error)

ConstructFn aliases a function that creates an ExtendedHeader.

func FraudMaker 

func FraudMaker(t *testing.T, faultHeight int64) ConstructFn

FraudMaker creates a custom ConstructFn that breaks the block at the given height.

type DataAvailabilityHeader 

type DataAvailabilityHeader = da.DataAvailabilityHeader

type DummySubscriber 

type DummySubscriber struct {
	Headers []*ExtendedHeader
}

func (*DummySubscriber) AddValidator 

func (mhs *DummySubscriber) AddValidator(Validator) error

func (*DummySubscriber) Cancel 

func (mhs *DummySubscriber) Cancel()

func (*DummySubscriber) NextHeader 

func (mhs *DummySubscriber) NextHeader(ctx context.Context) (*ExtendedHeader, error)

func (*DummySubscriber) Stop 

func (mhs *DummySubscriber) Stop(context.Context) error

func (*DummySubscriber) Subscribe 

func (mhs *DummySubscriber) Subscribe() (Subscription, error)

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 added in v0.4.0 

func (ena *ErrNonAdjacent) Error() string

type Exchange 

type Exchange interface {
	Getter
}

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

type ExtendedHeader 

type ExtendedHeader struct {
	RawHeader    `json:"header"`
	Commit       *core.Commit            `json:"commit"`
	ValidatorSet *core.ValidatorSet      `json:"validator_set"`
	DAH          *DataAvailabilityHeader `json:"dah"`
}

ExtendedHeader represents a wrapped "raw" header that includes information necessary for Celestia Nodes to be notified of new block headers and perform Data Availability Sampling.

func CreateFraudExtHeader 

func CreateFraudExtHeader(t *testing.T, eh *ExtendedHeader, dag blockservice.BlockService) *ExtendedHeader

func MakeExtendedHeader 

func MakeExtendedHeader(
	ctx context.Context,
	b *core.Block,
	comm *core.Commit,
	vals *core.ValidatorSet,
	bServ blockservice.BlockService,
) (*ExtendedHeader, error)

MakeExtendedHeader assembles new ExtendedHeader.

func ProtoToExtendedHeader 

func ProtoToExtendedHeader(pb *header_pb.ExtendedHeader) (*ExtendedHeader, error)

func RandExtendedHeader 

func RandExtendedHeader(t *testing.T) *ExtendedHeader

RandExtendedHeader provides an ExtendedHeader fixture.

func UnmarshalExtendedHeader 

func UnmarshalExtendedHeader(data []byte) (*ExtendedHeader, error)

UnmarshalExtendedHeader deserializes given data into a new ExtendedHeader using protobuf. Paired with MarshalExtendedHeader.

func (*ExtendedHeader) Equals 

func (eh *ExtendedHeader) Equals(header *ExtendedHeader) bool

Equals returns whether the hash and height of the given header match.

func (*ExtendedHeader) Hash 

func (eh *ExtendedHeader) Hash() bts.HexBytes

Hash returns Hash of the wrapped RawHeader. NOTE: It purposely overrides Hash method of RawHeader to get it directly from Commit without recomputing.

func (*ExtendedHeader) IsBefore 

func (eh *ExtendedHeader) IsBefore(h *ExtendedHeader) bool

IsBefore returns whether the given header is of a higher height.

func (*ExtendedHeader) IsExpired 

func (eh *ExtendedHeader) IsExpired() bool

IsExpired checks if header is expired against trusting period.

func (*ExtendedHeader) IsRecent 

func (eh *ExtendedHeader) IsRecent(blockTime time.Duration) bool

IsRecent checks if header is recent against the given blockTime.

func (*ExtendedHeader) LastHeader 

func (eh *ExtendedHeader) LastHeader() bts.HexBytes

LastHeader returns the Hash of the last wrapped RawHeader.

func (*ExtendedHeader) MarshalBinary 

func (eh *ExtendedHeader) MarshalBinary() ([]byte, error)

MarshalBinary marshals ExtendedHeader to binary.

func (*ExtendedHeader) MarshalJSON added in v0.5.0 

func (eh *ExtendedHeader) MarshalJSON() ([]byte, error)

MarshalJSON marshals an ExtendedHeader to JSON. The ValidatorSet is wrapped with amino encoding, to be able to unmarshal the crypto.PubKey type back from JSON.

func (*ExtendedHeader) UnmarshalBinary 

func (eh *ExtendedHeader) UnmarshalBinary(data []byte) error

UnmarshalBinary unmarshals ExtendedHeader from binary.

func (*ExtendedHeader) UnmarshalJSON added in v0.5.0 

func (eh *ExtendedHeader) UnmarshalJSON(data []byte) error

UnmarshalJSON unmarshals an ExtendedHeader from JSON. The ValidatorSet is wrapped with amino encoding, to be able to unmarshal the crypto.PubKey type back from JSON.

func (*ExtendedHeader) ValidateBasic 

func (eh *ExtendedHeader) ValidateBasic() error

ValidateBasic performs *basic* validation to check for missed/incorrect fields.

func (*ExtendedHeader) VerifyAdjacent 

func (eh *ExtendedHeader) VerifyAdjacent(untrst *ExtendedHeader) error

VerifyAdjacent validates adjacent untrusted header against trusted 'eh'.

func (*ExtendedHeader) VerifyNonAdjacent 

func (eh *ExtendedHeader) VerifyNonAdjacent(untrst *ExtendedHeader) error

VerifyNonAdjacent validates non-adjacent untrusted header against trusted 'eh'.

type Getter 

type Getter interface {
	Head

	// Get returns the ExtendedHeader corresponding to the given hash.
	Get(context.Context, tmbytes.HexBytes) (*ExtendedHeader, error)

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

	// GetRangeByHeight returns the given range [from:to) of ExtendedHeaders.
	GetRangeByHeight(ctx context.Context, from, to uint64) ([]*ExtendedHeader, error)
}

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

type Head interface {
	// Head returns the latest known header.
	Head(context.Context) (*ExtendedHeader, 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 RawHeader 

type RawHeader = core.Header

RawHeader is an alias to core.Header. It is "raw" because it is not yet wrapped to include the DataAvailabilityHeader.

func RandRawHeader 

func RandRawHeader(t *testing.T) *RawHeader

RandRawHeader provides a RawHeader fixture.

type Store 

type Store 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

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

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

	// Has checks whether ExtendedHeader is already stored.
	Has(context.Context, tmbytes.HexBytes) (bool, error)

	// Append stores and verifies the given ExtendedHeader(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, ...*ExtendedHeader) (int, error)
}

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

type Subscriber 

type Subscriber interface {
	// Subscribe creates long-living Subscription for validated ExtendedHeaders.
	// Multiple Subscriptions can be created.
	Subscribe() (Subscription, error)
	// AddValidator registers a Validator for all Subscriptions.
	// Registered Validators screen ExtendedHeaders for their validity
	// before they are sent through Subscriptions.
	// Multiple validators can be registered.
	AddValidator(Validator) error
	// Stop removes header-sub validator and closes the topic.
	Stop(context.Context) error
}

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

type Subscription 

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

Subscription can retrieve the next ExtendedHeader from the network.

type TestSuite 

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

TestSuite provides everything you need to test chain of Headers. If not, please don't hesitate to extend it for your case.

func NewTestSuite 

func NewTestSuite(t *testing.T, num int) *TestSuite

NewTestSuite setups a new test suite with a given number of validators.

func (*TestSuite) Commit 

func (s *TestSuite) Commit(h *RawHeader) *types.Commit

func (*TestSuite) GenExtendedHeader 

func (s *TestSuite) GenExtendedHeader() *ExtendedHeader

func (*TestSuite) GenExtendedHeaders 

func (s *TestSuite) GenExtendedHeaders(num int) []*ExtendedHeader

func (*TestSuite) GenRawHeader 

func (s *TestSuite) GenRawHeader(
	height int64, lastHeader, lastCommit, dataHash bytes.HexBytes) *RawHeader

func (*TestSuite) Head 

func (s *TestSuite) Head() *ExtendedHeader

type Validator 

type Validator = func(context.Context, *ExtendedHeader) pubsub.ValidationResult

Validator aliases a func that validates ExtendedHeader.

type VerifyError 

type VerifyError struct {
	Reason error
}

VerifyError is thrown on during VerifyAdjacent and VerifyNonAdjacent if verification fails.

func (*VerifyError) Error 

func (vr *VerifyError) Error() string

Source Files

View all Source files

Directories

Path Synopsis
p2p
pb

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.