types

package
v1.20.0 Latest Latest
Warning

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

 Go to latest Published: Jul 20, 2024 License: GPL-3.0 Imports: 16 Imported by: 0

Documentation

Overview

Package types implements a few types of the beacon chain for light client usage.

Index

Constants

View Source 
const SerializedSyncCommitteeSize = (params.SyncCommitteeSize + 1) * params.BLSPubkeySize

SerializedSyncCommitteeSize is the size of the sync committee plus the aggregate public key.

Variables

This section is empty.

Functions

func SyncPeriod 

func SyncPeriod(slot uint64) uint64

SyncPeriod returns the sync period that the given slot belongs to.

func SyncPeriodStart 

func SyncPeriodStart(period uint64) uint64

SyncPeriodStart returns the first slot of the given period.

Types

type BootstrapData 

type BootstrapData struct {
	Header          Header
	CommitteeRoot   common.Hash
	Committee       *SerializedSyncCommittee `rlp:"-"`
	CommitteeBranch merkle.Values
}

BootstrapData contains a sync committee where light sync can be started, together with a proof through a beacon header and corresponding state. Note: BootstrapData is fetched from a server based on a known checkpoint hash.

func (*BootstrapData) Validate 

func (c *BootstrapData) Validate() error

Validate verifies the proof included in BootstrapData.

type ChainConfig 

type ChainConfig struct {
	GenesisTime           uint64      // Unix timestamp of slot 0
	GenesisValidatorsRoot common.Hash // Root hash of the genesis validator set, used for signature domain calculation
	Forks                 Forks
}

ChainConfig contains the beacon chain configuration.

func (*ChainConfig) AddFork 

func (c *ChainConfig) AddFork(name string, epoch uint64, version []byte) *ChainConfig

AddFork adds a new item to the list of forks.

func (*ChainConfig) LoadForks 

func (c *ChainConfig) LoadForks(path string) error

LoadForks parses the beacon chain configuration file (config.yaml) and extracts the list of forks.

type Fork 

type Fork struct {
	// Name of the fork in the chain config (config.yaml) file{
	Name string

	// Epoch when given fork version is activated
	Epoch uint64

	// Fork version, see https://github.com/ethereum/consensus-specs/blob/dev/specs/phase0/beacon-chain.md#custom-types
	Version []byte
	// contains filtered or unexported fields
}

Fork describes a single beacon chain fork and also stores the calculated signature domain used after this fork.

type Forks 

type Forks []*Fork

Forks is the list of all beacon chain forks in the chain configuration.

func (Forks) Len 

func (f Forks) Len() int

func (Forks) Less 

func (f Forks) Less(i, j int) bool

func (Forks) SigningRoot 

func (f Forks) SigningRoot(header Header) (common.Hash, error)

SigningRoot calculates the signing root of the given header.

func (Forks) Swap 

func (f Forks) Swap(i, j int)
type Header struct {
	// Monotonically increasing slot number for the beacon block (may be gapped)
	Slot uint64 `gencodec:"required" json:"slot"`

	// Index into the validator table who created the beacon block
	ProposerIndex uint64 `gencodec:"required" json:"proposer_index"`

	// SSZ hash of the parent beacon header
	ParentRoot common.Hash `gencodec:"required" json:"parent_root"`

	// SSZ hash of the beacon state (https://github.com/ethereum/consensus-specs/blob/dev/specs/bellatrix/beacon-chain.md#beacon-state)
	StateRoot common.Hash `gencodec:"required" json:"state_root"`

	// SSZ hash of the beacon block body (https://github.com/ethereum/consensus-specs/blob/dev/specs/bellatrix/beacon-chain.md#beaconblockbody)
	BodyRoot common.Hash `gencodec:"required" json:"body_root"`
}

Header defines a beacon header.

See data structure definition here: https://github.com/ethereum/consensus-specs/blob/dev/specs/phase0/beacon-chain.md#beaconblockheader

func (*Header) Epoch 

func (h *Header) Epoch() uint64

Epoch returns the epoch the header belongs to.

func (*Header) Hash 

func (h *Header) Hash() common.Hash

Hash calculates the block root of the header.

TODO(zsfelfoldi): Remove this when an SSZ encoder lands.

func (Header) MarshalJSON 

func (h Header) MarshalJSON() ([]byte, error)

MarshalJSON marshals as JSON.

func (*Header) SyncPeriod 

func (h *Header) SyncPeriod() uint64

SyncPeriod returns the sync period the header belongs to.

func (*Header) UnmarshalJSON 

func (h *Header) UnmarshalJSON(input []byte) error

UnmarshalJSON unmarshals from JSON.

type LightClientUpdate 

type LightClientUpdate struct {
	AttestedHeader          SignedHeader  // Arbitrary header out of the period signed by the sync committee
	NextSyncCommitteeRoot   common.Hash   // Sync committee of the next period advertised in the current one
	NextSyncCommitteeBranch merkle.Values // Proof for the next period's sync committee

	FinalizedHeader *Header       `rlp:"nil"` // Optional header to announce a point of finality
	FinalityBranch  merkle.Values // Proof for the announced finality
	// contains filtered or unexported fields
}

