beacon

package
v0.0.2 Latest Latest
Warning

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

 Go to latest Published: Jul 8, 2026 License: GPL-3.0 Imports: 26 Imported by: 0

Documentation

Overview

Package beacon provides a client for interacting with Ethereum consensus layer nodes.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AttestationEvent 

type AttestationEvent struct {
	AggregationBits []byte
	Slot            phase0.Slot
	Index           uint64
	BeaconBlockRoot phase0.Root
	CommitteeBits   []byte // nil for pre-Electra
	ReceivedAt      time.Time
}

AttestationEvent represents an attestation event from the beacon node.

type BidEvent 

type BidEvent struct {
	Slot               phase0.Slot
	ParentBlockHash    phase0.Hash32
	ParentBlockRoot    phase0.Root
	BlockHash          phase0.Hash32
	FeeRecipient       [20]byte
	GasLimit           uint64
	BuilderIndex       uint64
	Value              uint64
	ExecutionPayment   uint64
	BlobKZGCommitments [][]byte
	Signature          phase0.BLSSignature
	ReceivedAt         time.Time
}

BidEvent represents an execution payload bid event.

type BlockInfo 

type BlockInfo struct {
	Slot               phase0.Slot
	Root               phase0.Root
	ExecutionBlockHash phase0.Hash32
	// Execution block hash safe to use as an FCU safe/finalized hash; always
	// present on the EL. See agnosticFinalitySafeExecutionBlockHash.
	FinalitySafeExecutionBlockHash phase0.Hash32
	ParentRoot                     phase0.Root
	StateRoot                      phase0.Root
}

BlockInfo contains execution-relevant information from a beacon block.

type ChainStatusResult 

type ChainStatusResult struct {
	FinalizedRoot  phase0.Root
	FinalizedEpoch uint64
	HeadRoot       phase0.Root
	HeadSlot       uint64
}

ChainStatusResult holds the head and finality data needed to populate a libp2p StatusV2 message. Fork digest computation is intentionally excluded here — callers that have access to the chain spec (BPO schedule) are responsible for computing it and applying all cumulative BPO XORs.

type Client 

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

Client wraps the consensus layer client for beacon node interactions.

func NewClient 

func NewClient(ctx context.Context, baseURL string, log logrus.FieldLogger) (*Client, error)

NewClient creates a new CL client connected to the specified beacon node. The client allows delayed start so it can be created even when the beacon node is not yet reachable; callers should retry API calls until the node is ready.

func (*Client) Close 

func (c *Client) Close()

Close closes the client and stops the event stream.

func (*Client) Events 

func (c *Client) Events() *EventStream

Events returns the event stream for subscribing to beacon events.

func (*Client) GetBaseURL 

func (c *Client) GetBaseURL() string

GetBaseURL returns the base URL of the beacon node.

func (*Client) GetBlockInfo 

func (c *Client) GetBlockInfo(ctx context.Context, blockID string) (*BlockInfo, error)

GetBlockInfo fetches beacon block info at the given block ID.

It uses the fork-agnostic block type and computes the block root via dynssz, which honours the network's spec (set via InitGlobalSSZSpecs). The versioned type's Root() routes through fastssz code generated for mainnet preset sizes, so it returns wrong roots on non-mainnet presets (e.g. minimal).

func (*Client) GetChainStatus 

func (c *Client) GetChainStatus(ctx context.Context) (*ChainStatusResult, error)

GetChainStatus fetches the current chain head and finality data from the beacon node. It does NOT compute the fork digest — use GetCurrentForkVersion alongside the chain spec's BlobSchedule to compute the correct BPO-modified fork digest for StatusV2 messages.

func (*Client) GetCurrentForkVersion 

func (c *Client) GetCurrentForkVersion(ctx context.Context) (phase0.Version, error)

GetCurrentForkVersion fetches the current fork version from the beacon node's head state. This reflects the currently active fork (e.g. Fulu or Gloas), not a future scheduled fork.

func (*Client) GetExecutionPayloadEnvelope 

func (c *Client) GetExecutionPayloadEnvelope(
	ctx context.Context,
	blockID string,
) (*PayloadEnvelopeInfo, error)

GetExecutionPayloadEnvelope fetches the signed execution payload envelope for a block. The blockID can be a block root (hex), slot number, or "head"/"finalized"/"genesis".

func (*Client) GetFinalityInfo 

