Web3 RPC Proxy

     

中文  |  English

🎯 Introduction

Web3 RPC Proxy is a proxy middleware for accessing EVM blockchains that supports cluster deployment, designed to provide users with optimal, stable, and latest block height proxy access.

✨ Features

• ⚡ High concurrency, fast access
• 🙌 Combined with web3-rpc-provider to automatically load available free endpoints
• 💫 Flexible support for multiple chains
• 🔍 Efficient endpoint selection
• 👷 Supports distributed deployment
• 📈 Comprehensive reporting support

Functionality

• Tenant isolation
• Multi-bucket rate limiting
• Request result caching and reuse
• WSS endpoint configuration
• Dynamic endpoint configuration updates
• JSON-RPC API schema validation
• Alternating retries across multiple endpoints
• Prometheus metrics
• Grafana monitoring reports

🚀 Deployment

# Build the docker image
$ docker build ./Dockerfile -t dodozoo/web3-rpc-proxy:latest

# Run the image
$ docker run -p 8080:8080 -d dodozoo/web3-rpc-proxy:latest

Or

# Start the service using docker compose
$ docker-compose up

Modify system configuration using the following environment variables:

• WEB3RPCPROXY_APP_HOST to set the service host and port, default is 0.0.0.0:8080
• WEB3RPCPROXY_ETCD_CONFIG_ENDPOINTS to set the ETCD endpoints
• WEB3RPCPROXY_ETCD_SETUP_CONFIG_FILE to specify the system startup configuration path on ETCD
• WEB3RPCPROXY_ETCD_ENDPOINTS_CONFIG_FILE to specify the endpoint configuration path on ETCD for each chain

Dependencies

• PostgreSQL Depends on the Tenant table
• Redis Used for distributed rate limiting of Tenant in the service
• Amqp, optional After completion, the request information will be published to the mq

Grafana Reports

Import the Grafana template file

💡 Usage

The usage is straightforward, just make a JSON-RPC request to a specific chain.

$ curl --location --request POST 'https://localhost:8080/{{CHAIN}}' \
--header 'Content-Type: application/json' \
--data-raw '[
    {
        "jsonrpc": "2.0",
        "id": 1,
        "method": "net_version",
        "params": []
    },
    {
        "jsonrpc": "2.0",
        "id": 2,
        "method": "eth_blockNumber",
        "params": []
    }
]'

• CHAIN: Required Represents the Chain ID or code of a specific blockchain, refer to the YAML configuration file below.

Request Parameters:

• x_api_key: Required The client must provide an API key when accessing the service, otherwise, it will be rejected with a 403 error. It can also be provided via the X-API-KEY header.
• x_api_bucket: Optional Allows the client to specify different buckets based on the situation, placing different values into different buckets for separate rate limiting. It can also be provided via the X-API-BUCKET header, such as using different chain IDs as bucket values to isolate rate limiting.
• cache: Optional, default true Whether to use cache, acceptable values are true, false
• timeout: Optional, default 30000ms Timeout duration, if exceeded, the request returns a 408 error
• attempts: Optional, default 3 Maximum retry attempts, 0 means no retries
• attempt_strategy: Optional, default same The strategy for selecting endpoints during failure retries: same always retries the same endpoint, rotation alternates retries among available endpoints
• endpoint_type: Optional, string, default Specifies the type of endpoint to select: default automatically selects the most suitable endpoint type based on the request method, acceptable values are fullnode, activenode

For details on the JSON-RPC call body, see JSON-RPC API METHODS

🔧 Configuration

See the default configuration file

🧑‍💻 Development

Starting the Project

# Clone the project
$ git clone https://github.com/DODOEX/web3-rpc-proxy

# Navigate to the project directory
$ cd web3-rpc-proxy

# Install project dependencies
go mod download

# Start the project
go run ./cmd/main.go

Local Debugging

Add a configuration config/local.yaml in the directory to override config/default.yaml for local development and debugging.

Note

The endpoint configuration for each chain should be written under the endpoints configuration item. See the default configuration file

Technology

The project uses the following technologies:

• Fasthttp
• PostgreSQL

Architecture

💬 FAQs

• How to select an endpoint?

  The endpoints are selected based on the nodes configured in WEB3RPCPROXY_ETCD_ENDPOINTS_CONFIG_FILE, and are chosen by sorting them according to their calculated scores.

• What is the configuration priority?

  The configuration priority is: local < env < etcd.

👥 Contribute

If you want to contribute to the Web3 RPC Proxy project:

Fix issues: Find and fix issues in the project. Write documentation: Improve and write relevant documentation for the project. Write tests: Write and optimize test cases for the project.

If you want to show appreciation or support the continued development of the Web3 RPC Proxy project, you can do so by:

Giving the project a GitHub Star. Supporting the project by donating a cup of tea.

📝 License

This project is under license from MIT. For more details, see the LICENSE file.

 

Back to top