light

Documentation

Index

• Variables
• func GenerateTestCheckpoint(period uint64, committee *types.SerializedSyncCommittee) *types.BootstrapData
• func GenerateTestCommittee() *types.SerializedSyncCommittee
• func GenerateTestSignedHeader(header types.Header, config *types.ChainConfig, ...) types.SignedHeader
• func GenerateTestUpdate(config *types.ChainConfig, period uint64, ...) *types.LightClientUpdate
• type CommitteeChain
  • func NewCommitteeChain(db ethdb.KeyValueStore, config *types.ChainConfig, signerThreshold int, ...) *CommitteeChain
  • func NewTestCommitteeChain(db ethdb.KeyValueStore, config *types.ChainConfig, signerThreshold int, ...) *CommitteeChain
  • func (s *CommitteeChain) ChangeCounter() uint64
  • func (s *CommitteeChain) CheckpointInit(bootstrap types.BootstrapData) error
  • func (s *CommitteeChain) InsertUpdate(update *types.LightClientUpdate, nextCommittee *types.SerializedSyncCommittee) error
  • func (s *CommitteeChain) NextSyncPeriod() (uint64, bool)
  • func (s *CommitteeChain) Reset()
  • func (s *CommitteeChain) VerifySignedHeader(head types.SignedHeader) (bool, time.Duration, error)
• type HeadTracker
  • func NewHeadTracker(committeeChain *CommitteeChain, minSignerCount int) *HeadTracker
  • func (h *HeadTracker) ChangeCounter() uint64
  • func (h *HeadTracker) PrefetchHead() types.HeadInfo
  • func (h *HeadTracker) SetPrefetchHead(head types.HeadInfo)
  • func (h *HeadTracker) ValidateFinality(update types.FinalityUpdate) (bool, error)
  • func (h *HeadTracker) ValidateHead(head types.SignedHeader) (bool, error)
  • func (h *HeadTracker) ValidatedFinality() (types.FinalityUpdate, bool)
  • func (h *HeadTracker) ValidatedHead() (types.SignedHeader, bool)

Variables

var (
	ErrNeedCommittee      = errors.New("sync committee required")
	ErrInvalidUpdate      = errors.New("invalid committee update")
	ErrInvalidPeriod      = errors.New("invalid update period")
	ErrWrongCommitteeRoot = errors.New("wrong committee root")
	ErrCannotReorg        = errors.New("can not reorg committee chain")
)

Functions

func GenerateTestCheckpoint

func GenerateTestCheckpoint(period uint64, committee *types.SerializedSyncCommittee) *types.BootstrapData

func GenerateTestCommittee

func GenerateTestCommittee() *types.SerializedSyncCommittee

func GenerateTestSignedHeader

func GenerateTestSignedHeader(header types.Header, config *types.ChainConfig, committee *types.SerializedSyncCommittee, signatureSlot uint64, signerCount int) types.SignedHeader

func GenerateTestUpdate

func GenerateTestUpdate(config *types.ChainConfig, period uint64, committee, nextCommittee *types.SerializedSyncCommittee, signerCount int, finalizedHeader bool) *types.LightClientUpdate

Types

type CommitteeChain

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

CommitteeChain is a passive data structure that can validate, hold and update a chain of beacon light sync committees and updates. It requires at least one externally set fixed committee root at the beginning of the chain which can be set either based on a BootstrapData or a trusted source (a local beacon full node). This makes the structure useful for both light client and light server setups.

It always maintains the following consistency constraints:

• a committee can only be present if its root hash matches an existing fixed root or if it is proven by an update at the previous period
• an update can only be present if a committee is present at the same period and the update signature is valid and has enough participants. The committee at the next period (proven by the update) should also be present (note that this means they can only be added together if neither is present yet). If a fixed root is present at the next period then the update can only be present if it proves the same committee root.

Once synced to the current sync period, CommitteeChain can also validate signed beacon headers.