func (c *Client) GetFinalityInfo(ctx context.Context) (*FinalityInfo, error)

GetFinalityInfo fetches finality checkpoints and returns execution block hashes.

func (*Client) GetForkVersion 

func (c *Client) GetForkVersion(ctx context.Context) (phase0.Version, error)

GetForkVersion returns the current fork version.

func (*Client) GetGenesis 

func (c *Client) GetGenesis(ctx context.Context) (*Genesis, error)

GetGenesis fetches genesis information from the beacon node via direct HTTP. This bypasses go-eth2-client's active check so it works before the node is fully ready.

func (*Client) GetNodeIdentity 

func (c *Client) GetNodeIdentity(ctx context.Context) (*NodeIdentity, error)

GetNodeIdentity fetches the beacon node's P2P identity via /eth/v1/node/identity.

func (*Client) GetRawClient 

func (c *Client) GetRawClient() eth2client.Service

GetRawClient returns the underlying eth2client.Service for direct API access.

func (*Client) GetRawSpecData 

func (c *Client) GetRawSpecData(ctx context.Context) (map[string]string, map[string]json.RawMessage, error)

GetRawSpecData fetches /eth/v1/config/spec via direct HTTP, bypassing go-eth2-client. Returns both a string map (for simple values) and the raw JSON map (for complex values like BLOB_SCHEDULE).

func (*Client) GetValidatorIndexToPubkeyMap 

func (c *Client) GetValidatorIndexToPubkeyMap(ctx context.Context, stateID string) (map[phase0.ValidatorIndex]phase0.BLSPubKey, error)

GetValidatorIndexToPubkeyMap fetches the beacon state once and returns a map of validator index to pubkey. Used to refresh an index→pubkey cache once per epoch instead of querying per payload build.

func (*Client) InitGlobalSSZSpecs 

func (c *Client) InitGlobalSSZSpecs(ctx context.Context) error

InitGlobalSSZSpecs configures the global dynssz instance with this network's spec values. The go-eth2-client SSZ codecs (e.g. block.Root()) route through dynssz.GetGlobalDynSsz(), which otherwise defaults to mainnet preset sizes — producing wrong hash-tree-roots on minimal-preset networks. We reuse the spec map go-eth2-client already parses (SpecProvider.Spec), which is directly compatible with dynssz.SetGlobalSpecs.

func (*Client) SubmitExecutionPayloadBid 

func (c *Client) SubmitExecutionPayloadBid(ctx context.Context, bid *eth2all.SignedExecutionPayloadBid) error

