api

package
v0.0.2 Latest Latest
Warning

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

 Go to latest Published: Jul 8, 2026 License: GPL-3.0 Imports: 26 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type APIHandler 

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

APIHandler handles API requests for the buildoor web UI.

func NewAPIHandler 

func NewAPIHandler(
	authHandler *auth.AuthHandler,
	settingsSvc *config.Service,
	stateDB *db.Database,
	builderSvc *payload_builder.Service,
	epbsSvc *p2p_bidder.Service,
	lifecycleMgr *lifecycle.Manager,
	chainSvc chain.Service,
	validatorStore *memstore.Store[phase0.BLSPubKey, *apiv1.SignedValidatorRegistration],
	builderAPISvc *builderapi.Server,
	propPrefSvc *payload_bidder.ProposerPreferencesService,
	valRanges *validatorranges.Resolver,
	revealSvc *payload_bidder.RevealService,
	inclusionTracker *payload_bidder.InclusionTracker,
	payments *payload_bidder.PaymentTracker,
) *APIHandler

NewAPIHandler creates a new API handler.

func (*APIHandler) EventStream 

func (h *APIHandler) EventStream(w http.ResponseWriter, r *http.Request)

EventStream handles the SSE endpoint for real-time events.

func (*APIHandler) GetAuditLog 

func (h *APIHandler) GetAuditLog(w http.ResponseWriter, r *http.Request)

GetAuditLog godoc @Id getAuditLog @Summary Get the audit log @Tags Buildoor @Description Returns a paginated list of authenticated mutating actions. Empty when no state-db is configured. @Produce json @Param Authorization header string true "Bearer token" @Param offset query int false "Offset for pagination" default(0) @Param limit query int false "Limit for pagination (max 100)" default(20) @Success 200 {object} AuditLogResponse "Success" @Failure 401 {object} map[string]string "Unauthorized" @Failure 500 {object} map[string]string "Server Error" @Router /api/buildoor/audit-log [get]

func (*APIHandler) GetBidsWon 

func (h *APIHandler) GetBidsWon(w http.ResponseWriter, r *http.Request)

GetBidsWon godoc @Id getBidsWon @Summary Get bids won (blocks of ours included on chain) @Tags Buildoor @Description Returns a paginated list of won blocks (Builder API and p2p ePBS) with transaction counts, blob counts, and values, read from the shared inclusion tracker. @Produce json @Param offset query int false "Offset for pagination" default(0) @Param limit query int false "Limit for pagination (max 100)" default(20) @Success 200 {object} BidsWonResponse "Success" @Failure 500 {object} map[string]string "Server Error" @Router /api/buildoor/bids-won [get]

func (*APIHandler) GetBuilderAPIStatus 

func (h *APIHandler) GetBuilderAPIStatus(w http.ResponseWriter, _ *http.Request)

GetBuilderAPIStatus godoc @Id getBuilderAPIStatus @Summary Get Builder API status @Tags Buildoor @Description Returns the current status of the Builder API including configuration and validator count. @Produce json @Success 200 {object} BuilderAPIStatusResponse "Success" @Failure 500 {object} map[string]string "Server Error" @Router /api/buildoor/builder-api-status [get]

func (*APIHandler) GetBuilderPreferences 

func (h *APIHandler) GetBuilderPreferences(w http.ResponseWriter, _ *http.Request)

GetBuilderPreferences godoc @Id getBuilderPreferences @Summary Get cached builder preferences @Tags Buildoor @Description Returns all builder preferences currently in the cache, submitted by proposers via the submitBuilderPreferences API. @Produce json @Success 200 {object} BuilderPreferencesResponse "Success" @Failure 404 {object} map[string]string "Builder API not enabled" @Router /api/buildoor/builder-preferences [get]

func (*APIHandler) GetConfig 

func (h *APIHandler) GetConfig(w http.ResponseWriter, _ *http.Request)

GetConfig godoc @Id getConfig @Summary Get buildoor configuration @Tags Config @Description Returns the buildoor configuration in use. Sensitive fields (builder key, wallet key, JWT secret) are redacted. @Produce json @Success 200 {object} map[string]interface{} "Success" @Failure 500 {object} map[string]string "Server Error" @Router /api/config [get]

func (*APIHandler) GetEventStreamManager 

func (h *APIHandler) GetEventStreamManager() *EventStreamManager

GetEventStreamManager returns the event stream manager for external use.

func (*APIHandler) GetLifecycleStatus 

func (h *APIHandler) GetLifecycleStatus(w http.ResponseWriter, _ *http.Request)

GetLifecycleStatus godoc @Id getLifecycleStatus @Summary Get lifecycle status @Tags Lifecycle @Description Returns the builder lifecycle status including registration state, balance, @Description pending payments, and epoch information. @Produce json @Success 200 {object} LifecycleStatusResponse "Success" @Failure 404 {object} map[string]string "Lifecycle management not enabled" @Failure 500 {object} map[string]string "Server Error" @Router /api/lifecycle/status [get]

func (*APIHandler) GetOverview 

func (h *APIHandler) GetOverview(w http.ResponseWriter, r *http.Request)

GetOverview godoc @Id getOverview @Summary Get a compact overview of this buildoor instance @Tags Buildoor @Description Returns a single-payload summary used by the multi-instance overview UI: @Description running state, builder pubkey, current slot, EL client info, available/enabled @Description services, balances, and recent build stats. @Produce json @Success 200 {object} OverviewResponse "Success" @Router /api/buildoor/overview [get]

