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.
⚠️ The rpc-gateway is currently in development mode. It is not considered stable and should be used with caution in production environments.
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":[...]}
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
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 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
To run the application with authentication:
DEBUG=true GATEWAY_PASSWORD=my_auth_token go run . --config config.json --auth