store

type Options struct {
	// BeaconConfig is an optional DRAND verifier used at startup to
	// re-validate beacon entries on the most-recent N headers before
	// accepting the persisted head as current.
	BeaconConfig *beacon.Config
	// StartupVerifyDepth: how many recent headers to re-verify on Open.
	// 0 means "no verification" (e.g. unit tests).
	StartupVerifyDepth int
}

type RPCSource interface {
	// HeadEpoch returns the current chain head epoch.
	HeadEpoch(ctx context.Context) (abi.ChainEpoch, error)
	// TipsetCIDsByHeight returns the block CIDs that form the canonical
	// tipset at the given epoch.
	TipsetCIDsByHeight(ctx context.Context, h abi.ChainEpoch) ([]cid.Cid, error)
	// FetchBlock returns a single BlockHeader, CID-verified.
	FetchBlock(ctx context.Context, k cid.Cid) (*ltypes.BlockHeader, error)
}

type Stats struct {
	HeadEpoch abi.ChainEpoch
	OpenedAt  time.Time
}

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

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

type SyncOptions struct {
	// Interval between ChainHead polls. Default 6s.
	Interval time.Duration
	// MaxBacktrack caps how far back the agent walks on each poll
	// (defends against unbounded catch-up cost). Default 30.
	MaxBacktrack abi.ChainEpoch
	// BootstrapDepth is how many tipsets to ingest on the very first
	// poll when the store is empty. Defaults to MaxBacktrack. Operators
	// running against rate-limited public RPC providers (Glif) should
	// set this small (1–3) so startup is quick; subsequent polls catch
	// up incrementally.
	BootstrapDepth abi.ChainEpoch
	// CatchUpChunk caps how many epochs the warm-store catch-up advances
	// in a single poll. When the store falls behind by more than this,
	// each poll ingests a contiguous chunk of this size starting from
	// currentHead+1, so lag decreases monotonically without skipping
	// epochs (issue #33). 0 means "no cap" (advance straight to head).
	// Default 200 — large enough that normal operation (0–2 epochs
	// behind) is a single chunk, bounded enough that a deep backlog
	// against rate-limited RPC is paced over several polls.
	CatchUpChunk abi.ChainEpoch
	// GossipFresh, when set, reports whether an external head source
	// (the gossipsub block ingestor) has advanced the store's head
	// recently — i.e. within roughly the last poll Interval. When it
	// returns true the Sync skips its own RPCSource.HeadEpoch() poll for
	// that tick, because gossip is already supplying the live head with
	// no upstream-RPC dependency. The Sync then acts purely as a
	// catch-up fallback: it resumes polling the RPCSource only when
	// gossip goes quiet (stale store head). This is what keeps a node
	// with healthy gossipsub from hammering a rate-limited public RPC
	// (Glif 429) every Interval (#71). Nil disables the optimization
	// (the Sync polls every tick, the pre-#71 behavior).
	GossipFresh func() bool

	// GossipObservedHead, when set, reports the highest chain epoch the
	// gossip ingestor has observed/installed - i.e. the gossip layer's
	// view of the live tip (>= the canonical store head). It makes the
	// #71 GossipFresh skip LAG-AWARE (#83): GossipFresh alone only tells
	// us the head moved recently, not that it reached the tip. A node
	// whose gossip is fresh-but-lagging (installing some blocks while
	// skipping head+N>1 blocks it can't backfill) would otherwise have
	// Sync skip its catch-up poll forever, wedging the head ~10-20 epochs
	// behind the tip. With this set, Sync skips only when the store head
	// is within SkipLagTolerance of the observed tip; when further behind
	// it runs the catch-up poll regardless of GossipFresh. Returns a
	// negative epoch when no observation is available (treated as "can't
	// confirm we're at the tip" -> don't skip). Nil keeps the pre-#83
	// behavior (skip purely on GossipFresh).
	GossipObservedHead func() abi.ChainEpoch

	// SkipLagTolerance is how many epochs behind the gossip-observed tip
	// the store head may be and still skip the catch-up poll (#83). Only
	// consulted when GossipObservedHead is set. Default 2 (allows the
	// normal 0-1 epoch gossip latency without forcing an RPC poll).
	SkipLagTolerance abi.ChainEpoch

	// StaleResetThreshold is the lag (live head − store head, in epochs)
	// beyond which a warm store is considered hopelessly stale and is
	// re-bootstrapped near the live head instead of attempting a
	// contiguous backfill.
	//
	// This is the #51 "down for a week" fix. The contiguous catch-up
	// (issue #33) walks from currentHead+1 and relies on backfillParents
	// connecting each new tipset to the store's existing chain within
	// MaxBacktrack epochs. After a multi-day outage the gap is tens of
	// thousands of epochs — far beyond MaxBacktrack — so backfill never
	// connects, SetHead never fires, and the head pointer freezes at the
	// stale epoch (exactly the symptom reported 2026-06-18). Past this
	// threshold we stop trying to bridge the gap and re-anchor near live
	// head, the same way a cold start does. No keys, wallets, or other
	// secrets are touched — only rebuildable chain state.
	//
	// 0 disables the behaviour (pure contiguous catch-up, legacy).
	// Default 2880 (~1 day at 30s epochs): a node behind by more than a
	// day re-anchors instead of grinding.
	StaleResetThreshold abi.ChainEpoch
	// OnStaleReset, when set, is fired once when a stale warm store is
	// re-anchored, with (storeHead, liveHead). Used for logging/metrics.
	OnStaleReset func(storeHead, liveHead abi.ChainEpoch)
	// OnReorg is fired (after Store.SetHead) when the new head's parent
	// chain replaced canonical pointers at one or more epochs. The
	// argument is the divergence epoch (the deepest epoch whose
	// canonical pointer changed).
	OnReorg func(divergence abi.ChainEpoch)
}

type SyncStats struct {
	Polls              uint64
	SkippedGossipFresh uint64 // #71: ticks where the Glif poll was skipped because gossip was fresh
	HeadAdvances       uint64
	Reorgs             uint64
	StaleResets        uint64
	HeadersAdded       uint64
	LastError          string
	LastHeadEpoch      abi.ChainEpoch
}