Documentation
¶
Overview ¶
Package epbs implements ePBS-specific bid management and tracking logic.
Index ¶
- Constants
- func RegistrationStateName(state int32) string
- type BidCreator
- type BidIncludedEvent
- type BidSubmissionEvent
- type BidTracker
- func (t *BidTracker) AddDeposit(amount uint64)
- func (t *BidTracker) Cleanup(olderThan phase0.Slot)
- func (t *BidTracker) GetBalanceAdjustment() int64
- func (t *BidTracker) GetHighestBid(slot phase0.Slot) *TrackedBid
- func (t *BidTracker) GetOurBid(slot phase0.Slot) *TrackedBid
- func (t *BidTracker) GetSlotBids(slot phase0.Slot) *SlotBids
- func (t *BidTracker) GetTotalPendingPayments() uint64
- func (t *BidTracker) MarkRevealed(slot phase0.Slot)
- func (t *BidTracker) PruneExpiredPayments(currentEpoch phase0.Epoch)
- func (t *BidTracker) RecordWonBid(slot phase0.Slot, value uint64)
- func (t *BidTracker) ResetBalanceAdjustment()
- func (t *BidTracker) SetBuilderIndex(index uint64)
- func (t *BidTracker) TrackBid(bid *ExecutionPayloadBid, isOurs bool)
- type ExecutionPayloadBid
- type PayloadStore
- func (s *PayloadStore) Cleanup(olderThan phase0.Slot)
- func (s *PayloadStore) Delete(slot phase0.Slot)
- func (s *PayloadStore) Get(slot phase0.Slot) *payload_builder.Payload
- func (s *PayloadStore) GetByBlockHash(blockHash phase0.Hash32) *payload_builder.Payload
- func (s *PayloadStore) Store(p *payload_builder.Payload)
- type PendingPayment
- type RevealEvent
- type RevealHandler
- type Scheduler
- func (s *Scheduler) Cleanup(olderThan phase0.Slot)
- func (s *Scheduler) GetBidTracker() *BidTracker
- func (s *Scheduler) MarkBidIncluded(slot phase0.Slot, blockInfo *beacon.BlockInfo)
- func (s *Scheduler) OnHeadEvent(event *beacon.HeadEvent)
- func (s *Scheduler) OnPayloadReady(payload *payload_builder.Payload)
- func (s *Scheduler) ProcessTick(ctx context.Context)
- func (s *Scheduler) UpdateConfig(cfg *config.EPBSConfig)
- type Service
- func (s *Service) FireBidSubmission(event *BidSubmissionEvent)
- func (s *Service) FireReveal(event *RevealEvent)
- func (s *Service) GetBidTracker() *BidTracker
- func (s *Service) GetBuilderIndex() uint64
- func (s *Service) GetBuilderPubkey() phase0.BLSPubKey
- func (s *Service) GetPayloadStore() *PayloadStore
- func (s *Service) GetRegistrationState() int32
- func (s *Service) IsActive() bool
- func (s *Service) IsEnabled() bool
- func (s *Service) IsRegistered() bool
- func (s *Service) RefreshRegistrationState()
- func (s *Service) SetBuilderRegistered(index uint64)
- func (s *Service) SetEnabled(enabled bool)
- func (s *Service) SetRegistrationPending()
- func (s *Service) SetStateDB(stateDB *db.Database)
- func (s *Service) Start(ctx context.Context, builderSvc *payload_builder.Service) error
- func (s *Service) Stop()
- func (s *Service) SubscribeBidIncluded(capacity int) *utils.Subscription[*BidIncludedEvent]
- func (s *Service) SubscribeBidSubmissions(capacity int) *utils.Subscription[*BidSubmissionEvent]
- func (s *Service) SubscribeReveals(capacity int) *utils.Subscription[*RevealEvent]
- func (s *Service) UpdateConfig(cfg *config.EPBSConfig)
- type SlotBids
- type SlotState
- type TrackedBid
Constants ¶
const ( RegistrationStateUnknown int32 = 0 // Not checked yet RegistrationStatePending int32 = 1 // Deposit submitted, waiting for inclusion in beacon state RegistrationStateRegistered int32 = 2 // Builder registered and deposit epoch finalized RegistrationStateWaitingGloas int32 = 3 // Waiting for Gloas fork activation RegistrationStatePendingFinalization int32 = 4 // Builder in beacon state but deposit epoch not finalized RegistrationStateExiting int32 = 5 // Exit submitted, withdrawable epoch set but not reached RegistrationStateExited int32 = 6 // Withdrawable epoch passed, builder has exited RegistrationStateUnregistered int32 = 7 // Builder not in beacon state and no deposit in progress )
Registration state constants for the ePBS service.
Variables ¶
This section is empty.
Functions ¶
func RegistrationStateName ¶
RegistrationStateName returns the string name for a registration state.
Types ¶
type BidCreator ¶
type BidCreator struct {
// contains filtered or unexported fields
}
BidCreator builds ePBS bids via the shared payload_bidder and gossips them over p2p. It owns the p2p transport and the (caller-computed) bid economics; the bid construction and signing live in payload_bidder.
func NewBidCreator ¶
func NewBidCreator( signer *payload_bidder.Signer, clClient *beacon.Client, chainSvc chain.Service, builderIndex uint64, log logrus.FieldLogger, ) *BidCreator
NewBidCreator creates a new bid creator.
func (*BidCreator) CreateAndSubmitBid ¶
func (c *BidCreator) CreateAndSubmitBid( ctx context.Context, payload *payload_builder.Payload, bidValue uint64, ) error
CreateAndSubmitBid builds, signs, and gossips a bid for the given payload at the supplied value. The competitive bid value is decided by the scheduler; the ePBS p2p path takes no execution payment.
func (*BidCreator) GetBuilderIndex ¶
func (c *BidCreator) GetBuilderIndex() uint64
GetBuilderIndex returns the current builder index.
func (*BidCreator) SetBuilderIndex ¶
func (c *BidCreator) SetBuilderIndex(index uint64)
SetBuilderIndex updates the builder index.
type BidIncludedEvent ¶
BidIncludedEvent is fired when the beacon block includes our bid.
type BidSubmissionEvent ¶
type BidSubmissionEvent struct {
Slot phase0.Slot
BlockHash [32]byte
Value uint64
BidCount int
Success bool
Warning string // Non-fatal warning (e.g. "no proposer preferences")
Error string
}
BidSubmissionEvent represents a bid submission attempt (success or failure).
type BidTracker ¶
type BidTracker struct {
// contains filtered or unexported fields
}
BidTracker tracks bids for competition analysis and balance adjustments.
func NewBidTracker ¶
func NewBidTracker(ourBuilderIdx uint64, chainSvc chain.Service, log logrus.FieldLogger) *BidTracker
NewBidTracker creates a new bid tracker.
func (*BidTracker) AddDeposit ¶
func (t *BidTracker) AddDeposit(amount uint64)
AddDeposit adds a deposit/topup amount to the balance adjustment. Topups take effect immediately (no finalization delay).
func (*BidTracker) Cleanup ¶
func (t *BidTracker) Cleanup(olderThan phase0.Slot)
Cleanup removes old slot data.
func (*BidTracker) GetBalanceAdjustment ¶
func (t *BidTracker) GetBalanceAdjustment() int64
GetBalanceAdjustment returns the cumulative balance adjustment since last state refresh.
func (*BidTracker) GetHighestBid ¶
func (t *BidTracker) GetHighestBid(slot phase0.Slot) *TrackedBid
GetHighestBid returns the highest bid for a slot.
func (*BidTracker) GetOurBid ¶
func (t *BidTracker) GetOurBid(slot phase0.Slot) *TrackedBid
GetOurBid returns our bid for a slot.
func (*BidTracker) GetSlotBids ¶
func (t *BidTracker) GetSlotBids(slot phase0.Slot) *SlotBids
GetSlotBids returns all bids for a slot.
func (*BidTracker) GetTotalPendingPayments ¶
func (t *BidTracker) GetTotalPendingPayments() uint64
GetTotalPendingPayments returns the sum of unrevealed won bid obligations.
func (*BidTracker) MarkRevealed ¶
func (t *BidTracker) MarkRevealed(slot phase0.Slot)
MarkRevealed moves a won bid from pending to an immediate balance deduction. The payment is removed from pending and subtracted from the balance adjustment.
func (*BidTracker) PruneExpiredPayments ¶
func (t *BidTracker) PruneExpiredPayments(currentEpoch phase0.Epoch)
PruneExpiredPayments removes pending payments older than 2 epochs.
func (*BidTracker) RecordWonBid ¶
func (t *BidTracker) RecordWonBid(slot phase0.Slot, value uint64)
RecordWonBid records a won bid as a pending payment (unrevealed). Called when our bid is included in a beacon block. If we later reveal, call MarkRevealed to move it from pending to a balance deduction. If we don't reveal, it stays pending for 2 epochs then expires.
func (*BidTracker) ResetBalanceAdjustment ¶
func (t *BidTracker) ResetBalanceAdjustment()
ResetBalanceAdjustment resets the adjustment to 0. Called when the chain state refreshes and the balance is up to date.
func (*BidTracker) SetBuilderIndex ¶
func (t *BidTracker) SetBuilderIndex(index uint64)
SetBuilderIndex updates the builder index.
func (*BidTracker) TrackBid ¶
func (t *BidTracker) TrackBid(bid *ExecutionPayloadBid, isOurs bool)
TrackBid adds a bid to the tracker.
type ExecutionPayloadBid ¶
type ExecutionPayloadBid struct {
ParentBlockHash phase0.Hash32
ParentBlockRoot phase0.Root
BlockHash phase0.Hash32
FeeRecipient [20]byte
GasLimit uint64
BuilderIndex uint64
Slot phase0.Slot
Value uint64 // Gwei
ExecutionPayment uint64 // Gwei
}
ExecutionPayloadBid represents a bid for an execution payload.
type PayloadStore ¶
type PayloadStore struct {
// contains filtered or unexported fields
}
PayloadStore retains built payloads until they are revealed, keyed by proposal slot. It holds the canonical *payload_builder.Payload by reference — the heavy payload is never copied.
func NewPayloadStore ¶
func NewPayloadStore() *PayloadStore
NewPayloadStore creates a new payload store.
func (*PayloadStore) Cleanup ¶
func (s *PayloadStore) Cleanup(olderThan phase0.Slot)
Cleanup removes payloads for slots older than the given slot.
func (*PayloadStore) Delete ¶
func (s *PayloadStore) Delete(slot phase0.Slot)
Delete removes a payload for a slot.
func (*PayloadStore) Get ¶
func (s *PayloadStore) Get(slot phase0.Slot) *payload_builder.Payload
Get retrieves a stored payload for a slot.
func (*PayloadStore) GetByBlockHash ¶
func (s *PayloadStore) GetByBlockHash(blockHash phase0.Hash32) *payload_builder.Payload
GetByBlockHash retrieves a stored payload by its execution block hash.
func (*PayloadStore) Store ¶
func (s *PayloadStore) Store(p *payload_builder.Payload)
Store retains a built payload, keyed by its proposal slot.
type PendingPayment ¶
PendingPayment records an unrevealed won bid that may be deducted later.
type RevealEvent ¶
type RevealEvent struct {
Slot phase0.Slot
Success bool
Skipped bool
Error string // Failure reason (when Success is false)
Attempt int // 1-based attempt number for this reveal
MaxAttempts int // Total attempts allowed before giving up
}
RevealEvent represents a payload reveal (success or failure).
type RevealHandler ¶
type RevealHandler struct {
// contains filtered or unexported fields
}
RevealHandler reveals built payloads via the shared payload_bidder and gossips the envelope over p2p.
func NewRevealHandler ¶
func NewRevealHandler( signer *payload_bidder.Signer, clClient *beacon.Client, chainSvc chain.Service, builderIndex uint64, log logrus.FieldLogger, ) *RevealHandler
NewRevealHandler creates a new reveal handler.
func (*RevealHandler) SetBuilderIndex ¶
func (h *RevealHandler) SetBuilderIndex(index uint64)
SetBuilderIndex updates the builder index.
func (*RevealHandler) SubmitReveal ¶
func (h *RevealHandler) SubmitReveal( ctx context.Context, payload *payload_builder.Payload, blockInfo *beacon.BlockInfo, ) error
SubmitReveal builds the signed envelope via payload_bidder and publishes it (with blobs / KZG proofs) to the beacon node over p2p.
type Scheduler ¶
type Scheduler struct {
// contains filtered or unexported fields
}
Scheduler handles time-based bid and reveal scheduling. It uses a simple loop that checks current time and triggers actions.
func NewScheduler ¶
func NewScheduler( cfg *config.EPBSConfig, chainSvc chain.Service, bidCreator *BidCreator, revealHandler *RevealHandler, bidTracker *BidTracker, payloadStore *PayloadStore, payloadCache *payload_builder.PayloadCache, service *Service, blsSigner *signer.BLSSigner, propPrefCache *proposerpreferences.Cache, log logrus.FieldLogger, ) *Scheduler
NewScheduler creates a new scheduler.
func (*Scheduler) GetBidTracker ¶
func (s *Scheduler) GetBidTracker() *BidTracker
GetBidTracker returns the bid tracker.
func (*Scheduler) MarkBidIncluded ¶
MarkBidIncluded marks a bid as included for a slot.
func (*Scheduler) OnHeadEvent ¶
OnHeadEvent closes bidding for the slot — once a block is produced, no more bids can make it. Bid-inclusion marking happens via MarkBidIncluded from the async processHeadBlock path.
func (*Scheduler) OnPayloadReady ¶
func (s *Scheduler) OnPayloadReady(payload *payload_builder.Payload)
OnPayloadReady stores the payload (by reference) for later reveal.
func (*Scheduler) ProcessTick ¶
ProcessTick is called frequently to check if any bids or reveals are due.
func (*Scheduler) UpdateConfig ¶
func (s *Scheduler) UpdateConfig(cfg *config.EPBSConfig)
UpdateConfig updates the scheduler configuration.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service is the main ePBS orchestrator that handles time-scheduled bidding and revealing. It subscribes to builder payload events and handles the ePBS protocol.
func NewService ¶
func NewService( cfg *config.EPBSConfig, clClient *beacon.Client, chainSvc chain.Service, blsSigner *signer.BLSSigner, log logrus.FieldLogger, ) (*Service, error)
NewService creates a new ePBS service.
func (*Service) FireBidSubmission ¶
func (s *Service) FireBidSubmission(event *BidSubmissionEvent)
FireBidSubmission fires a bid submission event.
func (*Service) FireReveal ¶
func (s *Service) FireReveal(event *RevealEvent)
FireReveal fires a reveal event.
func (*Service) GetBidTracker ¶
func (s *Service) GetBidTracker() *BidTracker
GetBidTracker returns the bid tracker.
func (*Service) GetBuilderIndex ¶
GetBuilderIndex returns the builder index.
func (*Service) GetBuilderPubkey ¶
GetBuilderPubkey returns the builder public key.
func (*Service) GetPayloadStore ¶
func (s *Service) GetPayloadStore() *PayloadStore
GetPayloadStore returns the payload store.
func (*Service) GetRegistrationState ¶
GetRegistrationState returns the current registration state.
func (*Service) IsActive ¶
IsActive returns whether the builder can actively participate (registered or pending finalization).
func (*Service) IsRegistered ¶
IsRegistered returns whether the builder has a valid index and its deposit is finalized.
func (*Service) RefreshRegistrationState ¶
func (s *Service) RefreshRegistrationState()
RefreshRegistrationState re-evaluates the registration state from the chain service. Called periodically to detect state transitions (e.g. finalization, exit).
func (*Service) SetBuilderRegistered ¶
SetBuilderRegistered updates the builder index when the lifecycle manager detects registration. It sets the appropriate state based on finalization status. Called by the lifecycle manager's registration callback.
func (*Service) SetEnabled ¶
SetEnabled sets the enabled state of the ePBS service.
func (*Service) SetRegistrationPending ¶
func (s *Service) SetRegistrationPending()
SetRegistrationPending marks the builder as having a deposit in flight. Called by the lifecycle manager when a deposit is submitted.
func (*Service) SetStateDB ¶
SetStateDB sets the optional state-db used to persist won blocks. When unset (or disabled), ePBS won blocks are not persisted.
func (*Service) Start ¶
Start starts the ePBS service. It subscribes to the builder service's payload ready events.
func (*Service) SubscribeBidIncluded ¶
func (s *Service) SubscribeBidIncluded(capacity int) *utils.Subscription[*BidIncludedEvent]
SubscribeBidIncluded subscribes to bid included events.
func (*Service) SubscribeBidSubmissions ¶
func (s *Service) SubscribeBidSubmissions(capacity int) *utils.Subscription[*BidSubmissionEvent]
SubscribeBidSubmissions subscribes to bid submission events.
func (*Service) SubscribeReveals ¶
func (s *Service) SubscribeReveals(capacity int) *utils.Subscription[*RevealEvent]
SubscribeReveals subscribes to reveal events.
func (*Service) UpdateConfig ¶
func (s *Service) UpdateConfig(cfg *config.EPBSConfig)
UpdateConfig updates the service configuration at runtime.
type SlotBids ¶
type SlotBids struct {
Slot phase0.Slot
Bids map[uint64]*TrackedBid // BuilderIndex -> Bid
HighestBid *TrackedBid
OurBid *TrackedBid
WinningBid *TrackedBid // Set after block inclusion
}
SlotBids holds all bids for a specific slot.
func NewSlotBids ¶
NewSlotBids creates a new SlotBids instance for the given slot.
type SlotState ¶
type SlotState struct {
LastBidTime time.Time
LastBidHash phase0.Hash32
BidCount int
BidsClosed bool // Block received, no more bids possible
BidIncluded bool // Our bid was picked
IncludedInBlock *beacon.BlockInfo // Block that included our bid
Revealed bool
RevealAttempts int // Number of reveal attempts made (success or failure)
LastRevealAttempt time.Time // Time of the most recent reveal attempt
}
SlotState tracks the state for a single slot's bidding/revealing.
type TrackedBid ¶
type TrackedBid struct {
Bid *ExecutionPayloadBid
BuilderIndex uint64
ReceivedAt time.Time
IsOurs bool
}
TrackedBid represents a bid being tracked for competition analysis.