payload_bidder

type BidParams ¶

type BidParams struct {
	BuilderIndex     uint64
	FeeRecipient     bellatrix.ExecutionAddress
	Value            phase0.Gwei
	ExecutionPayment phase0.Gwei

	// Transform, when set, is an operator-supplied jq expression applied to the
	// bid MESSAGE (JSON) before signing; the modified message is then signed,
	// so the resulting bid is validly signed but customized.
	Transform string
}

BidParams are the policy-decided inputs a transport supplies for a bid. The transport owns the economics (value, execution payment) and identity (builder index, fee recipient); every other bid field is derived from the payload.

type InclusionTracker ¶ added in v0.0.2

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

InclusionTracker watches head events and detects inclusion of our payloads. It records the payment obligation, requests the payload reveal, fires inclusion events carrying the won-block summary (won-block storage is owned by the slot results tracker), and checks the follow-up block to detect orphaned (unrevealed) payloads. Shared by both the p2p and Builder API flows.

func NewInclusionTracker(
	clClient *beacon.Client,
	chainSvc chain.Service,
	builderSvc *payload_builder.Service,
	registry *builder_keys.Registry,
	revealSvc *RevealService,
	payments *PaymentTracker,
	log logrus.FieldLogger,
) *InclusionTracker

func (t *InclusionTracker) Start(ctx context.Context) error

func (t *InclusionTracker) Stop()

func (t *InclusionTracker) SubscribeIncluded(capacity int, blocking bool) *utils.Subscription[*PayloadIncludedEvent]

func (t *InclusionTracker) SubscribePayloadStatus(capacity int, blocking bool) *utils.Subscription[*PayloadStatusEvent]

type PayloadIncludedEvent ¶ added in v0.0.2

type PayloadIncludedEvent struct {
	Payload      *payload_builder.Payload
	BlockInfo    *beacon.BlockInfo
	BidValueGwei uint64
	WonBlock     *WonBlock // the won-block summary for this inclusion
}

PayloadIncludedEvent is fired when a beacon block committing to one of our payloads is observed at the head (consumed by the WebUI and the slot results tracker).

type PayloadStatusEvent ¶ added in v0.0.3

type PayloadStatusEvent struct {
	Slot           phase0.Slot // the won slot
	Verdict        PayloadVerdict
	NextBlockSlot  phase0.Slot   // canonical block the verdict was derived from
	NextParentHash phase0.Hash32 // execution parent hash that block committed to
}

PayloadStatusEvent reports the (possibly revised) canonical verdict for a won slot's payload.

type PayloadVerdict ¶ added in v0.0.3

type PayloadVerdict string

PayloadVerdict is the canonical outcome of a won slot's payload, derived from the current head's ancestry (Gloas+ only). Verdicts are re-evaluated on every head event within the tracking window, so a reorg can flip them; each change fires a new PayloadStatusEvent.

const (
	// PayloadVerdictCanonical: the canonical chain's first block after the
	// won slot builds on our payload.
	PayloadVerdictCanonical PayloadVerdict = "canonical"
	// PayloadVerdictMissed: the won block is canonical but the next block
	// builds on an older execution block — the payload was withheld, revealed
	// too late, or voted empty.
	PayloadVerdictMissed PayloadVerdict = "missed"
	// PayloadVerdictOrphaned: the won beacon block itself was reorged out of
	// the canonical chain.
	PayloadVerdictOrphaned PayloadVerdict = "orphaned"
)

type PaymentTracker ¶ added in v0.0.2

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

PaymentTracker tracks payment obligations and live balance adjustments per builder key, across both bid flows (p2p and Builder API). Fed by the InclusionTracker (won bids) and RevealService (reveals); consumed by the lifecycle manager (top-ups), the key registry (effective balances) and the WebUI. Passive and thread-safe: it runs no goroutine of its own.

Accounting is per key because a payment is owed by the key whose bid won — with several managed keys bidding, charging the wrong one would let an underfunded key keep bidding while a funded one looks broke.

func NewPaymentTracker(chainSvc chain.Service, log logrus.FieldLogger) *PaymentTracker

func (t *PaymentTracker) AddDeposit(keyIndex, amount uint64)

func (t *PaymentTracker) GetBalanceAdjustment(keyIndex uint64) int64

