beaconclient

package
v0.35.0 Latest Latest
Warning

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

Go to latest
Published: Aug 6, 2026 License: AGPL-3.0 Imports: 16 Imported by: 7

Documentation

Overview

Package beaconclient provides a beacon-node client

Index

Constants

This section is empty.

Variables

View Source
var (
	ErrBeaconNodeSyncing        = errors.New("beacon node is syncing or unavailable")
	ErrBeaconNodesUnavailable   = errors.New("all beacon nodes responded with error")
	ErrWithdrawalsBeforeCapella = errors.New("withdrawals are not supported before capella")
	ErrBeaconBlock202           = errors.New("beacon block failed validation but was still broadcast (202)")
)
View Source
var (
	ErrHTTPErrorResponse     = errors.New("got an HTTP error response")
	ErrInvalidRequestPayload = errors.New("invalid request payload")

	StateIDHead      = "head"
	StateIDGenesis   = "genesis"
	StateIDFinalized = "finalized"
	StateIDJustified = "justified"
)
View Source
var ErrStreamStateValidatorsUnsupported = errors.New("no beacon instance supports streaming state validators")

ErrStreamStateValidatorsUnsupported is returned when no configured beacon instance can stream, so the caller can fall back to GetStateValidators.

Functions

This section is empty.

Types

type BroadcastMode added in v0.27.1

type BroadcastMode string
const (
	Gossip                   BroadcastMode = "gossip"                     // lightweight gossip checks only
	Consensus                BroadcastMode = "consensus"                  // full consensus checks, including validation of all signatures and blocks fields
	ConsensusAndEquivocation BroadcastMode = "consensus_and_equivocation" // the same as `consensus`, with an extra equivocation check
)

type GetForkScheduleResponse added in v0.20.0

type GetForkScheduleResponse struct {
	Data []struct {
		PreviousVersion string `json:"previous_version"`
		CurrentVersion  string `json:"current_version"`
		Epoch           uint64 `json:"epoch,string"`
	}
}

type GetGenesisResponse added in v0.14.0

type GetGenesisResponse struct {
	Data GetGenesisResponseData `json:"data"`
}

type GetGenesisResponseData added in v0.20.0

type GetGenesisResponseData struct {
	GenesisTime           uint64 `json:"genesis_time,string"`
	GenesisValidatorsRoot string `json:"genesis_validators_root"`
	GenesisForkVersion    string `json:"genesis_fork_version"`
}

type GetHeaderResponse

type GetHeaderResponse struct {
	Data struct {
		Root   string `json:"root"`
		Header struct {
			Message *GetHeaderResponseMessage
		}
	}
}

type GetHeaderResponseMessage

type GetHeaderResponseMessage struct {
	Slot          uint64 `json:"slot,string"`
	ProposerIndex uint64 `json:"proposer_index,string"`
	ParentRoot    string `json:"parent_root"`
}

type GetRandaoResponse added in v0.14.0

type GetRandaoResponse struct {
	Data struct {
		Randao string `json:"randao"`
	}
}

type GetSpecResponse added in v0.14.0

type GetSpecResponse struct {
	SecondsPerSlot                  uint64 `json:"SECONDS_PER_SLOT,string"`            //nolint:tagliatelle
	DepositContractAddress          string `json:"DEPOSIT_CONTRACT_ADDRESS"`           //nolint:tagliatelle
	DepositNetworkID                string `json:"DEPOSIT_NETWORK_ID"`                 //nolint:tagliatelle
	DomainAggregateAndProof         string `json:"DOMAIN_AGGREGATE_AND_PROOF"`         //nolint:tagliatelle
	InactivityPenaltyQuotient       string `json:"INACTIVITY_PENALTY_QUOTIENT"`        //nolint:tagliatelle
	InactivityPenaltyQuotientAltair string `json:"INACTIVITY_PENALTY_QUOTIENT_ALTAIR"` //nolint:tagliatelle
}

type GetStateValidatorsResponse added in v0.20.0

type GetStateValidatorsResponse struct {
	// ExecutionOptimistic bool `json:"execution_optimistic"`
	// Finalized           bool `json:"finalized"`
	Data []ValidatorResponseEntry
}

