builder

package
v6.0.5 Latest Latest
Warning

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

Go to latest
Published: Sep 25, 2025 License: GPL-3.0 Imports: 34 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source
var ErrBadRequest = errors.Wrap(ErrNotOK, "recv 400 BadRequest response from API")

ErrBadRequest specifically means that a '400 - BAD REQUEST' response was received from the API.

View Source
var ErrNoContent = errors.New("recv 204 no content response from API, No header is available")

ErrNoContent specifically means that a '204 - No Content' response was received from the API. Typically, a 204 is a success but in this case for the Header API means No header is available

View Source
var ErrNotAcceptable = errors.Wrap(ErrNotOK, "The accept header value is not acceptable")

ErrNotAcceptable specifically means that a '406 - Not Acceptable' was received from the API.

View Source
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.

View Source
var ErrNotOK = errors.New("did not receive 200 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.

View Source
var ErrUnsupportedMediaType = errors.Wrap(ErrNotOK, "The media type in \"Content-Type\" header is unsupported, and the request has been rejected. This occurs when a HTTP request supplies a payload in a content-type that the server is not able to handle.")

ErrUnsupportedMediaType specifically means that a '415 - Unsupported Media Type' was received from the API.

Functions

This section is empty.

Types

type BeaconBlockHeader

type BeaconBlockHeader struct {
	*eth.BeaconBlockHeader
}

BeaconBlockHeader is a field of SignedBeaconBlockHeader.

func (*BeaconBlockHeader) MarshalJSON

func (h *BeaconBlockHeader) MarshalJSON() ([]byte, error)

MarshalJSON returns a JSON byte array representation of BeaconBlockHeader.

type Bid

type Bid interface {
	Header() (interfaces.ExecutionData, error)
	Value() primitives.Wei
	Pubkey() []byte
	Version() int
	IsNil() bool
	HashTreeRoot() ([32]byte, error)
	HashTreeRootWith(hh *ssz.Hasher) error
}

Bid is an interface describing the method set of a builder bid.

func WrappedBuilderBid

func WrappedBuilderBid(p *ethpb.BuilderBid) (Bid, error)

WrappedBuilderBid is a constructor which wraps a protobuf bid into an interface.

func WrappedBuilderBidCapella

func WrappedBuilderBidCapella(p *ethpb.BuilderBidCapella) (Bid, error)

WrappedBuilderBidCapella is a constructor which wraps a protobuf bid into an interface.

func WrappedBuilderBidDeneb

func WrappedBuilderBidDeneb(p *ethpb.BuilderBidDeneb) (Bid, error)

WrappedBuilderBidDeneb is a constructor which wraps a protobuf bid into an interface.

func WrappedBuilderBidElectra

func WrappedBuilderBidElectra(p *ethpb.BuilderBidElectra) (Bid, error)

WrappedBuilderBidElectra is a constructor which wraps a protobuf bid into an interface.

type BidDeneb

type BidDeneb interface {
	Bid
	BlobKzgCommitments() [][]byte
}

BidDeneb is an interface that exposes newly added kzg commitments on top of builder bid

type BidElectra

type BidElectra interface {
	BidDeneb
	ExecutionRequests() *v1.ExecutionRequests
}

BidElectra is an interface that exposes the newly added execution requests on top of the builder bid

type BlobBundler

type BlobBundler interface {
	BundleProto() (*v1.BlobsBundle, error)
}

BlobBundler can retrieve the underlying blob bundle protobuf message for the given execution payload response.

type BlobsBundle

type BlobsBundle struct {
	Commitments []hexutil.Bytes `json:"commitments"`
	Proofs      []hexutil.Bytes `json:"proofs"`
	Blobs       []hexutil.Bytes `json:"blobs"`
}

BlobsBundle is a field in ExecutionPayloadDenebAndBlobsBundle.

func FromBundleProto

func FromBundleProto(bundle *v1.BlobsBundle) *BlobsBundle

FromBundleProto converts the proto bundle type to the builder type.

func (BlobsBundle) ToProto

func (b BlobsBundle) ToProto() (*v1.BlobsBundle, error)

ToProto returns a BlobsBundle Proto.

type BuilderBid

type BuilderBid struct {
	Header *structs.ExecutionPayloadHeader `json:"header"`
	Value  Uint256                         `json:"value"`
	Pubkey hexutil.Bytes                   `json:"pubkey"`
}

BuilderBid is part of ExecHeaderResponse for Bellatrix.

func (*BuilderBid) ToProto

func (bb *BuilderBid) ToProto() (*eth.BuilderBid, error)

ToProto returns a BuilderBid Proto for Bellatrix.

type BuilderBidCapella

type BuilderBidCapella struct {
	Header *structs.ExecutionPayloadHeaderCapella `json:"header"`
	Value  Uint256                                `json:"value"`
	Pubkey hexutil.Bytes                          `json:"pubkey"`
}

BuilderBidCapella is field of ExecHeaderResponseCapella.

func (*BuilderBidCapella) ToProto

func (bb *BuilderBidCapella) ToProto() (*eth.BuilderBidCapella, error)

ToProto returns a BuilderBidCapella Proto.

type BuilderBidDeneb

type BuilderBidDeneb struct {
	Header             *structs.ExecutionPayloadHeaderDeneb `json:"header"`
	BlobKzgCommitments []hexutil.Bytes                      `json:"blob_kzg_commitments"`
	Value              Uint256                              `json:"value"`
	Pubkey             hexutil.Bytes                        `json:"pubkey"`
}

BuilderBidDeneb is a field of ExecHeaderResponseDeneb.

func (*BuilderBidDeneb) ToProto

func (bb *BuilderBidDeneb) ToProto() (*eth.BuilderBidDeneb, error)

ToProto creates a BuilderBidDeneb Proto from BuilderBidDeneb.

type BuilderBidElectra

type BuilderBidElectra struct {
	Header             *structs.ExecutionPayloadHeaderDeneb `json:"header"`
	BlobKzgCommitments []hexutil.Bytes                      `json:"blob_kzg_commitments"`
	ExecutionRequests  *structs.ExecutionRequests           `json:"execution_requests"`
	Value              Uint256                              `json:"value"`
	Pubkey             hexutil.Bytes                        `json:"pubkey"`
}

BuilderBidElectra is a field of ExecHeaderResponseElectra.

func (*BuilderBidElectra) ToProto

func (bb *BuilderBidElectra) ToProto(slot types.Slot) (*eth.BuilderBidElectra, error)

ToProto creates a BuilderBidElectra Proto from BuilderBidElectra.

type BuilderClient

type BuilderClient interface {
	NodeURL() string
	GetHeader(ctx context.Context, slot primitives.Slot, parentHash [32]byte, pubkey [48]byte) (SignedBid, error)
	RegisterValidator(ctx context.Context, svr []*ethpb.SignedValidatorRegistrationV1) error
	SubmitBlindedBlock(ctx context.Context, sb interfaces.ReadOnlySignedBeaconBlock) (interfaces.ExecutionData, *v1.BlobsBundle, error)
	Status(ctx context.Context) error
}

BuilderClient provides a collection of helper methods for calling Builder API endpoints.

type Client

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

Client provides a collection of helper methods for calling Builder 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) GetHeader

