json-rpc-scan 0.2.0

Scans Ethereum (EVM) Blocks via JSON-RPC and looks for client diffs

json-rpc-scan

Scans Ethereum (EVM) Blocks via JSON-RPC and looks for client diffs.

Features

• 🔍 Compare JSON-RPC responses across multiple Ethereum clients
• 🚀 Asynchronous requests for high performance
• 📊 Visual diff reporting (human-readable and machine-readable)
• 🐳 Docker support for easy deployment
• ⚡ Built with modern Python (3.13+)

Requirements

• Python 3.13 or higher
• uv (recommended) or pip

Installation

Using uv (Recommended)

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone the repository
git clone https://github.com/MysticRyuujin/json-rpc-scan.git
cd json-rpc-scan

# Create virtual environment and install dependencies
uv sync

Using pip

pip install json-rpc-scan

Using Docker

docker pull ghcr.io/MysticRyuujin/json-rpc-scan:latest

# Run with Docker
docker run --rm ghcr.io/MysticRyuujin/json-rpc-scan:latest --help

Development Setup

Prerequisites

• Python 3.13+
• pyenv (optional, for Python version management)
• uv (modern Python package manager)
• direnv (optional, for automatic environment activation)

Quick Start

# Clone the repository
git clone https://github.com/MysticRyuujin/json-rpc-scan.git
cd json-rpc-scan

# If using pyenv + direnv (recommended)
direnv allow

# Or manually set up with uv
uv venv --python 3.13
source .venv/bin/activate
uv sync --all-extras

# Install pre-commit hooks
pre-commit install
pre-commit install --hook-type commit-msg

# Run tests
pytest

# Run linting
ruff check src/
ruff format --check src/
mypy src/

Using pyenv

# Install Python 3.13
pyenv install 3.13

# Set local Python version (creates .python-version)
pyenv local 3.13

Using direnv

The project includes a .envrc file that automatically:

• Activates the correct Python version via pyenv
• Creates and activates a virtual environment
• Watches for dependency changes

# Allow direnv to manage the environment
direnv allow

Configuration

Create a config.yaml file (copy from config.example.yaml):

endpoints:
  - name: Geth
    url: http://localhost:8545
  - name: Nethermind
    url: http://localhost:8546

Usage

# Run the scanner
json-rpc-scan --help

# Or using Python module
python -m json_rpc_scan --help

Project Structure

json-rpc-scan/
├── .github/
│   ├── workflows/           # GitHub Actions workflows
│   │   ├── ci.yml          # Continuous Integration
│   │   ├── release.yml     # Release automation
│   │   └── release-please.yml
│   ├── dependabot.yml      # Dependency updates
│   └── release-please-*.json
├── src/
│   └── json_rpc_scan/      # Main package
│       ├── __init__.py
│       ├── __main__.py     # CLI entry point
│       ├── __version__.py  # Version info
│       └── py.typed        # PEP 561 marker
├── tests/                   # Test suite
├── .envrc                   # direnv configuration
├── .pre-commit-config.yaml  # Pre-commit hooks
├── .python-version          # pyenv Python version
├── Dockerfile               # Docker build
├── pyproject.toml           # Project configuration
└── README.md

Code Quality

This project uses several tools to maintain code quality:

Tool	Purpose
black	Code formatting
ruff	Linting and import sorting
mypy	Static type checking
pytest	Testing framework
pre-commit	Git hooks
bandit	Security scanning

Running Checks Locally

# Format code
ruff format src/ tests/

# Lint code
ruff check src/ tests/

# Type check
mypy src/

# Run tests
pytest

# Run all pre-commit hooks
pre-commit run --all-files

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feat/amazing-feature)
3. Make your changes
4. Run the test suite (pytest)
5. Run linting (pre-commit run --all-files)
6. Commit your changes using conventional commits
7. Push to your branch (git push origin feat/amazing-feature)
8. Open a Pull Request

Commit Message Format

This project follows Conventional Commits:

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore

Release Process

This project uses release-please for automated releases:

1. Commits to main are analyzed for conventional commit messages
2. Release PRs are automatically created/updated
3. Merging a release PR triggers:
   • PyPI package publication
   • Docker image build and push to GHCR
   • GitHub release creation

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Inspired by the need for better Ethereum client compatibility testing
• Built with modern Python tooling from the Astral ecosystem