This directory contains the tooling for building, validating, and testing the Execution API specification. The tools are used by CI and by contributors preparing PRs.

For the contribution workflow and how these tools fit in, see CONTRIBUTING.md and the Contributors Guide.

The CI pipeline runs the following. To pass locally before opening a PR:

1. Build the spec -- make build (from repo root)
2. Run speccheck -- make test (from repo root)
3. Fill tests -- make fill (from repo root, or make fill from tools/)
4. Lint tools -- make lint (from tools/)

If any of these fail, CI will fail. For new methods that require upstream go-ethereum changes, rpctestgen may not pass until go-ethereum implements them; see CONTRIBUTING.md for CI exception policy.

From the repo root:

This builds the tools and runs specgen to produce openrpc.json and refs-openrpc.json.

Validates that test cases in tests/ conform to the OpenRPC specification. Must pass for all PRs.

From the repo root:

Or from tools/ after building:

Options: --spec (default: openrpc.json), --tests (default: tests), --regexp (filter tests), -v (verbose).

Generates test fixtures by executing tests against a geth client. Uses go-ethereum libraries; requires geth to be built. The make fill target builds geth and rpctestgen, then runs the generator.

From the repo root or tools/:

Output is written to tests/. CI checks that no files change after make fill (except known non-deterministic tests). For new methods not yet in go-ethereum, this step may fail; maintainers may merge with CI exceptions.

Options: --bin (client binary), --chain (chain dir), --out (output dir), --tests (regex filter), -v (verbose). Run ./rpctestgen --help for details.

From tools/:

Runs gofmt, go vet, and staticcheck. Install staticcheck with go install honnef.co/go/tools/cmd/staticcheck@latest if needed.

Compiles the YAML method and schema files into a single OpenRPC document. Used internally by make build; typically not run directly by contributors.

Validates test fixtures against the spec. See speccheck above.

Test fixture generator. Runs test definitions against a client (default: geth) and records the request-response exchange. See rpctestgen (fill) above.

Fixtures use a simple line-delimited format. >> denotes a request; << denotes the response.

Tests are stored at tests/{method-name}/{test-name}.io. The generator also outputs chain.rlp and genesis.json so exchanges can be verified on all clients.

For more on test format and chain making, see the Tests documentation.

When you change the spec or docs, rebuild the documentation site:

Commit any generated doc updates. The spell checker (pyspelling -c spellcheck.yaml) runs in CI; fix spelling errors before pushing. When adding new method names, you may need to add them (or their parts) to wordlist.txt so the spell checker accepts them.