action_plan

type BidPlan struct {
	Mode Mode `json:"mode"`

	BidStartTime *int64  `json:"bid_start_time,omitempty"`
	BidEndTime   *int64  `json:"bid_end_time,omitempty"`
	BidMinAmount *uint64 `json:"bid_min_amount,omitempty"` // gwei
	BidIncrease  *uint64 `json:"bid_increase,omitempty"`   // gwei
	BidInterval  *int64  `json:"bid_interval,omitempty"`   // ms, >= 0, 0 = single bid
	BidSubsidy   *uint64 `json:"bid_subsidy,omitempty"`    // gwei

	// BidCandidate overrides which built candidate payload this slot's p2p
	// bids commit to: auto, all, or a specific candidate key.
	BidCandidate *string `json:"bid_candidate,omitempty"`

	// KeyStrategy overrides which managed builder key signs this slot's bids:
	// round_robin, single, random or least_used.
	KeyStrategy *string `json:"key_strategy,omitempty"`

	// BidKeysPerSlot overrides how many distinct builder keys may bid this
	// slot (0 = no cap beyond the fleet).
	BidKeysPerSlot *uint64 `json:"bid_keys_per_slot,omitempty"`

	// BidKeysPerStep overrides how many keys bid a payload per interval step
	// (0 = every remaining key at once).
	BidKeysPerStep *uint64 `json:"bid_keys_per_step,omitempty"`

	// BidValueGwei is an absolute bid base value replacing
	// max(blockValue, min) + subsidy; BidIncrease still applies per re-bid.
	// Allows underbidding the block value for testing.
	BidValueGwei *uint64 `json:"bid_value_gwei,omitempty"`

	// IgnoreMissingPrefs bids with the payload's fee recipient when no gossip
	// proposer preferences arrived for the slot, bypassing the skip gate.
	IgnoreMissingPrefs bool `json:"ignore_missing_prefs,omitempty"`
}

type BuildPlan struct {
	// ReorgParentPayload builds on the grandparent (n-2) execution payload
	// instead of the immediate parent: the FCU head block hash and the payload
	// attributes' withdrawals are taken from the PARENT slot's payload
	// attributes (whose parent is n-2), while every other property comes from
	// the current slot. This is a deliberate parent-payload reorg attempt —
	// rejected by mainnet forkchoice, but useful for exercising the reveal /
	// inclusion path against a withheld parent.
	ReorgParentPayload bool `json:"reorg_parent_payload,omitempty"`

	// Candidates overrides the global build-candidate policy for this slot:
	// candidate key (parent_full, parent_empty, grandparent_full,
	// grandparent_empty) -> mode (auto, always, never). Absent keys inherit
	// the global policy.
	Candidates map[string]string `json:"candidates,omitempty"`
}

type BuilderAPIPlan struct {
	Mode Mode `json:"mode"`

	// ValueSubsidyGwei replaces the global BlockValueSubsidyGwei for this slot.
	ValueSubsidyGwei *uint64 `json:"value_subsidy_gwei,omitempty"`

	// TotalValueOverrideGwei is the absolute total proposer-visible bid value
	// (before the Gloas execution-payment split), replacing block value +
	// subsidy. May exceed the block value to test payment edge cases.
	TotalValueOverrideGwei *uint64 `json:"total_value_override_gwei,omitempty"`

	// ResponseDelayMs delays the bid response by this many milliseconds
	// (context-cancellable, capped at one slot).
	ResponseDelayMs *int64 `json:"response_delay_ms,omitempty"`

	// KeyStrategy overrides which managed builder key signs this slot's served
	// bids: round_robin, single, random or least_used.
	KeyStrategy *string `json:"key_strategy,omitempty"`

	// ServeCandidates overrides which built candidate payloads bid requests
	// for this slot may be answered from: all, canonical_only, or a
	// comma-separated candidate key list.
	ServeCandidates *string `json:"serve_candidates,omitempty"`
}

type FrozenPlan struct {
	Slot     phase0.Slot `json:"slot"`
	Plan     *SlotPlan   `json:"plan,omitempty"` // raw sparse plan; nil = none existed
	Fork     string      `json:"fork"`           // fork name at the target slot
	FrozenAt time.Time   `json:"frozen_at"`

	// Build is the complete resolved build decision for the slot (schedule +
	// plan force/suppress). Always non-nil.
	Build *ResolvedBuildSettings `json:"build"`

	// Resolved effective settings; a nil category = suppressed for this slot
	// (by plan or by the global enable flags / protocol applicability).
	Bid        *ResolvedBidSettings        `json:"bid,omitempty"`
	BuilderAPI *ResolvedBuilderAPISettings `json:"builder_api,omitempty"`
	Reveal     *ResolvedRevealSettings     `json:"reveal,omitempty"`

	// Transforms carries the effective jq transform expressions (empty when no
	// transform plan applies). Nil only when no plan expression is set.
	Transforms *ResolvedTransforms `json:"transforms,omitempty"`
}

