Documentation
¶
Overview ¶
Package selector resolves Lotus /rpc/v2 tipset-selector tags (latest, finalized, safe) against Lantern's chain state (issue #99).
The three tags carry Lotus semantics byte-for-byte:
- latest = heaviest tipset (current head).
- finalized = max(EC-finalized, F3-finalized). If F3 is unavailable or behind EC, falls back to EC finality (from the FRC-0089 calculator shipped in #96, else static head - ChainFinality).
- safe = finalized clamped to at least (head - SafeHeightDistance). If the tipset at safe-height is null, the first non-null parent is returned (behavior of TipSetByHeight with previous=true).
Lantern serves these more honestly than a gateway because "finalized" and "safe" both derive from cryptographically verified state: F3 certs (BLS aggregate over >= 2/3 of committee power) and observed EC finality on top of a header store that verifies every header's BLS block signature.
This package is deliberately a pure resolver: it does no I/O beyond the Resolver interface it takes. That keeps the /rpc/v2 mount trivially testable with a mock Resolver, and lets non-RPC callers (finality-aware message-search, retention pruning, …) reuse the same logic.
Index ¶
Constants ¶
const ( // SafeHeightDistance is head - safeHeight. Lotus mainnet value. SafeHeightDistance abi.ChainEpoch = 200 // ChainFinality is the static-fallback EC finality window used when the // FRC-0089 calculator is not yet at threshold. Lotus mainnet value. ChainFinality abi.ChainEpoch = 900 )
Filecoin network constants, mirrored from Lotus buildconstants. These are mainnet + calibration values; devnet uses the same distances (they are derived from ChainFinality/epoch-length ratios, not the per-network block-time).
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Resolver ¶
type Resolver interface {
// HeadTipSet returns the heaviest known tipset.
HeadTipSet(ctx context.Context) (*types.TipSet, error)
// ECFinalizedTipSet returns the FRC-0089 EC-finalized tipset. Returns
// (nil, nil) if the calculator has not yet reached threshold; the
// resolver then falls back to (head - ChainFinality).
ECFinalizedTipSet(ctx context.Context) (*types.TipSet, error)
// F3FinalizedTipSet returns the tipset finalized by the latest F3
// cert, or (nil, nil) if F3 is unavailable / not ready. A non-nil
// error is treated as unavailable (a healthy node must not fail-open
// on selector queries when F3 has a transient issue; Lotus does the
// same).
F3FinalizedTipSet(ctx context.Context) (*types.TipSet, error)
// TipSetByHeight returns the tipset at `height` reached by walking
// back from `from`. When the tipset at height is null and
// previous=true, returns the first non-null parent (matches Lotus's
// GetTipsetByHeight semantics with prev=true).
TipSetByHeight(ctx context.Context, height abi.ChainEpoch, from *types.TipSet, previous bool) (*types.TipSet, error)
}
Resolver is the state-lookup surface a tipset selector needs. Callers wiring /rpc/v2 typically satisfy this with an adapter over the chain api + ecfinality.Cache + f3 accessor. Tests use a mock.
Source Files