func (c *Client) GetHeader(ctx context.Context, slot primitives.Slot, parentHash [32]byte, pubkey [48]byte) (SignedBid, error)

GetHeader is used by a proposing validator to request an execution payload header from the Builder node.

func (*Client) NodeURL

func (c *Client) NodeURL() string

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

func (*Client) RegisterValidator

func (c *Client) RegisterValidator(ctx context.Context, svr []*ethpb.SignedValidatorRegistrationV1) error

RegisterValidator encodes the SignedValidatorRegistrationV1 message to json (including hex-encoding the byte fields with 0x prefixes) and posts to the builder validator registration endpoint.

func (*Client) Status

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

Status asks the remote builder server for a health check. A response of 200 with an empty body is the success/healthy response, and an error response may have an error message. This method will return a nil value for error in the happy path, and an error with information about the server response body for a non-200 response.

func (*Client) SubmitBlindedBlock

SubmitBlindedBlock calls the builder API endpoint that binds the validator to the builder and submits the block. The response is the full execution payload used to create the blinded block.

type ClientOpt

type ClientOpt func(*Client)

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

func WithObserver

func WithObserver(m observer) ClientOpt

func WithSSZ

func WithSSZ() ClientOpt

type ErrorMessage

type ErrorMessage struct {
	Code        int      `json:"code"`
	Message     string   `json:"message"`
	Stacktraces []string `json:"stacktraces,omitempty"`
}

ErrorMessage is a JSON representation of the builder API's returned error message.

type ExecHeaderResponse

