feat(f3): expose simple ChainGetFinalizedTipSet that just returns a tipset #13299

rvagg · 2025-09-03T05:11:59Z

Alias for F3GetLatestCertificate -> ECChain.TipSets[-1] -> TipSet

As discussed with @BigLep here's what a user-focused F3 API in /v1 as opposed to the miner software or developer focused APIs and does away with the indirection complexity when trying to explain how to use F3 with /v2 APIs. An option on the table for us to consider in the range of possibilities for helping increase F3 adoption.

Edit: renamed and added EC fallback, see below.

BigLep

Conceptually this seems good/right to me. I didn't notice any logic issues, but this needs @Kubuxu sign off.

I assume it'll be a separate PR to make /v1 ETH APIs F3 aware.

We'll want a changelog entry for this. I am happy to create it 2025-09-03.

BigLep · 2025-09-03T05:21:29Z

I assume it'll be a separate PR to make /v1 ETH APIs F3 aware.

Doh, my bad. I see #13298

eshon · 2025-09-03T08:50:33Z

Can this just be called GetFinalizedTipset and if F3 is not running or behind it returns EC finality at 900?

Kubuxu

SGTM code wise, eshon's suggestion seems good as well

BigLep · 2025-09-03T16:26:14Z

Can this just be called GetFinalizedTipset and if F3 is not running or behind it returns EC finality at 900?

I am good with doing this instead. I can see reasons for it vs. the F3GetFinalizedTipset. No strong opinions here, but I would nudge towards GetFinalizedTipset given the intent to "just serve the user who wants to know a finalized tipset".

Note to self on followup actions I imagine taking after this and #13298 land:

Update https://www.notion.so/filecoindev/Exchange-and-RPC-providers-guide-to-F3-Fast-Finality-105dc41950c180c49175e4b3afcc5923
Update https://www.notion.so/filecoindev/Filecoin-V2-APIs-1d0dc41950c1808b914de5966d501658
Propose this as a new API to Common Node API https://github.com/filecoin-project/FIPs/blob/master/FRCs/frc-0104.md

Kubuxu · 2025-09-03T16:52:10Z

It is either F3GetFinalizedTipset or ChainGetFinalizedTipset the functionality difference is more important to me

BigLep · 2025-09-03T16:59:18Z

My understanding is there are two options:

What is currently implemented: F3GetFinalizedTipset which returns the latest finalized F3 tipset or if F3 is not running or has not finalized any rounds yet, an error is returned.
@eshon proposal: ChainGetFinalizedTipset which returns the latest finalized F3 tipset or if F3 is not running or behind more than 900 epochs it returns EC finality at head-900

What are you voting for @Kubuxu?

Kubuxu · 2025-09-03T19:18:54Z

Option two seems like better UX, but I don't have a strong opinion. If @eshon thinks that it will have better adoption, we should go for it unless there are implementation concerns.

BigLep · 2025-09-03T20:45:26Z

I'm good with option 2 as well. Are you @rvagg ?

rvagg · 2025-09-04T01:09:37Z

yep, option 2 it is, I like it, ChainGetFinalizedTipSet (capital S at the end there) and fall-back to 900. I'll make it so.

rvagg · 2025-09-04T03:54:06Z

Done, with comprehensive tests for the various states of F3 enablement or erroring. If there are any problems with F3, including it falling behind EC, then we revert to EC for finality, otherwise we return the F3 finalised tipset.

feat(f3): expose simple ChainGetFinalizedTipSet API on v1 (and gateway) that just returns the latest F3 finalized tipset, or falls back to EC finality if F3 is not operational on the node. This API can be used for follow-up state calls that clamp to a specific tipset to have assurance of state finality.

itests/f3_test.go

CHANGELOG.md

Copilot

Pull Request Overview

This PR introduces a new user-focused F3 API to simplify finality access by exposing ChainGetFinalizedTipSet in the v1 API. This method returns the latest F3 finalized tipset directly, eliminating the complexity of using F3GetLatestCertificate -> ECChain.TipSets[-1] pattern from v2 APIs. It falls back to Expected Consensus finality (head - 900 epochs) when F3 is not operational.

Key changes:

Adds ChainGetFinalizedTipSet method to v1 and gateway APIs
Implements fallback logic from F3 finality to EC finality
Includes comprehensive test coverage for various F3 states

Reviewed Changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
node/impl/full/chain.go	Core implementation of ChainGetFinalizedTipSet with F3 and EC fallback logic
node/impl/full/f3.go	Adds Chain dependency to F3API struct for finality operations
api/api_full.go	Adds ChainGetFinalizedTipSet method definition to FullNode interface
api/api_gateway.go	Adds ChainGetFinalizedTipSet method to Gateway interface
itests/f3_test.go	Comprehensive test suite covering F3 disabled, nominal, error, and fallback scenarios
itests/kit/stable.go	Helper utility for stable test execution across chain reorgs
gateway/proxy_fil_v1.go	Proxy implementation for ChainGetFinalizedTipSet in gateway

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

node/impl/full/chain.go

itests/f3_test.go

node/impl/full/chain.go

…ipset Alias for F3GetLatestCertificate -> ECChain.TipSets[-1] -> TipSet but with fall-back to EC when F3 is not properly functioning or is behind EC.

ribasushi · 2025-09-04T11:31:36Z

node/impl/full/chain.go

+	if ts := m.tryF3Finality(ctx, ecFinalityHeight); ts != nil {
+		return ts, nil
+	}


tryF3Finality should bubble up "hard" errors, so that the highlighted block of code can distinguish between "F3 is not running/behind" vs "node is under some novel type of attack, with invalid F3 or unexpectedly divergent F3/EC"

I disagree. This should continue working to reduce the impact on people who use it. 900 epochs is a totally valid fallback.

