ethereum / execution-apis

Execution API Specification JSON-RPC [View the spec][playground] 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 CONTRIBUTING.md for a concise workflow overview, and the [contributors guide][contributors-guide] for the full process of standardizing new API methods and making changes to existing ones. Information on test generation can be found in [test-gen][test-gen]. The specification itself is written in [OpenRPC][openrpc]. Refer to the OpenRPC specification and the JSON schema [specification][json-schema] to get started. Updating the specs Compiling The specification is split into multiple YAML files to improve readability. The spec can be compiled into a single OpenRPC document as follows: This will output the file in the root of the project. Notably, this file will have all schema s 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. The command starts watching the local repository and rebuilds the spec and copies the into the build. Running npm start starts a local development docusaurus server at 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 ; this builds a production ready version of the app, which will include a local search index. To access the production build call . For more information on the 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. The spec is always validated against the Open-RPC metaschema while being built. Next is . This tool validates the test cases in the directory against the specification. You can run it like this: Spelling The spell checker ensures the specification is free of spelling errors. pyspelling is a wrapper around either Aspell or Hunspell. You'll need to install one of those before running . Hive tests The test cases in the directory are run against execution clients using the [ ][hive] simulator [ ][rpc-compat]. During Docker build, rpc-compat clones this repository and copies the directory into the simulator container. By default it fetches ; the build arg can target a specific ref. Results are published at [hive.ethpandaops.io][hivetests] under the tag. Versioned releases are planned so hive can target specific execution-apis versions. See the [tests documentation][test-gen] for more details. GraphQL [View the spec][graphql-schema] [EIP-1767][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: GraphQL Schema Validation 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: Versioning Execution-apis follows [semantic versioning][semver]. Versioned releases will enable hive to target specific execution-apis versions (currently hive uses by default). • Major releases will include breaking changes to the [rpc-compat hive tests][rpc-compat], and other backwards incompatible changes. • Minor releases will include new backwards-compatible features. • Patch releases will include internal changes that don't impact end users and backwards-compatible bugfixes, along with fixing test cases that don't match the spec. Examples of changes by version type: **Major:** • 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 • Adding new fields to response objects **Minor:** • Removing tests for an existing RPC method • Adding optional parameters to existing methods • Adding new error codes for previously uncovered edge cases • Introducing new capabilities while maintaining backward compatibility • Fixing test cases that don't match the spec **Patch:** • Fixing typos or improving clarity in documentation • Correcting examples in the specification • Improving validation rules without changing the API • Updating internal tooling or build processes License This repository is licensed under [CC0][license]. [playground]: https://ethereum.github.io/execution-apis [openrpc]: https://open-rpc.org [graphql-schema]: http://graphql-schema.ethdevops.io/?url=https://raw.githubusercontent.com/ethereum/execution-apis/main/graphql.json [eip-1767]: https://eips.ethereum.org/EIPS/eip-1767 [contributors-guide]: https://github.com/ethereum/execution-apis/blob/main/docs-api/docs/contributors-guide.md [json-schema]: https://json-schema.org [hive]: https://github.com/ethereum/hive [rpc-compat]: https://github.com/ethereum/hive/tree/master/simulators/ethereum/rpc-compat [hivetests]: https://hive.ethpandaops.io [semver]: https://semver.org/ [test-gen]: https://github.com/ethereum/execution-apis/blob/main/docs-api/docs/tests.md [license]: https://github.com/ethereum/execution-apis/blob/main/LICENSE