type ExecHeaderResponse struct {
	Version string `json:"version"`
	Data    struct {
		Signature hexutil.Bytes `json:"signature"`
		Message   *BuilderBid   `json:"message"`
	} `json:"data"`
}

ExecHeaderResponse is a JSON representation of the builder API header response for Bellatrix.

func (*ExecHeaderResponse) ToProto

func (ehr *ExecHeaderResponse) ToProto() (*eth.SignedBuilderBid, error)

ToProto returns a SignedBuilderBid from ExecHeaderResponse for Bellatrix.

type ExecHeaderResponseCapella

type ExecHeaderResponseCapella struct {
	Version string `json:"version"`
	Data    struct {
		Signature hexutil.Bytes      `json:"signature"`
		Message   *BuilderBidCapella `json:"message"`
	} `json:"data"`
}

ExecHeaderResponseCapella is the response of builder API /eth/v1/builder/header/{slot}/{parent_hash}/{pubkey} for Capella.

func (*ExecHeaderResponseCapella) ToProto

ToProto returns a SignedBuilderBidCapella Proto from ExecHeaderResponseCapella.

type ExecHeaderResponseDeneb

type ExecHeaderResponseDeneb struct {
	Version string `json:"version"`
	Data    struct {
		Signature hexutil.Bytes    `json:"signature"`
		Message   *BuilderBidDeneb `json:"message"`
	} `json:"data"`
}

ExecHeaderResponseDeneb is the header response for builder API /eth/v1/builder/header/{slot}/{parent_hash}/{pubkey}.

func (*ExecHeaderResponseDeneb) ToProto

ToProto creates a SignedBuilderBidDeneb Proto from ExecHeaderResponseDeneb.

type ExecHeaderResponseElectra

type ExecHeaderResponseElectra struct {
	Version string `json:"version"`
	Data    struct {
		Signature hexutil.Bytes      `json:"signature"`
		Message   *BuilderBidElectra `json:"message"`
	} `json:"data"`
}

ExecHeaderResponseElectra is the header response for builder API /eth/v1/builder/header/{slot}/{parent_hash}/{pubkey}.

func (*ExecHeaderResponseElectra) ToProto

ToProto creates a SignedBuilderBidElectra Proto from ExecHeaderResponseElectra.

type ExecPayloadResponseCapella

type ExecPayloadResponseCapella struct {
	Version string                          `json:"version"`
	Data    structs.ExecutionPayloadCapella `json:"data"`
}

ExecPayloadResponseCapella is the builder API /eth/v1/builder/blinded_blocks for Capella.

func (*ExecPayloadResponseCapella) ToProto

ToProto returns a ExecutionPayloadCapella Proto.

type ExecPayloadResponseDeneb

type ExecPayloadResponseDeneb struct {
	Version string                               `json:"version"`
	Data    *ExecutionPayloadDenebAndBlobsBundle `json:"data"`
}

ExecPayloadResponseDeneb the response to the build API /eth/v1/builder/blinded_blocks that includes the version, execution payload object , and blobs bundle object.

func (*ExecPayloadResponseDeneb) ToProto

ToProto returns ExecutionPayloadDeneb Proto and BlobsBundle Proto separately.

type ExecutionPayloadDenebAndBlobsBundle

type ExecutionPayloadDenebAndBlobsBundle struct {
	ExecutionPayload *structs.ExecutionPayloadDeneb `json:"execution_payload"`
	BlobsBundle      *BlobsBundle                   `json:"blobs_bundle"`
}

ExecutionPayloadDenebAndBlobsBundle the main field used in ExecPayloadResponseDeneb.

func (*ExecutionPayloadDenebAndBlobsBundle) BundleProto

func (*ExecutionPayloadDenebAndBlobsBundle) PayloadProto

type ExecutionPayloadResponse

type ExecutionPayloadResponse struct {
	Version string          `json:"version"`
	Data    json.RawMessage `json:"data"`
}

ExecutionPayloadResponse allows for unmarshaling just the Version field of the payload. This allows it to return different ExecutionPayload types based on the version field.

func (*ExecutionPayloadResponse) ParsePayload

func (r *ExecutionPayloadResponse) ParsePayload() (ParsedPayload, error)

type ParsedExecutionRequests

type ParsedExecutionRequests interface {
	ExecutionRequestsProto() (*v1.ExecutionRequests, error)
}

ParsedExecutionRequests can retrieve the underlying execution requests for the given execution payload response.