SubmitExecutionPayloadBid submits a signed execution payload bid to the beacon node. The consensus version header and body encoding (SSZ or JSON per the client's content negotiation) are derived from the bid's Version by go-eth2-client.

func (*Client) SubmitExecutionPayloadEnvelope 

func (c *Client) SubmitExecutionPayloadEnvelope(
	ctx context.Context,
	envelope *eth2all.SignedExecutionPayloadEnvelope,
	blobs [][]byte,
	kzgProofs [][]byte,
) error

SubmitExecutionPayloadEnvelope submits a signed execution payload envelope using the stateless flow (SignedExecutionPayloadEnvelopeContents body, Eth-Execution-Payload-Blinded false). The stateful/blinded flow only works when the beacon node cached the full envelope from its own block production (produceBlockV4); buildoor builds payloads externally, so the beacon node never has them cached and the stateless form is the only valid one.

The consensus version header and body encoding (SSZ or JSON per the client's content negotiation) are derived from the envelope's Version by go-eth2-client.

func (*Client) SubmitProposal 

func (c *Client) SubmitProposal(ctx context.Context, opts *api.SubmitProposalOpts) error

SubmitProposal submits a full signed proposal (e.g. SignedBlockContents) to the beacon node. Used by the builder API after unblinding a blinded block.

func (*Client) SubmitVoluntaryExit 

func (c *Client) SubmitVoluntaryExit(ctx context.Context, exit *phase0.SignedVoluntaryExit) error

SubmitVoluntaryExit submits a signed voluntary exit to the beacon node.

type EventStream 

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

EventStream manages SSE connections to the beacon node event stream.

func NewEventStream 

func NewEventStream(client *Client) *EventStream

NewEventStream creates a new event stream for the given client.

func (*EventStream) CleanupPayloadAttributesCache 

func (e *EventStream) CleanupPayloadAttributesCache(beforeSlot phase0.Slot)

CleanupPayloadAttributesCache removes cached payload_attributes entries for slots older than beforeSlot.

func (*EventStream) GetLatestPayloadAttributes 

func (e *EventStream) GetLatestPayloadAttributes(slot phase0.Slot) *PayloadAttributesEvent

GetLatestPayloadAttributes returns the latest cached payload_attributes event for the given slot, or nil if none has been received.

func (*EventStream) Start 

func (e *EventStream) Start(ctx context.Context) error

Start begins listening to beacon node events.

func (*EventStream) Stop 

func (e *EventStream) Stop()

Stop stops the event stream.

func (*EventStream) SubscribeAttestations 

func (e *EventStream) SubscribeAttestations() *utils.Subscription[*AttestationEvent]

SubscribeAttestations returns a subscription for attestation events.

func (*EventStream) SubscribeBids 

func (e *EventStream) SubscribeBids() *utils.Subscription[*BidEvent]

SubscribeBids returns a subscription for bid events.

func (*EventStream) SubscribeHead 

func (e *EventStream) SubscribeHead() *utils.Subscription[*HeadEvent]

SubscribeHead returns a subscription for head events.

func (*EventStream) SubscribePayloadAttributes 

func (e *EventStream) SubscribePayloadAttributes() *utils.Subscription[*PayloadAttributesEvent]

SubscribePayloadAttributes returns a subscription for payload attributes events.

func (*EventStream) SubscribePayloadAvailable 

func (e *EventStream) SubscribePayloadAvailable() *utils.Subscription[*PayloadAvailableEvent]

SubscribePayloadAvailable returns a subscription for execution_payload_available events.

func (*EventStream) SubscribeProposerPreferences 

func (e *EventStream) SubscribeProposerPreferences() *utils.Subscription[*gloas.SignedProposerPreferences]

SubscribeProposerPreferences returns a subscription for proposer_preferences events.

type FinalityInfo 

type FinalityInfo struct {
	HeadExecutionBlockHash      phase0.Hash32
	SafeExecutionBlockHash      phase0.Hash32
	FinalizedExecutionBlockHash phase0.Hash32
}

FinalityInfo contains finality checkpoint execution block hashes.

type Genesis 

type Genesis struct {
	GenesisTime           time.Time
	GenesisValidatorsRoot phase0.Root
	GenesisForkVersion    phase0.Version
}

Genesis holds genesis information.

type HeadEvent 

type HeadEvent struct {
	Slot                      phase0.Slot
	Block                     phase0.Root
	State                     phase0.Root
	EpochTransition           bool
	ExecutionOptimistic       bool
	PreviousDutyDependentRoot phase0.Root
	CurrentDutyDependentRoot  phase0.Root
}

HeadEvent represents a head event from the beacon node.

type NodeIdentity 

type NodeIdentity struct {
	PeerID       string   `json:"peer_id"`
	P2PAddresses []string `json:"p2p_addresses"`
}

NodeIdentity holds the beacon node's P2P identity information.

type PayloadAttributesEvent 

type PayloadAttributesEvent struct {
	Version                   string
	ProposalSlot              phase0.Slot
	ProposerIndex             phase0.ValidatorIndex
	ParentBlockRoot           phase0.Root
	ParentBlockNumber         uint64
	ParentBlockHash           phase0.Hash32
	Timestamp                 uint64
	PrevRandao                phase0.Root
	SuggestedFeeRecipient     common.Address
	Withdrawals               []*capella.Withdrawal
	ParentBeaconBlockRoot     phase0.Root
	TargetGasLimit            uint64
	InclusionListTransactions [][]byte
}

PayloadAttributesEvent represents a payload_attributes event from the beacon node. This is emitted when a validator is scheduled to propose and contains all parameters needed for building an execution payload.

type PayloadAvailableEvent 

type PayloadAvailableEvent struct {
	Slot       phase0.Slot
	BlockRoot  phase0.Root // Beacon block root this payload belongs to
	ReceivedAt time.Time
}

PayloadAvailableEvent represents an execution_payload_available event (Gloas). This is emitted when the node has verified that the execution payload and blobs for a block are available and ready for payload attestation.

type PayloadEnvelopeInfo 

type PayloadEnvelopeInfo struct {
	BlockRoot    phase0.Root
	BlockHash    phase0.Hash32
	BuilderIndex uint64
}

PayloadEnvelopeInfo contains key fields from a fetched execution payload envelope.

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.