type GetWithdrawalsResponse added in v0.20.0

type GetWithdrawalsResponse struct {
	Data struct {
		Withdrawals []*capella.Withdrawal `json:"withdrawals"`
	}
}

type HeadEventData

type HeadEventData struct {
	Slot  uint64 `json:"slot,string"`
	Block string `json:"block"`
	State string `json:"state"`
}

HeadEventData represents the data of a head event {"slot":"827256","block":"0x56b683afa68170c775f3c9debc18a6a72caea9055584d037333a6fe43c8ceb83","state":"0x419e2965320d69c4213782dae73941de802a4f436408fddd6f68b671b3ff4e55","epoch_transition":false,"execution_optimistic":false,"previous_duty_dependent_root":"0x5b81a526839b7fb67c3896f1125451755088fb578ad27c2690b3209f3d7c6b54","current_duty_dependent_root":"0x5f3232c0d5741e27e13754e1d88285c603b07dd6164b35ca57e94344a9e42942"}

type IBeaconInstance added in v0.5.1

type IBeaconInstance interface {
	SyncStatus() (*SyncStatusPayloadData, error)
	CurrentSlot() (uint64, error)
	SubscribeToHeadEvents(slotC chan HeadEventData)
	SubscribeToPayloadAttributesEvents(slotC chan PayloadAttributesEvent)
	GetStateValidators(stateID string) (*GetStateValidatorsResponse, error)
	GetProposerDuties(epoch uint64) (*ProposerDutiesResponse, error)
	GetURI() string
	GetPublishURI() string
	PublishBlock(block *common.VersionedSignedProposal, broadcastMode BroadcastMode) (code int, err error)
	GetGenesis() (*GetGenesisResponse, error)
	GetSpec() (spec *GetSpecResponse, err error)
	GetForkSchedule() (spec *GetForkScheduleResponse, err error)
	GetRandao(slot uint64) (spec *GetRandaoResponse, err error)
	GetWithdrawals(slot uint64) (spec *GetWithdrawalsResponse, err error)
}

IBeaconInstance is the interface for a single beacon client instance

type IMultiBeaconClient added in v0.5.1

type IMultiBeaconClient interface {
	BestSyncStatus() (*SyncStatusPayloadData, error)
	SubscribeToHeadEvents(slotC chan HeadEventData)
	// SubscribeToPayloadAttributesEvents subscribes to payload attributes events to validate fields such as prevrandao and withdrawals
	SubscribeToPayloadAttributesEvents(payloadAttrC chan PayloadAttributesEvent)

	// GetStateValidators returns all active and pending validators from the beacon node
	GetStateValidators(stateID string) (*GetStateValidatorsResponse, error)
	GetProposerDuties(epoch uint64) (*ProposerDutiesResponse, error)
	PublishBlock(block *common.VersionedSignedProposal) (code int, err error)
	GetGenesis() (*GetGenesisResponse, error)
	GetSpec() (spec *GetSpecResponse, err error)
	GetForkSchedule() (spec *GetForkScheduleResponse, err error)
	GetRandao(slot uint64) (spec *GetRandaoResponse, err error)
	GetWithdrawals(slot uint64) (spec *GetWithdrawalsResponse, err error)
}

IMultiBeaconClient is the interface for the MultiBeaconClient, which can manage several beacon client instances under the hood

type MockBeaconInstance added in v0.5.1

type MockBeaconInstance struct {
	MockSyncStatus         *SyncStatusPayloadData
	MockSyncStatusErr      error
	MockProposerDuties     *ProposerDutiesResponse
	MockProposerDutiesErr  error
	MockFetchValidatorsErr error

	ResponseDelay time.Duration
	// contains filtered or unexported fields
}

func NewMockBeaconInstance added in v0.5.1

func NewMockBeaconInstance() *MockBeaconInstance

func (*MockBeaconInstance) AddValidator added in v0.5.1

func (c *MockBeaconInstance) AddValidator(entry ValidatorResponseEntry)

func (*MockBeaconInstance) CurrentSlot added in v0.5.1

func (c *MockBeaconInstance) CurrentSlot() (uint64, error)

