types

package
v1.0.3 Latest Latest
Warning

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

Go to latest
Published: Sep 5, 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: https://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 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 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 (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 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: 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 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: https://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

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL