bootstrap

type Bucket struct {
	Finality Finality
	Sources  []string
}

type Finality struct {
	// Instance is the GPBFT instance that finalized this tipset. Lantern
	// requires it to be > 0 (the bootstrap manifest's initial instance
	// is 0 and we never accept that as a live-chain head).
	Instance uint64
	// TipSetKey is the block CIDs of the finalized tipset, in canonical
	// order (matches gpbft.TipSet.MarshalCBOR / Lotus tipset key form).
	TipSetKey []cid.Cid
	// StateRoot is the state root computed by applying the messages in
	// the finalized tipset. Light clients use this as the trust anchor
	// for state queries at and after the finalized epoch.
	StateRoot cid.Cid
	// Epoch is the chain epoch of the finalized tipset, if known.
	// Optional; used for human-readable display only. Quorum equality
	// does NOT depend on Epoch (because not every source can answer it
	// without extra round-trips).
	Epoch int64
}

type Kind string

type QuorumOptions struct {
	// Quorum is the minimum number of agreeing, counted sources required.
	// Default: 5. Required is enforced before any source is queried;
	// Quorum() returns ErrInsufficientSources if len(sources_counted) <
	// Quorum.
	Quorum int
	// Timeout is the total wall-clock budget. Default: 60s.
	Timeout time.Duration
	// CountGateway: if true, KindLanternGateway sources count toward
	// quorum. Default false; the Lantern gateway is used for fast block
	// fetch but is not part of the trust quorum unless the operator opts
	// in.
	CountGateway bool
	// Progress, if non-nil, is called once per source result as it
	// completes. Useful for live spinners / per-source ✓/✗ in init UX.
	Progress func(SourceResult)
}

type QuorumResult struct {
	// Reached is true iff at least Quorum sources agreed on the same
	// finality.
	Reached bool
	// Required is the quorum threshold that was asked for.
	Required int
	// Winning is the finality that reached quorum (zero-value if none).
	Winning Finality
	// Agreeing is the names of sources that agreed on Winning.
	Agreeing []string
	// Results is per-source detail (all sources, in completion order).
	Results []SourceResult
	// Counted is the number of sources whose answers were actually
	// tallied (i.e. counted=true and OK).
	Counted int
	// Buckets summarises the distinct finalities seen, by count.
	Buckets []Bucket
	// Elapsed is the wall-clock time the probe took.
	Elapsed time.Duration
}

type Source interface {
	// Name returns a short human-readable identifier for log/error output
	// (e.g. "libp2p-peer:12D3KooW...", "forest-archive", "user-peer:...").
	Name() string

	// Kind returns the source category for quorum policy decisions
	// (e.g. independent operators count, the project's own gateway does
	// not by default). See KindLibp2p / KindForest / KindLanternBeacon /
	// KindLanternGateway / KindUser.
	Kind() Kind

	// LatestFinality asks the source for its view of the most recent
	// F3-finalized result. Returns the GPBFT Instance, the tipset key
	// (block CIDs of the finalized tipset), and the state root after
	// applying that tipset.
	//
	// Implementations should respect ctx and return promptly on
	// cancellation. Network errors should be wrapped to be diagnosable.
	LatestFinality(ctx context.Context) (Finality, error)
}

type SourceResult struct {
	Name     string
	Kind     Kind
	Finality Finality
	Error    error
	Duration time.Duration
	// Counted is true if this source contributes to the quorum tally
	// (i.e. it's not a non-counted KindLanternGateway when CountGateway
	// is false).
	Counted bool
}