func (t *PaymentTracker) GetPendingPayments(keyIndex uint64) uint64

func (t *PaymentTracker) GetTotalPendingPayments() uint64

func (t *PaymentTracker) MarkRevealed(keyIndex uint64, slot phase0.Slot)

func (t *PaymentTracker) PruneExpiredPayments(currentEpoch phase0.Epoch)

func (t *PaymentTracker) ReconcileToEpoch(snapshotEpoch phase0.Epoch)

func (t *PaymentTracker) RecordWonBid(keyIndex uint64, slot phase0.Slot, value uint64)

func (t *PaymentTracker) SetPaymentDisputed(keyIndex uint64, slot phase0.Slot, disputed bool)

type PendingPayment ¶ added in v0.0.2

type PendingPayment struct {
	KeyIndex uint64
	Slot     phase0.Slot
	Epoch    phase0.Epoch
	Value    uint64 // Gwei
	// Disputed marks a payment whose winning block was reorged out: it no
	// longer counts toward the pending total unless the block returns.
	Disputed bool
}

PendingPayment records an unrevealed won bid that may be deducted later.

type ProposerPreferencesCodec ¶ added in v0.0.2

type ProposerPreferencesCodec struct{}

ProposerPreferencesCodec translates the proposer preference store's entries to their persisted form: decimal slot string keys, SSZ-encoded values.

func (ProposerPreferencesCodec) DecodeKey(key string) (phase0.Slot, error)

func (ProposerPreferencesCodec) DecodeValue(value []byte) (*gloasspec.SignedProposerPreferences, error)

func (ProposerPreferencesCodec) EncodeKey(slot phase0.Slot) string

func (ProposerPreferencesCodec) EncodeValue(prefs *gloasspec.SignedProposerPreferences) ([]byte, error)

type ProposerPreferencesService ¶ added in v0.0.2

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

ProposerPreferencesService listens to the beacon node's proposer_preferences SSE topic, caches the first valid preference per slot, prunes old slots on epoch transitions, and resolves proposer settings for Gloas+ payload builds (it implements payload_builder.ProposerSettingsResolver).

func NewProposerPreferencesService(clClient *beacon.Client, chainSvc chain.Service,
	log logrus.FieldLogger) *ProposerPreferencesService

func (s *ProposerPreferencesService) GetStore() *memstore.Store[phase0.Slot, *gloasspec.SignedProposerPreferences]

func (s *ProposerPreferencesService) ResolveProposerSettings(slot phase0.Slot,
	_ phase0.ValidatorIndex) (payload_builder.ProposerSettings, bool)

func (s *ProposerPreferencesService) Start(ctx context.Context) error

func (s *ProposerPreferencesService) Stop()

type RevealContext ¶

type RevealContext struct {
	BuilderIndex          uint64
	BeaconBlockRoot       phase0.Root
	ParentBeaconBlockRoot phase0.Root

	// Transform, when set, is an operator-supplied jq expression applied to the
	// envelope MESSAGE (JSON) before signing; the modified message is then
	// signed, so the resulting envelope is validly signed but customized.
	Transform string
}

RevealContext are the inputs a transport supplies for a payload reveal that aren't carried by the payload: the builder index and the beacon block roots the envelope is bound to.

type RevealRequest ¶ added in v0.0.2

type RevealRequest struct {
	Payload *payload_builder.Payload
	// Key is the builder key whose bid the block committed to. The envelope
	// must be signed by it and carry its builder index, or the reveal is
	// rejected while the payment is still owed.
	Key       *builder_keys.Key
	BlockInfo *beacon.BlockInfo // root + parent root of the committing beacon block
	Transport payload_builder.BidTransport
}

RevealRequest asks the RevealService to publish a payload's envelope at the configured reveal time. Both flows submit these; the service dedupes by slot.

type RevealResult ¶ added in v0.0.2