func (*MockBeaconInstance) GetForkSchedule added in v0.20.0

func (c *MockBeaconInstance) GetForkSchedule() (spec *GetForkScheduleResponse, err error)

func (*MockBeaconInstance) GetGenesis added in v0.14.0

func (c *MockBeaconInstance) GetGenesis() (*GetGenesisResponse, error)

func (*MockBeaconInstance) GetProposerDuties added in v0.5.1

func (c *MockBeaconInstance) GetProposerDuties(epoch uint64) (*ProposerDutiesResponse, error)

func (*MockBeaconInstance) GetPublishURI added in v0.30.0

func (c *MockBeaconInstance) GetPublishURI() string

func (*MockBeaconInstance) GetRandao added in v0.14.0

func (c *MockBeaconInstance) GetRandao(slot uint64) (spec *GetRandaoResponse, err error)

func (*MockBeaconInstance) GetSpec added in v0.14.0

func (c *MockBeaconInstance) GetSpec() (spec *GetSpecResponse, err error)

func (*MockBeaconInstance) GetStateValidators added in v0.20.0

func (c *MockBeaconInstance) GetStateValidators(stateID string) (*GetStateValidatorsResponse, error)

func (*MockBeaconInstance) GetURI added in v0.5.1

func (c *MockBeaconInstance) GetURI() string

func (*MockBeaconInstance) GetWithdrawals added in v0.20.0

func (c *MockBeaconInstance) GetWithdrawals(slot uint64) (spec *GetWithdrawalsResponse, err error)

func (*MockBeaconInstance) IsValidator added in v0.5.1

func (c *MockBeaconInstance) IsValidator(pubkey common.PubkeyHex) bool

func (*MockBeaconInstance) NumValidators added in v0.5.1

func (c *MockBeaconInstance) NumValidators() uint64

func (*MockBeaconInstance) PublishBlock added in v0.6.0

func (c *MockBeaconInstance) PublishBlock(block *common.VersionedSignedProposal, broadcaseMode BroadcastMode) (code int, err error)

func (*MockBeaconInstance) SetValidators added in v0.5.1

func (c *MockBeaconInstance) SetValidators(validatorSet map[common.PubkeyHex]ValidatorResponseEntry)

func (*MockBeaconInstance) SubscribeToHeadEvents added in v0.5.1

func (c *MockBeaconInstance) SubscribeToHeadEvents(slotC chan HeadEventData)

func (*MockBeaconInstance) SubscribeToPayloadAttributesEvents added in v0.20.0

func (c *MockBeaconInstance) SubscribeToPayloadAttributesEvents(slotC chan PayloadAttributesEvent)

func (*MockBeaconInstance) SyncStatus added in v0.5.1

func (c *MockBeaconInstance) SyncStatus() (*SyncStatusPayloadData, error)

type MockMultiBeaconClient added in v0.24.0

type MockMultiBeaconClient struct{}

func NewMockMultiBeaconClient added in v0.24.0

func NewMockMultiBeaconClient() *MockMultiBeaconClient

func (*MockMultiBeaconClient) BestSyncStatus added in v0.24.0

func (*MockMultiBeaconClient) BestSyncStatus() (*SyncStatusPayloadData, error)

func (*MockMultiBeaconClient) GetForkSchedule added in v0.24.0

func (*MockMultiBeaconClient) GetForkSchedule() (spec *GetForkScheduleResponse, err error)

func (*MockMultiBeaconClient) GetGenesis added in v0.24.0

func (*MockMultiBeaconClient) GetProposerDuties added in v0.24.0

func (*MockMultiBeaconClient) GetProposerDuties(epoch uint64) (*ProposerDutiesResponse, error)

func (*MockMultiBeaconClient) GetRandao added in v0.24.0

func (*MockMultiBeaconClient) GetRandao(slot uint64) (spec *GetRandaoResponse, err error)

func (*MockMultiBeaconClient) GetSpec added in v0.24.0

func (*MockMultiBeaconClient) GetSpec() (spec *GetSpecResponse, err error)

func (*MockMultiBeaconClient) GetStateValidators added in v0.24.0

func (*MockMultiBeaconClient) GetStateValidators(stateID string) (*GetStateValidatorsResponse, error)

