Documentation ¶
Overview ¶
Package types implements a few types of the beacon chain for light client usage.
Index ¶
- Constants
- func SyncPeriod(slot uint64) uint64
- func SyncPeriodStart(period uint64) uint64
- type BeaconBlock
- type BootstrapData
- type ChainConfig
- type ChainHeadEvent
- type ExecutionHeader
- type FinalityUpdate
- type Fork
- type Forks
- type HeadInfo
- type Header
- type HeaderWithExecProof
- type LightClientUpdate
- type OptimisticUpdate
- type SerializedSyncCommittee
- type SignedHeader
- type SyncAggregate
- type SyncCommittee
- type UpdateScore
Constants ¶
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 ¶
SyncPeriod returns the sync period that the given slot belongs to.
func SyncPeriodStart ¶
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 ¶
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) SigningRoot ¶
SigningRoot calculates the signing root of the given header.
type Header ¶
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) Hash ¶
Hash calculates the block root of the header.
TODO(zsfelfoldi): Remove this when an SSZ encoder lands.
func (Header) MarshalJSON ¶
MarshalJSON marshals as JSON.
func (*Header) SyncPeriod ¶
SyncPeriod returns the sync period the header belongs to.
func (*Header) UnmarshalJSON ¶
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 ¶
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.