execution-apis: the JSON-RPC contract every Ethereum execution client must satisfy

What the repository is: an interface contract, not an implementation

The repository is a collection of APIs provided by Ethereum execution layer clients, and the README is precise about what that means. The Ethereum JSON-RPC is a standard collection of methods that all execution clients implement, and it is described as the canonical interface between users and the network. The stated benefit of that canonical status is the reason the project exists: this interface allows downstream tooling and infrastructure to treat different Ethereum clients as modules that can be swapped at will. That is a strong claim and a precise one. A tool written against the spec rather than against one client can move between Geth, Besu, Nethermind or Erigon without being rewritten, and the price of that portability is that the spec has to be the thing everybody agrees on. This repository is where that agreement is written down.

OpenRPC as the source format, and why the spec is split into YAML

The specification itself is written in OpenRPC, and the README points at the OpenRPC specification and the JSON schema for getting started. The choice of OpenRPC rather than a hand written document is what makes the spec machine readable, and that in turn is what makes the tooling below possible. The spec is split into multiple YAML files to improve readability, and the Makefile shows the structure: separate schema directories for the general schemas and the engine OpenRPC schemas, separate method directories for eth, debug and txpool, one for the engine OpenRPC methods and one for testing, plus a directory of error groups. A single 200 page JSON file would be unusable to review, and a spec that cannot be reviewed does not get reviewed, so the split is a reviewability decision as much as an organisational one.

Compiling the spec: one command produces a dereferenced openrpc.json

The build step is short and the output matters. Running make build compiles the YAML sources into a single OpenRPC document, and the command output ends with wrote spec to openrpc.json. The README notes one important property of that file, that it will have all schema $ref references resolved. The Makefile shows the two passes that produce it, one writing refs-openrpc.json without dereferencing and a second writing openrpc.json with the -deref flag, and the same spec flags for both, covering the schema directories, the method directories and the error groups. The dereferenced form is what a consumer wants, because a consumer should not have to resolve references to find out what a field means, but keeping the referenced form around means the build can produce both and the difference is explicit rather than accidental.

$ make build
...
wrote spec to openrpc.json

Testing has four layers, from metaschema to live clients

The Testing section describes several mechanisms rather than one. The spec is always validated against the Open-RPC metaschema while it is being built, so a malformed document never reaches the output. Next is speccheck, a tool that validates the test cases in the tests directory against the specification, run with make test, which ends with all passing. Then there is the spell checker, pyspelling with a configuration file, which checks the specification is free of spelling errors, and which is a wrapper around either Aspell or Hunspell, one of which you need to install first. Finally there are the hive tests, where the test cases in the tests directory are run against execution clients using the hive simulator rpc-compat, with results published at a public results site under the rpc-compat tag. That last layer is the one that turns a specification into an agreement.

$ make test
...
all passing.

$ pip install pyspelling
$ pyspelling -c spellcheck.yaml
Spelling check passed :)

Hive conformance, and the branch that decides which spec you are tested against

The hive integration has one detail that will matter to anyone reproducing results. During the Docker build, rpc-compat clones this repository and copies the tests directory into the simulator container, and by default it fetches main, with the branch build argument able to target a specific ref. The README also notes that versioned releases are planned so that hive can target specific execution-apis versions. Until that exists, a conformance result is a result against the tip of main, not against a fixed version, which means a client can pass today and fail tomorrow because the spec moved rather than because the client regressed. The results are published at a public site under the rpc-compat tag, and the tests documentation in the repository is the place to look for the details of the generation and running process.

GraphQL is a second spec, generated from a live node

Alongside the JSON-RPC there is a GraphQL schema, and its history is different. EIP-1767 proposed a GraphQL schema for interacting with Ethereum clients, and since then Besu and Geth have implemented the interface. This repository holds a live specification to integrate changes to the protocol as well as other improvements into the GraphQL schema. The unusual part is how it is produced. The schema is generated by issuing a meta GraphQL query against a live node, which is the inverse of the JSON-RPC workflow, where the spec is written and clients are tested against it. Here the spec is derived from what a real node already answers, and a separate script reads the schema and validates that it is a valid one, which the README recommends running after modifying the schema. The output of the generation command is committed as graphql.json at the repository root.

$ npm run graphql:schema
...

$ npm run graphql:validate
Schema is valid.

Semantic versioning that treats a spec change as a breaking change

The versioning section follows semantic versioning, and the examples given are unusual enough to be worth reading. A major release includes breaking changes to the rpc-compat hive tests and other backwards incompatible changes, and the examples of a major change include adding tests for a new RPC method, changing the parameters or return type of an existing method in an incompatible way, renaming fields in responses, changing error codes or error response structures, removing support for previously accepted input formats, and adding new fields to response objects. Adding a field to a response is a breaking change for a strict consumer, which tells you the bar here. A minor release includes new backwards compatible features, with examples such as removing tests for an existing method, adding optional parameters, and adding new error codes for previously uncovered edge cases. A patch release is internal changes and backwards compatible bugfixes, including fixing test cases that do not match the spec.

The documentation site, the release tags, and a licence that is not a software licence

The docs are built with Docusaurus and there is a specific dance to see a change locally. The build:docs command builds the spec and then the docs, the watch command watches the repository and rebuilds the spec while copying the README into the build, and npm start runs a local development server on localhost:3000 that rebuilds when the specs are updated, with the honest caveat that sometimes you must reload the page to see your changes. Search requires a production build first, since npm run build:docs produces a production ready version that includes a local search index, served with npm run serve. The releases are v1.0.0-beta.5 on 2026-06-08, v1.0.0-beta.6 on 2026-06-09 and v1.0.0-beta.7 on 2026-06-10, three betas in three days, and the last push to the repository was on 2026-10-19. The licence is CC0, and it is worth noting why that is the right choice here, since a specification is a document rather than software, and a public domain dedication lets anyone implement it without attribution obligations.

Editorial conclusion

execution-apis suits anyone who writes tooling against Ethereum execution clients and needs to know what a method actually means, or who runs a client and wants to check conformance rather than guess. It is the wrong tool for a team that only needs a client, since it is a specification with no runtime behaviour of its own, and a poor fit for anyone expecting a stable release to pin against, because the listed releases are all v1.0.0 betas with the last one from 2026-06-10 even though the repository is pushed to regularly. Before relying on it, read the versioning section rather than assuming semantic versioning means the interface is frozen, because major releases are explicitly expected to include breaking changes to the rpc-compat tests and to remove previously accepted input formats.

Frequently asked questions

Official sources

1. ethereum/execution-apis on GitHub
2. Issues
3. License: CC0-1.0
4. README
5. Releases