LightClientUpdate is a proof of the next sync committee root based on a header signed by the sync committee of the given period. Optionally, the update can prove quasi-finality by the signed header referring to a previous, finalized header from the same period, and the finalized header referring to the next sync committee root.

See data structure definition here: https://github.com/ethereum/consensus-specs/blob/dev/specs/altair/light-client/sync-protocol.md#lightclientupdate

func (*LightClientUpdate) Score 

func (update *LightClientUpdate) Score() UpdateScore

Score returns the UpdateScore describing the proof strength of the update Note: thread safety can be ensured by always calling Score on a newly received or decoded update before making it potentially available for other threads

func (*LightClientUpdate) Validate 

func (update *LightClientUpdate) Validate() error

Validate verifies the validity of the update.

type SerializedSyncCommittee 

type SerializedSyncCommittee [SerializedSyncCommitteeSize]byte

SerializedSyncCommittee is the serialized version of a sync committee plus the aggregate public key.

func (*SerializedSyncCommittee) Deserialize 

func (s *SerializedSyncCommittee) Deserialize() (*SyncCommittee, error)

Deserialize splits open the pubkeys into proper BLS key types.

func (*SerializedSyncCommittee) MarshalJSON 

func (s *SerializedSyncCommittee) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

func (*SerializedSyncCommittee) Root 

func (s *SerializedSyncCommittee) Root() common.Hash

Root calculates the root hash of the binary tree representation of a sync committee provided in serialized format.

TODO(zsfelfoldi): Get rid of this when SSZ encoding lands.

func (*SerializedSyncCommittee) UnmarshalJSON 

func (s *SerializedSyncCommittee) UnmarshalJSON(input []byte) error

UnmarshalJSON implements json.Marshaler.

type SignedHeader 

type SignedHeader struct {
	// Beacon header being signed
	Header Header

	// Sync committee BLS signature aggregate
	Signature SyncAggregate

	// Slot in which the signature has been created (newer than Header.Slot,
	// determines the signing sync committee)
	SignatureSlot uint64
}

SignedHeader represents a beacon header signed by a sync committee.

This structure is created from either an optimistic update or an instant update:

type SyncAggregate 

type SyncAggregate struct {
	Signers   [params.SyncCommitteeBitmaskSize]byte `gencodec:"required" json:"sync_committee_bits"`
	Signature [params.BLSSignatureSize]byte         `gencodec:"required" json:"sync_committee_signature"`
}

SyncAggregate represents an aggregated BLS signature with Signers referring to a subset of the corresponding sync committee.

See data structure definition here: https://github.com/ethereum/consensus-specs/blob/dev/specs/altair/beacon-chain.md#syncaggregate

func (SyncAggregate) MarshalJSON 

func (s SyncAggregate) MarshalJSON() ([]byte, error)

MarshalJSON marshals as JSON.

func (*SyncAggregate) SignerCount 

func (s *SyncAggregate) SignerCount() int

SignerCount returns the number of signers in the aggregate signature.

func (*SyncAggregate) UnmarshalJSON 

func (s *SyncAggregate) UnmarshalJSON(input []byte) error

UnmarshalJSON unmarshals from JSON.

type SyncCommittee 

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

SyncCommittee is a set of sync committee signer pubkeys and the aggregate key.

See data structure definition here: https://github.com/ethereum/consensus-specs/blob/dev/specs/altair/beacon-chain.md#syncaggregate

func (*SyncCommittee) VerifySignature 

func (sc *SyncCommittee) VerifySignature(signingRoot common.Hash, signature *SyncAggregate) bool

VerifySignature returns true if the given sync aggregate is a valid signature or the given hash.

type UpdateScore 

type UpdateScore struct {
	SignerCount     uint32 // number of signers in the header signature aggregate
	SubPeriodIndex  uint32 // signed header's slot modulo params.SyncPeriodLength
	FinalizedHeader bool   // update is considered finalized if has finalized header from the same period and 2/3 signatures
}

UpdateScore allows the comparison between updates at the same period in order to find the best update chain that provides the strongest proof of being canonical.

UpdateScores have a tightly packed binary encoding format for efficient p2p protocol transmission. Each UpdateScore is encoded in 3 bytes. When interpreted as a 24 bit little indian unsigned integer:

  • the lowest 10 bits contain the number of signers in the header signature aggregate
  • the next 13 bits contain the "sub-period index" which is he signed header's slot modulo params.SyncPeriodLength (which is correlated with the risk of the chain being re-orged before the previous period boundary in case of non-finalized updates)
  • the highest bit is set when the update is finalized (meaning that the finality header referenced by the signed header is in the same period as the signed header, making reorgs before the period boundary impossible

func (UpdateScore) BetterThan 

func (u UpdateScore) BetterThan(w UpdateScore) bool

BetterThan returns true if update u is considered better than w.

Source Files

View all Source files

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.