type Mode string

type PlanChangeEvent struct {
	Slots []uint64    `json:"slots"`
	Plans []*SlotPlan `json:"plans"`
}

type PlanCodec struct{}

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

type PlanUpdate struct {
	Slots    []uint64 `json:"slots,omitempty"`
	FromSlot *uint64  `json:"from_slot,omitempty"`
	ToSlot   *uint64  `json:"to_slot,omitempty"`
	Delete   bool     `json:"delete,omitempty"`

	Bid        json.RawMessage `json:"bid,omitempty"`
	BuilderAPI json.RawMessage `json:"builder_api,omitempty"`
	Reveal     json.RawMessage `json:"reveal,omitempty"`
	Build      json.RawMessage `json:"build,omitempty"`
	Transforms json.RawMessage `json:"transforms,omitempty"`

	// IgnoreRules is two-state on purpose: absent = unchanged, true/false =
	// set the slot's recurring-rule opt-out.
	IgnoreRules *bool `json:"ignore_rules,omitempty"`

	Set map[string]json.RawMessage `json:"set,omitempty"`
}

type ResolvedBidSettings struct {
	StartMs      int64  `json:"start_ms"`
	EndMs        int64  `json:"end_ms"`
	IntervalMs   int64  `json:"interval_ms"`
	MinGwei      uint64 `json:"min_gwei"`
	IncreaseGwei uint64 `json:"increase_gwei"`
	SubsidyGwei  uint64 `json:"subsidy_gwei"`

	// ValueGwei, when set, is the absolute bid base value replacing the
	// max(blockValue, min) + subsidy formula (IncreaseGwei still applies).
	ValueGwei *uint64 `json:"value_gwei,omitempty"`

	// IgnoreMissingPrefs bids without gossip proposer preferences.
	IgnoreMissingPrefs bool `json:"ignore_missing_prefs,omitempty"`

	// BidCandidate is the effective bid candidate selection for the slot:
	// auto, all, or a specific candidate key.
	BidCandidate string `json:"bid_candidate,omitempty"`

	// KeyStrategy is the effective builder key selection strategy for the
	// slot's bids.
	KeyStrategy string `json:"key_strategy,omitempty"`

	// BidKeysPerSlot caps how many distinct builder keys bid the slot
	// (0 = no cap beyond the fleet).
	BidKeysPerSlot uint64 `json:"bid_keys_per_slot,omitempty"`

	// BidKeysPerStep is how many keys bid a payload per interval step
	// (0 = every remaining key at once).
	BidKeysPerStep uint64 `json:"bid_keys_per_step,omitempty"`

	// Forced marks that the plan activated bidding although the module is
	// globally disabled.
	Forced bool `json:"forced,omitempty"`
}

type ResolvedBuildSettings struct {
	// Build is the final decision: build a payload for this slot or not.
	Build bool `json:"build"`

	// Forced marks builds the plan pushed past the schedule (they never
	// consume the next_n budget).
	Forced bool `json:"forced,omitempty"`

	// SkipReason is one of the BuildSkipReason* constants when Build is
	// false, empty otherwise.
	SkipReason string `json:"skip_reason,omitempty"`

	// PlanInvolved marks decisions where a per-slot plan existed or any
	// consumer was effectively active — i.e. skips worth surfacing.
	PlanInvolved bool `json:"plan_involved,omitempty"`

	// BuildStartTimeMs is the effective build start time, milliseconds
	// relative to slot start (signed).
	BuildStartTimeMs int64 `json:"build_start_time_ms"`

	// ReorgParentPayload builds the slot's payload on the grandparent (n-2)
	// execution payload instead of the immediate parent — a deliberate
	// parent-payload reorg attempt (see BuildPlan.ReorgParentPayload).
	ReorgParentPayload bool `json:"reorg_parent_payload,omitempty"`

	// CandidateModes is the effective build-candidate policy for the slot:
	// candidate key -> auto/always/never, merged from the global config and
	// the plan's build.candidates overrides.
	CandidateModes map[string]string `json:"candidate_modes,omitempty"`
}

type ResolvedBuilderAPISettings struct {
	SubsidyGwei uint64 `json:"subsidy_gwei"`

	// TotalValueGwei, when set, is the absolute total proposer-visible bid
	// value (before the Gloas execution-payment split).
	TotalValueGwei *uint64 `json:"total_value_gwei,omitempty"`

	DelayMs int64 `json:"delay_ms,omitempty"`

	// ServeCandidates is the effective serve-candidates policy for the slot
	// (all, canonical_only, or a comma-separated candidate key list).
	ServeCandidates string `json:"serve_candidates,omitempty"`

	// KeyStrategy is the effective builder key selection strategy for the
	// slot's served bids.
	KeyStrategy string `json:"key_strategy,omitempty"`

	// Forced marks that the plan activated serving although the module is
	// globally disabled.
	Forced bool `json:"forced,omitempty"`
}

