beacon

Documentation

Overview

Package beacon provides a client for interacting with the standard Eth Beacon Node API. Interactive swagger documentation for the API is available here: https://ethereum.github.io/beacon-APIs/

Index

• Variables
• type Client
  • func NewClient(host string, opts ...ClientOpt) (*Client, error)
  • func (c *Client) GetBLStoExecutionChanges(ctx context.Context) (*apimiddleware.BLSToExecutionChangesPoolResponseJson, error)
  • func (c *Client) GetBlock(ctx context.Context, blockId StateOrBlockId) ([]byte, error)
  • func (c *Client) GetBlockRoot(ctx context.Context, blockId StateOrBlockId) ([32]byte, error)
  • func (c *Client) GetFork(ctx context.Context, stateId StateOrBlockId) (*ethpb.Fork, error)
  • func (c *Client) GetForkSchedule(ctx context.Context) (forks.OrderedSchedule, error)
  • func (c *Client) GetNodeVersion(ctx context.Context) (*NodeVersion, error)
  • func (c *Client) GetState(ctx context.Context, stateId StateOrBlockId) ([]byte, error)
  • func (c *Client) GetWeakSubjectivity(ctx context.Context) (*WeakSubjectivityData, error)
  • func (c *Client) NodeURL() string
  • func (c *Client) SubmitChangeBLStoExecution(ctx context.Context, request []*apimiddleware.SignedBLSToExecutionChangeJson) error
• type ClientOpt
  • func WithTimeout(timeout time.Duration) ClientOpt
• type NodeVersion
• type OriginData
  • func DownloadFinalizedData(ctx context.Context, client *Client) (*OriginData, error)
  • func (o *OriginData) BlockBytes() []byte
  • func (o *OriginData) SaveBlock(dir string) (string, error)
  • func (o *OriginData) SaveState(dir string) (string, error)
  • func (o *OriginData) StateBytes() []byte
• type StateOrBlockId
  • func IdFromRoot(r [32]byte) StateOrBlockId
  • func IdFromSlot(s primitives.Slot) StateOrBlockId
• type WeakSubjectivityData
  • func ComputeWeakSubjectivityCheckpoint(ctx context.Context, client *Client) (*WeakSubjectivityData, error)
  • func (wsd *WeakSubjectivityData) CheckpointString() string

Variables

var ErrInvalidNodeVersion = errors.New("invalid node version response")

ErrInvalidNodeVersion indicates that the /eth/v1/node/version api response format was not recognized.

var ErrMalformedHostname = errors.New("hostname must include port, separated by one colon, like example.com:3500")

var ErrNotFound = errors.Wrap(ErrNotOK, "recv 404 NotFound response from API")

ErrNotFound specifically means that a '404 - NOT FOUND' response was received from the API.

var ErrNotOK = errors.New("did not receive 2xx response from API")

ErrNotOK is used to indicate when an HTTP request to the Beacon Node API failed with any non-2xx response code. More specific errors may be returned, but an error in reaction to a non-2xx response will always wrap ErrNotOK.

Types

type Client

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

Client provides a collection of helper methods for calling the Eth Beacon Node API endpoints.

func NewClient

func NewClient(host string, opts ...ClientOpt) (*Client, error)

NewClient constructs a new client with the provided options (ex WithTimeout). `host` is the base host + port used to construct request urls. This value can be a URL string, or NewClient will assume an http endpoint if just `host:port` is used.

func (*Client) GetBLStoExecutionChanges

func (c *Client) GetBLStoExecutionChanges(ctx context.Context) (*apimiddleware.BLSToExecutionChangesPoolResponseJson, error)

GetBLStoExecutionChanges gets all the set withdrawal messages in the node's operation pool. Returns a struct representation of json response.

func (*Client) GetBlock

func (c *Client) GetBlock(ctx context.Context, blockId StateOrBlockId) ([]byte, error)

