Refactor Filecoin JSON RPC API to a new repo for all node implementations to conform to

[eshon]

Checklist

• This is not brainstorming ideas. If you have an idea you'd like to discuss, please open a new discussion on the lotus forum and select the category as Ideas.
• I have a specific, actionable, and well motivated feature request to propose.

Lotus component

• lotus daemon - chain sync
• lotus fvm/fevm - Lotus FVM and FEVM interactions
• lotus miner/worker - sealing
• lotus miner - proving(WindowPoSt/WinningPoSt)
• lotus JSON-RPC API
• lotus message management (mpool)
• Other

What is the motivation behind this feature request? Is your feature request related to a problem? Please describe.

Currently, the Filecoin JSON-RPC API is tightly coupled with Lotus, making it difficult for other node implementations and ecosystem tools to rely on a clear, shared specification. This results in:

• Inconsistent behavior across implementations (e.g., Lotus, Lotus Gateway, CLI, lotus-shed, etc.)

• Difficulty in understanding and using the API from different programming languages due to complex or unclear type definitions

• Ad hoc negotiations about what RPC methods should be public, with API access policies spread across teams and custom logic

• Limited visibility into the evolution of the API across versions (v0, v1, v2), and no shared view of which methods are stable, experimental, or deprecated

• For RPC providers what should or shouldn't be made accessible via public RPC is currently a messy negotiation between the Lotus Gateway, what is deemed efficient by implementers, and different teams making custom requests for their own use cases

• Attempts to create a specification such as the Common Node API effort has been overly complex and difficult for other teams to adopt and support.

A standalone repository would:

• Enable better visibility, discussion, and governance around API changes and stable, mutable and experimental versions

• Allow node implementations to run shared conformance tests

• Provide a single source of truth for stable API behavior

• Help clarify expectations around permissions, caching strategies, and public/private method exposure

• Support maintainability and onboarding for external developers and RPC providers

Stakeholders impacted:

• Node Implementation Teams: Gain clarity and a shared contract for API behavior
• RPC Providers: Can apply their own logic (e.g., permissions, caching) more reliably
• Library Developers: Benefit from a clear and language-agnostic API spec
• Builders and DApp Developers: Get consistent and predictable developer experience
• Filecoin Community: Gains confidence in a standardized and stable API and update process

Describe the solution you'd like

The ideal state would be the Filecoin and Ethereum JSON RPC API separated out into its own repository with supporting conformance tests that all node implementations can interface with.

• Every node implementation including Lotus can pull in the API interface and run conformance tests against it.

• Updates to the API are made to this repo and discussed and approved across stakeholder teams so that the logic and history are made more clear to all teams.

Describe alternatives you've considered

While the Common Node API effort was considered valuable several years ago, not much progress has been made on it and there is no built-in way to have all teams adopt it and find immediate utility from it. The original creator has also left the project. We need a strategy that is more technically direct and immediately useful.

OpenRPC support was also added to Lotus years ago but is currently not working and RPC API documentation is lacking.

Instead of reviving these efforts, this proposal offers a simpler, more technically direct path: separate the API definition into its own repo, with conformance across implementations. This ensures shared accountability and a better foundation for long-term maintainability.

Additional context

This approach mirrors how other successful protocols (e.g., Ethereum) separate their API specs from specific implementations, enabling faster iteration, better tooling, and broader ecosystem alignment.

[rvagg]

@eshon Lotus & Forest teams met yesterday to talk about Common Node API. We're committed to getting filecoin-project/FIPs#1027 merged ASAP but it's going to take a new PR since the two people involved there have moved on, but Forest is keen to do the necessary (minor) tidy up of that and attach an OpenRPC spec doc in that repo and we'll get it landed.

Beyond that, we've also agreed that it would be good for Lotus' API spec to live external to this repo, that it's something we consume rather than produce; with the complication that Lotus will have its own API endpoints that are not part of a shared standard so we may have a combination of consuming and producing in the end. How we move toward a better place is open for discussion. We think that having the spec live in a separate repo is probably inevitable but will defer that until we have more resources that we want to publish along with it (such as test fixtures, which we'd like to include too).

[BigLep]

Thanks a lot for this issue @eshon . I 100% agree we need to move to a common watering hole where we discuss API changes with a human authored spec rather than relying on the spec generated from Lotus go code. I agree we have to be realistic about what we can take on and identify tasks we can actually land in a reasonable amount of time. Since this is bigger than just Lotus though, I'm planning to post more in filecoin-project/FIPs#1032 once I get reminded of some of the discussion notes from FDS-6 on the topic.

[BigLep]

Common Node discussion comment: filecoin-project/FIPs#1032 (comment)

In terms of the Lotus RPC API /v1 and /v2, we think these definitions should get moved out of the Lotus repo to start this process.

We could create filecoin-project/node-specs (as there is prior art for other spec repos per https://github.com/filecoin-project?q=spec&type=all&language=&sort= ), but I'm actually wondering instead if should embed in https://github.com/filecoin-project/specs . I'm imagining in the left-hand nav we have:

8. Node RPC Specs
8.1 Common Node /v1 // frc-104 content would move here instead
8.2 Lotus Node /v1  // copy of https://github.com/filecoin-project/lotus/blob/master/documentation/en/api-v1-unstable-methods.md
8.2 Lotus Node /v2  // copy of https://github.com/filecoin-project/lotus/blob/master/documentation/en/api-v2-unstable-methods.md

The reasons I'm suggesting this:

1. It already has accompanying public website infrastructure which is FF is supporting
2. It's a forcing function to drive some improvements/attention to the specs website/repo

Concerns:

1. The specs repo/site is maybe more overhead and crufty than we want
2. Friction for getting changes through (but in the worst case we should be able to setup codeowners for the "node rpc" docs that require less/different approval).

Once we copy things out of lotus (either into https://github.com/filecoin-project/specs or not-currently-created https://github.com/filecoin-project/node-specs), we would add pointers from the lotus autogenerated specs documents to point to the "authoritative" version so it's clear where we're doing more of our development/discussion, even if .)

@rvagg, @masih, and others: what do you think of this idea of using https://github.com/filecoin-project/specs ? If we're on board with this, I'll either take care of it or create the issue in the https://github.com/filecoin-project/specs repo.

[rvagg]

I guess this is doable, if this is actually a big lift for others vs the friction for Lotus. I think it's openrpc spec docs that we want, not markdown, at least that should be the source of truth. The main catch is all the work we need to do to pull it back in here and munge and check to make sure things align. I don't relish the idea of a new submodule for this.

[masih]

Related issues:

• Missing JSON-RPC Specification for Gateway v0 API #13153
• Auto-generated JSON-RPC specs have vague parameter docs #13154

[eshon]

@BigLep - I'd recommend not using https://github.com/filecoin-project/specs which is famously for the very outdated Filecoin Spec. Better in a new repo that can also be used to generate docs independent of the old Filecoin Spec, etc.