type ParsedPayload

type ParsedPayload interface {
	PayloadProto() (proto.Message, error)
}

ParsedPayload can retrieve the underlying protobuf message for the given execution payload response.

type ProposerSlashing

type ProposerSlashing struct {
	*eth.ProposerSlashing
}

ProposerSlashing is a field in BlindedBeaconBlockBodyCapella.

func (*ProposerSlashing) MarshalJSON

func (s *ProposerSlashing) MarshalJSON() ([]byte, error)

MarshalJSON returns a JSON byte array representation of ProposerSlashing.

type SignedBeaconBlockHeader

type SignedBeaconBlockHeader struct {
	*eth.SignedBeaconBlockHeader
}

SignedBeaconBlockHeader is a field of ProposerSlashing.

func (*SignedBeaconBlockHeader) MarshalJSON

func (h *SignedBeaconBlockHeader) MarshalJSON() ([]byte, error)

MarshalJSON returns a JSON byte array representation of SignedBeaconBlockHeader.

type SignedBid

type SignedBid interface {
	Message() (Bid, error)
	Signature() []byte
	Version() int
	IsNil() bool
}

SignedBid is an interface describing the method set of a signed builder bid.

func WrappedSignedBuilderBid

func WrappedSignedBuilderBid(p *ethpb.SignedBuilderBid) (SignedBid, error)

WrappedSignedBuilderBid is a constructor which wraps a protobuf signed bit into an interface.

func WrappedSignedBuilderBidCapella

func WrappedSignedBuilderBidCapella(p *ethpb.SignedBuilderBidCapella) (SignedBid, error)

WrappedSignedBuilderBidCapella is a constructor which wraps a protobuf signed bit into an interface.

func WrappedSignedBuilderBidDeneb

func WrappedSignedBuilderBidDeneb(p *ethpb.SignedBuilderBidDeneb) (SignedBid, error)

WrappedSignedBuilderBidDeneb is a constructor which wraps a protobuf signed bit into an interface.

func WrappedSignedBuilderBidElectra

func WrappedSignedBuilderBidElectra(p *ethpb.SignedBuilderBidElectra) (SignedBid, error)

WrappedSignedBuilderBidElectra is a constructor which wraps a protobuf signed bit into an interface.

type SignedBlindedBeaconBlockBellatrix

type SignedBlindedBeaconBlockBellatrix struct {
	*eth.SignedBlindedBeaconBlockBellatrix
}

SignedBlindedBeaconBlockBellatrix is the request object for builder API /eth/v1/builder/blinded_blocks.

type Uint256

type Uint256 struct {
	*big.Int
}

Uint256 a wrapper representation of big.Int

func (Uint256) MarshalJSON

func (s Uint256) MarshalJSON() ([]byte, error)

MarshalJSON returns a json byte representation of Uint256.

func (Uint256) MarshalText

func (s Uint256) MarshalText() ([]byte, error)

MarshalText returns a text byte representation of Uint256.

func (Uint256) SSZBytes

func (s Uint256) SSZBytes() []byte

SSZBytes creates an ssz-style (little-endian byte slice) representation of the Uint256.

func (*Uint256) UnmarshalJSON

func (s *Uint256) UnmarshalJSON(t []byte) error

UnmarshalJSON takes in a byte array and unmarshals the value in Uint256

func (*Uint256) UnmarshalText

func (s *Uint256) UnmarshalText(t []byte) error

UnmarshalText takes in a byte array and unmarshals the text in Uint256

type Uint64String

type Uint64String uint64

Uint64String is a custom type that allows marshalling from text to uint64 and vice versa.

func (Uint64String) MarshalText

func (s Uint64String) MarshalText() ([]byte, error)

MarshalText returns a byte representation of the text from Uint64String.

func (*Uint64String) UnmarshalText

func (s *Uint64String) UnmarshalText(t []byte) error

UnmarshalText takes a byte array and unmarshals the text in Uint64String.

type VersionResponse

type VersionResponse struct {
	Version string `json:"version"`
}

VersionResponse is a JSON representation of a field in the builder API header response.

type Withdrawal

type Withdrawal struct {
	Index          Uint256       `json:"index"`
	ValidatorIndex Uint256       `json:"validator_index"`
	Address        hexutil.Bytes `json:"address"`
	Amount         Uint256       `json:"amount"`
}

Withdrawal is a field of ExecutionPayloadCapella.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

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