epbs

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: 20 Imported by: 0

Documentation

Overview

Package epbs implements ePBS-specific bid management and tracking logic.

Index

Constants

View Source
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

func RegistrationStateName(state int32) string

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

type BidIncludedEvent struct {
	Slot      phase0.Slot
	BlockHash phase0.Hash32
	BidValue  uint64
}

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

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

type PendingPayment struct {
	Slot  phase0.Slot
	Epoch phase0.Epoch
	Value uint64 // Gwei
}

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

func (s *Scheduler) Cleanup(olderThan phase0.Slot)

Cleanup removes old state.

func (*Scheduler) GetBidTracker

func (s *Scheduler) GetBidTracker() *BidTracker

GetBidTracker returns the bid tracker.

func (*Scheduler) MarkBidIncluded

func (s *Scheduler) MarkBidIncluded(slot phase0.Slot, blockInfo *beacon.BlockInfo)

MarkBidIncluded marks a bid as included for a slot.

func (*Scheduler) OnHeadEvent

func (s *Scheduler) OnHeadEvent(event *beacon.HeadEvent)

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

func (s *Scheduler) ProcessTick(ctx context.Context)

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

func (s *Service) GetBuilderIndex() uint64

GetBuilderIndex returns the builder index.

func (*Service) GetBuilderPubkey

func (s *Service) GetBuilderPubkey() phase0.BLSPubKey

GetBuilderPubkey returns the builder public key.

func (*Service) GetPayloadStore

func (s *Service) GetPayloadStore() *PayloadStore

GetPayloadStore returns the payload store.

func (*Service) GetRegistrationState

func (s *Service) GetRegistrationState() int32

GetRegistrationState returns the current registration state.

func (*Service) IsActive

func (s *Service) IsActive() bool

IsActive returns whether the builder can actively participate (registered or pending finalization).

func (*Service) IsEnabled

func (s *Service) IsEnabled() bool

IsEnabled returns whether the ePBS service is enabled.

func (*Service) IsRegistered

func (s *Service) IsRegistered() bool

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

func (s *Service) SetBuilderRegistered(index uint64)

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

func (s *Service) SetEnabled(enabled bool)

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

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

SetStateDB sets the optional state-db used to persist won blocks. When unset (or disabled), ePBS won blocks are not persisted.

func (*Service) Start

func (s *Service) Start(ctx context.Context, builderSvc *payload_builder.Service) error

Start starts the ePBS service. It subscribes to the builder service's payload ready events.

func (*Service) Stop

func (s *Service) Stop()

Stop stops the ePBS service.

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

func NewSlotBids(slot phase0.Slot) *SlotBids

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL