FRC-0104: Common Node API #1158
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
AlexeyKrasnoperov
requested review from
jennijuju,
anorth,
jsoares,
TippyFlitsUK,
momack2,
rvagg,
lanzafame and
dannyob
as code owners
FRCs/frc-0104.md
Outdated
| <!--The technical specification should describe the syntax and semantics of any new feature. The specification should be detailed enough to allow competing, interoperable implementations for any of the current Filecoin implementations. --> | ||
|
|
||
| Using the [OpenRPC document](https://spec.open-rpc.org/#openrpc-document) format we define several groups of methods. | ||
| This specification can be found here: https://github.com/ChainSafe/filecoin-openrpc-spec. A list of the methods is included below for posterity. |
There was a problem hiding this comment.
This repository is archived. The only up-to-date specification should be the one you added.
FRCs/frc-0104.md
Outdated
Comment on lines
52
to
55
| > Note: Lotus hosts two different API's at HTTP paths [`/rpc/v0`](https://github.com/filecoin-project/lotus/blob/v1. | ||
| > 28.0-rc5/documentation/en/api-v0-methods.md) and [`/rpc/v1`](https://github.com/filecoin-project/lotus/blob/v1.28.0-rc5/documentation/en/api-v1-unstable-methods.md), | ||
| with the latter being marked as _unstable_. | ||
| This document aims to specify the `v1` API. |
There was a problem hiding this comment.
It now hosts /v2 as well.
Closed
masih
reviewed
Jun 3, 2025
|
|
||
| ## Methods | ||
|
|
||
| > Working document: https://docs.google.com/spreadsheets/d/1fFkQuEjvFAd2s1dGX5zGmhxsEMLMUZ4uQFnIXgSZA5w/edit?usp=drivesdk |
There was a problem hiding this comment.
The table below does not render correctly Can I ask you to adjust the blockquote spacing to fix this please?
| <!--The technical specification should describe the syntax and semantics of any new feature. The specification should be detailed enough to allow competing, interoperable implementations for any of the current Filecoin implementations. --> | ||
|
|
||
| Using the [OpenRPC document](https://spec.open-rpc.org/#openrpc-document) format we define several groups of methods. | ||
| This specification can be found in `/resources/frc-0104` directory. A list of the methods is included below for posterity. |
There was a problem hiding this comment.
Link it? You can use relative path in Markdown to link to the JSON API spec.
| ## Test Cases | ||
| <!--Test cases for an implementation are mandatory for FIPs that are affecting consensus changes. Other FIPs can choose to include links to test cases if applicable.--> | ||
|
|
||
| [TODO] |
There was a problem hiding this comment.
Are there any existing GitHub issues to link here?
| ## Security Considerations | ||
| <!--All FIPs must contain a section that discusses the security implications/considerations relevant to the proposed change. Include information that might be important for security discussions, surfaces risks and can be used throughout the life cycle of the proposal. E.g., include security-relevant design decisions, concerns, important discussions, implementation-specific guidance and pitfalls, an outline of threats and risks and how they are being addressed. FIP submissions missing the "Security Considerations" section will be rejected. A FIP cannot proceed to status "Final" without a Security Considerations discussion deemed sufficient by the reviewers.--> | ||
|
|
||
| Node implementers must consider the security implications of all methods and ensure sufficient access controls are implemented. This is beyond the scope of this FIP. |
There was a problem hiding this comment.
Hint at existing read vs. write vs. admin permissions as defined in Lotus as a guideline?
lanzafame
requested changes
Jun 4, 2025
| | ChainReadObj | State query | Reads IPLD nodes referenced by the specified CID from the chain blockstore and returns raw bytes. | | ||
| | ChainTipSetWeight | State query | Returns the weight of the specified tipset. | | ||
| | GasEstimateFeeCap | Transactions | Returns the estimated fee cap for the given parameters. | | ||
| | GasEstimateGasLimit | Transactions | Returns the estimated gas limit for the given parameters. | |
There was a problem hiding this comment.
common-node-api.json is missing GasEstimateGasLimit and GasEstimateGasPremium methods.
| # FRC-0104: Common Node API | ||
|
|
||
| ## Simple Summary | ||
| Establish an basic specification for the common JSON-RPC API provided by Filecoin node implementations. |
There was a problem hiding this comment.
Suggested change
| Establish an basic specification for the common JSON-RPC API provided by Filecoin node implementations. | |
| Establish a basic specification for the common JSON-RPC API provided by Filecoin node implementations. |
| <!--The motivation is critical for FIPs that want to change the Filecoin protocol. It should clearly explain why the existing protocol specification is inadequate to address the problem that the FIP solves. FIP submissions without sufficient motivation may be rejected outright.--> | ||
|
|
||
|
|
||
| The JSON-RPC interface provided by Filecoin node implementations is the primary interaction point for many systems, however a standard interface has yet to be established definitively. Lacking such standards, builders are forced to invest additional time and resources in reverse engineering implementations. Node interoperability is hindered as there are no gurantees about what APIs will be encountered in the wild. A proper specification will enable the development of applications that are implementation-agnostic. |
There was a problem hiding this comment.
Suggested change
| The JSON-RPC interface provided by Filecoin node implementations is the primary interaction point for many systems, however a standard interface has yet to be established definitively. Lacking such standards, builders are forced to invest additional time and resources in reverse engineering implementations. Node interoperability is hindered as there are no gurantees about what APIs will be encountered in the wild. A proper specification will enable the development of applications that are implementation-agnostic. | |
| The JSON-RPC interface provided by Filecoin node implementations is the primary interaction point for many systems, however a standard interface has yet to be established definitively. Lacking such standards, builders are forced to invest additional time and resources in reverse engineering implementations. Node interoperability is hindered as there are no guarantees about what APIs will be encountered in the wild. A proper specification will enable the development of applications that are implementation-agnostic. |
| Node implementations must include all specified methods in their API without any modifications. | ||
|
|
||
| Conformance to the specification requires the following conditions to be met: | ||
| - For each method, the `name`, `paramStructure` and `deprecated` fields must match the specification. Additionally, the number and order of parameters much also match the specification. |
There was a problem hiding this comment.
Suggested change
| - For each method, the `name`, `paramStructure` and `deprecated` fields must match the specification. Additionally, the number and order of parameters much also match the specification. | |
| - For each method, the `name`, `paramStructure` and `deprecated` fields must match the specification. Additionally, the number and order of parameters must also match the specification. |
| | StateGetRandomnessDigestFromBeacon | State query | Samples the beacon for randomness. | | ||
| | StateGetRandomnessDigestFromTickets | State query | Samples the chain for randomness. | | ||
| | StateGetRandomnessFromBeacon | State query | Returns the beacon entry for the specified Filecoin epoch. If unavailable, the call blocks until it becomes available. | | ||
| | StateGetRandomnessFromTickets | State query | | |
github-project-automation
bot
moved this from 🔎 Awaiting Review
to ⌨️ In Progress
in FilOz
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
As discussed during FDS-6 in Toronto, I'm opening this PR as a replacement for the previously closed #1027.
The OpenRPC spec is added to the resources directory.