Meta
Status
- 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.
- 2025-05-01: Updated to make clear the impact on the APIs if F3 isn't finalizing. This was reviewed in PR #13068.
- 2025-04-24: This document has been updated to include information about Eth APIs in
/v2. This was reviewed in PR #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. This was reviewed in PR #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.
Table of Contents
Introduction
The Filecoin V2 APIs represent a significant redesign of Filecoin's RPC interface with several important goals in mind:
- User-Friendly Interface: The APIs provide intuitive ways to interact with the Filecoin network without requiring deep technical knowledge of its internals.
- Expressive Selection Mechanisms: Through the Selector pattern, users can clearly express what data they want using criteria that make sense for their use case.
- Smaller API Footprint: By using flexible selectors, we've reduced the number of distinct API methods needed, consolidating functionality into fewer, more powerful endpoints.
- F3 Awareness: The APIs are fully aware of Filecoin Fast Finality (F3) and can automatically adapt to provide the appropriate finality guarantees based on the node's consensus protocol.
- Future Extensibility: The design allows for extending selection criteria without breaking existing functionality or requiring new API methods.
The Selector Pattern
At the core of the V2 APIs design is the concept of "Selectors" - flexible constructs that let you specify exactly what blockchain data you want. Rather than having different methods for different selection criteria, a single method accepts various selector types to retrieve data in different ways.
This documentation focuses on the TipSetSelector as implemented in the ChainGetTipSet, StateGetActor, and StateGetID methods. Additional API groups are under development, including: