types

package
v0.0.0-...-4ac1123 Latest Latest
Warning

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

 Go to latest Published: Oct 14, 2024 License: GPL-3.0 Imports: 28 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 BeaconBlock 

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

BeaconBlock represents a full block in the beacon chain.

func BlockFromJSON 

func BlockFromJSON(forkName string, data []byte) (*BeaconBlock, error)

BlockFromJSON decodes a beacon block from JSON.

func NewBeaconBlock 

func NewBeaconBlock(obj blockObject) *BeaconBlock

NewBeaconBlock wraps a ZRNT block.

func (*BeaconBlock) ExecutionPayload 

func (b *BeaconBlock) ExecutionPayload() (*types.Block, error)

ExecutionPayload parses and returns the execution payload of the block.

func (*BeaconBlock) Header 

func (b *BeaconBlock) Header() Header

Header returns the block's header data.

func (*BeaconBlock) Root 

func (b *BeaconBlock) Root() common.Hash

Root computes the SSZ root hash of the block.

func (*BeaconBlock) Slot 

func (b *BeaconBlock) Slot() uint64

Slot returns the slot number of the block.

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

func (c *ChainConfig) ForkAtEpoch(epoch uint64) Fork

ForkAtEpoch returns the latest active fork at the given epoch.

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 ChainHeadEvent 

type ChainHeadEvent struct {
	BeaconHead Header
	Block      *ctypes.Block
	Finalized  common.Hash
}

ChainHeadEvent returns an authenticated execution payload associated with the latest accepted head of the beacon chain, along with the hash of the latest finalized execution block.

type ExecutionHeader 

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

func ExecutionHeaderFromJSON 

func ExecutionHeaderFromJSON(forkName string, data []byte) (*ExecutionHeader, error)

ExecutionHeaderFromJSON decodes an execution header from JSON data provided by the beacon chain API.

func NewExecutionHeader 

func NewExecutionHeader(obj headerObject) *ExecutionHeader

func (*ExecutionHeader) BlockHash 

func (eh *ExecutionHeader) BlockHash() common.Hash

func (*ExecutionHeader) PayloadRoot 

func (eh *ExecutionHeader) PayloadRoot() merkle.Value

type FinalityUpdate 

type FinalityUpdate struct {
	Attested, Finalized HeaderWithExecProof
	FinalityBranch      merkle.Values
	// 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
}

FinalityUpdate proves a finalized beacon header by a sync committee commitment on an attested beacon header, referring to the latest finalized header with a Merkle proof. It also proves the execution payload header belonging to both the attested and the finalized beacon header with Merkle proofs.

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

func (*FinalityUpdate) SignedHeader 

func (u *FinalityUpdate) SignedHeader() SignedHeader

SignedHeader returns the signed attested header of the update.

func (*FinalityUpdate) Validate 

func (u *FinalityUpdate) Validate() error

Validate verifies the Merkle proofs proving the finalized beacon header and the execution payload headers belonging to the attested and finalized headers. Note that the sync committee signature of the attested header should be verified separately by a synced committee chain.

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

type HeadInfo struct {
	Slot      uint64
	BlockRoot common.Hash
}

HeadInfo represents an unvalidated new head announcement. 

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 (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 (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: 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 HeaderWithExecProof 

type HeaderWithExecProof struct {
	Header
	PayloadHeader *ExecutionHeader
	PayloadBranch merkle.Values
}

HeaderWithExecProof contains a beacon header and proves the belonging execution payload header with a Merkle proof.

func (*HeaderWithExecProof) Validate 

func (h *HeaderWithExecProof) Validate() error

Validate verifies the Merkle proof of the execution payload header.

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: 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 OptimisticUpdate 

type OptimisticUpdate struct {
	Attested HeaderWithExecProof
	// 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
}

OptimisticUpdate proves sync committee commitment on the attested beacon header. It also proves the belonging execution payload header with a Merkle proof.

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

func (*OptimisticUpdate) SignedHeader 

func (u *OptimisticUpdate) SignedHeader() SignedHeader

SignedHeader returns the signed attested header of the update.

func (*OptimisticUpdate) Validate 

func (u *OptimisticUpdate) Validate() error

Validate verifies the Merkle proof proving the execution payload header. Note that the sync committee signature of the attested header should be verified separately by a synced committee chain.

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:

  • github.com/ethereum/consensus-specs/blob/dev/specs/altair/light-client/sync-protocol.md#lightclientoptimisticupdate
  • github.com/zsfelfoldi/beacon-APIs/blob/instant_update/apis/beacon/light_client/instant_update.yaml

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