builderapi

package
v0.0.1 Latest Latest
Warning

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

 Go to latest Published: Jun 24, 2026 License: GPL-3.0 Imports: 39 Imported by: 0

Documentation

Overview

Package builderapi implements the HTTP server that serves both: - The traditional Builder API (pre-ePBS) for proposers: /eth/v1/builder/* - Buildoor-specific APIs for debugging and tooling: /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 BidWonEntry 

type BidWonEntry struct {
	Slot            uint64 `json:"slot"`
	BlockHash       string `json:"block_hash"`
	NumTransactions int    `json:"num_transactions"`
	NumBlobs        int    `json:"num_blobs"`
	ValueETH        string `json:"value_eth"` // Formatted as ETH string for precision
	ValueWei        string `json:"value_wei"` // Stored as decimal wei string
	Timestamp       int64  `json:"timestamp"` // Unix timestamp in milliseconds
}

BidWonEntry represents a single successfully delivered block via Builder API.

type BidsWonStore 

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

BidsWonStore manages an in-memory circular buffer of bid wins. Thread-safe for concurrent access.

func NewBidsWonStore 

func NewBidsWonStore(maxSize int) *BidsWonStore

NewBidsWonStore creates a new BidsWonStore with the specified maximum size. When the store reaches capacity, oldest entries are evicted (FIFO).

func (*BidsWonStore) Add 

func (s *BidsWonStore) Add(entry BidWonEntry)

Add adds a new bid won entry to the store. Entries are stored in reverse chronological order (newest first). If at capacity, the oldest entry is evicted.

func (*BidsWonStore) Count 

func (s *BidsWonStore) Count() int

Count returns the total number of entries in the store.

func (*BidsWonStore) GetPage 

func (s *BidsWonStore) GetPage(offset, limit int) ([]BidWonEntry, int)

GetPage returns a page of entries with pagination support. Returns (entries, totalCount) where entries is the requested page and totalCount is the total number of entries in the store.

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).

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 

func (s *BuilderPreferencesStore) Get(pubkey phase0.BLSPubKey) (phase0.Gwei, bool)

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.

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)
	BroadcastBidWon(slot uint64, blockHash string, numTxs, numBlobs int, valueETH string, valueWei string)
}

EventBroadcaster provides methods for broadcasting Builder API events to the WebUI.

type FuluBlockPublisher 

type FuluBlockPublisher interface {
	SubmitFuluBlock(ctx context.Context, contents *apiv1fulu.SignedBlockContents) error
}

FuluBlockPublisher submits unblinded Fulu block contents to the beacon node. Implemented by *beacon.Client in production.

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 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 PayloadCacheProvider 

type PayloadCacheProvider interface {
	GetPayloadCache() *payload_builder.PayloadCache
}

PayloadCacheProvider provides access to the payload cache (e.g. *payload_builder.Service). Used so tests can inject a mock without full builder deps.

type RequestStats 

type RequestStats struct {
	HeadersRequested uint64
	BlocksPublished  uint64
	ValidatorCount   int
}

RequestStats holds counters for Builder API requests.

type Server 

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

Server implements the combined Builder API + Buildoor API HTTP server.

func NewServer 

func NewServer(cfg *config.BuilderAPIConfig, log *logrus.Logger, chainSvc chain.Service, builderSvc PayloadCacheProvider, blsSigner *signer.BLSSigner, validatorStore *validators.Store) *Server

NewServer creates a new server. builderSvc may be nil; if set, buildoor-specific endpoints and Fulu getHeader/submitBlindedBlockV2 will be enabled. blsSigner may be nil; if set, getHeader will sign builder bids. fuluPublisher may be set later via SetFuluPublisher. validatorStore is optional; when provided it is shared with the builder service for fee recipient lookup. genesisForkVersion is used for DomainBuilder (genesis fork + zero root) like mev-boost-relay; forkVersion and genesisValidatorsRoot are used for chain-specific verification. Pass chain values from the beacon node.

func (*Server) GetBidsWonStore 

func (s *Server) GetBidsWonStore() *BidsWonStore

GetBidsWonStore returns the bids won store.

func (*Server) GetBuilderPreferencesStore 

func (s *Server) GetBuilderPreferencesStore() *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.

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.

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 used to publish Gloas execution payload envelopes after a SignedBeaconBlock is submitted via the Builder API.

func (*Server) SetChainService 

func (s *Server) SetChainService(c chain.Service)

SetChainService wires the chain service used to verify the builder is active (deposit finalized, not exited) before serving Gloas execution payload bids.

func (*Server) SetEnabled 

func (s *Server) SetEnabled(enabled bool)

SetEnabled sets the enabled state of the Builder API server.

func (*Server) SetEventBroadcaster 

func (s *Server) SetEventBroadcaster(b EventBroadcaster)

SetEventBroadcaster sets the optional event broadcaster for WebUI events.

func (*Server) SetFuluPublisher 

func (s *Server) SetFuluPublisher(p FuluBlockPublisher)

SetFuluPublisher sets the optional publisher for unblinded Fulu blocks (e.g. beacon node client).

func (*Server) SetProposerPreferencesCache 

func (s *Server) SetProposerPreferencesCache(cache *proposerpreferences.Cache)

SetProposerPreferencesCache wires the proposer preferences cache used to resolve fee recipient and gas limit when building Gloas execution payload bids.

func (*Server) SetStateDB 

func (s *Server) SetStateDB(stateDB *db.Database)

SetStateDB sets the optional state-db used to persist won blocks. When unset (or disabled), won blocks are only kept in the in-memory store.

Source Files

View all Source files

Directories

Path Synopsis
Package fulu provides Fulu (builder-specs) bid types for the Builder API.
 Package fulu provides Fulu (builder-specs) bid types for the Builder API.
Package gloas implements the Gloas-fork Builder API handlers and helpers.
 Package gloas implements the Gloas-fork Builder API handlers and helpers.
types
Code generated by dynamic-ssz.
 Code generated by dynamic-ssz.
Package validators provides types and storage for Builder API validator registrations.
 Package validators provides types and storage for Builder API validator registrations.

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.