RPC Gateway

The rpc-gateway is a failover proxy designed for node providers. It ensures high availability and reliability by automatically rerouting requests to a backup node provider when health checks indicate the primary provider is down. This process ensures uninterrupted service even in the event of node provider failures.

Caution

⚠️ The rpc-gateway is currently in development mode. It is not considered stable and should be used with caution in production environments.

Overview

The rpc-gateway operates by continuously performing health checks on configured node providers. If the primary node provider fails these checks, the gateway will automatically attempt to route requests to the next available provider based on a predefined failover sequence.

sequenceDiagram
Alice->>RPC Gateway: eth_call
loop Healthcheck
    RPC Gateway->>Alchemy: Check health
    RPC Gateway->>Infura: Check health
end
Note right of RPC Gateway: Routes only to healthy targets
loop Configurable Retries
RPC Gateway->>Alchemy: eth_call?
Alchemy-->>RPC Gateway: ERROR
end
Note right of RPC Gateway: RPC Call is rerouted after failing retries
RPC Gateway->>Infura: eth_call?
Infura-->>RPC Gateway: {"result":[...]}
RPC Gateway-->>Alice: {"result":[...]}

Loading

Development

To contribute to the development of rpc-gateway, ensure that you have Go installed and the project set up locally. Start by running tests to ensure everything is working as expected.

go test -v ./...

For local development and testing, you can run the application with:

DEBUG=true go run . --config config.json

Additionally, to load configuration from an environment variable, use the --env flag. Ensure the GATEWAY_CONFIG environment variable is set with the main configuration data.

DEBUG=true go run . --env

Configuration

The main configuration has been updated to use JSON format (config.json). It specifies the metrics server port and multiple gateways, each with its own JSON configuration file:

{
  "metrics": {
    "port": 9090
  },
  "port": 4000,
  "gateways": [
    {
      "configFile": "config_holesky.json",
      "name": "Holesky gateway"
    },
    {
      "configFile": "config_sepolia.json",
      "name": "Sepolia gateway"
    }
  ]
}

Each JSON configuration file for the gateways can specify detailed settings for proxy behavior, health checks, and target node providers. Here is an example of what these individual gateway configuration files might contain:

{
  "proxy": {
    "port": "3000",
    "upstreamTimeout": "1s"
  },
  "healthChecks": {
    "interval": "5s",
    "timeout": "1s",
    "failureThreshold": 2,
    "successThreshold": 1
  },
  "targets": [
    {
      "name": "Cloudflare",
      "connection": {
        "http": {
          "url": "https://cloudflare-eth.com"
        }
      }
    },
    {
      "name": "Alchemy",
      "connection": {
        "http": {
          "url": "https://alchemy.com/rpc/<apikey>"
        }
      }
    }
  ]
}

Authentication

Authentication can be enabled using the --auth flag. The auth token should be set through environment variables GATEWAY_PASSWORD.

Auth token needs to be the last entry in the RPC gateway URL. Example:

https://sample/rpc-gateway/sepolia/a1b2c3d4e5f7

Running the Application

To run the application with authentication:

DEBUG=true GATEWAY_PASSWORD=my_auth_token go run . --config config.json --auth