Documentation
¶
Overview ¶
Package legacy implements the pre-Gloas Builder API dialect (Electra/Fulu): validator registration, getHeader bid delivery, and blinded block submission on top of the shared payload cache.
Index ¶
- Constants
- func BuildSignedBuilderBid(event *payload_builder.Payload, fork version.DataVersion, ...) (*legacytypes.SignedBuilderBid, error)
- func ExecutionPayloadHeaderFromBeacon(p *eth2all.ExecutionPayload, fork version.DataVersion, ...) (*eth2all.ExecutionPayloadHeader, error)
- func UnblindSignedBlindedBeaconBlock(blinded *apiv1all.SignedBlindedBeaconBlock, event *payload_builder.Payload) (*apiv1all.SignedBlockContents, error)
- func VerifyRegistration(reg *apiv1.SignedValidatorRegistration) bool
- func VerifyRegistrationWithDomain(reg *apiv1.SignedValidatorRegistration, ...) bool
- type BidSigner
- type EventBroadcaster
- type GetHeaderResponse
- type Handler
- func (h *Handler) BlocksPublished() uint64
- func (h *Handler) HandleGetHeader(w http.ResponseWriter, r *http.Request)
- func (h *Handler) HandleRegisterValidators(w http.ResponseWriter, r *http.Request)
- func (h *Handler) HandleSubmitBlindedBlock(w http.ResponseWriter, r *http.Request)
- func (h *Handler) HandleSubmitBlindedBlockV1(w http.ResponseWriter, r *http.Request)
- func (h *Handler) HeadersRequested() uint64
- func (h *Handler) SetCLClient(c ProposalSubmitter)
- func (h *Handler) SetEnabled(enabled bool)
- func (h *Handler) SetEventBroadcaster(b EventBroadcaster)
- type ProposalSubmitter
- type RegistrationCodec
- func (RegistrationCodec) DecodeKey(key string) (phase0.BLSPubKey, error)
- func (RegistrationCodec) DecodeValue(value []byte) (*apiv1.SignedValidatorRegistration, error)
- func (RegistrationCodec) EncodeKey(pubkey phase0.BLSPubKey) string
- func (RegistrationCodec) EncodeValue(reg *apiv1.SignedValidatorRegistration) ([]byte, error)
- type RegistrationSettingsResolver
- type SubmitBlindedBlockV1Response
Constants ¶
const RegistrationsNamespace = "validator_registrations"
RegistrationsNamespace is the kv_store namespace holding the Builder API validator registrations.
Variables ¶
This section is empty.
Functions ¶
func BuildSignedBuilderBid ¶
func BuildSignedBuilderBid( event *payload_builder.Payload, fork version.DataVersion, proposerPubkey phase0.BLSPubKey, blsSigner BidSigner, subsidyGwei uint64, genesisForkVersion phase0.Version, maxWithdrawalsPerPayload uint64, ) (*legacytypes.SignedBuilderBid, error)
BuildSignedBuilderBid builds a SignedBuilderBid for the given fork from a Payload and the proposer's pubkey, and signs it with the builder's BLS key using DOMAIN_APPLICATION_BUILDER with the provided genesis fork version and a zero genesis validators root (matches mev-boost-relay behavior). The bid carries the fork's field set (blob KZG commitments from Deneb, execution requests from Electra). subsidyGwei is added to the bid value so the proposer sees a higher bid (e.g. for testing).
func ExecutionPayloadHeaderFromBeacon ¶
func ExecutionPayloadHeaderFromBeacon( p *eth2all.ExecutionPayload, fork version.DataVersion, maxWithdrawalsPerPayload uint64, ) (*eth2all.ExecutionPayloadHeader, error)
ExecutionPayloadHeaderFromBeacon builds a fork-agnostic execution payload header, pinned to the given fork, from the fork-agnostic beacon execution payload. Used to construct BuilderBids for getHeader responses (Bellatrix onwards).
func UnblindSignedBlindedBeaconBlock ¶
func UnblindSignedBlindedBeaconBlock( blinded *apiv1all.SignedBlindedBeaconBlock, event *payload_builder.Payload, ) (*apiv1all.SignedBlockContents, error)
UnblindSignedBlindedBeaconBlock builds full SignedBlockContents from a fork-agnostic blinded block and the matching Payload (full payload + blobs). The proposer signature is preserved and the returned contents carry the blinded block's fork version.
func VerifyRegistration ¶
func VerifyRegistration(reg *apiv1.SignedValidatorRegistration) bool
VerifyRegistration verifies the BLS signature of a validator registration using DOMAIN_APPLICATION_BUILDER with zero parameters (for tests). For chain-specific verification (e.g. mev-boost registrations), use VerifyRegistrationWithDomain.
func VerifyRegistrationWithDomain ¶
func VerifyRegistrationWithDomain(reg *apiv1.SignedValidatorRegistration, genesisForkVersion, forkVersion phase0.Version, genesisValidatorsRoot phase0.Root) bool
VerifyRegistrationWithDomain verifies the BLS signature of a validator registration using DOMAIN_APPLICATION_BUILDER. Tries (0,0), (genesisForkVersion, 0) from the beacon (mev-boost-relay style), then (forkVersion, genesisValidatorsRoot). Genesis fork version is taken from the beacon so local devnets with their own fork versions work.
Types ¶
type BidSigner ¶
type BidSigner interface {
SignWithDomain(root phase0.Root, domain phase0.Domain) (phase0.BLSSignature, error)
}
BidSigner signs a BuilderBid and returns the signature.
type EventBroadcaster ¶
type EventBroadcaster interface {
BroadcastBuilderAPIGetHeaderReceived(slot uint64, parentHash, pubkey string)
BroadcastBuilderAPIGetHeaderDelivered(slot uint64, blockHash, blockValue string)
BroadcastBuilderAPISubmitBlindedReceived(slot uint64, blockHash string)
BroadcastBuilderAPISubmitBlindedDelivered(slot uint64, blockHash string)
}
EventBroadcaster is the narrow WebUI event surface the legacy dialect needs (satisfied structurally by the webui EventStreamManager).
type GetHeaderResponse ¶
type GetHeaderResponse struct {
Version string `json:"version"`
Data *legacytypes.SignedBuilderBid `json:"data"`
}
GetHeaderResponse is the JSON response for getHeader: { "version": "<fork>", "data": SignedBuilderBid }.
type Handler ¶
type Handler struct {
// contains filtered or unexported fields
}
Handler serves the pre-Gloas Builder API dialect endpoints (registerValidators, getHeader, submitBlindedBlock). It is constructed and mounted by the parent builderapi.Server.
func NewHandler ¶
func NewHandler(cfg *config.BuilderAPIConfig, log logrus.FieldLogger, chainSvc chain.Service, payloadCache *payload_builder.PayloadCache, validatorsStore *memstore.Store[phase0.BLSPubKey, *apiv1.SignedValidatorRegistration], blsSigner *signer.BLSSigner) *Handler
NewHandler creates a new pre-Gloas Builder API dialect handler. cfg is the shared mutable config pointer; values are read live, never copied out.
func (*Handler) BlocksPublished ¶
BlocksPublished returns the count of successfully published blocks.
func (*Handler) HandleGetHeader ¶
func (h *Handler) HandleGetHeader(w http.ResponseWriter, r *http.Request)
HandleGetHeader handles GET /eth/v1/builder/header/{slot}/{parent_hash}/{pubkey}. Returns 200 with the active fork's SignedBuilderBid, or 204 if no bid, or 400 on invalid params / unregistered proposer.
func (*Handler) HandleRegisterValidators ¶
func (h *Handler) HandleRegisterValidators(w http.ResponseWriter, r *http.Request)
HandleRegisterValidators handles POST /eth/v1/builder/validators. Accepts a list of SignedValidatorRegistration as JSON or SSZ (application/octet-stream), verifies each signature, and stores valid registrations. Returns 200 on success, 400 on validation failure, and 415 on an unsupported Content-Type.
func (*Handler) HandleSubmitBlindedBlock ¶
func (h *Handler) HandleSubmitBlindedBlock(w http.ResponseWriter, r *http.Request)
HandleSubmitBlindedBlock handles POST /eth/v2/builder/blinded_blocks. The v2 flow publishes the unblinded block and returns 202 Accepted with no body (the payload and blobs reach the network via the builder's publish).
func (*Handler) HandleSubmitBlindedBlockV1 ¶
func (h *Handler) HandleSubmitBlindedBlockV1(w http.ResponseWriter, r *http.Request)
HandleSubmitBlindedBlockV1 handles POST /eth/v1/builder/blinded_blocks (Bellatrix onwards). Unlike v2, the v1 flow returns the unblinded execution payload (plus blobs bundle from Deneb) in the response body so the proposer can publish the block itself; the block is additionally published by the builder, mirroring mev-boost-relay behavior.
func (*Handler) HeadersRequested ¶
HeadersRequested returns the count of getHeader requests received.
func (*Handler) SetCLClient ¶
func (h *Handler) SetCLClient(c ProposalSubmitter)
SetCLClient sets the beacon node client used to publish unblinded blocks.
func (*Handler) SetEnabled ¶
SetEnabled sets the enabled state of the legacy Builder API dialect.
func (*Handler) SetEventBroadcaster ¶
func (h *Handler) SetEventBroadcaster(b EventBroadcaster)
SetEventBroadcaster sets the optional event broadcaster for WebUI events.
type ProposalSubmitter ¶
type ProposalSubmitter interface {
SubmitProposal(ctx context.Context, opts *api.SubmitProposalOpts) error
}
ProposalSubmitter submits a full signed proposal to the beacon node (implemented by *beacon.Client).
type RegistrationCodec ¶
type RegistrationCodec struct{}
RegistrationCodec translates the validator registration store's entries to their persisted form: 0x-hex pubkey keys, SSZ-encoded values.
func (RegistrationCodec) DecodeKey ¶
func (RegistrationCodec) DecodeKey(key string) (phase0.BLSPubKey, error)
DecodeKey parses a 0x-prefixed hex pubkey string.
func (RegistrationCodec) DecodeValue ¶
func (RegistrationCodec) DecodeValue(value []byte) (*apiv1.SignedValidatorRegistration, error)
DecodeValue SSZ-decodes a signed validator registration.
func (RegistrationCodec) EncodeKey ¶
func (RegistrationCodec) EncodeKey(pubkey phase0.BLSPubKey) string
EncodeKey encodes a validator pubkey as its 0x-prefixed hex string form.
func (RegistrationCodec) EncodeValue ¶
func (RegistrationCodec) EncodeValue(reg *apiv1.SignedValidatorRegistration) ([]byte, error)
EncodeValue SSZ-encodes a signed validator registration.
type RegistrationSettingsResolver ¶
type RegistrationSettingsResolver struct {
// contains filtered or unexported fields
}
RegistrationSettingsResolver resolves pre-Gloas proposer settings from the validator registration store. It implements payload_builder.ProposerSettingsResolver and self-scopes: post-Gloas the gossip proposer-preferences resolver applies instead, so it returns false.
func NewRegistrationSettingsResolver ¶
func NewRegistrationSettingsResolver( store *memstore.Store[phase0.BLSPubKey, *apiv1.SignedValidatorRegistration], chainSvc chain.Service, ) *RegistrationSettingsResolver
NewRegistrationSettingsResolver creates a resolver over the shared validator registration store.
func (*RegistrationSettingsResolver) ResolveProposerSettings ¶
func (r *RegistrationSettingsResolver) ResolveProposerSettings(_ phase0.Slot, proposerIndex phase0.ValidatorIndex) (payload_builder.ProposerSettings, bool)
ResolveProposerSettings looks up the proposer's validator registration and returns its fee recipient. TargetGasLimit is deliberately left 0 (not announced): the registration gas limit was never used for pre-Gloas builds and this preserves that behavior.
type SubmitBlindedBlockV1Response ¶
SubmitBlindedBlockV1Response is the JSON envelope returned by POST /eth/v1/builder/blinded_blocks: { "version": "<fork>", "data": ... } where data is the bare ExecutionPayload pre-Deneb and an ExecutionPayloadAndBlobsBundle from Deneb onwards.
Source Files
Directories