erpc-py 0.1.0b3

Python subprocess manager for eRPC v0.0.62 — fault-tolerant EVM RPC proxy

erpc.py

Python subprocess manager for eRPC — the fault-tolerant EVM RPC proxy.

Like py-geth for Go-Ethereum, but for eRPC.

---

[!NOTE] This repository was built entirely by an AI agent (TARS) under the direction of a human engineer (Kieran Prasch). Every commit is co-authored. The architecture, priorities, and quality bar were set by a human; the implementation, tests, and documentation were produced by an AI — from first scaffold to 451 tests at 98% coverage. We believe this is how software will increasingly be built: human intent, machine execution, shared accountability.

---

Compatibility

erpc.py	eRPC binary	Status
0.1.x	v0.0.62	✅ Current

erpc.py pins a specific eRPC binary version (erpc.ERPC_VERSION). All config generation, tests, and CI target this version. Use install_erpc() to install the matching binary automatically.

from erpc import ERPC_VERSION, install_erpc

print(ERPC_VERSION)  # "0.0.62"
install_erpc()       # downloads the pinned version

---

Overview

erpc.py gives you full programmatic control over eRPC from Python — binary installation, YAML config generation, process lifecycle, health monitoring, and runtime metrics. Pure Python with only pyyaml as a runtime dependency.

from erpc import ERPCProcess

with ERPCProcess(upstreams={1: ["https://eth.llamarpc.com"]}) as erpc:
    url = erpc.endpoint_url(1)  # http://127.0.0.1:4000/py-erpc/evm/1
    print(f"Proxying Ethereum mainnet at {url}")

---

Installation

pip install erpc-py

To install the eRPC binary:

erpc-py install --version 0.0.62

Or programmatically:

from erpc.install import install_erpc

install_erpc("0.0.62")  # → /usr/local/bin/erpc

---

Quick Start

Minimal — just upstreams

from erpc import ERPCProcess

with ERPCProcess(upstreams={1: ["https://eth.llamarpc.com"]}) as erpc:
    print(erpc.endpoint_url(1))
    print(f"Healthy: {erpc.is_healthy}")

Full config

from erpc import ERPCConfig, ERPCProcess, CacheConfig

config = ERPCConfig(
    project_id="my-project",
    upstreams={
        1: ["https://eth.llamarpc.com", "https://rpc.ankr.com/eth"],
        137: ["https://polygon-rpc.com"],
    },
    server_port=4000,
    metrics_port=4001,
    log_level="info",
    cache=CacheConfig(max_items=50_000),
)

with ERPCProcess(config=config) as erpc:
    print(erpc.endpoint_url(1))
    print(erpc.endpoint_url(137))

---

Features

🔧 Binary Management

Auto-detect or install eRPC binaries from GitHub releases with optional SHA256 verification.

from erpc.install import install_erpc

path = install_erpc("0.0.62", checksum="abc123...")

📝 Config Builder

Full-fidelity Python config that generates valid erpc.yaml — networks, upstreams, failsafe policies, rate limiters, auth, caching, database connectors, and more.

from erpc import ERPCConfig, DatabaseConfig, RedisConnector, AuthConfig, SecretAuth

config = ERPCConfig(
    project_id="production",
    upstreams={1: ["https://eth.llamarpc.com"]},
    database=DatabaseConfig(
        evm_json_rpc_cache=RedisConnector(addr="localhost:6379"),
    ),
    auth=AuthConfig(
        strategies=[SecretAuth(value="my-secret-key")],
    ),
)

config.write("erpc.yaml")  # Write to file
print(config.to_yaml())    # Or get YAML string

Supported config sections:

• Networks with per-chain policies
• Upstream defaults and rich upstream configs
• 20+ provider presets (Alchemy, Infura, QuickNode, Ankr, etc.)
• Rate limiters and failsafe policies
• Auth strategies (Secret, JWT, SIWE, Network-based)
• Database connectors (Redis, PostgreSQL, DynamoDB, Memory)
• Cache policies with per-method TTLs
• Server config (CORS, timeouts) and metrics

🏥 Health & Metrics Client

Query eRPC's runtime health and Prometheus metrics — stdlib only, no requests needed.

from erpc.client import ERPCClient

client = ERPCClient("http://localhost:4000")

# Structured health check
status = client.health()
print(f"{status.version} — uptime: {status.uptime}s")

# Prometheus metrics as dict
metrics = client.metrics()
print(metrics.get("erpc_requests_total"))

📊 Health Monitoring

Track health state transitions over time.

from erpc import HealthMonitor, HealthEvent

monitor = HealthMonitor(url="http://localhost:4000", interval=30.0)
event = monitor.latest_event()  # HealthEvent.HEALTHY / DOWN / etc.

🐳 Docker Integration

Run eRPC as a Docker container — no local binary needed. Uses the docker CLI, no Python Docker SDK required.

from erpc import ERPCConfig, DockerERPCProcess

config = ERPCConfig(upstreams={1: ["https://eth.llamarpc.com"]})

with DockerERPCProcess(config=config, name="my-erpc") as erpc:
    print(erpc.endpoint_url(1))
    print(erpc.logs(tail=20))

🖥️ CLI Tool

Manage eRPC from the command line:

erpc-py version                    # Show versions
erpc-py install --version 0.0.62   # Install binary
erpc-py health                     # Check health
erpc-py metrics                    # Show Prometheus metrics
erpc-py config generate \
  --chains 1,137 \
  --upstreams https://eth.llamarpc.com,https://polygon-rpc.com \
  --output erpc.yaml               # Generate config
erpc-py start --config erpc.yaml   # Start eRPC
erpc-py stop                       # Stop eRPC

🛡️ Provider Presets

20+ built-in provider configurations for popular RPC services:

from erpc import AlchemyProvider, InfuraProvider, ERPCConfig

config = ERPCConfig(
    upstreams={1: ["https://eth.llamarpc.com"]},
    providers=[
        AlchemyProvider(api_key="..."),
        InfuraProvider(api_key="..."),
    ],
)

All supported providers

Alchemy · Ankr · BlastAPI · BlockPi · Chainstack · Conduit · DRPC · Dwellir · Envio · Etherspot · Infura · OnFinality · Pimlico · QuickNode · Repository · RouteMesh · Superchain · Tenderly · Thirdweb

---

API Overview

Class	Description
ERPCConfig	Config builder — generates erpc.yaml from Python dataclasses
ERPCProcess	Subprocess lifecycle manager with context manager support
DockerERPCProcess	Docker container lifecycle manager
ERPCClient	Health and Prometheus metrics client (stdlib HTTP)
HealthMonitor	Health state tracking with event history
install_erpc()	Binary installer from GitHub releases
CacheConfig	Memory cache settings with per-method TTLs
DatabaseConfig	Database connector config (Redis, Postgres, DynamoDB, Memory)
AuthConfig	Auth strategies (Secret, JWT, SIWE, Network)
ServerConfig	Server settings (CORS, timeouts, host/port)

---

Development

git clone https://github.com/tars-endurance/erpc.py.git
cd erpc.py
pip install -e ".[dev]"

# Run tests (319 tests, 96% coverage)
pytest

# Type checking
mypy erpc/

# Linting
ruff check .
ruff format --check .

---

License

MIT