func (*APIHandler) GetProposerPreferences 

func (h *APIHandler) GetProposerPreferences(w http.ResponseWriter, _ *http.Request)

GetProposerPreferences godoc @Id getProposerPreferences @Summary Get cached proposer preferences @Tags Buildoor @Description Returns all proposer preferences currently in the cache, received via P2P gossip. @Produce json @Success 200 {object} ProposerPreferencesResponse "Success" @Failure 404 {object} map[string]string "Proposer preferences not enabled" @Router /api/buildoor/proposer-preferences [get]

func (*APIHandler) GetStats 

func (h *APIHandler) GetStats(w http.ResponseWriter, _ *http.Request)

GetStats godoc @Id getStats @Summary Get builder statistics @Tags Stats @Description Returns builder statistics including slots built, bids submitted/won, @Description total paid, and reveal success/failure counts. @Produce json @Success 200 {object} StatsResponse "Success" @Failure 500 {object} map[string]string "Server Error" @Router /api/stats [get]

func (*APIHandler) GetStatus 

func (h *APIHandler) GetStatus(w http.ResponseWriter, r *http.Request)

GetStatus godoc @Id getStatus @Summary Get builder status @Tags Status @Description Returns the current builder status including running state, current slot, @Description builder index and public key. @Produce json @Success 200 {object} StatusResponse "Success" @Failure 500 {object} map[string]string "Server Error" @Router /api/status [get]

func (*APIHandler) GetValidators 

func (h *APIHandler) GetValidators(w http.ResponseWriter, _ *http.Request)

GetValidators godoc @Id getValidators @Summary List registered validators @Tags Buildoor @Description Returns the list of validators registered via the Builder API (fee recipient preferences). Not paginated. @Produce json @Success 200 {object} GetValidatorsResponse "Success" @Failure 500 {object} map[string]string "Server Error" @Router /api/buildoor/validators [get]

func (*APIHandler) GetVersion 

func (h *APIHandler) GetVersion(w http.ResponseWriter, _ *http.Request)

GetVersion godoc @Id getVersion @Summary Get the current version @Tags Version @Description Returns the current version @Produce json @Success 200 {string} string "Success" @Failure 500 {string} string "Server Error" @Router /api/version [get]

func (*APIHandler) PostDeposit 

func (h *APIHandler) PostDeposit(w http.ResponseWriter, r *http.Request)

PostDeposit godoc @Id postDeposit @Summary Trigger builder deposit @Tags Lifecycle @Description Initiates a builder registration deposit. If the builder is not yet @Description registered, this will register it with the specified amount. Requires authentication. @Accept json @Produce json @Param Authorization header string true "Bearer token" @Param request body object{amount_gwei=uint64} true "Deposit amount in gwei" @Success 200 {object} map[string]string "Success" @Failure 400 {object} map[string]string "Bad Request" @Failure 401 {object} map[string]string "Unauthorized" @Failure 404 {object} map[string]string "Lifecycle management not enabled" @Failure 500 {object} map[string]string "Server Error" @Router /api/lifecycle/deposit [post]

func (*APIHandler) PostExit 

func (h *APIHandler) PostExit(w http.ResponseWriter, r *http.Request)

PostExit godoc @Id postExit @Summary Trigger voluntary exit @Tags Lifecycle @Description Initiates a voluntary exit for the builder. This will begin the withdrawal @Description process and the builder will stop being eligible for block building after @Description the exit is processed. Requires authentication. @Accept json @Produce json @Param Authorization header string true "Bearer token" @Success 200 {object} map[string]string "Success" @Failure 401 {object} map[string]string "Unauthorized" @Failure 404 {object} map[string]string "Lifecycle management not enabled" @Failure 500 {object} map[string]string "Server Error" @Router /api/lifecycle/exit [post]

func (*APIHandler) PostTopup 

func (h *APIHandler) PostTopup(w http.ResponseWriter, r *http.Request)

PostTopup godoc @Id postTopup @Summary Trigger balance top-up @Tags Lifecycle @Description Checks the builder balance and initiates a top-up if needed based on @Description configured thresholds. Requires authentication. @Accept json @Produce json @Param Authorization header string true "Bearer token" @Success 200 {object} map[string]string "Success" @Failure 401 {object} map[string]string "Unauthorized" @Failure 404 {object} map[string]string "Lifecycle management not enabled" @Failure 500 {object} map[string]string "Server Error" @Router /api/lifecycle/topup [post]

func (*APIHandler) ToggleServices 

func (h *APIHandler) ToggleServices(w http.ResponseWriter, r *http.Request)

ToggleServices toggles the enabled state of ePBS and/or Builder API services.

func (*APIHandler) UpdateBuilderAPIConfig 

func (h *APIHandler) UpdateBuilderAPIConfig(w http.ResponseWriter, r *http.Request)

UpdateBuilderAPIConfig updates the Builder API configuration.

func (*APIHandler) UpdateBuilderConfig 

func (h *APIHandler) UpdateBuilderConfig(w http.ResponseWriter, r *http.Request)

UpdateBuilderConfig updates the shared builder configuration (build start time, payload build delay).

func (*APIHandler) UpdateEPBS 

