types

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 ChainConfig
  • func (c *ChainConfig) AddFork(name string, epoch uint64, version []byte) *ChainConfig
  • func (c *ChainConfig) LoadForks(path string) error
• type Fork
• type Forks
  • func (f Forks) Len() int
  • func (f Forks) Less(i, j int) bool
  • func (f Forks) SigningRoot(header Header) (common.Hash, error)
  • func (f Forks) Swap(i, j int)
• type Header
  • func (h *Header) Epoch() uint64
  • func (h *Header) Hash() common.Hash
  • func (h Header) MarshalJSON() ([]byte, error)
  • func (h *Header) SyncPeriod() uint64
  • func (h *Header) UnmarshalJSON(input []byte) error
• type LightClientUpdate
  • func (update *LightClientUpdate) Score() UpdateScore
  • func (update *LightClientUpdate) Validate() error
• type SerializedSyncCommittee
  • func (s *SerializedSyncCommittee) Deserialize() (*SyncCommittee, error)
  • func (s *SerializedSyncCommittee) MarshalJSON() ([]byte, error)
  • func (s *SerializedSyncCommittee) Root() common.Hash
  • func (s *SerializedSyncCommittee) UnmarshalJSON(input []byte) error
• type SignedHeader
• type SyncAggregate
  • func (s SyncAggregate) MarshalJSON() ([]byte, error)
  • func (s *SyncAggregate) SignerCount() int
  • func (s *SyncAggregate) UnmarshalJSON(input []byte) error
• type SyncCommittee
  • func (sc *SyncCommittee) VerifySignature(signingRoot common.Hash, signature *SyncAggregate) bool
• type UpdateScore
  • func (u UpdateScore) BetterThan(w UpdateScore) bool

Constants

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

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

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

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:

• https://github.com/ethereum/consensus-specs/blob/dev/specs/altair/light-client/sync-protocol.md#lightclientoptimisticupdate
• https://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: 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.