func NewCommitteeChain

func NewCommitteeChain(db ethdb.KeyValueStore, config *types.ChainConfig, signerThreshold int, enforceTime bool) *CommitteeChain

NewCommitteeChain creates a new CommitteeChain.

func NewTestCommitteeChain

func NewTestCommitteeChain(db ethdb.KeyValueStore, config *types.ChainConfig, signerThreshold int, enforceTime bool, clock *mclock.Simulated) *CommitteeChain

NewTestCommitteeChain creates a new CommitteeChain for testing.

func (*CommitteeChain) ChangeCounter

func (s *CommitteeChain) ChangeCounter() uint64

func (*CommitteeChain) CheckpointInit

func (s *CommitteeChain) CheckpointInit(bootstrap types.BootstrapData) error

CheckpointInit initializes a CommitteeChain based on a checkpoint. Note: if the chain is already initialized and the committees proven by the checkpoint do match the existing chain then the chain is retained and the new checkpoint becomes fixed.

func (*CommitteeChain) InsertUpdate

func (s *CommitteeChain) InsertUpdate(update *types.LightClientUpdate, nextCommittee *types.SerializedSyncCommittee) error

InsertUpdate adds a new update if possible.

func (*CommitteeChain) NextSyncPeriod

func (s *CommitteeChain) NextSyncPeriod() (uint64, bool)

NextSyncPeriod returns the next period where an update can be added and also whether the chain is initialized at all.

func (*CommitteeChain) Reset

func (s *CommitteeChain) Reset()

Reset resets the committee chain.

func (*CommitteeChain) VerifySignedHeader

func (s *CommitteeChain) VerifySignedHeader(head types.SignedHeader) (bool, time.Duration, error)

VerifySignedHeader returns true if the given signed header has a valid signature according to the local committee chain. The caller should ensure that the committees advertised by the same source where the signed header came from are synced before verifying the signature. The age of the header is also returned (the time elapsed since the beginning of the given slot, according to the local system clock). If enforceTime is true then negative age (future) headers are rejected.

type HeadTracker

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

HeadTracker keeps track of the latest validated head and the "prefetch" head which is the (not necessarily validated) head announced by the majority of servers.

func NewHeadTracker

func NewHeadTracker(committeeChain *CommitteeChain, minSignerCount int) *HeadTracker

NewHeadTracker creates a new HeadTracker.

func (*HeadTracker) ChangeCounter

func (h *HeadTracker) ChangeCounter() uint64

func (*HeadTracker) PrefetchHead

func (h *HeadTracker) PrefetchHead() types.HeadInfo

PrefetchHead returns the latest known prefetch head's head info. This head can be used to start fetching related data hoping that it will be validated soon. Note that the prefetch head cannot be validated cryptographically so it should only be used as a performance optimization hint.

func (*HeadTracker) SetPrefetchHead

func (h *HeadTracker) SetPrefetchHead(head types.HeadInfo)

SetPrefetchHead sets the prefetch head info. Note that HeadTracker does not verify the prefetch head, just acts as a thread safe bulletin board.

func (*HeadTracker) ValidateFinality

func (h *HeadTracker) ValidateFinality(update types.FinalityUpdate) (bool, error)

func (*HeadTracker) ValidateHead

func (h *HeadTracker) ValidateHead(head types.SignedHeader) (bool, error)

Validate validates the given signed head. If the head is successfully validated and it is better than the old validated head (higher slot or same slot and more signers) then ValidatedHead is updated. The boolean return flag signals if ValidatedHead has been changed.

func (*HeadTracker) ValidatedFinality

func (h *HeadTracker) ValidatedFinality() (types.FinalityUpdate, bool)

ValidatedHead returns the latest validated head.

func (*HeadTracker) ValidatedHead

func (h *HeadTracker) ValidatedHead() (types.SignedHeader, bool)

ValidatedHead returns the latest validated head.