heads

type Broadcaster[H chains.Head[BLOCK_HASH], BLOCK_HASH chains.Hashable] interface {
	services.Service
	BroadcastNewLongestChain(H)
	Subscribe(callback Trackable[H, BLOCK_HASH]) (currentLongestChain H, unsubscribe func())
}

type ChainConfig interface {
	BlockEmissionIdleWarningThreshold() time.Duration
	FinalityDepth() uint32
	SafeDepth() uint32
	FinalityTagEnabled() bool
	SafeTagSupported() bool
	FinalizedBlockOffset() uint32
}

type Client[H chains.Head[BLOCK_HASH], S chains.Subscription, ID chains.ID, BLOCK_HASH chains.Hashable] interface {
	HeadByNumber(ctx context.Context, number *big.Int) (head H, err error)
	HeadByHash(ctx context.Context, hash BLOCK_HASH) (head H, err error)
	// ConfiguredChainID returns the chain ID that the node is configured to connect to
	ConfiguredChainID() (id ID)
	// SubscribeToHeads is the method in which the client receives new Head.
	// It can be implemented differently for each chain i.e websocket, polling, etc
	SubscribeToHeads(ctx context.Context) (<-chan H, S, error)
	// LatestSafeBlock - returns the latest block that was marked as safe
	LatestSafeBlock(ctx context.Context) (safe H, err error)
	// LatestFinalizedBlock - returns the latest block that was marked as finalized
	LatestFinalizedBlock(ctx context.Context) (head H, err error)
}

type FinalizedMissingError[BLOCK_HASH chains.Hashable] struct {
	Finalized, Canonical BLOCK_HASH
}

type Handler[H chains.Head[BLOCK_HASH], BLOCK_HASH chains.Hashable] func(ctx context.Context, header H) error

type Head[BLOCK_HASH chains.Hashable, CHAIN_ID chains.ID] interface {
	chains.Head[BLOCK_HASH]
	// ChainID returns the chain ID of the head.
	ChainID() CHAIN_ID
	// HasChainID returns true if the head has a chain ID.
	HasChainID() bool
	// IsValid returns true if the head is valid.
	IsValid() bool
}

type Listener[H chains.Head[BLOCK_HASH], BLOCK_HASH chains.Hashable] interface {
	services.Service

	// ListenForNewHeads runs the listen loop (not thread safe)
	ListenForNewHeads(ctx context.Context)

	// ReceivingHeads returns true if the listener is receiving heads (thread safe)
	ReceivingHeads() bool

	// Connected returns true if the listener is connected (thread safe)
	Connected() bool

	// HealthReport returns report of errors within Listener
	HealthReport() map[string]error
}

type ListenerConfig interface {
	BlockEmissionIdleWarningThreshold() time.Duration
}

type Saver[H chains.Head[BLOCK_HASH], BLOCK_HASH chains.Hashable] interface {
	// Save updates the latest block number, if indeed the latest, and persists
	// this number in case of reboot.
	Save(ctx context.Context, head H) error
	// Load loads latest heads up to latestFinalized - historyDepth, returns the latest chain.
	Load(ctx context.Context, latestFinalized int64) (H, error)
	// LatestChain returns the block header with the highest number that has been seen, or nil.
	LatestChain() H
	// Chain returns a head for the specified hash, or nil.
	Chain(hash BLOCK_HASH) H
	// MarkFinalized - marks matching block and all it's direct ancestors as finalized
	MarkFinalized(ctx context.Context, latestFinalized H) error
}

type Trackable[H chains.Head[BLOCK_HASH], BLOCK_HASH chains.Hashable] interface {
	// OnNewLongestChain sends a new head when it becomes available. Subscribers can recursively trace the parent
	// of the head to the finalized block back.
	OnNewLongestChain(ctx context.Context, head H)
}

type Tracker[H chains.Head[BLOCK_HASH], BLOCK_HASH chains.Hashable] interface {
	services.Service
	// Backfill given a head will fill in any missing heads up to latestFinalized
	Backfill(ctx context.Context, headWithChain H, prevHeadWithChain H) (err error)
	LatestChain() H
	// LatestSafeBlock returns the latest block that is considered safe to use.
	LatestSafeBlock(ctx context.Context) (safe H, err error)
	// LatestAndFinalizedBlock - returns latest and latest finalized blocks.
	// NOTE: Returns latest finalized block as is, ignoring the FinalityTagBypass feature flag.
	LatestAndFinalizedBlock(ctx context.Context) (latest, finalized H, err error)
}

type TrackerConfig interface {
	HistoryDepth() uint32
	MaxBufferSize() uint32
	SamplingInterval() time.Duration
	FinalityTagBypass() bool
	MaxAllowedFinalityDepth() uint32
	PersistenceEnabled() bool
	PersistenceBatchSize() int64
}