compare-nodes

Compares two Ethereum JSON-RPC endpoints for response equivalence and categorizes differences.

1|2|Updated Jun 5, 2025
One-click install
npx skills add https://github.com/NethermindEth/json-bench --skill compare-nodes-nethermindeth
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: compare-nodes
Source: https://github.com/NethermindEth/json-bench/tree/main/.claude/skills/compare-nodes
Command: npx skills add https://github.com/NethermindEth/json-bench --skill compare-nodes-nethermindeth

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve? Verifying that a new, upgraded, or resynced Ethereum node returns the same JSON-RPC responses as a trusted baseline is hard: raw diffs are flooded with benign serialization, tolerance, configuration, and sync-gap noise. This Skill drives the repo's runner compare tool to run a controlled cross-node correctness comparison and produce a findings report where only genuine defects survive. ## Core Features & Use Cases - Pinned-block comparison: Probes both endpoints, verifies chainId and block-hash agreement, and pins all calls to a static historical block so head drift never pollutes results. - Expected-difference rules: Suppresses benign version, numeric-tolerance, and error-wording differences via a YAML rules file, and auto-classifies configuration/capability errors (namespace disabled, range caps, pruned state) separately from real defects. - Categorized findings report: Writes comparison-results.json, an HTML report, provenance, and an ANALYSIS.md that separates real defects (with reproduction curls) from config deltas. - Use Case: After upgrading a Nethermind archive node, compare it against the old Geth baseline over a sampled corpus of RPC calls to confirm no response regressions before switching traffic. ## Quick Start Ask the AI to compare your baseline and candidate Ethereum RPC endpoints for response correctness using the compare-nodes workflow, providing both endpoint URLs.

Frequently Asked Questions about compare-nodes

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I compare two Ethereum RPC nodes for correctness?▼

Run the repo's `runner compare` with both endpoints in a clients.yaml, pin calls to a static historical block via --block-override, and supply a rules file for expected differences. The probe-nodes.sh script verifies both nodes agree on the pin block before comparing.

How to check if an upgraded Ethereum node returns the same responses?▼

Point the comparison at the old node as baseline (first in --client-refs) and the upgraded node as candidate, sample calls from the JSONL corpus, and use --fail-on-diff as a gate. Benign version differences are suppressed by rules so only real regressions remain.

Why do two correct Ethereum clients return different RPC responses?▼

Correct clients differ in benign ways: serialization fields like totalDifficulty, gas-estimate rounding, error wording, and configuration limits such as getLogs range caps or disabled namespaces. The rules file and built-in env-error classification separate these from genuine defects.

Can I compare a still-syncing node against a fully synced archive?▼

Yes, but pin all calls to a block below the syncing node's head and pass --skip-above-head to drop numeric-block calls it cannot serve. Hash-addressed calls above its head will still appear as sync-gap differences, not defects.

Why does the comparison report transport errors or rate limiting?▼

Remote nodes throttle request bursts, so high concurrency causes 429s and truncated responses. Lower --concurrency to 4 or less, set --rate-limit per client (about 2.4 rps for Infura free tier), and always pass --fail-on-transport-error so decimated runs cannot pass silently.

When should I not use cross-node response comparison?▼

Do not use it for latency, throughput, or load testing; that is the run-benchmark skill's job. It also cannot compare head-relative calls like eth_gasPrice or eth_blockNumber, which the corpus loader excludes automatically.