Documentation
¶
Overview ¶
TODO(@Wondertan): Ideally, we should move that into subpackage, so this does not get included into binary of
production code, but that does not matter at the moment.
Index ¶
- Constants
- Variables
- func ExtendedHeaderToProto(eh *ExtendedHeader) (*header_pb.ExtendedHeader, error)
- func MarshalExtendedHeader(in *ExtendedHeader) (_ []byte, err error)
- func MarshalExtendedHeaderRequest(in *ExtendedHeaderRequest) ([]byte, error)
- func RandBlockID(t *testing.T) types.BlockID
- func VerifyAdjacent(trusted, untrusted *ExtendedHeader) error
- type Broadcaster
- type CoreExchange
- func (ce *CoreExchange) RequestByHash(ctx context.Context, hash tmbytes.HexBytes) (*ExtendedHeader, error)
- func (ce *CoreExchange) RequestHead(ctx context.Context) (*ExtendedHeader, error)
- func (ce *CoreExchange) RequestHeader(ctx context.Context, height uint64) (*ExtendedHeader, error)
- func (ce *CoreExchange) RequestHeaders(ctx context.Context, from, amount uint64) ([]*ExtendedHeader, error)
- type DataAvailabilityHeader
- type Exchange
- type ExtendedHeader
- type ExtendedHeaderRequest
- type LocalExchange
- func (l *LocalExchange) RequestByHash(ctx context.Context, hash bytes.HexBytes) (*ExtendedHeader, error)
- func (l *LocalExchange) RequestHead(ctx context.Context) (*ExtendedHeader, error)
- func (l *LocalExchange) RequestHeader(ctx context.Context, height uint64) (*ExtendedHeader, error)
- func (l *LocalExchange) RequestHeaders(ctx context.Context, origin, amount uint64) ([]*ExtendedHeader, error)
- func (l *LocalExchange) Start(context.Context) error
- func (l *LocalExchange) Stop(context.Context) error
- type P2PExchange
- func (ex *P2PExchange) Connected(_ network.Network, conn network.Conn)
- func (ex *P2PExchange) RequestByHash(ctx context.Context, hash tmbytes.HexBytes) (*ExtendedHeader, error)
- func (ex *P2PExchange) RequestHead(ctx context.Context) (*ExtendedHeader, error)
- func (ex *P2PExchange) RequestHeader(ctx context.Context, height uint64) (*ExtendedHeader, error)
- func (ex *P2PExchange) RequestHeaders(ctx context.Context, from, amount uint64) ([]*ExtendedHeader, error)
- func (ex *P2PExchange) Start(ctx context.Context) error
- func (ex *P2PExchange) Stop(context.Context) error
- type RawHeader
- type Service
- type Store
- type Subscriber
- type Subscription
- type Syncer
- type TestSuite
- func (s *TestSuite) Commit(h *RawHeader) *types.Commit
- func (s *TestSuite) GenExtendedHeader() *ExtendedHeader
- func (s *TestSuite) GenExtendedHeaders(num int) []*ExtendedHeader
- func (s *TestSuite) GenRawHeader(height int64, lastHeader, lastCommit, dataHash bytes.HexBytes) *RawHeader
- func (s *TestSuite) Head() *ExtendedHeader
Constants ¶
const PubSubTopic = "header-sub"
PubSubTopic hardcodes the name of the ExtendedHeader gossipsub topic.
Variables ¶
var ( // ErrNotFound is returned when there is no requested header. ErrNotFound = errors.New("header: not found") // ErrNoHead is returned when Store does not contain Head of the chain, ErrNoHead = fmt.Errorf("header/store: no chain head") )
var ( // DefaultStoreCache defines the amount of max entries allowed in the Header Store cache. DefaultStoreCacheSize = 1024 // DefaultIndexCache defines the amount of max entries allowed in the Height to Hash index cache. DefaultIndexCacheSize = 256 )
TODO(@Wondertan): Those values must be configurable and proper defaults should be set for specific node type.
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 MarshalExtendedHeaderRequest ¶
func MarshalExtendedHeaderRequest(in *ExtendedHeaderRequest) ([]byte, error)
MarshalExtendedHeaderRequest serializes the given ExtendedHeaderRequest to bytes using protobuf. Paired with UnmarshalExtendedHeaderRequest.
func RandBlockID ¶
RandBlockID provides a BlockID fixture.
func VerifyAdjacent ¶
func VerifyAdjacent(trusted, untrusted *ExtendedHeader) error
Types ¶
type Broadcaster ¶
type Broadcaster interface {
Broadcast(ctx context.Context, header *ExtendedHeader) error
}
Broadcaster broadcasts an ExtendedHeader to the network.
type CoreExchange ¶
type CoreExchange struct {
// contains filtered or unexported fields
}
func NewCoreExchange ¶
func NewCoreExchange(fetcher *core.BlockFetcher, dag format.DAGService) *CoreExchange
func (*CoreExchange) RequestByHash ¶
func (ce *CoreExchange) RequestByHash(ctx context.Context, hash tmbytes.HexBytes) (*ExtendedHeader, error)
func (*CoreExchange) RequestHead ¶
func (ce *CoreExchange) RequestHead(ctx context.Context) (*ExtendedHeader, error)
func (*CoreExchange) RequestHeader ¶
func (ce *CoreExchange) RequestHeader(ctx context.Context, height uint64) (*ExtendedHeader, error)
func (*CoreExchange) RequestHeaders ¶
func (ce *CoreExchange) RequestHeaders(ctx context.Context, from, amount uint64) ([]*ExtendedHeader, error)
type DataAvailabilityHeader ¶
type DataAvailabilityHeader = da.DataAvailabilityHeader
func DataAvailabilityHeaderFromExtendedData ¶
func DataAvailabilityHeaderFromExtendedData(data *rsmt2d.ExtendedDataSquare) (DataAvailabilityHeader, error)
DataAvailabilityHeaderFromExtendedData generates a DataAvailabilityHeader from the given data square. TODO @renaynay: use da.NewDataAvailabilityHeader
type Exchange ¶
type Exchange interface {
// RequestHead requests the latest ExtendedHeader. Note that the ExtendedHeader
// must be verified thereafter.
RequestHead(ctx context.Context) (*ExtendedHeader, error)
// RequestHeader performs a request for the ExtendedHeader at the given
// height to the network. Note that the ExtendedHeader must be verified
// thereafter.
RequestHeader(ctx context.Context, height uint64) (*ExtendedHeader, error)
// RequestHeaders performs a request for the given range of ExtendedHeaders
// to the network. Note that the ExtendedHeaders must be verified thereafter.
RequestHeaders(ctx context.Context, origin, amount uint64) ([]*ExtendedHeader, error)
// RequestByHash performs a request for the ExtendedHeader by the given hash corresponding
// to the RawHeader. Note that the ExtendedHeader must be verified thereafter.
RequestByHash(ctx context.Context, hash tmbytes.HexBytes) (*ExtendedHeader, error)
}
Exchange encompasses the behavior necessary to request ExtendedHeaders from the network.
func NewLocalExchange ¶
NewLocalExchange creates new Exchange.
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 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) 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) 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) UnmarshalBinary ¶
func (eh *ExtendedHeader) UnmarshalBinary(data []byte) error
UnmarshalBinary unmarshals ExtendedHeader from binary.
func (*ExtendedHeader) ValidateBasic ¶
func (eh *ExtendedHeader) ValidateBasic() error
ValidateBasic performs *basic* validation to check for missed/incorrect fields.
type ExtendedHeaderRequest ¶
type ExtendedHeaderRequest struct {
Origin uint64 // block height from which to request ExtendedHeaders
Amount uint64 // amount of desired ExtendedHeaders starting from Origin, syncing in ascending order
}
ExtendedHeaderRequest is the packet format for nodes to request ExtendedHeaders from the network.
func UnmarshalExtendedHeaderRequest ¶
func UnmarshalExtendedHeaderRequest(data []byte) (*ExtendedHeaderRequest, error)
UnmarshalExtendedHeaderRequest deserializes given data into a new ExtendedHeader using protobuf. Paired with MarshalExtendedHeaderRequest.
func (*ExtendedHeaderRequest) MarshalBinary ¶
func (ehr *ExtendedHeaderRequest) MarshalBinary() ([]byte, error)
MarshalBinary marshals ExtendedHeaderRequest to binary.
func (*ExtendedHeaderRequest) ToProto ¶
func (ehr *ExtendedHeaderRequest) ToProto() *header_pb.ExtendedHeaderRequest
func (*ExtendedHeaderRequest) UnmarshalBinary ¶
func (ehr *ExtendedHeaderRequest) UnmarshalBinary(data []byte) error
type LocalExchange ¶
type LocalExchange struct {
// contains filtered or unexported fields
}
LocalExchange is a simple Exchange that reads Headers from Store without any networking.
func (*LocalExchange) RequestByHash ¶
func (l *LocalExchange) RequestByHash(ctx context.Context, hash bytes.HexBytes) (*ExtendedHeader, error)
func (*LocalExchange) RequestHead ¶
func (l *LocalExchange) RequestHead(ctx context.Context) (*ExtendedHeader, error)
func (*LocalExchange) RequestHeader ¶
func (l *LocalExchange) RequestHeader(ctx context.Context, height uint64) (*ExtendedHeader, error)
func (*LocalExchange) RequestHeaders ¶
func (l *LocalExchange) RequestHeaders(ctx context.Context, origin, amount uint64) ([]*ExtendedHeader, error)
type P2PExchange ¶
type P2PExchange struct {
// contains filtered or unexported fields
}
P2PExchange enables sending outbound ExtendedHeaderRequests to the network as well as handling inbound ExtendedHeaderRequests from the network.
func NewP2PExchange ¶
func (*P2PExchange) Connected ¶
func (ex *P2PExchange) Connected(_ network.Network, conn network.Conn)
func (*P2PExchange) RequestByHash ¶
func (ex *P2PExchange) RequestByHash(ctx context.Context, hash tmbytes.HexBytes) (*ExtendedHeader, error)
func (*P2PExchange) RequestHead ¶
func (ex *P2PExchange) RequestHead(ctx context.Context) (*ExtendedHeader, error)
func (*P2PExchange) RequestHeader ¶
func (ex *P2PExchange) RequestHeader(ctx context.Context, height uint64) (*ExtendedHeader, error)
func (*P2PExchange) RequestHeaders ¶
func (ex *P2PExchange) RequestHeaders(ctx context.Context, from, amount uint64) ([]*ExtendedHeader, error)
type RawHeader ¶
RawHeader is an alias to core.Header. It is "raw" because it is not yet wrapped to include the DataAvailabilityHeader.
func RandRawHeader ¶
RandRawHeader provides a RawHeader fixture.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service represents the Header service that can be started / stopped on a node. Service contains 3 main functionalities:
- Listening for/requesting new ExtendedHeaders from the network.
- Verifying and serving ExtendedHeaders to the network.
- Storing/caching ExtendedHeaders.
func NewHeaderService ¶
NewHeaderService creates a new instance of header Service.
func (*Service) Broadcast ¶
func (s *Service) Broadcast(ctx context.Context, header *ExtendedHeader) error
func (*Service) Subscribe ¶
func (s *Service) Subscribe() (Subscription, error)
Subscribe returns a new subscription to the header pubsub topic
type Store ¶
type Store interface {
// Head returns the ExtendedHeader of the chain head.
Head(context.Context) (*ExtendedHeader, error)
// 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)
// 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.
Append(context.Context, ...*ExtendedHeader) error
}
Store encompasses the behavior necessary to store and retrieve ExtendedHeaders from a node's local storage.
func NewStore ¶
NewStore constructs a Store over datastore. The datastore must have a head there otherwise Start will error. For first initialization of Store use NewStoreWithHead.
func NewStoreWithHead ¶
func NewStoreWithHead(ds datastore.Batching, head *ExtendedHeader) (Store, error)
NewStoreWithHead initiates a new Store and forcefully sets a given trusted header as head.
type Subscriber ¶
type Subscriber interface {
Subscribe() (Subscription, 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 Syncer ¶
type Syncer struct {
// contains filtered or unexported fields
}
Syncer implements simplest possible synchronization for headers.
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 ¶
NewTestSuite setups a new test suite with a given number of validators.
func (*TestSuite) GenExtendedHeader ¶
func (s *TestSuite) GenExtendedHeader() *ExtendedHeader
func (*TestSuite) GenExtendedHeaders ¶
func (s *TestSuite) GenExtendedHeaders(num int) []*ExtendedHeader
func (*TestSuite) GenRawHeader ¶
func (*TestSuite) Head ¶
func (s *TestSuite) Head() *ExtendedHeader