func (h *APIHandler) UpdateEPBS(w http.ResponseWriter, r *http.Request)

UpdateEPBS godoc @Id updateEPBS @Summary Update EPBS configuration @Tags Config @Description Updates the EPBS (enshrined PBS) configuration including timing and bid @Description parameters. Requires authentication. @Accept json @Produce json @Param Authorization header string true "Bearer token" @Param request body UpdateEPBSRequest true "EPBS configuration" @Success 200 {object} map[string]string "Success" @Failure 400 {object} map[string]string "Bad Request" @Failure 401 {object} map[string]string "Unauthorized" @Failure 500 {object} map[string]string "Server Error" @Router /api/config/epbs [post]

func (*APIHandler) UpdateLifecycleConfig 

func (h *APIHandler) UpdateLifecycleConfig(w http.ResponseWriter, r *http.Request)

UpdateLifecycleConfig updates the lifecycle configuration (topup threshold/amount).

func (*APIHandler) UpdateSchedule 

func (h *APIHandler) UpdateSchedule(w http.ResponseWriter, r *http.Request)

UpdateSchedule godoc @Id updateSchedule @Summary Update schedule configuration @Tags Config @Description Updates the builder schedule configuration including mode, every_nth, and next_n @Description settings. Requires authentication. @Accept json @Produce json @Param Authorization header string true "Bearer token" @Param request body UpdateScheduleRequest true "Schedule configuration" @Success 200 {object} map[string]string "Success" @Failure 400 {object} map[string]string "Bad Request" @Failure 401 {object} map[string]string "Unauthorized" @Failure 500 {object} map[string]string "Server Error" @Router /api/config/schedule [post]

type AuditLogResponse 

type AuditLogResponse struct {
	Entries []db.AuditLog `json:"entries"`
	Total   int           `json:"total"`
	Offset  int           `json:"offset"`
	Limit   int           `json:"limit"`
}

AuditLogResponse is the paginated response for GetAuditLog.

type BidStreamEvent 

type BidStreamEvent struct {
	Slot         uint64 `json:"slot"`
	BuilderIndex uint64 `json:"builder_index"`
	Value        uint64 `json:"value"`
	BlockHash    string `json:"block_hash"`
	IsOurs       bool   `json:"is_ours"`
	ReceivedAt   int64  `json:"received_at"`
}

BidStreamEvent represents a bid from any payload_builder.

type BidSubmittedEvent 

type BidSubmittedEvent struct {
	Slot      uint64 `json:"slot"`
	BlockHash string `json:"block_hash"`
	Value     uint64 `json:"value"`
	BidCount  int    `json:"bid_count"`
	Timestamp int64  `json:"timestamp"`
	Success   bool   `json:"success"`
	Error     string `json:"error,omitempty"`
	Warning   string `json:"warning,omitempty"`
}

BidSubmittedEvent is sent when we submit a bid (success or failure).

type BidWonStreamEvent 

type BidWonStreamEvent 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"`
	ValueWei        string `json:"value_wei"`
	Timestamp       int64  `json:"timestamp"`
}

BidWonStreamEvent is sent when a bid is won (block successfully delivered).

type BidsWonResponse 

type BidsWonResponse struct {
	BidsWon []*payload_bidder.WonBlock `json:"bids_won"`
	Total   int                        `json:"total"`
	Offset  int                        `json:"offset"`
	Limit   int                        `json:"limit"`
}

BidsWonResponse is the response for GetBidsWon.

type BuilderAPIGetBidDeliveredEvent 

type BuilderAPIGetBidDeliveredEvent struct {
	Slot        uint64 `json:"slot"`
	BlockHash   string `json:"block_hash"`
	BlockValue  string `json:"block_value"`
	DeliveredAt int64  `json:"delivered_at"`
}

BuilderAPIGetBidDeliveredEvent is sent when a Gloas execution payload bid is delivered.

type BuilderAPIGetBidReceivedEvent 

type BuilderAPIGetBidReceivedEvent struct {
	Slot       uint64 `json:"slot"`
	ParentHash string `json:"parent_hash"`
	Pubkey     string `json:"pubkey"`
	ReceivedAt int64  `json:"received_at"`
}

BuilderAPIGetBidReceivedEvent is sent when a Gloas getExecutionPayloadBid request is received.

type BuilderAPIGetHeaderDeliveredEvent 

type BuilderAPIGetHeaderDeliveredEvent struct {
	Slot        uint64 `json:"slot"`
	BlockHash   string `json:"block_hash"`
	BlockValue  string `json:"block_value"`
	DeliveredAt int64  `json:"delivered_at"`
}

BuilderAPIGetHeaderDeliveredEvent is sent when a header is successfully delivered.

type BuilderAPIGetHeaderReceivedEvent 

type BuilderAPIGetHeaderReceivedEvent struct {
	Slot       uint64 `json:"slot"`
	ParentHash string `json:"parent_hash"`
	Pubkey     string `json:"pubkey"`
	ReceivedAt int64  `json:"received_at"`
}

BuilderAPIGetHeaderReceivedEvent is sent when a getHeader request is received.

type BuilderAPIStatusResponse 

type BuilderAPIStatusResponse struct {
	Enabled               bool   `json:"enabled"`
	ValidatorCount        int    `json:"validator_count"`
	BlockValueSubsidyGwei uint64 `json:"block_value_subsidy_gwei"`
}