type ResolvedRevealSettings struct {
	Suppressed   bool  `json:"suppressed,omitempty"`
	RevealTimeMs int64 `json:"reveal_time_ms"`

	// GateMode decides the reveal moment: time | vote | vote_or_time |
	// vote_and_time.
	GateMode string `json:"gate_mode"`

	// VoteThresholdPct is the participation threshold (percent) opening the
	// vote gate.
	VoteThresholdPct uint64 `json:"vote_threshold_pct"`

	// BroadcastValidation is the envelope submission's broadcast_validation
	// level: gossip | consensus | consensus_and_equivocation.
	BroadcastValidation string `json:"broadcast_validation"`

	// MaxAttempts / RetryIntervalMs are the publish retry policy
	// (global-only, no per-slot override).
	MaxAttempts     uint64 `json:"max_attempts"`
	RetryIntervalMs int64  `json:"retry_interval_ms"`

	// BypassDeadline disables the "past the in-slot deadline → skip" check so
	// deliberately late reveals are attempted.
	BypassDeadline bool `json:"bypass_deadline,omitempty"`
}

type ResolvedTransforms struct {
	Payload  string `json:"payload,omitempty"`
	Bid      string `json:"bid,omitempty"`
	Envelope string `json:"envelope,omitempty"`
}

type RevealPlan struct {
	Mode Mode `json:"mode"`

	// RevealTimeMs is signed milliseconds relative to slot start (time gate).
	RevealTimeMs *int64 `json:"reveal_time_ms,omitempty"`

	// GateMode overrides the reveal gate: time | vote | vote_or_time |
	// vote_and_time.
	GateMode *string `json:"gate_mode,omitempty"`

	// VoteThresholdPct overrides the vote gate's participation threshold.
	VoteThresholdPct *uint64 `json:"vote_threshold_pct,omitempty"`

	// BroadcastValidation overrides the envelope submission's broadcast
	// validation level: gossip | consensus | consensus_and_equivocation.
	BroadcastValidation *string `json:"broadcast_validation,omitempty"`
}

type RuleChangeEvent struct {
	Rules []*SlotRule `json:"rules"`
}

type RuleCodec struct{}

type SlotPlan struct {
	Slot       phase0.Slot     `json:"slot"`
	Bid        *BidPlan        `json:"bid,omitempty"`
	BuilderAPI *BuilderAPIPlan `json:"builder_api,omitempty"`
	Reveal     *RevealPlan     `json:"reveal,omitempty"`
	Build      *BuildPlan      `json:"build,omitempty"`
	Transforms *TransformPlan  `json:"transforms,omitempty"`

	// IgnoreRules opts the slot out of every recurring rule, so it runs on the
	// plain global baseline. Without it an empty plan is dropped, which would
	// hand the slot straight back to the matching rule.
	IgnoreRules bool `json:"ignore_rules,omitempty"`

	// RuleID marks a plan synthesized from a recurring rule. Synthesized plans
	// are never stored — the field is empty on every persisted plan.
	RuleID string `json:"rule_id,omitempty"`

	UpdatedAt time.Time `json:"updated_at"`
	UpdatedBy string    `json:"updated_by"`
}

type SlotRule struct {
	ID          string `json:"id"`
	Enabled     bool   `json:"enabled"`
	Description string `json:"description,omitempty"`

	// SlotsInEpoch are the matched slot indices within an epoch (0-based, so
	// 31 is the last slot of a 32-slot epoch).
	SlotsInEpoch []uint64 `json:"slots_in_epoch"`

	// FromEpoch / ToEpoch bound the rule to an inclusive epoch window; nil is
	// unbounded on that side.
	FromEpoch *uint64 `json:"from_epoch,omitempty"`
	ToEpoch   *uint64 `json:"to_epoch,omitempty"`

	Bid        *BidPlan        `json:"bid,omitempty"`
	BuilderAPI *BuilderAPIPlan `json:"builder_api,omitempty"`
	Reveal     *RevealPlan     `json:"reveal,omitempty"`
	Build      *BuildPlan      `json:"build,omitempty"`
	Transforms *TransformPlan  `json:"transforms,omitempty"`

	UpdatedAt time.Time `json:"updated_at"`
	UpdatedBy string    `json:"updated_by"`
}

type TransformPlan struct {
	Payload  string `json:"payload,omitempty"`
	Bid      string `json:"bid,omitempty"`
	Envelope string `json:"envelope,omitempty"`
}