chain

type ActiveIndiceIndex uint32

type BlobScheduleEntry struct {
	Epoch            uint64
	MaxBlobsPerBlock uint64
}

type BuilderInfo struct {
	Index             uint64
	Pubkey            phase0.BLSPubKey
	Balance           uint64
	Active            bool
	DepositEpoch      uint64
	WithdrawableEpoch uint64
	PendingPayments   uint64 // Sum of pending payments from BuilderPendingPayments in state
}

type ChainSpec struct {
	SecondsPerSlot time.Duration
	SlotsPerEpoch  uint64

	// Duty calculation parameters
	ShuffleRoundCount          uint64
	TargetCommitteeSize        uint64
	MaxCommitteesPerSlot       uint64
	MaxEffectiveBalance        uint64
	MaxEffectiveBalanceElectra uint64
	EpochsPerHistoricalVector  uint64
	MinSeedLookahead           uint64

	// Pending-deposit processing parameters (Electra). Used to estimate how many
	// pending deposits drain per epoch when timing the pre-Gloas early onboarding
	// deposit (see pkg/lifecycle pending-deposit simulation).
	MinPerEpochChurnLimit               uint64
	ChurnLimitQuotient                  uint64
	MaxPerEpochActivationExitChurnLimit uint64
	MaxPendingDepositsPerEpoch          uint64
	MinActivationBalance                uint64
	EffectiveBalanceIncrement           uint64

	// Domain types
	DomainBeaconProposer      phase0.DomainType
	DomainBeaconAttester      phase0.DomainType
	DomainPtcAttester         phase0.DomainType
	DomainProposerPreferences phase0.DomainType

	// Fork epochs and versions (nil if not configured)
	ForkSchedule []ForkSchedule

	// Blob schedule (BPO - Blob Parameters Only)
	BlobSchedule []BlobScheduleEntry

	// ePBS parameters
	PtcSize uint64

	// Deposit contract
	DepositContractAddress *common.Address
}

type DutyState struct {
	RandaoMix           *phase0.Hash32
	NextRandaoMix       *phase0.Hash32
	GetRandaoMixes      func() []phase0.Root
	GetActiveCount      func() uint64
	GetEffectiveBalance func(index ActiveIndiceIndex) phase0.Gwei
}

type EpochStats struct {
	Version        version.DataVersion
	Epoch          phase0.Epoch
	FinalizedEpoch phase0.Epoch
	StateSlot      phase0.Slot

	// Validator data
	ActiveValidators  uint64
	ValidatorCount    uint64
	ActiveIndices     []phase0.ValidatorIndex
	EffectiveBalances []uint32 // Effective balance in full ETH units

	// Builder data (for lifecycle management, Gloas only).
	// Populated (possibly empty) for any Gloas+ state; nil for pre-Gloas epochs.
	Builders []*BuilderInfo

	// Total active effective balance (gwei). Used to estimate the activation-exit
	// churn limit for pending-deposit processing (early-onboarding timing).
	TotalActiveBalance uint64

	// Pending-deposit queue data (Electra+). Used to time the pre-Gloas early
	// onboarding deposit so it is still queued at the fork boundary.
	PendingDeposits           []PendingDepositInfo
	DepositBalanceToConsume   uint64 // gwei
	Eth1DepositIndex          uint64
	DepositRequestsStartIndex uint64

	// Pre-computed duties
	RandaoMix      phase0.Hash32
	NextRandaoMix  phase0.Hash32
	ProposerDuties []phase0.ValidatorIndex // [slot_index] -> validator index
	AttesterDuties [][][]ActiveIndiceIndex // [slot_index][committee_index][member] -> active indice index
	PtcDuties      [][]ActiveIndiceIndex   // [slot_index][ptc_member] -> active indice index (Gloas only)
}

type ForkSchedule struct {
	Fork    version.DataVersion
	Version phase0.Version
	Epoch   phase0.Epoch
}

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

type HeadVoteUpdate struct {
	Slot             phase0.Slot
	ParticipationPct float64
	ParticipationETH uint64
	TotalSlotETH     uint64
	Timestamp        int64
}

type PendingDepositInfo struct {
	Pubkey phase0.BLSPubKey
	Amount uint64 // gwei
	Slot   phase0.Slot
}

type Service interface {
	Start(ctx context.Context) error
	Stop() error

	// Chain state accessors
	GetChainSpec() *ChainSpec
	GetGenesis() *beacon.Genesis
	SlotToTime(slot phase0.Slot) time.Time
	TimeToSlot(t time.Time) phase0.Slot
	GetCurrentEpoch() phase0.Epoch
	GetCurrentSlot() phase0.Slot
	GetCurrentFork() version.DataVersion
	ActiveForkAtEpoch(epoch phase0.Epoch) version.DataVersion
	GetForkVersion() (phase0.Version, error)
	GetEpochOfSlot(slot phase0.Slot) phase0.Epoch

	// Epoch stats access
	GetCurrentEpochStats() *EpochStats
	GetEpochStats(epoch phase0.Epoch) *EpochStats

	// Subscriptions
	SubscribeEpochStats() *utils.Subscription[*EpochStats]

	// Head vote tracking
	GetHeadVoteTracker() *HeadVoteTracker

	// Finality
	GetFinalizedEpoch() phase0.Epoch

	// Builder access
	GetBuilderByIndex(index uint64) *BuilderInfo
	GetBuilderByPubkey(pubkey phase0.BLSPubKey) *BuilderInfo
	GetBuilders() []*BuilderInfo

	// Validator access
	GetValidatorPubkeyByIndex(index phase0.ValidatorIndex) *phase0.BLSPubKey

	// RefreshBuilders re-fetches the beacon state to pick up new builder registrations.
	RefreshBuilders(ctx context.Context) error

	// SetProposerPreferencesCache registers the proposer preferences cache so
	// it can be pruned on each epoch transition. Pass nil to disable pruning.
	SetProposerPreferencesCache(cache *proposerpreferences.Cache)
}