RPC Gateway

A high-performance, configurable RPC gateway for Ethereum networks. This service provides load balancing, caching, and health monitoring for RPC endpoints.

Features

• Load Balancing: Distribute requests across multiple RPC endpoints
• Caching: Cache responses to reduce load on upstream providers
• Health Monitoring: Automatic health checks for upstream providers
• Canned Responses: Predefined responses for specific RPC methods
• Configurable: Flexible configuration through YAML
• Docker Support: Ready-to-use Docker images
• Kubernetes Support: Helm charts for easy deployment
• Logging: Configurable logging with multiple backends

Quick Start

Prerequisites

• Rust 1.85 or later
• Docker (optional)
• Kubernetes (optional)

Installation

1. Clone the repository:

git clone https://github.com/whats-good/rpc-gateway.git
cd rpc-gateway

2. Build the project:

make build

Configuration

Create a configuration file (e.g., config.yml) based on the example:

server:
  host: "127.0.0.1"
  port: 8080

load_balancing:
  strategy: "primary_only"

upstream_health_checks:
  enabled: true
  interval: "5m"

cache:
  enabled: true

chains:
  1:
    upstreams:
      - url: "$ALCHEMY_URL"
        timeout: "10s"
        weight: 1

Running the Service

1. Set your environment variables:

export ALCHEMY_URL="your-alchemy-url"

2. Start the service in development mode:

cargo run -- -c config.yml

• Or, if you want to use our pre-defined example config:

make dev

Docker

Build and run using Docker:

docker compose up

Or pull the latest image from Docker Hub:

docker pull whats-good/rpc-gateway:latest

Kubernetes

Deploy using Helm:

helm install rpc-gateway oci://ghcr.io/whats-good/rpc-gateway/helm

API Usage

The service exposes a JSON-RPC endpoint that's compatible with Ethereum clients. The endpoint is /1 for the mainnet, /11155111 for sepolia, and so on. These chains must be configured in the config.yml file, under the chains section.

Example CURL Request

curl -X POST http://localhost:8080/1 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_blockNumber",
    "params": [],
    "id": 1
  }'

Example Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x1234"
}

Configuration Options

Server Configuration

• host: Server host address
• port: Server port number

Load Balancing

Configure how requests are distributed across upstream providers:

load_balancing:
  strategy: "weighted_order"
  fallback_order: ["backup-rpc"]  # optional, for weighted_order only

Available strategies:

Strategy	Description
primary_only	Uses only the single upstream with the highest weight. Simple and predictable.
failover	Tries upstreams by weight (highest first), failing over on connection errors, HTTP errors (e.g., 429), or invalid JSON responses.
weighted_order	Distributes traffic proportionally based on weights, with configurable failover.

Failover Strategy

Routes all traffic to the highest-weight upstream. If it fails, tries the next highest, and so on.

load_balancing:
  strategy: "failover"

chains:
  1:
    upstreams:
      - name: "primary"
        url: "$PRIMARY_RPC"
        weight: 100  # Tried first
      - name: "backup"
        url: "$BACKUP_RPC"
        weight: 50   # Tried if primary fails

Weighted Order Strategy

Distributes traffic proportionally based on weights. For example, with weights [10, 90], approximately 10% of traffic goes to the first upstream and 90% to the second.

load_balancing:
  strategy: "weighted_order"
  fallback_order: ["backup-rpc"]  # Optional: explicit failover order

chains:
  1:
    upstreams:
      - name: "main-rpc"
        url: "$MAIN_RPC"
        weight: 10   # ~10% of traffic
      - name: "backup-rpc"
        url: "$BACKUP_RPC"
        weight: 90   # ~90% of traffic

Options:

• fallback_order: List of upstream names specifying failover priority. If omitted, falls back to other upstreams in descending weight order.

Upstream Health Checks

• enabled: Enable/disable health checks
• interval: Health check interval

Cache

• enabled: Enable/disable response caching

Chains

Configure multiple chains with their respective upstream providers:

• url: RPC endpoint URL
• timeout: Request timeout
• weight: Load balancing weight

Logging

Configure logging through the configuration file:

• Console logging
• File logging
• Log rotation
• Log levels and formats

Development

Building

make build

Testing

make test

Linting

make lint

License

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

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Honorable Mentions

This project wouldn't be possible without the amazing work of the following projects:

• Alloy
• Foundry

License

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