func (*MockMultiBeaconClient) GetWithdrawals added in v0.24.0

func (*MockMultiBeaconClient) GetWithdrawals(slot uint64) (spec *GetWithdrawalsResponse, err error)

func (*MockMultiBeaconClient) PublishBlock added in v0.24.0

func (*MockMultiBeaconClient) PublishBlock(block *common.VersionedSignedProposal) (code int, err error)

func (*MockMultiBeaconClient) SubscribeToHeadEvents added in v0.24.0

func (*MockMultiBeaconClient) SubscribeToHeadEvents(slotC chan HeadEventData)

func (*MockMultiBeaconClient) SubscribeToPayloadAttributesEvents added in v0.24.0

func (*MockMultiBeaconClient) SubscribeToPayloadAttributesEvents(payloadAttrC chan PayloadAttributesEvent)

type MultiBeaconClient added in v0.5.1

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

func NewMultiBeaconClient added in v0.5.1

func NewMultiBeaconClient(log *logrus.Entry, beaconInstances []IBeaconInstance) *MultiBeaconClient

func (*MultiBeaconClient) BestSyncStatus added in v0.5.1

func (c *MultiBeaconClient) BestSyncStatus() (*SyncStatusPayloadData, error)

func (*MultiBeaconClient) GetForkSchedule added in v0.20.0

func (c *MultiBeaconClient) GetForkSchedule() (spec *GetForkScheduleResponse, err error)

GetForkSchedule - https://ethereum.github.io/beacon-APIs/#/Config/getForkSchedule

func (*MultiBeaconClient) GetGenesis added in v0.14.0

func (c *MultiBeaconClient) GetGenesis() (genesisInfo *GetGenesisResponse, err error)

GetGenesis returns the genesis info - https://ethereum.github.io/beacon-APIs/#/Beacon/getGenesis

func (*MultiBeaconClient) GetProposerDuties added in v0.5.1

func (c *MultiBeaconClient) GetProposerDuties(epoch uint64) (*ProposerDutiesResponse, error)

func (*MultiBeaconClient) GetRandao added in v0.14.0

func (c *MultiBeaconClient) GetRandao(slot uint64) (randaoResp *GetRandaoResponse, err error)

GetRandao - 3500/eth/v1/beacon/states/<slot>/randao

func (*MultiBeaconClient) GetSpec added in v0.14.0

func (c *MultiBeaconClient) GetSpec() (spec *GetSpecResponse, err error)

GetSpec - https://ethereum.github.io/beacon-APIs/#/Config/getSpec

func (*MultiBeaconClient) GetStateValidators added in v0.20.0

func (c *MultiBeaconClient) GetStateValidators(stateID string) (*GetStateValidatorsResponse, error)

GetStateValidators returns all known validators, and queries the beacon nodes in reverse order (because it is a heavy request for the CL client)

func (*MultiBeaconClient) GetWithdrawals added in v0.20.0

func (c *MultiBeaconClient) GetWithdrawals(slot uint64) (withdrawalsResp *GetWithdrawalsResponse, err error)

GetWithdrawals - 3500/eth/v1/beacon/states/<slot>/withdrawals

func (*MultiBeaconClient) PublishBlock added in v0.6.0

func (c *MultiBeaconClient) PublishBlock(block *common.VersionedSignedProposal) (code int, err error)

PublishBlock publishes the signed beacon block via https://ethereum.github.io/beacon-APIs/#/ValidatorRequiredApi/publishBlock

func (*MultiBeaconClient) StreamStateValidators added in v0.35.0

func (c *MultiBeaconClient) StreamStateValidators(stateID string, collector ValidatorCollector) error

StreamStateValidators streams all known validators to the collector, querying the beacon nodes in least-used order because it is a heavy call on the CL.

func (*MultiBeaconClient) SubscribeToHeadEvents added in v0.5.1

func (c *MultiBeaconClient) SubscribeToHeadEvents(slotC chan HeadEventData)

SubscribeToHeadEvents subscribes to head events from all beacon nodes. A single head event will be received multiple times, likely once for every beacon nodes.

func (*MultiBeaconClient) SubscribeToPayloadAttributesEvents added in v0.20.0