BuilderAPIStatusResponse is the response for GetBuilderAPIStatus.

type BuilderAPISubmitBlindedDeliveredEvent 

type BuilderAPISubmitBlindedDeliveredEvent struct {
	Slot        uint64 `json:"slot"`
	BlockHash   string `json:"block_hash"`
	DeliveredAt int64  `json:"delivered_at"`
}

BuilderAPISubmitBlindedDeliveredEvent is sent when a blinded block is successfully published.

type BuilderAPISubmitBlindedReceivedEvent 

type BuilderAPISubmitBlindedReceivedEvent struct {
	Slot       uint64 `json:"slot"`
	BlockHash  string `json:"block_hash"`
	ReceivedAt int64  `json:"received_at"`
}

BuilderAPISubmitBlindedReceivedEvent is sent when a submitBlindedBlock request is received.

type BuilderAPISubmitBlockDeliveredEvent 

type BuilderAPISubmitBlockDeliveredEvent struct {
	Slot        uint64 `json:"slot"`
	BlockHash   string `json:"block_hash"`
	DeliveredAt int64  `json:"delivered_at"`
}

BuilderAPISubmitBlockDeliveredEvent is sent when a Gloas envelope is successfully published.

type BuilderAPISubmitBlockReceivedEvent 

type BuilderAPISubmitBlockReceivedEvent struct {
	Slot       uint64 `json:"slot"`
	BlockHash  string `json:"block_hash"`
	ReceivedAt int64  `json:"received_at"`
}

BuilderAPISubmitBlockReceivedEvent is sent when a Gloas submitSignedBeaconBlock request is received.

type BuilderInfoEvent 

type BuilderInfoEvent struct {
	BuilderPubkey     string `json:"builder_pubkey"`
	BuilderIndex      uint64 `json:"builder_index"`
	IsRegistered      bool   `json:"is_registered"`
	CLBalance         uint64 `json:"cl_balance_gwei"`
	PendingPayments   uint64 `json:"pending_payments_gwei"`
	EffectiveBalance  uint64 `json:"effective_balance_gwei"`
	LifecycleEnabled  bool   `json:"lifecycle_enabled"`
	WalletAddress     string `json:"wallet_address,omitempty"`
	WalletBalance     string `json:"wallet_balance_wei,omitempty"`
	DepositEpoch      uint64 `json:"deposit_epoch"`
	WithdrawableEpoch uint64 `json:"withdrawable_epoch"`
}

BuilderInfoEvent contains builder identity and balance information.

type BuilderPreferencesEntry 

type BuilderPreferencesEntry struct {
	ValidatorPubkey     string `json:"validator_pubkey"`
	MaxExecutionPayment uint64 `json:"max_execution_payment"`
}

BuilderPreferencesEntry represents a single cached builder preference for the API response.

type BuilderPreferencesResponse 

type BuilderPreferencesResponse struct {
	Preferences []BuilderPreferencesEntry `json:"preferences"`
}

BuilderPreferencesResponse is the response for GetBuilderPreferences.

type EventStreamManager 

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

EventStreamManager manages SSE connections and event broadcasting.

func NewEventStreamManager 

func NewEventStreamManager(
	builderSvc *payload_builder.Service,
	epbsSvc *p2p_bidder.Service,
	lifecycleMgr *lifecycle.Manager,
	chainSvc chain.Service,
	builderAPISvc *builderapi.Server,
	revealSvc *payload_bidder.RevealService,
	inclusionTracker *payload_bidder.InclusionTracker,
	payments *payload_bidder.PaymentTracker,
) *EventStreamManager

NewEventStreamManager creates a new event stream manager.

func (*EventStreamManager) AddClient 

func (m *EventStreamManager) AddClient(ch chan *StreamEvent)

AddClient adds a new SSE client.

func (*EventStreamManager) Broadcast 

func (m *EventStreamManager) Broadcast(event *StreamEvent)

Broadcast sends an event to all connected clients.

func (*EventStreamManager) BroadcastBidFailed 

func (m *EventStreamManager) BroadcastBidFailed(slot uint64, blockHash string, value uint64, bidCount int, errMsg string)

BroadcastBidFailed broadcasts a bid submission failure event.

func (*EventStreamManager) BroadcastBidSubmitted 

func (m *EventStreamManager) BroadcastBidSubmitted(slot uint64, blockHash string, value uint64, bidCount int)

BroadcastBidSubmitted broadcasts a bid submitted event (success).

func (*EventStreamManager) BroadcastBidWon 

func (m *EventStreamManager) BroadcastBidWon(wonBlock *payload_bidder.WonBlock)