type RevealResult struct {
	Slot        phase0.Slot
	Transport   payload_builder.BidTransport
	Success     bool
	Skipped     bool   // reveal was skipped without publishing (see SkipReason)
	SkipReason  string `json:"skip_reason,omitempty"` // RevealSkipReasonPlanDisabled | RevealSkipReasonLate
	Error       string // failure reason (when Success is false)
	Attempt     int    // 1-based
	MaxAttempts int

	// StartedAt/CompletedAt bracket the attempt (envelope construction +
	// submit call) — the submit call alone takes several hundred ms on some
	// clients, so the span matters. Zero on skips (nothing was attempted).
	StartedAt   time.Time
	CompletedAt time.Time

	// Envelope is the signed envelope built for the attempt. It is set from
	// construction onward on every attempt (including failed publishes) and
	// nil on skips and pre-construction failures.
	Envelope *eth2all.SignedExecutionPayloadEnvelope `json:"-"`
}

RevealResult reports the outcome of a reveal attempt.

type RevealService ¶ added in v0.0.2

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

RevealService publishes execution payload envelopes once the slot's reveal gates open. It runs its own main loop: requests arrive on a channel, due times are awaited with a timer (no polling), head-vote updates open vote gates event-driven, reveals are deduped per slot (the first request wins regardless of transport), and failed publishes are retried per the configured retry policy. It is independent of the p2p bidder and Builder API modules and their enable flags. Each slot's reveal follows the slot's frozen action plan (suppression, gate mode, reveal time, vote threshold, broadcast validation, deadline bypass) — the plan service is the single per-slot settings authority.

func NewRevealService(
	cfg *config.Config,
	registry *builder_keys.Registry,
	publisher envelopePublisher,
	chainSvc chain.Service,
	builderSvc *payload_builder.Service,
	payments *PaymentTracker,
	planSvc *action_plan.PlanService,
	votes headVoteSource,
	log logrus.FieldLogger,
) *RevealService

func (s *RevealService) RequestReveal(req *RevealRequest)

func (s *RevealService) Start(ctx context.Context) error

func (s *RevealService) Stop()

func (s *RevealService) SubscribeResults(capacity int, blocking bool) *utils.Subscription[*RevealResult]

func (s *RevealService) SubscribeStarts(capacity int, blocking bool) *utils.Subscription[*RevealStarted]

type RevealStarted ¶ added in v0.0.3

type RevealStarted struct {
	Slot      phase0.Slot
	Transport payload_builder.BidTransport
	Attempt   int // 1-based
	StartedAt time.Time
}

RevealStarted announces the beginning of a reveal attempt (envelope construction + submit call) so the UI can render the in-flight call live; the matching RevealResult follows when the attempt completes.

type Signer ¶

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

Signer signs execution payload bids and envelopes with the builder's BLS key.

func NewSigner(blsSigner *signer.BLSSigner) *Signer

func (s *Signer) SignBid(
	bid *eth2all.ExecutionPayloadBid,
	forkVersion phase0.Version,
	genesisValidatorsRoot phase0.Root,
) (phase0.BLSSignature, error)

func (s *Signer) SignEnvelope(
	envelope *eth2all.ExecutionPayloadEnvelope,
	forkVersion phase0.Version,
	genesisValidatorsRoot phase0.Root,
) (phase0.BLSSignature, error)

type WonBlock ¶ added in v0.0.2

type WonBlock struct {
	Source          string `json:"source"`
	Slot            uint64 `json:"slot"`
	BlockHash       string `json:"block_hash"`
	NumTransactions int    `json:"num_transactions"`
	NumBlobs        int    `json:"num_blobs"`
	ValueWei        string `json:"value_wei"`
	ValueETH        string `json:"value_eth"`
	Timestamp       int64  `json:"timestamp"` // Unix milliseconds at inclusion time
}

WonBlock is a block of ours that was included in a beacon block, won via either the Builder API or p2p ePBS bidding. The JSON tags are the wire shape consumed by the WebUI (bids-won REST endpoint and bid_won SSE event) — do not change them.

type WonBlockCodec ¶ added in v0.0.2

type WonBlockCodec struct{}

WonBlockCodec translates the won-block store's entries to their persisted form: decimal slot string keys, JSON-encoded values. JSON is deliberate: WonBlock is a local aggregate (not a spec SSZ type), and the kv_store value is an opaque blob either way.

func (WonBlockCodec) DecodeKey(key string) (phase0.Slot, error)

func (WonBlockCodec) DecodeValue(value []byte) (*WonBlock, error)

func (WonBlockCodec) EncodeKey(slot phase0.Slot) string

func (WonBlockCodec) EncodeValue(wonBlock *WonBlock) ([]byte, error)