func (c *MultiBeaconClient) SubscribeToPayloadAttributesEvents(slotC chan PayloadAttributesEvent)

type PayloadAttributes added in v0.20.0

type PayloadAttributes struct {
	Timestamp             uint64                `json:"timestamp,string"`
	PrevRandao            string                `json:"prev_randao"`
	SuggestedFeeRecipient string                `json:"suggested_fee_recipient"`
	Withdrawals           []*capella.Withdrawal `json:"withdrawals"`
	ParentBeaconBlockRoot string                `json:"parent_beacon_block_root"`
}

type PayloadAttributesEvent added in v0.20.0

type PayloadAttributesEvent struct {
	Version string                     `json:"version"`
	Data    PayloadAttributesEventData `json:"data"`
}

PayloadAttributesEvent represents the data of a payload_attributes event {"version": "capella", "data": {"proposer_index": "123", "proposal_slot": "10", "parent_block_number": "9", "parent_block_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "parent_block_hash": "0x9a2fefd2fdb57f74993c7780ea5b9030d2897b615b89f808011ca5aebed54eaf", "payload_attributes": {"timestamp": "123456", "prev_randao": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "suggested_fee_recipient": "0x0000000000000000000000000000000000000000", "withdrawals": [{"index": "5", "validator_index": "10", "address": "0x0000000000000000000000000000000000000000", "amount": "15640"}]}}}

type PayloadAttributesEventData added in v0.20.0

type PayloadAttributesEventData struct {
	ProposerIndex     uint64            `json:"proposer_index,string"`
	ProposalSlot      uint64            `json:"proposal_slot,string"`
	ParentBlockNumber uint64            `json:"parent_block_number,string"`
	ParentBlockRoot   string            `json:"parent_block_root"`
	ParentBlockHash   string            `json:"parent_block_hash"`
	PayloadAttributes PayloadAttributes `json:"payload_attributes"`
}

type ProdBeaconInstance added in v0.5.1

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

func NewProdBeaconInstance added in v0.5.1

func NewProdBeaconInstance(log *logrus.Entry, beaconURI, beaconPublishURI string) *ProdBeaconInstance

func (*ProdBeaconInstance) CurrentSlot added in v0.5.1

func (c *ProdBeaconInstance) CurrentSlot() (uint64, error)

func (*ProdBeaconInstance) GetForkSchedule added in v0.20.0

func (c *ProdBeaconInstance) GetForkSchedule() (spec *GetForkScheduleResponse, err error)

GetForkSchedule - https://ethereum.github.io/beacon-APIs/#/Config/getForkSchedule

func (*ProdBeaconInstance) GetGenesis added in v0.14.0

func (c *ProdBeaconInstance) GetGenesis() (*GetGenesisResponse, error)

GetGenesis returns the genesis info - https://ethereum.github.io/beacon-APIs/#/Beacon/getGenesis

func (*ProdBeaconInstance) GetHeader added in v0.5.1

func (c *ProdBeaconInstance) GetHeader() (*GetHeaderResponse, error)

GetHeader returns the latest header - https://ethereum.github.io/beacon-APIs/#/Beacon/getBlockHeader

func (*ProdBeaconInstance) GetHeaderForSlot added in v0.12.3

func (c *ProdBeaconInstance) GetHeaderForSlot(slot uint64) (*GetHeaderResponse, error)

GetHeaderForSlot returns the header for a given slot - https://ethereum.github.io/beacon-APIs/#/Beacon/getBlockHeader

func (*ProdBeaconInstance) GetProposerDuties added in v0.5.1

func (c *ProdBeaconInstance) GetProposerDuties(epoch uint64) (*ProposerDutiesResponse, error)

GetProposerDuties returns proposer duties for every slot in this epoch https://ethereum.github.io/beacon-APIs/#/Validator/getProposerDuties

func (*ProdBeaconInstance) GetPublishURI added in v0.30.0

func (c *ProdBeaconInstance) GetPublishURI() string

func (*ProdBeaconInstance) GetRandao added in v0.14.0

func (c *ProdBeaconInstance) GetRandao(slot uint64) (randaoResp *GetRandaoResponse, err error)

GetRandao - /eth/v1/beacon/states/<slot>/randao

func (*ProdBeaconInstance) GetSpec added in v0.14.0

func (c *ProdBeaconInstance) GetSpec() (spec *GetSpecResponse, err error)

GetSpec - https://ethereum.github.io/beacon-APIs/#/Config/getSpec

func (*ProdBeaconInstance) GetStateValidators added in v0.20.0

func (c *ProdBeaconInstance) GetStateValidators(stateID string) (*GetStateValidatorsResponse, error)

GetStateValidators loads all active and pending validators https://ethereum.github.io/beacon-APIs/#/Beacon/getStateValidators

func (*ProdBeaconInstance) GetURI added in v0.5.1

func (c *ProdBeaconInstance) GetURI() string

func (*ProdBeaconInstance) GetWithdrawals added in v0.20.0

func (c *ProdBeaconInstance) GetWithdrawals(slot uint64) (withdrawalsResp *GetWithdrawalsResponse, err error)

GetWithdrawals - /eth/v1/beacon/states/<slot>/withdrawals

func (*ProdBeaconInstance) PublishBlock added in v0.6.0

func (c *ProdBeaconInstance) PublishBlock(block *common.VersionedSignedProposal, broadcastMode BroadcastMode) (code int, err error)

func (*ProdBeaconInstance) StreamStateValidators added in v0.35.0

func (c *ProdBeaconInstance) StreamStateValidators(stateID string, collector ValidatorCollector) error

StreamStateValidators loads all active and pending validators, handing each to the collector as it is decoded. https://ethereum.github.io/beacon-APIs/#/Beacon/getStateValidators

func (*ProdBeaconInstance) SubscribeToHeadEvents added in v0.5.1

func (c *ProdBeaconInstance) SubscribeToHeadEvents(slotC chan HeadEventData)

func (*ProdBeaconInstance) SubscribeToPayloadAttributesEvents added in v0.20.0

func (c *ProdBeaconInstance) SubscribeToPayloadAttributesEvents(payloadAttributesC chan PayloadAttributesEvent)

func (*ProdBeaconInstance) SyncStatus added in v0.5.1

func (c *ProdBeaconInstance) SyncStatus() (*SyncStatusPayloadData, error)

SyncStatus returns the current node sync-status https://ethereum.github.io/beacon-APIs/#/ValidatorRequiredApi/getSyncingStatus

type ProposerDutiesResponse

type ProposerDutiesResponse struct {
	Data []ProposerDutiesResponseData
}

type ProposerDutiesResponseData

type ProposerDutiesResponseData struct {
	Slot           uint64 `json:"slot,string"`
	Pubkey         string `json:"pubkey"`
	ValidatorIndex uint64 `json:"validator_index,string"`
}

type SyncStatusPayload

type SyncStatusPayload struct {
	Data SyncStatusPayloadData
}

SyncStatusPayload is the response payload for /eth/v1/node/syncing {"data":{"head_slot":"251114","sync_distance":"0","is_syncing":false,"is_optimistic":false}}

type SyncStatusPayloadData

type SyncStatusPayloadData struct {
	HeadSlot  uint64 `json:"head_slot,string"`
	IsSyncing bool   `json:"is_syncing"`
}

type ValidatorCollector added in v0.35.0

type ValidatorCollector interface {
	// Reset discards everything collected so far. It is called once before the first
	// validator of an attempt, so a beacon node that fails part-way through leaves no
	// partial state behind for the next one.
	Reset()
	Add(index uint64, pubkey string)
}

ValidatorCollector accumulates validators as they are decoded, so the validator set is never held in its serialized form.

type ValidatorResponseEntry

type ValidatorResponseEntry struct {
	Index uint64 `json:"index,string"` // Index of validator in validator registry.
	// Balance   string                         `json:"balance"`      // Current validator balance in gwei.
	// Status    string                         `json:"status"`
	Validator ValidatorResponseValidatorData `json:"validator"`
}

type ValidatorResponseValidatorData

type ValidatorResponseValidatorData struct {
	Pubkey string `json:"pubkey"`
}

Jump to

Keyboard shortcuts

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