From ab7c8d0c92d0c6c9603f71e9a6963d378ba5e7f7 Mon Sep 17 00:00:00 2001 From: Phi Date: Thu, 1 May 2025 10:17:47 +0200 Subject: [PATCH 1/9] build: release Lotus Node v1.33.0-rc1 build: release Lotus Node v1.33.0-rc1 --- build/openrpc/full.json | 2 +- build/openrpc/gateway.json | 2 +- build/openrpc/miner.json | 2 +- build/openrpc/v2/full.json | 2 +- build/openrpc/v2/gateway.json | 2 +- build/openrpc/worker.json | 2 +- build/version.go | 2 +- documentation/en/cli-lotus.md | 2 +- 8 files changed, 8 insertions(+), 8 deletions(-) diff --git a/build/openrpc/full.json b/build/openrpc/full.json index 7babbfec07d..059cb58293b 100644 --- a/build/openrpc/full.json +++ b/build/openrpc/full.json @@ -2,7 +2,7 @@ "openrpc": "1.2.6", "info": { "title": "Lotus RPC API", - "version": "1.32.3-dev" + "version": "1.33.0-rc1" }, "methods": [ { diff --git a/build/openrpc/gateway.json b/build/openrpc/gateway.json index 38639eceec9..4a8f7cb351a 100644 --- a/build/openrpc/gateway.json +++ b/build/openrpc/gateway.json @@ -2,7 +2,7 @@ "openrpc": "1.2.6", "info": { "title": "Lotus RPC API", - "version": "1.32.3-dev" + "version": "1.33.0-rc1" }, "methods": [ { diff --git a/build/openrpc/miner.json b/build/openrpc/miner.json index ebef8e06741..c76c6ffc463 100644 --- a/build/openrpc/miner.json +++ b/build/openrpc/miner.json @@ -2,7 +2,7 @@ "openrpc": "1.2.6", "info": { "title": "Lotus RPC API", - "version": "1.32.3-dev" + "version": "1.33.0-rc1" }, "methods": [ { diff --git a/build/openrpc/v2/full.json b/build/openrpc/v2/full.json index f960fde3222..8e0e7d69245 100644 --- a/build/openrpc/v2/full.json +++ b/build/openrpc/v2/full.json @@ -2,7 +2,7 @@ "openrpc": "1.2.6", "info": { "title": "Lotus RPC API", - "version": "1.32.3-dev" + "version": "1.33.0-rc1" }, "methods": [ { diff --git a/build/openrpc/v2/gateway.json b/build/openrpc/v2/gateway.json index ce487caf50c..ad2be872b27 100644 --- a/build/openrpc/v2/gateway.json +++ b/build/openrpc/v2/gateway.json @@ -2,7 +2,7 @@ "openrpc": "1.2.6", "info": { "title": "Lotus RPC API", - "version": "1.32.3-dev" + "version": "1.33.0-rc1" }, "methods": [ { diff --git a/build/openrpc/worker.json b/build/openrpc/worker.json index d61e679af7c..f6e58aff902 100644 --- a/build/openrpc/worker.json +++ b/build/openrpc/worker.json @@ -2,7 +2,7 @@ "openrpc": "1.2.6", "info": { "title": "Lotus RPC API", - "version": "1.32.3-dev" + "version": "1.33.0-rc1" }, "methods": [ { diff --git a/build/version.go b/build/version.go index 1441905ad75..1c7e3060189 100644 --- a/build/version.go +++ b/build/version.go @@ -7,7 +7,7 @@ import ( ) // NodeBuildVersion is the local build version of the Lotus daemon -const NodeBuildVersion string = "1.32.3-dev" +const NodeBuildVersion string = "1.33.0-rc1" func NodeUserVersion() BuildVersion { if os.Getenv("LOTUS_VERSION_IGNORE_COMMIT") == "1" { diff --git a/documentation/en/cli-lotus.md b/documentation/en/cli-lotus.md index baa308df3e3..dfcef5df8a7 100644 --- a/documentation/en/cli-lotus.md +++ b/documentation/en/cli-lotus.md @@ -8,7 +8,7 @@ USAGE: lotus [global options] command [command options] VERSION: - 1.32.3-dev + 1.33.0-rc1 COMMANDS: daemon Start a lotus daemon process From 9e1d5a848c8ce297fc9da8833997a5d0ee8ebb4a Mon Sep 17 00:00:00 2001 From: Phi Date: Thu, 1 May 2025 11:13:38 +0200 Subject: [PATCH 2/9] chore: update Changelog chore: update Changelog --- CHANGELOG.md | 29 +++++++++++++++++++++++------ 1 file changed, 23 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e0be8dc7f3b..5f8c862fa85 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,18 +7,24 @@ > * [CHANGELOG_1.1x.md](./documentation/changelog/CHANGELOG_1.1x.md) - v1.10.0 to v1.19.0 > * [CHANGELOG_1.2x.md](./documentation/changelog/CHANGELOG_1.2x.md) - v1.20.0 to v1.29.2 -# UNRELEASED +# Node v1.33.0-rc1 / 2025-05-01 +The Lotus v1.33.0-rc1 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 while improving existing /v1 APIs and implements intelligent fallback mechanisms between F3 and Expected Consensus. + +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: -- test!: add test for proxy contract minting ([filecoin-project/lotus#13010](https://github.com/ -- fix(deps): fix Ledger hardware wallet support ([filecoin-project/lotus#13048](https://github.com/filecoin-project/lotus/pull/13048)) -- fix(eth): always return nil for eth transactions not found ([filecoin-project/lotus#12999](https://github.com/filecoin-project/lotus/pull/12999)) - feat: add gas to application metric reporting `vm/applyblocks_early_gas`, `vm/applyblocks_messages_gas`, `vm/applyblocks_cron_gas` ([filecoin-project/lotus#13030](https://github.com/filecoin-project/lotus/pull/13030)) +- feat: add F3 Grafana Dashboard Template ([filecoin-project/lotus#12934](https://github.com/filecoin-project/lotus/pull/12934)) +- feat: expose /v2 APIs through Lotus Gateway ([filecoin-project/lotus#13075](https://github.com/filecoin-project/lotus/pull/13075)) - feat: fall back to EC if F3 finalized tipeset is older than 900 epochs ([filecoin-project/lotus#13066](https://github.com/filecoin-project/lotus/pull/13066)) - feat: fall back to EC finalized tipset if F3 is too far behind in eth APIs ([filecoin-project/lotus#13070](https://github.com/filecoin-project/lotus/pull/13070)) -- feat: expose `/v2` APIs through Lotus Gateway ([filecoin-project/lotus#13075](https://github.com/filecoin-project/lotus/pull/13075)) -- chore: upgrade to go-f3 `v0.8.4` ([filecoin-project/lotus#13084](https://github.com/filecoin-project/lotus/pull/13084)) - fix(f3): limit the concurrency of F3 power table calculation ([filecoin-project/lotus#13085](https://github.com/filecoin-project/lotus/pull/13085)) - feat(f3): remove dynnamic manifest functionality and use static manifest ([filecoin-project/lotus#13074](https://github.com/filecoin-project/lotus/pull/13074)) +- docs: add ETH API information to V2 API documentation ([filecoin-project/lotus#13068](https://github.com/filecoin-project/lotus/pull/13068)) ### Experimental v2 APIs with F3 awareness @@ -49,6 +55,17 @@ Lotus now offers two versions of its Ethereum-compatible APIs (`eth_*`, `trace_* * 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. +## 🐛 Bug Fix Highlights +- fix(eth): apply limit in EthGetBlockReceiptsLimited ([filecoin-project/lotus#12883](https://github.com/filecoin-project/lotus/pull/12883)) +- fix(eth): always return nil for eth transactions not found ([filecoin-project/lotus#12999](https://github.com/filecoin-project/lotus/pull/12999)) +- fix(deps): fix Ledger hardware wallet support ([filecoin-project/lotus#13048](https://github.com/filecoin-project/lotus/pull/13048)) + +## 📝 Changelog + +For the full set of changes since the last stable release: + +- Node: https://github.com/filecoin-project/lotus/compare/v1.32.3...v1.33.0-rc1 + # Node v1.32.3 / 2025-04-29 This Node v1.32.3 patch release contains a critical update for all node operators. This release ensures that the F3 initial power table CID is correctly set in your Lotus node now that F3 is enabled on Mainnet. All node operators must upgrade to this release before their next node restart to ensure proper F3 functionality. From 4ae7e82b6802a3415332123ff743ad8eda581618 Mon Sep 17 00:00:00 2001 From: Phi Date: Thu, 1 May 2025 11:16:43 +0200 Subject: [PATCH 3/9] chore: update Changelog chore: update Changelog --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5f8c862fa85..6cbb3faf670 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -25,6 +25,7 @@ Please review the detailed documentation for these experimental APIs, as they ar - fix(f3): limit the concurrency of F3 power table calculation ([filecoin-project/lotus#13085](https://github.com/filecoin-project/lotus/pull/13085)) - feat(f3): remove dynnamic manifest functionality and use static manifest ([filecoin-project/lotus#13074](https://github.com/filecoin-project/lotus/pull/13074)) - docs: add ETH API information to V2 API documentation ([filecoin-project/lotus#13068](https://github.com/filecoin-project/lotus/pull/13068)) +- feat(metrics): capture total gas metric from ApplyBlocks ([filecoin-project/lotus#13037](https://github.com/filecoin-project/lotus/pull/13037)) ### Experimental v2 APIs with F3 awareness From d31ad4f0fae611071cbad1d544e45bba3662fa22 Mon Sep 17 00:00:00 2001 From: Phi Date: Thu, 1 May 2025 11:36:38 +0200 Subject: [PATCH 4/9] chore: call out Lotus Gateway /v2 exposing chore: call out Lotus Gateway /v2 exposing --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6cbb3faf670..0c79572a839 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,7 +8,7 @@ > * [CHANGELOG_1.2x.md](./documentation/changelog/CHANGELOG_1.2x.md) - v1.20.0 to v1.29.2 # Node v1.33.0-rc1 / 2025-05-01 -The Lotus v1.33.0-rc1 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 while improving existing /v1 APIs and implements intelligent fallback mechanisms between F3 and Expected Consensus. +The Lotus v1.33.0-rc1 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 while improving existing /v1 APIs and implements intelligent fallback mechanisms between F3 and Expected Consensus. These /v2 APIs are also 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. From 41d93457bf0d7d3080c30170fdb7cbb3e36e7ebf Mon Sep 17 00:00:00 2001 From: Phi Date: Thu, 1 May 2025 11:44:34 +0200 Subject: [PATCH 5/9] chore: add contributors section chore: add contributors section --- CHANGELOG.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0c79572a839..d507accd78f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -67,6 +67,34 @@ For the full set of changes since the last stable release: - Node: https://github.com/filecoin-project/lotus/compare/v1.32.3...v1.33.0-rc1 +## 👨‍👩‍👧‍👦 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 | + # Node v1.32.3 / 2025-04-29 This Node v1.32.3 patch release contains a critical update for all node operators. This release ensures that the F3 initial power table CID is correctly set in your Lotus node now that F3 is enabled on Mainnet. All node operators must upgrade to this release before their next node restart to ensure proper F3 functionality. From bf805dd2d7825138dbc9831e23e8604d64147b52 Mon Sep 17 00:00:00 2001 From: Steve Loeppky Date: Thu, 1 May 2025 09:29:41 -0700 Subject: [PATCH 6/9] Update CHANGELOG.md --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d507accd78f..984d5d0e905 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,7 +8,7 @@ > * [CHANGELOG_1.2x.md](./documentation/changelog/CHANGELOG_1.2x.md) - v1.20.0 to v1.29.2 # Node v1.33.0-rc1 / 2025-05-01 -The Lotus v1.33.0-rc1 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 while improving existing /v1 APIs and implements intelligent fallback mechanisms between F3 and Expected Consensus. These /v2 APIs are also exposed through the Lotus Gateway +The Lotus v1.33.0-rc1 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. From 7ada03bc3285155d98e6075588dcf8f9f0c4b16f Mon Sep 17 00:00:00 2001 From: Steve Loeppky Date: Thu, 1 May 2025 09:30:20 -0700 Subject: [PATCH 7/9] Update CHANGELOG.md --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 984d5d0e905..8bc74b55ede 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -65,7 +65,7 @@ Lotus now offers two versions of its Ethereum-compatible APIs (`eth_*`, `trace_* For the full set of changes since the last stable release: -- Node: https://github.com/filecoin-project/lotus/compare/v1.32.3...v1.33.0-rc1 +- Node: https://github.com/filecoin-project/lotus/compare/release/v1.32.3...release/v1.33.0 ## 👨‍👩‍👧‍👦 Contributors From 5c530d541f3de3ff1ba7f6aebbbe8d3fa900c0d5 Mon Sep 17 00:00:00 2001 From: Steve Loeppky Date: Thu, 1 May 2025 09:47:33 -0700 Subject: [PATCH 8/9] Reogranize feature/improvement highlights to make v2 API work front and center and more concise --- CHANGELOG.md | 26 ++++++++++++-------------- 1 file changed, 12 insertions(+), 14 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8bc74b55ede..51b1d7108ff 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,16 +17,6 @@ Please review the detailed documentation for these experimental APIs, as they ar ## ⭐ Feature/Improvement Highlights: -- feat: add gas to application metric reporting `vm/applyblocks_early_gas`, `vm/applyblocks_messages_gas`, `vm/applyblocks_cron_gas` ([filecoin-project/lotus#13030](https://github.com/filecoin-project/lotus/pull/13030)) -- feat: add F3 Grafana Dashboard Template ([filecoin-project/lotus#12934](https://github.com/filecoin-project/lotus/pull/12934)) -- feat: expose /v2 APIs through Lotus Gateway ([filecoin-project/lotus#13075](https://github.com/filecoin-project/lotus/pull/13075)) -- feat: fall back to EC if F3 finalized tipeset is older than 900 epochs ([filecoin-project/lotus#13066](https://github.com/filecoin-project/lotus/pull/13066)) -- feat: fall back to EC finalized tipset if F3 is too far behind in eth APIs ([filecoin-project/lotus#13070](https://github.com/filecoin-project/lotus/pull/13070)) -- fix(f3): limit the concurrency of F3 power table calculation ([filecoin-project/lotus#13085](https://github.com/filecoin-project/lotus/pull/13085)) -- feat(f3): remove dynnamic manifest functionality and use static manifest ([filecoin-project/lotus#13074](https://github.com/filecoin-project/lotus/pull/13074)) -- docs: add ETH API information to V2 API documentation ([filecoin-project/lotus#13068](https://github.com/filecoin-project/lotus/pull/13068)) -- feat(metrics): capture total gas metric from ApplyBlocks ([filecoin-project/lotus#13037](https://github.com/filecoin-project/lotus/pull/13037)) - ### 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. @@ -34,12 +24,11 @@ The Lotus V2 APIs introduce a powerful new TipSet selection mechanism that signi > [!NOTE] > V2 APIs are highly experimental and subject to change without notice. -> [!IMPORTANT] -> The `/v2` APIs rely on F3 data even if F3 is not yet finalizing the chain (i.e., `EC.Finalize` is `false` in the live F3 manifest used by all participants). To determine if F3 is actively finalizing, call the `F3GetManifest` API and check if `Manifest.EC.Finalize` is `true`. Only when `EC.Finalize` is `true` will the `/v2` `"finalized"` and `"safe"` tags accurately reflect the chain's finality according to F3. This also applies to Ethereum APIs discussed below. +See [Filecoin v2 APIs docs](https://filoznotebook.notion.site/Filecoin-V2-APIs-1d0dc41950c1808b914de5966d501658) for an in-depth overview. /v2 APIs are exosed through Lotus Gateway. -See [Filecoin v2 APIs](https://filoznotebook.notion.site/Filecoin-V2-APIs-1d0dc41950c1808b914de5966d501658) for an in-depth overview. ([filecoin-project/lotus#13003](https://github.com/filecoin-project/lotus/pull/13003)), ([filecoin-project/lotus#13027](https://github.com/filecoin-project/lotus/pull/13027)), ([filecoin-project/lotus#13034](https://github.com/filecoin-project/lotus/pull/13034)) +This work was primarily done in ([filecoin-project/lotus#13003](https://github.com/filecoin-project/lotus/pull/13003)), ([filecoin-project/lotus#13027](https://github.com/filecoin-project/lotus/pull/13027)), ([filecoin-project/lotus#13034](https://github.com/filecoin-project/lotus/pull/13034)), ([filecoin-project/lotus#13075](https://github.com/filecoin-project/lotus/pull/13075)), ([filecoin-project/lotus#13066](https://github.com/filecoin-project/lotus/pull/13066)) -**F3-aware Ethereum APIs via `/v2` endpoint and improvements to existing `/v1` APIs** ([filecoin-project/lotus#13026](https://github.com/filecoin-project/lotus/pull/13026)) +### 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. @@ -56,6 +45,15 @@ Lotus now offers two versions of its Ethereum-compatible APIs (`eth_*`, `trace_* * 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](https://github.com/filecoin-project/lotus/pull/13026)), ([filecoin-project/lotus#13070](https://github.com/filecoin-project/lotus/pull/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](https://github.com/filecoin-project/lotus/pull/13030)) +- feat(metrics): capture total gas metric from ApplyBlocks ([filecoin-project/lotus#13037](https://github.com/filecoin-project/lotus/pull/13037)) +- feat: add F3 Grafana Dashboard Template ([filecoin-project/lotus#12934](https://github.com/filecoin-project/lotus/pull/12934)) +- fix(f3): limit the concurrency of F3 power table calculation ([filecoin-project/lotus#13085](https://github.com/filecoin-project/lotus/pull/13085)) +- feat(f3): remove dynnamic manifest functionality and use static manifest ([filecoin-project/lotus#13074](https://github.com/filecoin-project/lotus/pull/13074)) + ## 🐛 Bug Fix Highlights - fix(eth): apply limit in EthGetBlockReceiptsLimited ([filecoin-project/lotus#12883](https://github.com/filecoin-project/lotus/pull/12883)) - fix(eth): always return nil for eth transactions not found ([filecoin-project/lotus#12999](https://github.com/filecoin-project/lotus/pull/12999)) From 977d49e559ddf618506504f3337959297d98d5b9 Mon Sep 17 00:00:00 2001 From: Steve Loeppky Date: Thu, 1 May 2025 09:51:31 -0700 Subject: [PATCH 9/9] Moved f3 finalization note to experimental v2 docs --- .../api-v2-experimental.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/documentation/en/api-experimental-user-facing-v2-docs/api-v2-experimental.md b/documentation/en/api-experimental-user-facing-v2-docs/api-v2-experimental.md index a31ec88e66f..211e13986ec 100644 --- a/documentation/en/api-experimental-user-facing-v2-docs/api-v2-experimental.md +++ b/documentation/en/api-experimental-user-facing-v2-docs/api-v2-experimental.md @@ -8,6 +8,7 @@ # Meta ## Status +- 2025-05-01: Updated to make clear the impact on the APIs if F3 isn't finalizing. This was reviewed in [PR #13088](https://github.com/filecoin-project/lotus/pull/13088). - 2025-04-24: This document has been updated to include information about Eth APIs in `/v2`. This was reviewed in [PR #13068](https://github.com/filecoin-project/lotus/pull/13068). - 2025-04-23: This document has been updated to account for the minimum initial set of non-Eth /v2 API groups as specified in [issue #12991](https://github.com/filecoin-project/lotus/issues/12991). This was reviewed in [PR #13051](https://github.com/filecoin-project/lotus/pull/13051) - 2025-04-09: This document is still actively a Work In Progress. It has a draft discussing `ChainGetTipSet`. Additional APIs and API Groups will be added as part of working on [issue #12987](https://github.com/filecoin-project/lotus/issues/12987). @@ -86,7 +87,8 @@ This ToC was generated using [Markdown All in One](https://marketplace.visualstu - [Actor Information Retrieval](#actor-information-retrieval) - [Address Resolution](#address-resolution) - [Design decisions](#design-decisions) - - [Why aren’t named parameters used?](#why-arent-named-parameters-used) + - [Why aren't named parameters used?](#why-arent-named-parameters-used) + - [What happens if F3 is not finalizing the chain?](#what-happens-if-f3-is-not-finalizing-the-chain) - [Future API Groups](#future-api-groups) - [State API Group](#state-api-group) - [Mpool API Group](#mpool-api-group) @@ -1121,7 +1123,7 @@ Resolve an address (e.g., robust `f2...` or delegated `f4...`) to its canonical The design for these `/v2` APIs happened as a result of [issue #12987](https://github.com/filecoin-project/lotus/issues/12987) and the resulting subtasks and their linked PRs (in particular [issue #12990](https://github.com/filecoin-project/lotus/issues/12990)). Some of the larger design decisions and their rationale are extracted here. -### Why aren’t named parameters used? +### Why aren't named parameters used? JSON-RPC allows named parameters (using a JSON object instead of an array for `params`), but positional parameters (using a JSON array) were chosen for the Filecoin V2 APIs. These comments are lifted directly from PR feedback discussions: @@ -1129,6 +1131,9 @@ JSON-RPC allows named parameters (using a JSON object instead of an array for `p - *Tooling Compatibility*: Most existing tooling (Lotus' internal JSON-RPC library, `lotus-shed rpc`, client libraries in other languages) primarily expects and works best with positional parameters. - *Simplicity*: While named parameters can sometimes improve readability for complex calls, positional parameters are simpler to implement and parse consistently. Client-side abstractions can easily map more readable function calls to positional parameters if desired. +### What happens if F3 is not finalizing the chain? +The `/v2` APIs rely on F3 data even if F3 is not yet finalizing the chain (i.e., `EC.Finalize` is `false` in the live F3 manifest used by all participants). To determine if F3 is actively finalizing, call the `F3GetManifest` API and check if `Manifest.EC.Finalize` is `true`. Only when `EC.Finalize` is `true` will the `/v2` `"finalized"` and `"safe"` tags accurately reflect the chain's finality according to F3. That said, as of epoch 4919580 on mainnet (2025-04-29T10:00:00Z), F3 is being finalized and this shouldn't be a concern. + ## Future API Groups The Filecoin V2 APIs initiative will expand beyond the Chain, State, and Eth API groups demonstrated in this document. Each API group will follow the same principles of using selectors for expressive queries while maintaining a minimal API surface.