RPCBench

Which RPC endpoint is fastest — for this call, from this machine?

A small CLI that compares EVM JSON-RPC over HTTP: latency, P50/P95/P99, error rate, a ranked table, and JSON. Read-only by default. No accounts. No telemetry. Localhost and RFC1918 are allowed (that is how you bench your own node).

It is not a security scanner (Nodeprobe) and not validator monitoring (ValidatorPulse). Split: docs/BOUNDARY.md. Roadmap: issues · epic #19.

Install

pip install rpcbench

Python 3.10+. rpcbench --version prints 0.1.1.

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

PRs run pytest, then a live smoke against PublicNode and dRPC (--samples 1 --warmup 0). No local node in CI; the smoke passes if either public endpoint is ok.

Quick start

rpcbench compare --endpoints https://ethereum.publicnode.com --samples 5 --warmup 1

Or a YAML/JSON file of named endpoints (keep API keys in a local file; do not commit it):

endpoints:
  - name: publicnode
    url: https://ethereum.publicnode.com
  - name: drpc
    url: https://eth.drpc.org
  - name: paid
    url: https://eth.example/v3/YOUR_KEY
    bearer: YOUR_TOKEN
    headers:
      X-Api-Key: YOUR_KEY

rpcbench run --endpoints endpoints.yaml
rpcbench compare --endpoints endpoints.yaml --json
rpcbench run --endpoints endpoints.yaml -o report.json

run and compare are the same command.

Report

The CLI prints, in order:

1. Summary — Fastest (P95 by default)
2. Comparison — same numbers in your YAML order (failed rows stay in place)
3. Ranking — ordered by --rank-by; failed endpoints last, never Fastest
4. Providers — redacted URL + id= hash, samples, errors
5. Capabilities — who answered this method

On a TTY, ok is green and fail is red (NO_COLOR or a pipe turns color off). Reports never print API keys, bearer tokens, or header values.

How a run works

• Paired by default: one shared read-only sequence; each sample is raced to every provider at the same time. --sequential is A-then-B.
• Warmup is excluded from min/mean/max, percentiles, and error rate.
• P50/P95/P99 are nearest-rank over successful samples.
• Error rate is failed/attempted, with a class (timeout, connection, HTTP 4xx/5xx, JSON-RPC, malformed).
• Ranking is P95 of successes. Override with --rank-by p50|p95|p99|mean|rps (throughput = rps). Lower latency wins; higher rps wins. Ties: mean, then config order.
• rps is 1000 / mean_ms for this probe — not parallel throughput.
• JSON (--json or -o FILE) includes mode, seed, sequence_id, and per-sample pairs (body hashes). Reliability score is success rate.

Flags

rpcbench run --endpoints endpoints.yaml --samples 10 --warmup 1 --preset head
rpcbench compare --endpoints http://127.0.0.1:8545
rpcbench run --endpoints endpoints.yaml --rank-by p95
rpcbench run --endpoints endpoints.yaml --sequential
rpcbench run --endpoints endpoints.yaml --verbose --json

Safety

Kill switch: RPCBENCH_DISABLED=1, or create ~/.config/rpcbench/DISABLED (override path with RPCBENCH_DISABLE_FILE). RPCBench never prompts for a private key.

License

MIT