feat(api): integrate EC finality calculator into v2 API and Eth RPC

[rvagg]

Builds on #12093 but integrates FRC-0089 much deeper.

• Moves calculator into lotus-proper and adds a caching module for it that'll only recalculate once every head change, max.
• Adds the probabilistic EC finality calculator alongside F3 for determining finalized/safe tipsets.
• Introduces ChainGetTipSetFinalityStatus v2 endpoint.
• Wires the calculator into both v2 and Eth tag resolution, and disables the calculator by default in itests; **i.e. "finalized" will now essentially be min(f3, ec-calculator), we should almost never see 900.
• Adds a new doc that explains Filecoin's notion of "finality": documentation/en/finality.md.

In practice, this means that asking for "finalized" or querying Lotus what it thinks the finalized epoch is, will give you ~4-10 epochs when F3 is behaving and ~20-30 epochs when F3 is misbehaving. Only when the chain is degraded (measured by historical blocks count per tipset) does that number increase. This matches the probabilistic assumptions that went into deriving the 900 epoch figure we use, it's just that 900 is based on absolute worst-case chain conditions, but with the calculator we can measure actual chain conditions and adjust accordingly.

[Copilot]

Pull request overview

Integrates the FRC-0089 probabilistic EC finality calculator into Lotus “v2” chain APIs and Ethereum JSON-RPC tag resolution, and adds a new v2 endpoint to introspect finality inputs/decisions.

Changes:

• Adds chain/ecfinality (calculator + per-head caching) and wires it into Chain v2 + Eth tipset resolution (finalized/safe now consider EC calculator alongside F3).
• Introduces ChainGetTipSetFinalityStatus (v2) and propagates it through gateway/proxy, OpenRPC, mocks, and docs.
• Updates itests and lotus-shed tooling/docs to reflect and validate the new finality behavior.

Reviewed changes

Copilot reviewed 24 out of 24 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
node/modules/eth.go	Passes EC finality provider into the Eth tipset resolver via fx wiring.
node/impl/full/chain_v2.go	Adds ChainGetTipSetFinalityStatus and updates finalized/safe tag logic to incorporate EC calculator + F3.
node/impl/eth/tipsetresolver.go	Extends resolver to accept an EC finality provider and incorporate it into finalized/safe decisions.
node/builder_chain.go	Provides and wires ecfinality.Provider and maps it into the Eth resolver interface.
itests/kit/node_opts.go	Disables EC finality calculator by default in itests; provides override hooks.
itests/kit/ec_finality.go	Adds a mock EC finality provider usable by both Chain v2 and Eth resolver paths.
itests/eth_api_f3_test.go	Adds coverage for finalized/safe tags when EC calculator and F3 disagree/fail.
itests/api_v2_test.go	Adds coverage for finalized/safe tags and the new ChainGetTipSetFinalityStatus RPC method.
gateway/proxy_v2.go	Proxies the new v2 finality-status endpoint with rate limiting.
documentation/en/finality.md	New user-facing explanation of Filecoin finality and how Lotus resolves finalized/safe.
documentation/en/api-methods-v2-experimental.md	Documents the new experimental ChainGetTipSetFinalityStatus method.
cmd/lotus-shed/finality.go	Switches lotus-shed command to use the new ecfinality package implementation.
chain/types/finality.go	Introduces types.FinalityStatus response type.
chain/ecfinality/calculator_test.go	Moves/updates tests to validate calculator output and threshold search.
chain/ecfinality/calculator.go	New Go implementation of FRC-0089 probability + threshold search.
chain/ecfinality/cache.go	New cache that recomputes EC finality at most once per head change.
build/openrpc/v2/gateway.json	OpenRPC regeneration to include the new method/type.
build/openrpc/v2/full.json	OpenRPC regeneration to include the new method/type.
api/v2api/v2mocks/mock_full.go	Adds mock method for ChainGetTipSetFinalityStatus.
api/v2api/proxy_gen.go	Adds proxy/stub wiring for the new v2 method.
api/v2api/gateway.go	Extends v2 Gateway interface with the new method.
api/v2api/full.go	Extends v2 FullNode interface with the new method and docs.
api/docgen/docgen.go	Adds docgen example for types.FinalityStatus.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[ZenGround0]

Im ignorant about this part of the system these days but this PR looks pretty nice. No obvious issues.