GetBlock retrieves the SignedBeaconBlock for the given block id. Block identifier can be one of: "head" (canonical head in node's view), "genesis", "finalized", <slot>, <hex encoded blockRoot with 0x prefix>. Variables of type StateOrBlockId are exported by this package for the named identifiers. The return value contains the ssz-encoded bytes.

func (*Client) GetBlockRoot

func (c *Client) GetBlockRoot(ctx context.Context, blockId StateOrBlockId) ([32]byte, error)

GetBlockRoot retrieves the hash_tree_root of the BeaconBlock for the given block id. Block identifier can be one of: "head" (canonical head in node's view), "genesis", "finalized", <slot>, <hex encoded blockRoot with 0x prefix>. Variables of type StateOrBlockId are exported by this package for the named identifiers.

func (*Client) GetFork

func (c *Client) GetFork(ctx context.Context, stateId StateOrBlockId) (*ethpb.Fork, error)

GetFork queries the Beacon Node API for the Fork from the state identified by stateId. Block identifier can be one of: "head" (canonical head in node's view), "genesis", "finalized", <slot>, <hex encoded blockRoot with 0x prefix>. Variables of type StateOrBlockId are exported by this package for the named identifiers.

func (*Client) GetForkSchedule

func (c *Client) GetForkSchedule(ctx context.Context) (forks.OrderedSchedule, error)

GetForkSchedule retrieve all forks, past present and future, of which this node is aware.

func (*Client) GetNodeVersion

func (c *Client) GetNodeVersion(ctx context.Context) (*NodeVersion, error)

GetNodeVersion requests that the beacon node identify information about its implementation in a format similar to a HTTP User-Agent field. ex: Lighthouse/v0.1.5 (Linux x86_64)

func (*Client) GetState

func (c *Client) GetState(ctx context.Context, stateId StateOrBlockId) ([]byte, error)

GetState retrieves the BeaconState for the given state id. State identifier can be one of: "head" (canonical head in node's view), "genesis", "finalized", <slot>, <hex encoded stateRoot with 0x prefix>. Variables of type StateOrBlockId are exported by this package for the named identifiers. The return value contains the ssz-encoded bytes.

func (*Client) GetWeakSubjectivity

func (c *Client) GetWeakSubjectivity(ctx context.Context) (*WeakSubjectivityData, error)

GetWeakSubjectivity calls a proposed API endpoint that is unique to prysm This api method does the following: - computes weak subjectivity epoch - finds the highest non-skipped block preceding the epoch - returns the htr of the found block and returns this + the value of state_root from the block

func (*Client) NodeURL

func (c *Client) NodeURL() string

NodeURL returns a human-readable string representation of the beacon node base url.

func (*Client) SubmitChangeBLStoExecution

func (c *Client) SubmitChangeBLStoExecution(ctx context.Context, request []*apimiddleware.SignedBLSToExecutionChangeJson) error

SubmitChangeBLStoExecution calls a beacon API endpoint to set the withdrawal addresses based on the given signed messages. If the API responds with something other than OK there will be failure messages associated to the corresponding request message.

type ClientOpt

type ClientOpt func(*Client)

ClientOpt is a functional option for the Client type (http.Client wrapper)

func WithTimeout

func WithTimeout(timeout time.Duration) ClientOpt

WithTimeout sets the .Timeout attribute of the wrapped http.Client.

type NodeVersion

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

type OriginData

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

OriginData represents the BeaconState and ReadOnlySignedBeaconBlock necessary to start an empty Beacon Node using Checkpoint Sync.

func DownloadFinalizedData

func DownloadFinalizedData(ctx context.Context, client *Client) (*OriginData, error)

DownloadFinalizedData downloads the most recently finalized state, and the block most recently applied to that state. This pair can be used to initialize a new beacon node via checkpoint sync.

func (*OriginData) BlockBytes

func (o *OriginData) BlockBytes() []byte

BlockBytes returns the ssz-encoded bytes of the downloaded ReadOnlySignedBeaconBlock value.

func (*OriginData) SaveBlock

func (o *OriginData) SaveBlock(dir string) (string, error)

SaveBlock saves the downloaded block to a unique file in the given path. For readability and collision avoidance, the file name includes: type, config name, slot and root

func (*OriginData) SaveState

func (o *OriginData) SaveState(dir string) (string, error)

SaveState saves the downloaded state to a unique file in the given path. For readability and collision avoidance, the file name includes: type, config name, slot and root

func (*OriginData) StateBytes

func (o *OriginData) StateBytes() []byte

StateBytes returns the ssz-encoded bytes of the downloaded BeaconState value.

type StateOrBlockId

type StateOrBlockId string

StateOrBlockId represents the block_id / state_id parameters that several of the Eth Beacon API methods accept. StateOrBlockId constants are defined for named identifiers, and helper methods are provided for slot and root identifiers. Example text from the Eth Beacon Node API documentation:

"Block identifier can be one of: "head" (canonical head in node's view), "genesis", "finalized", <slot>, <hex encoded blockRoot with 0x prefix>."

const (
	IdGenesis   StateOrBlockId = "genesis"
	IdHead      StateOrBlockId = "head"
	IdFinalized StateOrBlockId = "finalized"
)

func IdFromRoot

func IdFromRoot(r [32]byte) StateOrBlockId

IdFromRoot encodes a block root in the format expected by the API in places where a root can be used to identify a BeaconState or SignedBeaconBlock.

func IdFromSlot

func IdFromSlot(s primitives.Slot) StateOrBlockId

IdFromSlot encodes a Slot in the format expected by the API in places where a slot can be used to identify a BeaconState or SignedBeaconBlock.

type WeakSubjectivityData

type WeakSubjectivityData struct {
	BlockRoot [32]byte
	StateRoot [32]byte
	Epoch     primitives.Epoch
}

WeakSubjectivityData represents the state root, block root and epoch of the BeaconState + ReadOnlySignedBeaconBlock that falls at the beginning of the current weak subjectivity period. These values can be used to construct a weak subjectivity checkpoint beacon node flag to be used for validation.

func ComputeWeakSubjectivityCheckpoint

func ComputeWeakSubjectivityCheckpoint(ctx context.Context, client *Client) (*WeakSubjectivityData, error)

ComputeWeakSubjectivityCheckpoint attempts to use the prysm weak_subjectivity api to obtain the current weak_subjectivity checkpoint. For non-prysm nodes, the same computation will be performed with extra steps, using the head state downloaded from the beacon node api.

func (*WeakSubjectivityData) CheckpointString

func (wsd *WeakSubjectivityData) CheckpointString() string

CheckpointString returns the standard string representation of a Checkpoint. The format is a a hex-encoded block root, followed by the epoch of the block, separated by a colon. For example: "0x1c35540cac127315fabb6bf29181f2ae0de1a3fc909d2e76ba771e61312cc49a:74888"