etherproxy-lite

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
pnpm test

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 | | --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 | | test/proxy.test.ts | Integration tests (Vitest) |