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 CandidateKey string

type CandidateParent struct {
	Key             CandidateKey
	ParentBlockRoot phase0.Root
	ParentSlot      phase0.Slot
	ParentBlockHash phase0.Hash32
	// ELParentGasLimit is the gas limit of the execution block identified by
	// ParentBlockHash (0 = unknown). Committed gas limits come from the bid
	// (Gloas) or the embedded payload (pre-Gloas).
	ELParentGasLimit uint64
	// ELParentNumber is the block number of the execution block identified by
	// ParentBlockHash (0 = unknown; Gloas blocks require the revealed
	// envelope to learn it).
	ELParentNumber uint64
	// ParentPayloadStatus is the reveal status of the beacon parent block's
	// own committed payload. Full candidates are only viable when it is (or
	// becomes) revealed; empty candidates when it stays withheld.
	ParentPayloadStatus PayloadStatus
}

type ChainSpec struct {
	// SecondsPerSlot is the slot duration, taken from SLOT_DURATION_MS when the
	// beacon node serves it (EIP-7782 networks keep serving a stale
	// SECONDS_PER_SLOT preset default alongside it) and from SECONDS_PER_SLOT
	// otherwise.
	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
	MaxWithdrawalsPerPayload            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
	// PAYLOAD_DUE_BPS: the builder payload reveal deadline as basis points of
	// the slot duration (Gloas). A block whose payload has not been seen by
	// this offset is treated as empty by payload timeliness voting.
	PayloadDueBps 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 HeadChangeEvent struct {
	Old            *beacon.BlockInfo // nil on the first observed head
	New            *beacon.BlockInfo
	ReorgDepth     uint64
	CommonAncestor phase0.Root
}

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

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

type HeadVoteUpdate struct {
	Slot             phase0.Slot
	BlockRoot        phase0.Root
	ParticipationPct float64
	ParticipationETH uint64
	TotalSlotETH     uint64
	VoteCount        int
	TotalMembers     int
	ThresholdPct     float64 // effective threshold at fire time (0 = disabled)
	ThresholdMet     bool
	Timestamp        int64
}

type PayloadStatus string

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

	// Canonical head / ancestry / payload-status view
	GetHeadTracker() *HeadTracker

	// 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
}

type SubnetCoverage struct {
	Slots     int     // measured blocks in the window
	Attesters int     // total attesters counted across the window
	SeenPct   float64 // percent of those attesters seen as singles beforehand
	Low       bool    // sustained miss above coverageMissThreshold
}

type VoteAttester struct {
	Index    phase0.ValidatorIndex
	SeenAtMs int32 // ms offset from slot start; -1 = never seen as a raw single
	InBlock  bool  // attested on chain per the next-block ground truth
}

type VoteDetail struct {
	Slot         phase0.Slot
	BlockRoot    phase0.Root
	TotalMembers int
	Attesters    []VoteAttester
}