v1.33.0

The Lotus v1.33.0 release introduces experimental v2 APIs with F3 awareness, featuring a new TipSet selection mechanism that significantly enhances how applications interact with the Filecoin blockchain. This release candidate also adds F3-aware Ethereum APIs via the /v2 endpoint. All of the /v2 APIs implement intelligent fallback mechanisms between F3 and Expected Consensus and are exposed through the Lotus Gateway.

Please review the detailed documentation for these experimental APIs, as they are subject to change and have important operational considerations for node operators and API providers.

☢️ Upgrade Warnings ☢️

• There are no upgrade warnings for this release candidate.

⭐ Feature/Improvement Highlights:

Experimental v2 APIs with F3 awareness

The Lotus V2 APIs introduce a powerful new TipSet selection mechanism that significantly enhances how applications interact with the Filecoin blockchain. The design reduces API footprint, seamlessly handles both traditional Expected Consensus (EC) and the new F3 protocol, and provides graceful fallbacks.

Note

V2 APIs are highly experimental and subject to change without notice.

See Filecoin v2 APIs docs for an in-depth overview. /v2 APIs are exosed through Lotus Gateway.

This work was primarily done in (filecoin-project/lotus#13003), (filecoin-project/lotus#13027), (filecoin-project/lotus#13034), (filecoin-project/lotus#13075), (filecoin-project/lotus#13066)

F3-aware Ethereum APIs via /v2 endpoint and improvements to existing /v1 APIs

Lotus now offers two versions of its Ethereum-compatible APIs (eth_*, trace_*, net_*, web3_* and associated Filecoin.* APIs including Filecoin-specific functions such as Filecoin.EthAddressToFilecoinAddress and Filecoin.FilecoinAddressToEthAddress) with different finality handling:

• /v2 APIs (New & Experimental): These APIs consult the F3 subsystem (if enabled) for finality information.
  • "finalized" tag maps to the F3 finalized epoch.
  • "safe" tag maps to the F3 finalized epoch or 200 epochs behind head, whichever is more recent.
• /v1 APIs (Existing & Recommended): These maintain behavior closer to pre-F3 Lotus (EC finality) for compatibility.
  • "finalized" tag continues to use a fixed 900-epoch delay from the head (EC finality).
  • "safe" tag uses a 30-epoch delay from the head.
  • One or both of these tags may be adjusted in a future upgrade to take advantage of F3 finality.
• Note: Previously, "finalized" and "safe" tags referred to epochs N-1. This -1 offset has been removed in both V1 and V2.
• Additional improvements affecting both /v1 and /v2 Ethereum APIs:
  • eth_getBlockTransactionCountByNumber now accepts standard Ethereum block specifiers (hex numbers or tags like "latest", "safe", "finalized").
  • Methods accepting BlockNumberOrHash now support all standard tags ("pending", "latest", "safe", "finalized"). This includes eth_estimateGas, eth_call, eth_getCode, eth_getStorageAt, eth_getBalance, eth_getTransactionCount, and eth_getBlockReceipts.
  • Removed internal Eth*Limited methods (e.g., EthGetTransactionByHashLimited) from the supported gateway API surface.
  • Improved error handling: block selection endpoints now consistently return ErrNullRound (and corresponding JSONRPC errors) for null tipsets.

This work was done in (filecoin-project/lotus#13026), (filecoin-project/lotus#13070).

Others

• feat: add gas to application metric reporting vm/applyblocks_early_gas, vm/applyblocks_messages_gas, vm/applyblocks_cron_gas (filecoin-project/lotus#13030)
• feat(metrics): capture total gas metric from ApplyBlocks (filecoin-project/lotus#13037)
• feat: add F3 Grafana Dashboard Template (filecoin-project/lotus#12934)
• fix(f3): limit the concurrency of F3 power table calculation (filecoin-project/lotus#13085)
• feat(f3): remove dynnamic manifest functionality and use static manifest (filecoin-project/lotus#13074)

🐛 Bug Fix Highlights

• fix(eth): apply limit in EthGetBlockReceiptsLimited (filecoin-project/lotus#12883)
• fix(eth): always return nil for eth transactions not found (filecoin-project/lotus#12999)
• fix(deps): fix Ledger hardware wallet support (filecoin-project/lotus#13048)

📝 Changelog

For the full set of changes since the last stable release:

• Node: release/v1.32.3...release/v1.33.0

👨‍👩‍👧‍👦 Contributors

Contributors

Contributor	Commits	Lines ±	Files Changed
Rod Vagg	19	+13805/-3639	129
Masih H. Derkani	19	+11910/-2369	119
Jakub Sztandera	14	+2528/-202	32
Phi-rjan	12	+1707/-79	42
Steve Loeppky	3	+1287/-32	8
Piotr Galar	2	+298/-3	4
Barbara Peric	3	+182/-73	5
ZenGround0	1	+191/-0	4
CoolCu	1	+15/-49	6
Volker Mische	1	+18/-31	5
Phi	3	+32/-14	10
dependabot[bot]	1	+15/-15	2
Amit Gaikwad	1	+19/-2	2
tom	1	+0/-14	2
xixishidibei	1	+2/-11	1
Tomass	1	+4/-4	2
tsinghuacoder	1	+3/-2	1
dropbigfish	1	+1/-1	1
James Niken	1	+1/-1	1
Hubert	1	+1/-0	1
Steven Allen	1	+0/-0	2