Etherproxy

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.

How it works

• 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)

Install & build

pnpm install
pnpm build

Usage

node dist/index.js \
--hostname 0.0.0.0 \
--port 8545 \
--target http://localhost:8546 \
--ttl 60 \
--timeout 30

Required arguments

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

Optional arguments

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)

Management API

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:

PUT /target

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.

Structure

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