Execution API Specification

JSON-RPC

View the spec

The Ethereum JSON-RPC is a standard collection of methods that all execution clients implement. It is the canonical interface between users and the network. This interface allows downstream tooling and infrastructure to treat different Ethereum clients as modules that can be swapped at will.

Contributing

Please see the contributors guide for general information about the process of standardizing new API methods and making changes to existing ones. Information on test generation can be found in test-gen

The specification itself is written in OpenRPC. Refer to the OpenRPC specification and the JSON schema specification to get started.

Updating the specs

Compiling

The specification is split into multiple files to improve readability. The spec can be compiled into a single document as follows:

$ npm install
$ npm run build
Build successful.

This will output the file openrpc.json in the root of the project. This file will have all schema #refs resolved.

Building the docs

Once you've updated something in the spec, you can use the docs generation tools to view the updated specs locally.

$ npm run build:docs
$ npm run watch
$ npm run start

The watch command starts watching the local repository and rebuilds the spec and copies the README.md into the build. Running npm start starts a local development docusaurus server at http://localhost:3000 and it rebuilds when you update something in the specs.
Sometimes you must reload the page to see your changes.

There is also search to see the search index built you must npm run build:docs this builds a production ready version of the app, which will include a local search index. To access the production build call npm run serve

For more information on the @open-rpc/docusaurus-plugin see the docs for additional configuration options.

Commits

When the documentation build updates. The documentation updates should be committed as well.

Testing

There are several mechanisms for testing specification contributions and client conformance.

Linting

First is the OpenRPC validator. It performs some basic syntactic checks on the generated specification.

$ npm install
$ npm run lint
OpenRPC spec validated successfully.

Spec tests

Next is speccheck. This tool validates the test cases in the tests directory against the specification. There are two npm scripts to simplify this.

$ npm run build:test
$ npm run test
all passing.

or

$ go install github.com/lightclient/rpctestgen/cmd/speccheck@latest
$ speccheck -v

If you get an error that says: speccheck: command not found, make sure that the go binary is in your $PATH:

$ export PATH=$HOME/go/bin:$PATH

Spelling

The spell checker ensures the specification is free of spelling errors.

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

pyspelling is a wrapper around either Aspell or Hunspell. You'll need to install one of those before running pyspelling.

Hive tests

Finally, the test cases in the tests/ directory may be run against individual execution client using the hive simulator rpc-compat. Please see the documentation in the aforementioned repositories for more information.

GraphQL

View the spec

EIP-1767 proposed a GraphQL schema for interacting with Ethereum clients. Since then Besu and Geth have implemented the interface. This repo contains a live specification to integrate changes to the protocol as well as other improvements into the GraphQL schema.

Generation

The schema in this repo is generated by issuing a meta GraphQL query against a live node. This can be done as follows:

$ npm run graphql:schema

Testing

A script is included in the source code which reads and validates the given schema to be a valid one. It is recommended to perform this check after modifying the schema by:

$ npm run graphql:validate

License

This repository is licensed under CC0.