In cases of an attack on F3, this is a fallback we would recommend and use.

While typing this I see that the PR was merged. So my comments are likely moot. Nevertheless leaving them here for posterity.

@Kubuxu notionally you are totally correct - the exposed finality should match the "internal finality", that is whatever the chainsync algorithm would do. The problem is that holistically ChainGetFinalizedTipSet is not the only finality-aware API - there are literally hundreds of them. Given tryF3Finality is a newly written function, which does not seem a copy of something that already exists - the likelihood of divergence is high

The more in-depth thing to point out in review would be

This looks fishy, the decision path should be unified, not unlike the internal GetHeaviestTipSet. Then all of the ETH v1/2 and this new API call would reliably return the same thing

I did not say this earlier, because it is untenable to implement a cleanup pass in the short window FilOz committed themselves to. So the second best thing was the practical "have the API error instead of potentially diverging under uncharted circumstances"

rvagg requested review from Kubuxu and Copilot September 3, 2025 05:11

github-project-automation bot added this to F3 and FilOz Sep 3, 2025

github-project-automation bot moved this to Todo in F3 Sep 3, 2025

github-project-automation bot moved this to 📌 Triage in FilOz Sep 3, 2025

rvagg force-pushed the rvagg/F3GetFinalizedTipSet branch from 04591c5 to e9ce42b Compare September 3, 2025 05:12

This comment was marked as outdated.

Sign in to view

BigLep self-requested a review September 3, 2025 05:14

BigLep assigned rvagg Sep 3, 2025

BigLep reviewed Sep 3, 2025

View reviewed changes

rvagg force-pushed the rvagg/F3GetFinalizedTipSet branch from e9ce42b to 4522926 Compare September 3, 2025 05:31

Kubuxu reviewed Sep 3, 2025

View reviewed changes

BigLep mentioned this pull request Sep 1, 2025

Lotus Node and Miner v1.34.0 Release (nv27) #13269

Open

77 tasks

rvagg force-pushed the rvagg/F3GetFinalizedTipSet branch from 3c265a1 to a5278af Compare September 4, 2025 03:54

rvagg requested a review from Kubuxu September 4, 2025 03:54

BigLep reviewed Sep 4, 2025

View reviewed changes

itests/f3_test.go Show resolved Hide resolved

CHANGELOG.md Outdated Show resolved Hide resolved

BigLep approved these changes Sep 4, 2025

View reviewed changes

github-project-automation bot moved this from 📌 Triage to ✔️ Approved by reviewer in FilOz Sep 4, 2025

github-project-automation bot moved this from Todo to In review in F3 Sep 4, 2025

BigLep requested a review from Copilot September 4, 2025 04:50

Copilot AI reviewed Sep 4, 2025

View reviewed changes

node/impl/full/chain.go Show resolved Hide resolved

itests/f3_test.go Show resolved Hide resolved

node/impl/full/chain.go Show resolved Hide resolved

rvagg force-pushed the rvagg/F3GetFinalizedTipSet branch 3 times, most recently from d92d5f2 to 22cc545 Compare September 4, 2025 05:27

rvagg changed the title ~~feat(f3): expose simple F3GetFinalizedTipSet that just returns a tipset~~ feat(f3): expose simple ChainGetFinalizedTipSet that just returns a tipset Sep 4, 2025

feat(f3): expose simple ChainGetFinalizedTipSet that just returns a t…

ca89516

…ipset Alias for F3GetLatestCertificate -> ECChain.TipSets[-1] -> TipSet but with fall-back to EC when F3 is not properly functioning or is behind EC.

rvagg force-pushed the rvagg/F3GetFinalizedTipSet branch from 22cc545 to ca89516 Compare September 4, 2025 05:46

ribasushi reviewed Sep 4, 2025

View reviewed changes

Kubuxu approved these changes Sep 4, 2025

View reviewed changes

Merge branch 'master' into rvagg/F3GetFinalizedTipSet

cfdd3f3

BigLep enabled auto-merge (squash) September 4, 2025 14:35

BigLep merged commit bc06e19 into master Sep 4, 2025
97 checks passed

BigLep deleted the rvagg/F3GetFinalizedTipSet branch September 4, 2025 14:39

github-project-automation bot moved this from ✔️ Approved by reviewer to 🎉 Done in FilOz Sep 4, 2025

github-project-automation bot moved this from In review to Done in F3 Sep 4, 2025

BigLep mentioned this pull request Sep 4, 2025

build: release Lotus Node and Miner v1.34.0-rc1 #13314

Merged

8 tasks

feat(f3): expose simple ChainGetFinalizedTipSet that just returns a tipset #13299

feat(f3): expose simple ChainGetFinalizedTipSet that just returns a tipset #13299

Uh oh!

Conversation

rvagg commented Sep 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as outdated.

Uh oh!

BigLep left a comment

Choose a reason for hiding this comment

Uh oh!

BigLep commented Sep 3, 2025

Uh oh!

eshon commented Sep 3, 2025

Uh oh!

Kubuxu left a comment

Choose a reason for hiding this comment

Uh oh!

BigLep commented Sep 3, 2025

Uh oh!

Kubuxu commented Sep 3, 2025

Uh oh!

BigLep commented Sep 3, 2025

Uh oh!

Kubuxu commented Sep 3, 2025

Uh oh!

BigLep commented Sep 3, 2025

Uh oh!

rvagg commented Sep 4, 2025

Uh oh!

rvagg commented Sep 4, 2025

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ribasushi Sep 4, 2025

Choose a reason for hiding this comment

Uh oh!

Kubuxu Sep 4, 2025

Choose a reason for hiding this comment

Uh oh!

ribasushi Sep 4, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

rvagg commented Sep 3, 2025 •

edited

Loading