builderapi

package
v0.0.3 Latest Latest
Warning

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

 Go to latest Published: Aug 12, 2026 License: GPL-3.0 Imports: 21 Imported by: 0

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

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

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,
	planSvc *action_plan.PlanService, payloadCache *payload_builder.PayloadCache,
	registry *builder_keys.Registry,
	validatorStore *memstore.Store[phase0.BLSPubKey, *apiv1.SignedValidatorRegistration]) *Server

NewServer creates a new server and constructs both dialect handlers. planSvc is the mandatory per-slot scheduling/settings authority: the bid handlers freeze the slot's plan at request time and serve per the frozen effective settings. payloadCache may be nil; endpoints needing it degrade gracefully. registry is the managed builder key set; getHeader signs pre-Gloas builder bids with its primary key. 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) 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) SetOnDemandBuilder added in v0.0.3 

func (s *Server) SetOnDemandBuilder(builder epbsapi.OnDemandPayloadBuilder)

SetOnDemandBuilder wires the on-demand payload builder used by the post-Gloas dialect to serve bid requests for unbuilt (but legal) parents.

func (*Server) SetProposerPreferencesStore added in v0.0.2 

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) SetResultRecorder added in v0.0.3 

func (s *Server) SetResultRecorder(rec SlotResultRecorder)

SetResultRecorder wires the optional per-slot result recorder into both dialect handlers. All uses are nil-guarded.

func (*Server) SetRevealService added in v0.0.2 

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.

type SlotResultRecorder added in v0.0.3 

type SlotResultRecorder interface {
	RecordBuilderAPIBid(slot phase0.Slot, forkName string, signedBid any,
		totalValueGwei, executionPaymentGwei uint64, status string, errMsg string)
	RecordBlockSubmission(slot phase0.Slot, dialect string, status string, errMsg string)
}

SlotResultRecorder records builder-api activity into the per-slot result history. It is the combined surface of both dialects' narrow recorder interfaces (which it satisfies structurally); builderapi never imports the implementing package.

Bid statuses: "served" (response write succeeded; signedBid is the exact signed object served), "suppressed" (the slot plan or global enable flag suppressed serving; signedBid nil, values 0), "failed" (a gate, bid construction, or the response encode/write failed; errMsg set), and "cancelled" (the request context ended during a planned response delay). Submission statuses: "received" (block decoded), "accepted" (published / broadcast + reveal handoff done), "failed" (errMsg set). Dialect is "legacy" or "epbs".

Source Files

View all Source files

Directories

Path Synopsis
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.
 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.
types
Code generated by dynamic-ssz.
 Code generated by dynamic-ssz.
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.
 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.
types
Package types contains the fork-agnostic builder-spec wire containers of the legacy (pre-Gloas) Builder API dialect.
 Package types contains the fork-agnostic builder-spec wire containers of the legacy (pre-Gloas) Builder API dialect.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.