Skip to content

docs: update v2 api docs to account F3-awareness in v1.34.0 #13352

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
rjan90 merged 1 commit into from
Sep 20, 2025
Merged

docs: update v2 api docs to account F3-awareness in v1.34.0 #13352

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
12 changes: 7 additions & 5 deletions documentation/en/api-experimental-user-facing-v2-docs/api-v2-experimental.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,8 @@

# Meta
## Status
- 2025-09-19: Update to account for the F3-awareness that was added to `/v1` APIs in Lotus v1.34.0. This was reviewed in PR [#13352](https://github.com/filecoin-project/lotus/pull/13352).
- 2025-08-29: Updated to summarize the difference between `/v1` and `/v2`. This was reviewed in PR [#13284](https://github.com/filecoin-project/lotus/pull/13284).
- 2025-06-06: Updated to make clear the impact on the APIs if F3 isn't finalizing or if the latest F3-finalized tipset is older than the latest EC-finalized tipset. This was reviewed in [PR #13161](https://github.com/filecoin-project/lotus/pull/13161).
- 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)
Expand Down Expand Up @@ -113,12 +115,12 @@ ETH APIs have also been updated with F3 awareness for the `finalized` and `safe`

| Group | Dimension | `/v1` | `/v2` |
| --- | --- | --- | --- |
| non-ETH APIs | F3 awareness | ❌ | ✅ |
| non-ETH APIs | F3 awareness | ☑️ Only `ChainGetFinalizedTipSet` | ✅ |
| | Selector pattern | ❌ | ✅ |
| | Stable | ✅ | Experimental. There are no known changes to make, but we’ll make breaking changes in response to user feedback. |
| | Support level | Full. Critical bugs can trigger emergency patch releases. Backwards compatibility is a chief concern. | Very responsive to any feedback or bugs, and bugs impacting production usage can trigger an emergency patch release. Backwards compatbility isn’t a concern currently until we get more feedback on the API. |
| | Footprint | Large as has accumulated bloat over the years. | Small. There is a lot of functionality from `/v1` that doesn’t have a `v2` corrolary yet. |
| ETH APIs | F3 awareness | ❌ | ✅ :`finalized` and `safe` tags consult the F3 subsystem (see [Ethereum (Eth)](#ethereum-eth)). |
| | Support level | Full. Critical bugs can trigger emergency patch releases. Backwards compatibility is a chief concern. | Very responsive to any feedback or bugs, and bugs impacting production usage can trigger an emergency patch release. Backwards compatibility isn’t a concern currently until we get more feedback on the API. |
| | Footprint | Large as has accumulated bloat over the years. | Small. There is a lot of functionality from `/v1` that doesn’t have a `v2` equivalent yet. |
| ETH APIs | F3 awareness | ✅ :`finalized` and `safe` tags consult the F3 subsystem (see [Ethereum (Eth)](#ethereum-eth)). | ✅ Same |
| | Support level | Full | Same |
| | Footprint | See [Lotus Ethereum API Compatibility](https://www.notion.so/filecoindev/Lotus-Ethereum-API-Compatibility-1d0dc41950c180cc8c3ecc9033d56cc7) | Same. Any `/v1` ETH APIs are supported in `/v2`. |

Expand Down Expand Up @@ -445,7 +447,7 @@ If the address cannot be resolved to an ID address at the specified tipset state

## Ethereum (Eth)

The V2 API namespace includes all the Ethereum (Eth) APIs that `/v1` supports, but the `finalized` and `safe` tags have been updated to consult the F3 subsystem (if enabled) for finality information. `finalized` and `safe` for the "Eth" APIs has the same meaning and fallback outlined in [Consensus Protocol Notes](#consensus-protocol-notes). In addition, in V2, `safe` will look back a maximum 30 epochs, whereas V1 looks back 30.
The V2 API namespace includes all the Ethereum (Eth) APIs that `/v1` supports. As of Lotus v1.34.0, both `/v1` and `/v2` have had the `finalized` and `safe` tags updated to consult the F3 subsystem (if enabled) for finality information. `finalized` and `safe` for the "Eth" APIs has the same meaning and fallback outlined in [Consensus Protocol Notes](#consensus-protocol-notes). In addition, `safe` will look back a maximum 200 epochs.

For a complete list of available Eth methods in V2, refer to the [V2 autogenerated documentation](https://github.com/filecoin-project/lotus/blob/master/documentation/en/api-v2-unstable-methods.md#eth).

Expand Down
Loading