Skip to content

feat(eth): use F3 for "finalized" and "safe" resolution in v1 APIs #13298

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
BigLep merged 1 commit into from
Sep 4, 2025
Merged

feat(eth): use F3 for "finalized" and "safe" resolution in v1 APIs #13298

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@
- snapshot export now defaults to v2 format with embedded F3 finality certificates, dramatically reducing F3 catchup time from ~8 hours
- transparently imports both v1 and v2 snapshot formats
- to export v1 snapshots, use `lotus chain export --skip-old-msgs --recent-stateroots=2001 --snapshot-version=1 <filename>`

- feat(eth): use F3 for "finalized" and "safe" resolution in v1 APIs. This switches the /v1 Ethereum APIs to have the same resolution rules as /v2, enabling F3 awareness for all Ethereum calls where `"finalized"` or `"safe"` is supplied. See [F3-aware Ethereum APIs via `/v2` endpoint and improvements to existing `/v1` APIs](#f3-aware-ethereum-apis-via-v2-endpoint-and-improvements-to-existing-v1-apis) below for details of how the /v2 APIs work as introduced in the 1.33.0 release. Set the environment variable `LOTUS_ETH_V1_DISABLE_F3_FINALITY_RESOLUTION` to `1` to revert this behaviour but note that the option to revert will likely be removed in a future release. ([filecoin-project/lotus#13298](https://github.com/filecoin-project/lotus/pull/13298))

# Node v1.33.1 / 2025-07-31
This is the Lotus v1.33.1 release, which introduces performance improvements and operational enhancements. This release focuses on improving F3 subsystem performance, and enhancing CLI tools for better storage provider operations. Notable improvements include up to 6-10x performance gains in F3 power table calculations, ensuring that PreCommit and ProveCommit operations are aggregating to get optimal gas usage after FIP-100, and a enhanced sector management tool with CSV output support. These improvements collectively enhance the stability and efficiency of Lotus operations for both node operators and storage providers.
Expand Down
30 changes: 15 additions & 15 deletions itests/eth_api_f3_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -142,7 +142,7 @@ func TestEthAPIWithF3(t *testing.T) {
}
}
ecFinalized = ecFixedLookback(policy.ChainFinality)
ecSafeV1 = ecFixedLookback(30)
ecSafeV1 = ecFixedLookback(200)
ecSafeV2 = ecFixedLookback(200)
tipSetAtHeight = func(height abi.ChainEpoch) func(t *testing.T) *types.TipSet {
return func(t *testing.T) *types.TipSet {
Expand Down Expand Up @@ -218,7 +218,7 @@ func TestEthAPIWithF3(t *testing.T) {
mockF3.LatestCertErr = nil
mockF3.LatestCert = plausibleCertAt(t, f3FinalizedEpoch)
},
wantTipSetV1: ecFinalized,
wantTipSetV1: f3Finalized,
wantTipSetV2: f3Finalized,
},
{
Expand All @@ -230,7 +230,7 @@ func TestEthAPIWithF3(t *testing.T) {
mockF3.LatestCertErr = nil
mockF3.LatestCert = plausibleCertAt(t, targetHeight)
},
wantTipSetV1: ecSafeV1,
wantTipSetV1: tipSetAtHeight(targetHeight),
wantTipSetV2: tipSetAtHeight(targetHeight),
},
{
Expand Down Expand Up @@ -303,8 +303,8 @@ func TestEthAPIWithF3(t *testing.T) {
mockF3.LatestCert = nil
mockF3.LatestCertErr = internalF3Error
},
wantTipSetV1: ecFinalized,
wantErrV2: internalF3Error.Error(),
wantErrV1: internalF3Error.Error(),
wantErrV2: internalF3Error.Error(),
},
{
name: "safe tag when f3 fails, but f3 is not activated",
Expand All @@ -315,8 +315,8 @@ func TestEthAPIWithF3(t *testing.T) {
mockF3.LatestCert = nil
mockF3.LatestCertErr = internalF3Error
},
wantTipSetV1: ecSafeV1,
wantErrV2: internalF3Error.Error(),
wantErrV1: internalF3Error.Error(),
wantErrV2: internalF3Error.Error(),
},
{
name: "safe tag when f3 fails",
Expand All @@ -327,8 +327,8 @@ func TestEthAPIWithF3(t *testing.T) {
mockF3.LatestCert = nil
mockF3.LatestCertErr = internalF3Error
},
wantTipSetV1: ecSafeV1,
wantErrV2: internalF3Error.Error(),
wantErrV1: internalF3Error.Error(),
wantErrV2: internalF3Error.Error(),
},
{
name: "finalize tag when f3 is too far behind falls back to ec",
Expand Down Expand Up @@ -363,8 +363,8 @@ func TestEthAPIWithF3(t *testing.T) {
mockF3.LatestCert = implausibleCert
mockF3.LatestCertErr = nil
},
wantTipSetV1: ecFinalized,
wantErrV2: "decoding latest f3 cert tipset key",
wantErrV1: "decoding latest f3 cert tipset key",
wantErrV2: "decoding latest f3 cert tipset key",
},
{
name: "safe tag when f3 is broken, but f3 is not activated",
Expand All @@ -375,8 +375,8 @@ func TestEthAPIWithF3(t *testing.T) {
mockF3.LatestCert = implausibleCert
mockF3.LatestCertErr = nil
},
wantTipSetV1: ecSafeV1,
wantErrV2: "decoding latest f3 cert tipset key",
wantErrV1: "decoding latest f3 cert tipset key",
wantErrV2: "decoding latest f3 cert tipset key",
},
{
name: "safe tag when f3 is broken",
Expand All @@ -387,8 +387,8 @@ func TestEthAPIWithF3(t *testing.T) {
mockF3.LatestCert = implausibleCert
mockF3.LatestCertErr = nil
},
wantTipSetV1: ecSafeV1,
wantErrV2: "decoding latest f3 cert tipset key",
wantErrV1: "decoding latest f3 cert tipset key",
wantErrV2: "decoding latest f3 cert tipset key",
},
{
name: "height before ec finalized epoch is ok",
Expand Down
2 changes: 1 addition & 1 deletion itests/eth_api_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -410,7 +410,7 @@ func TestEthBlockNumberAliases(t *testing.T) {
expectedLag abi.ChainEpoch
}{
{"latest", 1}, // head - 1
{"safe", 30}, // "latest" - 30
{"safe", 200}, // "latest" - 200 when F3 isn't running
{"finalized", policy.ChainFinality}, // "latest" - 900
} {
t.Run(tc.param, func(t *testing.T) {
Expand Down
14 changes: 13 additions & 1 deletion node/modules/eth.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ package modules

import (
"context"
"os"
"time"

"go.uber.org/fx"
Expand Down Expand Up @@ -32,7 +33,18 @@ type TipSetResolverParams struct {
}

func MakeV1TipSetResolver(params TipSetResolverParams) full.EthTipSetResolverV2 {
return eth.NewTipSetResolver(params.ChainStore, nil, false)
// TODO: remove this env var in a future release and remove all special-casing for Eth v1 in
// builder_chain.go with a single path to instantiating Eth modules and re-using them for
// both v1 and v2 APIs.
// The env var is only intended as a temporary escape hatch for users who encounter issues
// with F3 certificate–based finality resolution in Eth APIs.
f3CertificateProvider := params.F3
useF3ForFinality := true
if os.Getenv("LOTUS_ETH_V1_DISABLE_F3_FINALITY_RESOLUTION") == "1" {
Comment thread
rvagg marked this conversation as resolved.
f3CertificateProvider = nil
useF3ForFinality = false
}
return eth.NewTipSetResolver(params.ChainStore, f3CertificateProvider, useF3ForFinality)
}

func MakeV2TipSetResolver(params TipSetResolverParams) full.EthTipSetResolverV2 {
Expand Down