A caching JSON-RPC proxy for Ethereum nodes. Sits in front of a node, deduplicates and caches identical requests for a configurable TTL, and forwards uncached ones upstream.
- Accepts HTTP POST JSON-RPC requests
- Normalizes request IDs and uses method + params as the cache key (id is excluded)
- Serves cached responses without hitting the upstream node until TTL expires
- Sends a Telegram alert on errors (throttled to once per 30 seconds)
pnpm install
pnpm buildnode dist/index.js \
--hostname 0.0.0.0 \
--port 8545 \
--target http://localhost:8546 \
--ttl 60 \
--timeout 30| Argument | Description |
|---|---|
--hostname |
Interface to bind |
--port |
Port to listen on |
--target |
Upstream JSON-RPC URL |
--ttl |
Cache TTL in seconds |
--timeout |
Upstream request timeout in seconds |
| Argument | Env var | Description |
|---|---|---|
--max-body-size |
MAX_BODY_SIZE |
Max request body in bytes (default 1 MB) |
--telegram-token |
TELEGRAM_TOKEN |
Bot token for error alerts |
--telegram-chat-id |
TELEGRAM_CHAT_ID |
Chat ID for error alerts |
--telegram-name |
TELEGRAM_NAME |
Label prepended to alerts (e.g. node hostname) |
--verbose |
Log every request and response | |
--record |
Write timestamped log file to disk | |
--metrics |
Write etherproxy-metrics-<timestamp>.json every 15 minutes |
|
--management-port |
Start a management server on 127.0.0.1:<port> (see below) |
When --management-port is set, a second HTTP server binds exclusively to 127.0.0.1 on that port and exposes a single endpoint for live reconfiguration:
Change the upstream JSON-RPC URL without restarting.
curl -X PUT http://127.0.0.1:9000/target -d 'http://backup-node:8546'The response body confirms the new target. The change takes effect immediately for all subsequent cache misses.
| File | Role |
|---|---|
src/proxy.ts |
Core proxy logic — createProxy(config) returns an HTTP server |
src/index.ts |
CLI entry point — parses args, sets up logging, calls createProxy |