Documentation
¶
Overview ¶
Package epbs implements the post-Gloas (Gloas/Heze+) Builder API dialect: execution payload bid delivery, signed beacon block acceptance (with the payload reveal delegated to the shared RevealService), and builder preferences, on top of the shared payload cache. See https://github.com/ethereum/builder-specs/blob/epbs-spec-updates/specs/gloas/builder.md
Index ¶
- Constants
- Variables
- func VerifyRequestAuth(signed *epbstypes.SignedRequestAuthV1, validatorPubkey phase0.BLSPubKey, ...) error
- type BlockBroadcaster
- type BuilderPreferencesStore
- func (s *BuilderPreferencesStore) Get(pubkey phase0.BLSPubKey) (phase0.Gwei, bool)
- func (s *BuilderPreferencesStore) GetAll() map[phase0.BLSPubKey]phase0.Gwei
- func (s *BuilderPreferencesStore) GetOrDefault(pubkey phase0.BLSPubKey) phase0.Gwei
- func (s *BuilderPreferencesStore) Set(pubkey phase0.BLSPubKey, maxExecutionPayment phase0.Gwei)
- func (s *BuilderPreferencesStore) SetPersistence(ctx context.Context, stateDB *db.Database, log logrus.FieldLogger)
- func (s *BuilderPreferencesStore) Stop()
- type EventBroadcaster
- type GetExecutionPayloadBidResponse
- type Handler
- func (h *Handler) BidsRequested() uint64
- func (h *Handler) BlocksAccepted() uint64
- func (h *Handler) GetBuilderPreferencesStore() *BuilderPreferencesStore
- func (h *Handler) HandleGetExecutionPayloadBid(w http.ResponseWriter, r *http.Request)
- func (h *Handler) HandleSubmitBeaconBlock(w http.ResponseWriter, r *http.Request)
- func (h *Handler) HandleSubmitBuilderPreferences(w http.ResponseWriter, r *http.Request)
- func (h *Handler) SetBlockBroadcaster(b BlockBroadcaster)
- func (h *Handler) SetBuilderIndex(index uint64)
- func (h *Handler) SetEnabled(enabled bool)
- func (h *Handler) SetEventBroadcaster(b EventBroadcaster)
- func (h *Handler) SetProposerPreferencesStore(store *memstore.Store[phase0.Slot, *gloasspec.SignedProposerPreferences])
- func (h *Handler) SetRevealService(rs *payload_bidder.RevealService)
- type PreferencesCodec
Constants ¶
const PreferencesNamespace = "builder_preferences"
PreferencesNamespace is the kv_store namespace holding the per-validator builder preferences (max_execution_payment).
Variables ¶
var ( // ErrNilSignedRequestAuth is returned when the SignedRequestAuth wrapper is nil. ErrNilSignedRequestAuth = errors.New("signed request auth is nil") // ErrNilRequestAuthMessage is returned when the inner RequestAuth message is nil. ErrNilRequestAuthMessage = errors.New("request auth message is nil") // ErrInvalidRequestAuthSignature is returned when BLS verification fails. ErrInvalidRequestAuthSignature = errors.New("invalid request auth signature") )
var DomainRequestAuth = phase0.DomainType{0x0B, 0x00, 0x00, 0x01}
DomainRequestAuth is the DomainType used to sign SignedRequestAuth messages. Defined in builder-specs as DOMAIN_REQUEST_AUTH = DomainType('0x0B000001').
Functions ¶
func VerifyRequestAuth ¶
func VerifyRequestAuth( signed *epbstypes.SignedRequestAuthV1, validatorPubkey phase0.BLSPubKey, genesisForkVersion phase0.Version, ) error
VerifyRequestAuth verifies the BLS signature on a SignedRequestAuth against the supplied validator public key.
Per the Gloas builder-specs validator.md, the signing domain is compute_domain(DOMAIN_REQUEST_AUTH), which defaults to (GENESIS_FORK_VERSION, zero genesis_validators_root). Callers pass the chain's genesis fork version; the genesis_validators_root is always zero per spec.
Returns nil on success, or one of the package's sentinel errors on failure.
Types ¶
type BlockBroadcaster ¶
type BlockBroadcaster interface {
SubmitProposal(ctx context.Context, opts *api.SubmitProposalOpts) error
}
BlockBroadcaster publishes the proposer's signed beacon block (implemented by *beacon.Client.SubmitProposal).
type BuilderPreferencesStore ¶
type BuilderPreferencesStore struct {
// contains filtered or unexported fields
}
BuilderPreferencesStore holds the latest per-validator builder preferences submitted via the submitBuilderPreferences API. It keeps only the most recent max_execution_payment for each validator pubkey (a later submission overwrites an earlier one) and optionally persists them to the state-db so they survive restarts.
Per the Gloas builder-specs, if no preferences have been submitted for a validator, the builder MUST treat its max_execution_payment as 0; GetOrDefault encodes that rule.
func NewBuilderPreferencesStore ¶
func NewBuilderPreferencesStore() *BuilderPreferencesStore
NewBuilderPreferencesStore creates an empty BuilderPreferencesStore.
func (*BuilderPreferencesStore) Get ¶
Get returns the stored max_execution_payment for a validator and whether a preference was found.
func (*BuilderPreferencesStore) GetAll ¶
func (s *BuilderPreferencesStore) GetAll() map[phase0.BLSPubKey]phase0.Gwei
GetAll returns a snapshot copy of all stored builder preferences, keyed by validator pubkey.
func (*BuilderPreferencesStore) GetOrDefault ¶
func (s *BuilderPreferencesStore) GetOrDefault(pubkey phase0.BLSPubKey) phase0.Gwei
GetOrDefault returns the stored max_execution_payment for a validator, or 0 if none has been submitted — the spec-mandated default that disallows execution layer payments.
func (*BuilderPreferencesStore) Set ¶
func (s *BuilderPreferencesStore) Set(pubkey phase0.BLSPubKey, maxExecutionPayment phase0.Gwei)
Set records the latest max_execution_payment for a validator, overwriting any previously stored value.
func (*BuilderPreferencesStore) SetPersistence ¶
func (s *BuilderPreferencesStore) SetPersistence(ctx context.Context, stateDB *db.Database, log logrus.FieldLogger)
SetPersistence attaches the optional state-db so preferences survive restarts: previously persisted entries are loaded and future changes are flushed (buffered) into the store's kv_store namespace. Call Stop before the state-db closes.
func (*BuilderPreferencesStore) Stop ¶
func (s *BuilderPreferencesStore) Stop()
Stop flushes pending changes and stops the persistence flush loop. No-op when no persistence is attached.
type EventBroadcaster ¶
type EventBroadcaster interface {
BroadcastBuilderAPIGetBidReceived(slot uint64, parentHash, pubkey string)
BroadcastBuilderAPIGetBidDelivered(slot uint64, blockHash, blockValue string)
BroadcastBuilderAPISubmitBlockReceived(slot uint64, blockHash string)
BroadcastBuilderAPISubmitBlockDelivered(slot uint64, blockHash string)
}
EventBroadcaster is the narrow WebUI event surface the post-Gloas dialect needs (satisfied structurally by the webui EventStreamManager).
type GetExecutionPayloadBidResponse ¶
type GetExecutionPayloadBidResponse struct {
Version string `json:"version"`
Data *eth2all.SignedExecutionPayloadBid `json:"data"`
}
GetExecutionPayloadBidResponse is the JSON envelope returned by POST /eth/v1/builder/execution_payload_bid/{slot}/{parent_hash}/{parent_root}/{proposer_pubkey}.
type Handler ¶
type Handler struct {
// contains filtered or unexported fields
}
Handler serves the post-Gloas Builder API dialect endpoints (getExecutionPayloadBid, submitBeaconBlock, submitBuilderPreferences). It is constructed and mounted by the parent builderapi.Server. Payload reveals are never published from the HTTP handlers: accepted beacon blocks hand the reveal to the shared payload_bidder.RevealService, which publishes the envelope at the configured reveal time.
func NewHandler ¶
func NewHandler(cfg *config.BuilderAPIConfig, log logrus.FieldLogger, chainSvc chain.Service, payloadCache *payload_builder.PayloadCache, blsSigner *signer.BLSSigner) *Handler
NewHandler creates a new post-Gloas Builder API dialect handler. cfg is the shared mutable config pointer; values are read live, never copied out.
func (*Handler) BidsRequested ¶
BidsRequested returns the count of getExecutionPayloadBid requests received.
func (*Handler) BlocksAccepted ¶
BlocksAccepted returns the count of accepted signed beacon blocks.
func (*Handler) GetBuilderPreferencesStore ¶
func (h *Handler) GetBuilderPreferencesStore() *BuilderPreferencesStore
GetBuilderPreferencesStore returns the store of latest per-validator builder preferences submitted via the submitBuilderPreferences API.
func (*Handler) HandleGetExecutionPayloadBid ¶
func (h *Handler) HandleGetExecutionPayloadBid(w http.ResponseWriter, r *http.Request)
HandleGetExecutionPayloadBid handles POST /eth/v1/builder/execution_payload_bid/{slot}/{parent_hash}/{parent_root}/{proposer_pubkey}.
Looks up the cached payload for the requested slot, validates the supplied parent_hash and parent_root against it, then constructs and signs a SignedExecutionPayloadBid using the proposer's fee recipient from the ProposerPreferences cache. The fork version — for the bid signing domain, the response envelope, and the Eth-Consensus-Version header — is the fork active at the requested slot's epoch. Returns 204 if no payload is cached, 400 if the inputs do not match the cached payload or proposer preferences are missing, and 503 while the requested slot is pre-Gloas.
If the request body contains a SignedRequestAuthV1, it is validated:
- auth.message.slot must match the requested slot
- auth.message.builder_url must match cfg.BuilderURL (if configured)
- BLS signature must verify against the proposer_pubkey path parameter
func (*Handler) HandleSubmitBeaconBlock ¶
func (h *Handler) HandleSubmitBeaconBlock(w http.ResponseWriter, r *http.Request)
HandleSubmitBeaconBlock handles POST /eth/v1/builder/beacon_block.
The proposer submits a full post-Gloas SignedBeaconBlock that binds them to the builder's bid. The block is decoded fork-agnostically from either JSON or SSZ (application/octet-stream); the wire version is taken from the Eth-Consensus-Version request header, falling back to the chain's current fork when the header is absent. If the builder still holds the payload referenced by the bid's block_hash, it broadcasts the beacon block immediately (block publication is time-critical) and schedules the execution payload envelope reveal with the shared RevealService, which publishes it at the configured reveal time (deduped per slot with the p2p flow).
Returns 202 on success, 400 on a malformed block or missing payload, 415 on wrong Content-Type, 500 on broadcast/internal errors, and 503 if the dialect is disabled, not fully configured, or the chain has not activated Gloas yet.
func (*Handler) HandleSubmitBuilderPreferences ¶
func (h *Handler) HandleSubmitBuilderPreferences(w http.ResponseWriter, r *http.Request)
HandleSubmitBuilderPreferences handles POST /eth/v1/builder/builder_preferences/{validator_pubkey}.
It records the validator's latest max_execution_payment after authenticating the request via the embedded SignedRequestAuthV1. Per the Gloas builder-specs, the builder MUST verify the auth signature against the validator_pubkey path param (401 on failure) and MUST check that auth.message.builder_url matches its own URL (400 on failure). The preference is stored only after both checks pass. On success it returns 202.
func (*Handler) SetBlockBroadcaster ¶
func (h *Handler) SetBlockBroadcaster(b BlockBroadcaster)
SetBlockBroadcaster wires the broadcaster used to publish the proposer's signed beacon block (e.g. the beacon node client).
func (*Handler) SetBuilderIndex ¶
SetBuilderIndex sets the on-chain builder index inserted into Gloas bids. Called from the lifecycle manager once registration is observed.
func (*Handler) SetEnabled ¶
SetEnabled sets the enabled state of the post-Gloas Builder API dialect.
func (*Handler) SetEventBroadcaster ¶
func (h *Handler) SetEventBroadcaster(b EventBroadcaster)
SetEventBroadcaster sets the optional event broadcaster for WebUI events.
func (*Handler) SetProposerPreferencesStore ¶
func (h *Handler) SetProposerPreferencesStore( store *memstore.Store[phase0.Slot, *gloasspec.SignedProposerPreferences])
SetProposerPreferencesStore wires the per-slot proposer preferences store (owned by payload_bidder.ProposerPreferencesService) used to resolve the fee recipient when building Gloas execution payload bids.
func (*Handler) SetRevealService ¶
func (h *Handler) SetRevealService(rs *payload_bidder.RevealService)
SetRevealService wires the shared reveal service that publishes execution payload envelopes at the configured reveal time.
type PreferencesCodec ¶
type PreferencesCodec struct{}
PreferencesCodec translates the builder preference store's entries to their persisted form: 0x-hex pubkey keys, 8-byte little-endian uint64 values.
func (PreferencesCodec) DecodeKey ¶
func (PreferencesCodec) DecodeKey(key string) (phase0.BLSPubKey, error)
DecodeKey parses a 0x-prefixed hex pubkey string.
func (PreferencesCodec) DecodeValue ¶
func (PreferencesCodec) DecodeValue(value []byte) (phase0.Gwei, error)
DecodeValue decodes an 8-byte little-endian max_execution_payment.
func (PreferencesCodec) EncodeKey ¶
func (PreferencesCodec) EncodeKey(pubkey phase0.BLSPubKey) string
EncodeKey encodes a validator pubkey as its 0x-prefixed hex string form.
func (PreferencesCodec) EncodeValue ¶
func (PreferencesCodec) EncodeValue(maxExecutionPayment phase0.Gwei) ([]byte, error)
EncodeValue encodes a max_execution_payment as 8 little-endian bytes.
Source Files
Directories