Home

Awesome

ethereum-jsonrpc-gateway

Go Report Card CircleCI Docker Cloud Automated build Docker Cloud Build Status

A transparent gateway on top of Ethereum nodes for load-balancing, permissions checking.

Background

Services that use the Ethereum blockchain typically need to maintain multiple Ethereum nodes in order to interact with on-chain data. Maintaining multiple Ethereum nodes creates a vast array of complications that eth-jsonrpc-gateways helps allieviate.

Using only a single node, while simpler than running multiple, often is insufficient for practical applications (and yields a singular point of failure). Instead, using a series of multiple Ethereum nodes is a standard practice.

ethereum-jsonrpc-gateway was created as a more elegant solution for Ethereum node management. Some of the complexities it addresses are:

Not all nodes will be available 100% of the time, but eth-jsonrpc-gateway acts as a transparent gateway on top of these nodes: assuring that at least some of them will be available to prevent application failure.

The gateway also acts as a load balancer across the nodes for rpc requests. It can also choose to only accept calls from specific addresses and smart contracts.

Features

Getting Started

There are two ways you can install and run eth-jsonrpc-gateway: you can build it from the source, or you can use a docker container. We'll go over both here.

Build From Source

Requirements

Go version >= 1.11

Steps

  1. Clone this repo
  2. Copy .config.sample.json to .config.json and set valid configuration. Learn More about configuration
  3. Install the dependencies:
go mod download
  1. Run
go build .
./ethereum-jsonrpc-gateway start     # Started on port 3005

Run Using Docker

  1. Clone this repo
  2. Copy .config.sample.json to .config.json and set valid configuration. Learn More about configuration
  3. docker run
chmod +x docker-run.sh
./docker-run.sh

Usage

We call the eth_blockNumber method (When set methodLimitationEnabled true, or eth_blockNumber in allowedMethods)

curl -X POST --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' http://localhost:3005

{"jsonrpc":"2.0","id":1,"result":"0x6c1100"}%

And if we set methodLimitationEnabled true, and eth_blockNumber is not in allowedMethods, when we call eth_blockNumber the gateway will deny the reqeust.

curl -X POST --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' http://localhost:3005

{"error":{"code":-32602,"message":"not allowed method"},"id":1,"jsonrpc":"2.0"}%

Configuration

Copy .config.sample.json to .config.json then edit .config.json

upstreams

Ethereum node upstream urls. You can set multiple nodes in this list. And upstream support http, https, ws, wss. eg.

  "upstreams": [
    "https://example.com/api/v1"
  ]

oldTrieUrl

This field is for Archive Data. If you set oldTrieUrl, Gateway will route Archive Data to this url. An archive node is a simplified way of identifying an Ethereum full node running in archive mode. If you are interested in inspecting historical data (data outside of the most recent 128 blocks), your request requires access to archive data. Learn More about Archive Data. eg.

  "oldTrieUrl": "https://example2.com/api/v1",

strategy

There are three strategies: NAIVE, RACE, FALLBACK. Learn More about the Proxy Strategy. eg.

  "strategy": "NAIVE"

methodLimitationEnabled

This field is about wether enabled the method limitation. The value of this field can be ture or false, if set false will ignore allowedMethods and contractWhitelist. eg.

  "methodLimitationEnabled": false

allowedMethods

Allowed call methods, If methodLimitationEnabled is true, only methods in this list can be called. Can be ignored when set methodLimitationEnabled false. eg.

  "allowedMethods": ["eth_getBalance"]

contractWhitelist

Contract Whitelist,I f methodLimitationEnabled is true, only contract in in this whitelist can be called. Can be ignored when set methodLimitationEnabled false

  "contractWhitelist": ["0x..."]

Proxy Strategy

Depending on the level of complexity needed, there are three proxy strategies for eth-jsonrpc-gateway: Naive, Race and Fallback. The pictures below display how these different proxy methods work.

Naive

Race

Fallback

Contributing

  1. Fork it (https://github.com/HydroProtocol/ethereum-jsonrpc-gateway/fork)
  2. Create your feature branch (git checkout -b feature/fooBar)
  3. Commit your changes (git commit -am 'Add some fooBar')
  4. Push to the branch (git push origin feature/fooBar)
  5. Create a new Pull Request

License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details