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 elysium-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 elysium-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 elysium-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 elysium-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 Elysium Data Availability (DA) network (via the HeaderSub)
3. p2p.Exchange or core.Exchange request ExtendedHeaders from other elysium DA nodes (default for full and light nodes) or from a elysium-core node connection (bridge nodes only)
4. Syncer manages syncing of past and recent ExtendedHeaders from either the DA network or a elysium-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 elysium-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 elysium-core connection is started simultaneously with the bridge node, then the elysium-core connection will handle the syncing component, piping every synced block to the core.Listener - If the elysium-core connection is already synced to the network, the Syncer handles requesting past headers up to the network head from the elysium-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

• Variables
• func ExtendedHeaderToProto(eh *ExtendedHeader) (*header_pb.ExtendedHeader, error)
• func MarshalExtendedHeader(in *ExtendedHeader) (_ []byte, err error)
• func MsgID(pmsg *pb.Message) string
• type ConstructFn
• type DataAvailabilityHeader
• type ExtendedHeader
  • func MakeExtendedHeader(_ context.Context, h *core.Header, comm *core.Commit, vals *core.ValidatorSet, ...) (*ExtendedHeader, error)
  • func ProtoToExtendedHeader(pb *header_pb.ExtendedHeader) (*ExtendedHeader, error)
  • func UnmarshalExtendedHeader(data []byte) (*ExtendedHeader, error)
  • func (eh *ExtendedHeader) ChainID() string
  • func (eh *ExtendedHeader) Equals(header *ExtendedHeader) bool
  • func (eh *ExtendedHeader) Hash() libhead.Hash
  • func (eh *ExtendedHeader) Height() int64
  • func (eh *ExtendedHeader) IsZero() bool
  • func (eh *ExtendedHeader) LastHeader() libhead.Hash
  • func (eh *ExtendedHeader) MarshalBinary() ([]byte, error)
  • func (eh *ExtendedHeader) MarshalJSON() ([]byte, error)
  • func (eh *ExtendedHeader) New() libhead.Header
  • func (eh *ExtendedHeader) Time() time.Time
  • func (eh *ExtendedHeader) UnmarshalBinary(data []byte) error
  • func (eh *ExtendedHeader) UnmarshalJSON(data []byte) error
  • func (eh *ExtendedHeader) Validate() error
  • func (eh *ExtendedHeader) Verify(untrusted libhead.Header) error
• type RawHeader

Variables

var EmptyDAH = da.MinDataAvailabilityHeader

EmptyDAH provides DAH of the empty block.

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 MsgID

func MsgID(pmsg *pb.Message) string

msgID computes an id for a pubsub message TODO(@Wondertan): This cause additional allocations per each recvd message in the topic

Find a way to avoid those.

Types

type ConstructFn

type ConstructFn = func(
	context.Context,
	*core.Header,
	*core.Commit,
	*core.ValidatorSet,
	*rsmt2d.ExtendedDataSquare,
) (*ExtendedHeader, error)

ConstructFn aliases a function that creates an ExtendedHeader.

type DataAvailabilityHeader

type DataAvailabilityHeader = da.DataAvailabilityHeader

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 Elysium Nodes to be notified of new block headers and perform Data Availability Sampling.

func MakeExtendedHeader

func MakeExtendedHeader(
	_ context.Context,
	h *core.Header,
	comm *core.Commit,
	vals *core.ValidatorSet,
	eds *rsmt2d.ExtendedDataSquare,
) (*ExtendedHeader, error)

MakeExtendedHeader assembles new ExtendedHeader.

func ProtoToExtendedHeader

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

func UnmarshalExtendedHeader

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

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

func (*ExtendedHeader) ChainID

func (eh *ExtendedHeader) ChainID() string

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() libhead.Hash

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

func (eh *ExtendedHeader) Height() int64

func (*ExtendedHeader) IsZero

func (eh *ExtendedHeader) IsZero() bool

func (*ExtendedHeader) LastHeader

func (eh *ExtendedHeader) LastHeader() libhead.Hash

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

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

func (eh *ExtendedHeader) New() libhead.Header

func (*ExtendedHeader) Time

func (eh *ExtendedHeader) Time() time.Time

func (*ExtendedHeader) UnmarshalBinary

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

UnmarshalBinary unmarshals ExtendedHeader from binary.

func (*ExtendedHeader) UnmarshalJSON

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

func (eh *ExtendedHeader) Validate() error

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

func (*ExtendedHeader) Verify

func (eh *ExtendedHeader) Verify(untrusted libhead.Header) error

Verify validates given untrusted Header against trusted ExtendedHeader.

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.