builderapi

Documentation

Overview

Package builderapi hosts the Builder API HTTP server. It mounts two flow-specific dialect handlers onto one route table:

• pkg/builderapi/legacy — the pre-Gloas dialect (Electra/Fulu): registerValidators, getHeader, submitBlindedBlock
• pkg/builderapi/epbs — the post-Gloas dialect (Gloas/Heze+): getExecutionPayloadBid, submitBeaconBlock, submitBuilderPreferences

plus Buildoor-specific debug/tooling endpoints under /buildoor/v1/*.

Builder API follows https://github.com/ethereum/builder-specs

Index

• type EventBroadcaster
• type PayloadBySlotResponse
• type RequestStats
• type Server
  • func NewServer(cfg *config.BuilderAPIConfig, log *logrus.Logger, chainSvc chain.Service, ...) *Server
  • func (s *Server) GetBuilderPreferencesStore() *epbsapi.BuilderPreferencesStore
  • func (s *Server) GetRequestStats() RequestStats
  • func (s *Server) Handler() http.Handler
  • func (s *Server) IsEnabled() bool
  • func (s *Server) RegisterRoutes(router *mux.Router)
  • func (s *Server) SetBuilderIndex(index uint64)
  • func (s *Server) SetCLClient(c *beacon.Client)
  • func (s *Server) SetEnabled(enabled bool)
  • func (s *Server) SetEventBroadcaster(b EventBroadcaster)
  • func (s *Server) SetProposerPreferencesStore(store *memstore.Store[phase0.Slot, *gloasspec.SignedProposerPreferences])
  • func (s *Server) SetRevealService(rs *payload_bidder.RevealService)

Types

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)
	// Gloas (post-Gloas) builder API interactions.
	BroadcastBuilderAPIGetBidReceived(slot uint64, parentHash, pubkey string)
	BroadcastBuilderAPIGetBidDelivered(slot uint64, blockHash, blockValue string)
	BroadcastBuilderAPISubmitBlockReceived(slot uint64, blockHash string)
	BroadcastBuilderAPISubmitBlockDelivered(slot uint64, blockHash string)
}

EventBroadcaster provides methods for broadcasting Builder API events to the WebUI. It is the combined surface of both dialects' narrow broadcaster interfaces (which it satisfies structurally).

type PayloadBySlotResponse

type PayloadBySlotResponse struct {
	Slot            uint64          `json:"slot"`
	BlockHash       string          `json:"block_hash"`
	ParentBlockHash string          `json:"parent_block_hash"`
	ParentBlockRoot string          `json:"parent_block_root"`
	Payload         json.RawMessage `json:"payload"`
	BlobsBundle     json.RawMessage `json:"blobs_bundle,omitempty"`
	BlockValue      string          `json:"block_value"` // wei as string
	FeeRecipient    string          `json:"fee_recipient"`
	GasLimit        uint64          `json:"gas_limit"`
	Timestamp       uint64          `json:"timestamp"`
	ReadyAt         time.Time       `json:"ready_at"`
}

PayloadBySlotResponse is the JSON response for GET /buildoor/v1/payloads/{slot}.

type RequestStats

type RequestStats struct {
	HeadersRequested uint64
	BlocksPublished  uint64
	ValidatorCount   int
}

RequestStats holds counters for Builder API requests, aggregated across both dialect handlers.

type Server

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

Server hosts the Builder API dialect handlers and the Buildoor debug API. It owns the route table, enable-state fan-out, and request-stat aggregation; all endpoint logic lives in the dialects. Won-block tracking is NOT done here — the shared payload_bidder.InclusionTracker is the single owner of won-block records, recording actual inclusion.

func NewServer

func NewServer(cfg *config.BuilderAPIConfig, log *logrus.Logger, chainSvc chain.Service,
	payloadCache *payload_builder.PayloadCache, blsSigner *signer.BLSSigner,
	validatorStore *memstore.Store[phase0.BLSPubKey, *apiv1.SignedValidatorRegistration]) *Server

NewServer creates a new server and constructs both dialect handlers. payloadCache may be nil; endpoints needing it degrade gracefully. blsSigner may be nil; if set, getHeader signs builder bids. validatorStore is optional (an in-memory store is created when nil); when provided it is the shared instance also read by the legacy registration settings resolver.

func (*Server) GetBuilderPreferencesStore

func (s *Server) GetBuilderPreferencesStore() *epbsapi.BuilderPreferencesStore

GetBuilderPreferencesStore returns the store of latest per-validator builder preferences submitted via the submitBuilderPreferences API.

func (*Server) GetRequestStats

func (s *Server) GetRequestStats() RequestStats

GetRequestStats returns the current request counters aggregated across both dialect handlers.

func (*Server) Handler

func (s *Server) Handler() http.Handler

Handler returns an HTTP handler with routes registered; used in tests.

func (*Server) IsEnabled

func (s *Server) IsEnabled() bool

IsEnabled returns whether the Builder API server is enabled.

func (*Server) RegisterRoutes

func (s *Server) RegisterRoutes(router *mux.Router)

RegisterRoutes registers Builder API and Buildoor API routes onto the given router, delegating the spec endpoints to the dialect handlers.

func (*Server) SetBuilderIndex

func (s *Server) SetBuilderIndex(index uint64)

SetBuilderIndex sets the on-chain builder index inserted into Gloas bids. Called from the lifecycle manager once registration is observed.

func (*Server) SetCLClient

func (s *Server) SetCLClient(c *beacon.Client)

SetCLClient wires the beacon client into both dialects: the legacy dialect publishes unblinded block contents through it and the post-Gloas dialect broadcasts the proposer's signed beacon block. Envelope publishing is owned by the shared payload_bidder.RevealService, not this package.

func (*Server) SetEnabled

func (s *Server) SetEnabled(enabled bool)

SetEnabled sets the enabled state of the Builder API server and both dialect handlers.

func (*Server) SetEventBroadcaster

func (s *Server) SetEventBroadcaster(b EventBroadcaster)

SetEventBroadcaster sets the optional event broadcaster for WebUI events on both dialect handlers.

func (*Server) SetProposerPreferencesStore

func (s *Server) SetProposerPreferencesStore(
	store *memstore.Store[phase0.Slot, *gloasspec.SignedProposerPreferences])

SetProposerPreferencesStore wires the per-slot proposer preferences store used by the post-Gloas dialect to resolve fee recipients when building bids.

func (*Server) SetRevealService

func (s *Server) SetRevealService(rs *payload_bidder.RevealService)

SetRevealService wires the shared reveal service used by the post-Gloas dialect to schedule execution payload envelope reveals.