BroadcastBidWon broadcasts a bid won event when one of our blocks is seen included at the head (fed by the inclusion tracker's won-block record).

func (*EventStreamManager) BroadcastBuilderAPIGetBidDelivered 

func (m *EventStreamManager) BroadcastBuilderAPIGetBidDelivered(slot uint64, blockHash, blockValue string)

BroadcastBuilderAPIGetBidDelivered broadcasts when a Gloas execution payload bid is delivered.

func (*EventStreamManager) BroadcastBuilderAPIGetBidReceived 

func (m *EventStreamManager) BroadcastBuilderAPIGetBidReceived(slot uint64, parentHash, pubkey string)

BroadcastBuilderAPIGetBidReceived broadcasts when a Gloas getExecutionPayloadBid request is received.

func (*EventStreamManager) BroadcastBuilderAPIGetHeaderDelivered 

func (m *EventStreamManager) BroadcastBuilderAPIGetHeaderDelivered(slot uint64, blockHash, blockValue string)

BroadcastBuilderAPIGetHeaderDelivered broadcasts when a header is successfully delivered.

func (*EventStreamManager) BroadcastBuilderAPIGetHeaderReceived 

func (m *EventStreamManager) BroadcastBuilderAPIGetHeaderReceived(slot uint64, parentHash, pubkey string)

BroadcastBuilderAPIGetHeaderReceived broadcasts when a getHeader request is received.

func (*EventStreamManager) BroadcastBuilderAPISubmitBlindedDelivered 

func (m *EventStreamManager) BroadcastBuilderAPISubmitBlindedDelivered(slot uint64, blockHash string)

BroadcastBuilderAPISubmitBlindedDelivered broadcasts when a blinded block is successfully published.

func (*EventStreamManager) BroadcastBuilderAPISubmitBlindedReceived 

func (m *EventStreamManager) BroadcastBuilderAPISubmitBlindedReceived(slot uint64, blockHash string)

BroadcastBuilderAPISubmitBlindedReceived broadcasts when a submitBlindedBlock request is received.

func (*EventStreamManager) BroadcastBuilderAPISubmitBlockDelivered 

func (m *EventStreamManager) BroadcastBuilderAPISubmitBlockDelivered(slot uint64, blockHash string)

BroadcastBuilderAPISubmitBlockDelivered broadcasts when a Gloas envelope is successfully published.

func (*EventStreamManager) BroadcastBuilderAPISubmitBlockReceived 

func (m *EventStreamManager) BroadcastBuilderAPISubmitBlockReceived(slot uint64, blockHash string)

BroadcastBuilderAPISubmitBlockReceived broadcasts when a Gloas submitSignedBeaconBlock request is received.

func (*EventStreamManager) BroadcastConfigUpdate 

func (m *EventStreamManager) BroadcastConfigUpdate()

BroadcastConfigUpdate broadcasts a config update event.

func (*EventStreamManager) BroadcastLifecycle 

func (m *EventStreamManager) BroadcastLifecycle(action, message, status string)

BroadcastLifecycle broadcasts a lifecycle event (deposit, exit, state change, etc.).

func (*EventStreamManager) BroadcastReveal 

func (m *EventStreamManager) BroadcastReveal(event *payload_bidder.RevealResult)

BroadcastReveal broadcasts a reveal event (one per attempt, success or failure).

func (*EventStreamManager) BroadcastServiceStatus 

func (m *EventStreamManager) BroadcastServiceStatus()

BroadcastServiceStatus broadcasts the current service status.

func (*EventStreamManager) RemoveClient 

func (m *EventStreamManager) RemoveClient(ch chan *StreamEvent)

RemoveClient removes an SSE client.

func (*EventStreamManager) SendInitialState 

func (m *EventStreamManager) SendInitialState(ctx context.Context, ch chan *StreamEvent)

SendInitialState sends the current state to a newly connected client. Sends are ctx-aware: if the client disconnects (or shutdown is signalled) while the channel buffer is full, the goroutine bails out instead of blocking forever. This is what lets the caller safely run this in a goroutine alongside the SSE read loop.

func (*EventStreamManager) Start 

func (m *EventStreamManager) Start()

Start begins the event stream manager.

func (*EventStreamManager) Stop 

func (m *EventStreamManager) Stop()

Stop stops the event stream manager.

type EventType 

type EventType string

EventType represents the type of event being streamed. 

const (
	EventTypeConfig                      EventType = "config"
	EventTypeStatus                      EventType = "status"
	EventTypeSlotStart                   EventType = "slot_start"
	EventTypePayloadAttributes           EventType = "payload_attributes"
	EventTypePayloadBuildStarted         EventType = "payload_build_started"
	EventTypePayloadBuildFailed          EventType = "payload_build_failed"
	EventTypePayloadReady                EventType = "payload_ready"
	EventTypeBidSubmitted                EventType = "bid_submitted"
	EventTypeHeadReceived                EventType = "head_received"
	EventTypeReveal                      EventType = "reveal"
	EventTypeBidEvent                    EventType = "bid_event"
	EventTypeStats                       EventType = "stats"
	EventTypeSlotState                   EventType = "slot_state"
	EventTypePayloadAvailable            EventType = "payload_available"
	EventTypeBuilderInfo                 EventType = "builder_info"
	EventTypeHeadVotes                   EventType = "head_votes"
	EventTypeBidWon                      EventType = "bid_won"
	EventTypeBuilderAPIGetHeaderRcvd     EventType = "builder_api_get_header_received"
	EventTypeBuilderAPIGetHeaderDlvd     EventType = "builder_api_get_header_delivered"
	EventTypeBuilderAPISubmitBlindedRcvd EventType = "builder_api_submit_blinded_received"
	EventTypeBuilderAPISubmitBlindedDlvd EventType = "builder_api_submit_blinded_delivered"
	EventTypeBuilderAPIGetBidRcvd        EventType = "builder_api_get_bid_received"
	EventTypeBuilderAPIGetBidDlvd        EventType = "builder_api_get_bid_delivered"
	EventTypeBuilderAPISubmitBlockRcvd   EventType = "builder_api_submit_block_received"
	EventTypeBuilderAPISubmitBlockDlvd   EventType = "builder_api_submit_block_delivered"
	EventTypeServiceStatus               EventType = "service_status"
	EventTypeLifecycle                   EventType = "lifecycle"
	EventTypeBidIncluded                 EventType = "bid_included"
)

type GetValidatorsResponse 

type GetValidatorsResponse struct {
	Validators []ValidatorRegistrationResponse `json:"validators"`
}

GetValidatorsResponse is the response for GetValidators.

type HeadReceivedEvent 

type HeadReceivedEvent struct {
	Slot       uint64 `json:"slot"`
	BlockRoot  string `json:"block_root"`
	ReceivedAt int64  `json:"received_at"`
}

HeadReceivedEvent is sent when a head event is received.

type HeadVotesStreamEvent 

type HeadVotesStreamEvent struct {
	Slot             uint64  `json:"slot"`
	ParticipationPct float64 `json:"participation_pct"`
	ParticipationETH uint64  `json:"participation_eth"`
	TotalSlotETH     uint64  `json:"total_slot_eth"`
	Timestamp        int64   `json:"timestamp"`
}

HeadVotesStreamEvent is sent when head vote participation changes.

type LifecycleStatusResponse 

type LifecycleStatusResponse struct {
	IsRegistered      bool   `json:"is_registered"`
	BuilderIndex      uint64 `json:"builder_index"`
	Balance           uint64 `json:"balance_gwei"`
	EffectiveBalance  uint64 `json:"effective_balance_gwei"`
	PendingPayments   uint64 `json:"pending_payments_gwei"`
	DepositEpoch      uint64 `json:"deposit_epoch"`
	WithdrawableEpoch uint64 `json:"withdrawable_epoch"`
}

LifecycleStatusResponse is the response for lifecycle status.

type LifecycleStreamEvent 

type LifecycleStreamEvent struct {
	Action  string `json:"action"`  // "deposit", "topup", "exit", "state_change", "waiting_gloas", "balance_topup"
	Message string `json:"message"` // Human-readable description
	Status  string `json:"status"`  // "info", "success", "warning", "error"
}

LifecycleStreamEvent is sent when a lifecycle action occurs (deposit, topup, exit, state change).

type OverviewBalances 

type OverviewBalances struct {
	CLBalanceGwei        uint64 `json:"cl_balance_gwei,omitempty"`
	PendingPaymentsGwei  uint64 `json:"pending_payments_gwei,omitempty"`
	EffectiveBalanceGwei uint64 `json:"effective_balance_gwei,omitempty"`
	WalletAddress        string `json:"wallet_address,omitempty"`
	WalletBalanceWei     string `json:"wallet_balance_wei,omitempty"`
}

OverviewBalances captures CL builder + wallet balance for display.

type OverviewELClient 

type OverviewELClient struct {
	Code    string `json:"code,omitempty"`
	Name    string `json:"name,omitempty"`
	Version string `json:"version,omitempty"`
	Commit  string `json:"commit,omitempty"`
}

OverviewELClient is the EL client identification surfaced by the overview endpoint.

type OverviewResponse 

type OverviewResponse struct {
	Version       string            `json:"version"`
	Running       bool              `json:"running"`
	BuilderPubkey string            `json:"builder_pubkey,omitempty"`
	BuilderIndex  uint64            `json:"builder_index,omitempty"`
	IsRegistered  bool              `json:"is_registered"`
	CurrentSlot   uint64            `json:"current_slot"`
	ELClient      *OverviewELClient `json:"el_client,omitempty"`
	Services      OverviewServices  `json:"services"`
	Balances      OverviewBalances  `json:"balances"`
	Stats         OverviewStats     `json:"stats"`
}

OverviewResponse is the response payload of /api/buildoor/overview — a compact summary used by the multi-instance overview UI.

type OverviewServices 

type OverviewServices struct {
	EPBSAvailable         bool   `json:"epbs_available"`
	EPBSEnabled           bool   `json:"epbs_enabled"`
	EPBSRegistrationState string `json:"epbs_registration_state,omitempty"`
	BuilderAPIAvailable   bool   `json:"builder_api_available"`
	BuilderAPIEnabled     bool   `json:"builder_api_enabled"`
	LifecycleAvailable    bool   `json:"lifecycle_available"`
	LifecycleEnabled      bool   `json:"lifecycle_enabled"`
}

OverviewServices captures which optional services are available and toggled on.

type OverviewStats 

type OverviewStats struct {
	SlotsBuilt                     uint64 `json:"slots_built"`
	BlocksIncluded                 uint64 `json:"blocks_included"`
	BidsSubmitted                  uint64 `json:"bids_submitted"`
	BidsWon                        uint64 `json:"bids_won"`
	BuilderAPIHeadersRequested     uint64 `json:"builder_api_headers_requested"`
	BuilderAPIBlocksPublished      uint64 `json:"builder_api_blocks_published"`
	BuilderAPIRegisteredValidators int    `json:"builder_api_registered_validators"`
}

OverviewStats is a compact subset of stats useful for the overview view.

type PayloadAttributesStreamEvent 

type PayloadAttributesStreamEvent struct {
	ProposalSlot       uint64 `json:"proposal_slot"`
	ProposerIndex      uint64 `json:"proposer_index"`
	ParentBlockHash    string `json:"parent_block_hash"`
	ParentBlockRoot    string `json:"parent_block_root"`
	ParentBlockNumber  uint64 `json:"parent_block_number"`
	Timestamp          uint64 `json:"timestamp"`
	FeeRecipient       string `json:"fee_recipient"`
	TargetGasLimit     uint64 `json:"target_gas_limit"`
	WithdrawalsCount   int    `json:"withdrawals_count"`
	ReceivedAt         int64  `json:"received_at"`
	InclusionListCount int    `json:"inclusion_list_count"`
}

PayloadAttributesStreamEvent is sent when a payload_attributes event is received from the beacon node. It arrives before the slot it targets (ProposalSlot), so the WebUI renders it on the parent slot's graph.

type PayloadAvailableStreamEvent 

type PayloadAvailableStreamEvent struct {
	Slot         uint64 `json:"slot"`
	BlockRoot    string `json:"block_root"`
	BlockHash    string `json:"block_hash"`
	BuilderIndex uint64 `json:"builder_index"`
	ReceivedAt   int64  `json:"received_at"`
}

PayloadAvailableStreamEvent is sent when a payload becomes available.

type PayloadBuildFailedStreamEvent 

type PayloadBuildFailedStreamEvent struct {
	Slot     uint64 `json:"slot"`
	Error    string `json:"error"`
	FailedAt int64  `json:"failed_at"`
}

PayloadBuildFailedStreamEvent is sent when a payload build fails, so the WebUI can mark the in-progress build as failed.

type PayloadBuildStartedStreamEvent 

type PayloadBuildStartedStreamEvent struct {
	Slot      uint64 `json:"slot"`
	StartedAt int64  `json:"started_at"`
}

PayloadBuildStartedStreamEvent is sent when payload building begins, before the payload is ready, so the WebUI can render the build as in-progress.

type PayloadReadyStreamEvent 

type PayloadReadyStreamEvent struct {
	Slot            uint64 `json:"slot"`
	BlockHash       string `json:"block_hash"`
	ParentBlockHash string `json:"parent_block_hash"`
	BlockValue      string `json:"block_value"`
	ReadyAt         int64  `json:"ready_at"`
}

PayloadReadyStreamEvent is sent when a payload becomes available.

type ProposerPreferencesEntry 

type ProposerPreferencesEntry struct {
	Slot           uint64 `json:"slot"`
	ValidatorIndex uint64 `json:"validator_index"`
	ClientName     string `json:"client_name,omitempty"`
	FeeRecipient   string `json:"fee_recipient"`
	TargetGasLimit uint64 `json:"target_gas_limit"`
}

ProposerPreferencesEntry represents a single cached proposer preference for the API response.

type ProposerPreferencesResponse 

type ProposerPreferencesResponse struct {
	Preferences []ProposerPreferencesEntry `json:"preferences"`
}

ProposerPreferencesResponse is the response for GetProposerPreferences.

type RevealStreamEvent 

type RevealStreamEvent struct {
	Slot        uint64 `json:"slot"`
	Success     bool   `json:"success"`
	Skipped     bool   `json:"skipped"`
	Error       string `json:"error,omitempty"`
	Attempt     int    `json:"attempt,omitempty"`
	MaxAttempts int    `json:"max_attempts,omitempty"`
	Timestamp   int64  `json:"timestamp"`
}

RevealStreamEvent is sent when we submit or skip a reveal (one per attempt).

type ServiceStatusEvent 

type ServiceStatusEvent struct {
	EPBSAvailable         bool   `json:"epbs_available"`
	EPBSEnabled           bool   `json:"epbs_enabled"`
	EPBSRegistrationState string `json:"epbs_registration_state"`
	BuilderAPIAvailable   bool   `json:"builder_api_available"`
	BuilderAPIEnabled     bool   `json:"builder_api_enabled"`
	LifecycleAvailable    bool   `json:"lifecycle_available"`
	LifecycleEnabled      bool   `json:"lifecycle_enabled"`
}

ServiceStatusEvent indicates which services are available and enabled.

type SlotStartEvent 

type SlotStartEvent struct {
	Slot          uint64 `json:"slot"`
	SlotStartTime int64  `json:"slot_start_time"`
}

SlotStartEvent is sent when a new slot starts.

type SlotStateEvent 

type SlotStateEvent struct {
	Slot           uint64 `json:"slot"`
	PayloadReady   bool   `json:"payload_ready"`
	BidCount       int    `json:"bid_count"`
	BidsClosed     bool   `json:"bids_closed"`
	BidIncluded    bool   `json:"bid_included"`
	Revealed       bool   `json:"revealed"`
	HighestBidOurs bool   `json:"highest_bid_ours"`
	HighestBid     uint64 `json:"highest_bid"`
	OurBid         uint64 `json:"our_bid"`
}

SlotStateEvent represents the current state of a slot.

type StatsResponse 

type StatsResponse struct {
	SlotsBuilt     uint64 `json:"slots_built"`
	BlocksIncluded uint64 `json:"blocks_included"`
	BidsSubmitted  uint64 `json:"bids_submitted"`
	BidsWon        uint64 `json:"bids_won"`
	TotalPaid      uint64 `json:"total_paid_gwei"`
	RevealsSuccess uint64 `json:"reveals_success"`
	RevealsFailed  uint64 `json:"reveals_failed"`
	RevealsSkipped uint64 `json:"reveals_skipped"`
	// Builder API stats
	BuilderAPIHeadersRequested     uint64 `json:"builder_api_headers_requested"`
	BuilderAPIBlocksPublished      uint64 `json:"builder_api_blocks_published"`
	BuilderAPIRegisteredValidators int    `json:"builder_api_registered_validators"`
}

StatsResponse is the response for the stats endpoint.

type StatusResponse 

type StatusResponse struct {
	Running           bool   `json:"running"`
	BuilderIndex      uint64 `json:"builder_index"`
	BuilderPubkey     string `json:"builder_pubkey"`
	CurrentSlot       uint64 `json:"current_slot"`
	IsRegistered      bool   `json:"is_registered"`
	CLBalance         uint64 `json:"cl_balance_gwei,omitempty"`
	PendingPayments   uint64 `json:"pending_payments_gwei,omitempty"`
	EffectiveBalance  uint64 `json:"effective_balance_gwei,omitempty"`
	LifecycleEnabled  bool   `json:"lifecycle_enabled"`
	WalletAddress     string `json:"wallet_address,omitempty"`
	WalletBalance     string `json:"wallet_balance_wei,omitempty"`
	DepositEpoch      uint64 `json:"deposit_epoch,omitempty"`
	WithdrawableEpoch uint64 `json:"withdrawable_epoch,omitempty"`
}

StatusResponse is the response for the status endpoint.

type StreamEvent 

type StreamEvent struct {
	Type      EventType `json:"type"`
	Timestamp int64     `json:"timestamp"`
	Data      any       `json:"data"`
}

StreamEvent is a wrapper for all event types sent to clients.

type ToggleServiceRequest 

type ToggleServiceRequest struct {
	EPBSEnabled       *bool `json:"epbs_enabled,omitempty"`
	BuilderAPIEnabled *bool `json:"builder_api_enabled,omitempty"`
	LifecycleEnabled  *bool `json:"lifecycle_enabled,omitempty"`
}

ToggleServiceRequest is the request for toggling services.

type UpdateBuilderAPIConfigRequest 

type UpdateBuilderAPIConfigRequest struct {
	BlockValueSubsidyGwei *uint64 `json:"block_value_subsidy_gwei,omitempty"`
}

UpdateBuilderAPIConfigRequest is the request for updating Builder API config.

type UpdateBuilderConfigRequest 

type UpdateBuilderConfigRequest struct {
	BuildStartTime    *int64  `json:"build_start_time,omitempty"`
	PayloadBuildDelay *int64  `json:"payload_build_delay,omitempty"`
	ExtraData         *string `json:"extra_data,omitempty"`
}

UpdateBuilderConfigRequest is the request for updating shared builder config.

type UpdateEPBSRequest 

type UpdateEPBSRequest struct {
	BuildStartTime    *int64  `json:"build_start_time,omitempty"`
	BidStartTime      *int64  `json:"bid_start_time,omitempty"`
	BidEndTime        *int64  `json:"bid_end_time,omitempty"`
	RevealTime        *int64  `json:"reveal_time,omitempty"`
	BidMinAmount      *uint64 `json:"bid_min_amount,omitempty"`
	BidIncrease       *uint64 `json:"bid_increase,omitempty"`
	BidInterval       *int64  `json:"bid_interval,omitempty"`
	PayloadBuildDelay *int64  `json:"payload_build_delay,omitempty"`
	BidSubsidy        *uint64 `json:"bid_subsidy,omitempty"`
}

UpdateEPBSRequest is the request for updating EPBS config.

type UpdateLifecycleConfigRequest 

type UpdateLifecycleConfigRequest struct {
	TopupThreshold *uint64 `json:"topup_threshold,omitempty"` // Gwei
	TopupAmount    *uint64 `json:"topup_amount,omitempty"`    // Gwei
}

UpdateLifecycleConfigRequest is the request for updating lifecycle config.

type UpdateScheduleRequest 

type UpdateScheduleRequest struct {
	Mode      string  `json:"mode"`
	EveryNth  uint64  `json:"every_nth,omitempty"`
	NextN     uint64  `json:"next_n,omitempty"`
	StartSlot *uint64 `json:"start_slot,omitempty"`
}

UpdateScheduleRequest is the request for updating schedule config.

type ValidatorRegistrationResponse 

type ValidatorRegistrationResponse struct {
	Pubkey       string `json:"pubkey"`        // Hex-encoded BLS public key
	FeeRecipient string `json:"fee_recipient"` // Hex-encoded Ethereum address
	GasLimit     uint64 `json:"gas_limit"`     // Gas limit for blocks
	Timestamp    uint64 `json:"timestamp"`     // Unix timestamp
}

GetValidators godoc @Id getValidators @Summary List registered validators @Tags Buildoor @Description Returns the list of validators registered via the Builder API (fee recipient preferences). Not paginated. @Produce json @Success 200 {object} map[string][]object "Success" @Failure 500 {object} map[string]string "Server Error" @Router /api/buildoor/validators [get] ValidatorRegistrationResponse represents a formatted validator registration for the UI.

Source Files

View all Source files

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.