🎯 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.

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.