Implementation of an Ethereum JSON RPC APIs for Hedera Hashgraph. Utilises both Hedera Consensus Nodes and Mirror nodes to support RPC queries as defined in the JSON RPC Specification
You must have installed
We also recommend installing the "prettier" plugin in IntelliJ.
From the root of the project workspace:
- Run
npm install. This will create and populatenode_modules. - Run
npm run setup. This will link thenode_modulesto the packages, and the packages together. - Run
npm run build. This will clean and compile the relay library and the server. - Run
npm run start. This will start the server on port7546.
Alternatively, after npm run setup, from within the IDE, you should see the Start Relay Microservice
run configuration. You should be able to just run that configuration, and it should start the server on port 7546.
First ensure newman is installed locally using npm, then execute newman.
npm install -g newman
newman run packages/server/tests/postman.json --env-var baseUrl=http://localhost:7546The relay has a suite of acceptance tests that may be run to confirm E2E operation of the relay in either a hedera-local-node or deployed env.
As in the case of a fully deployed relay the acceptance tests utilize the .env file. See the Configuration for setup details.
For test context additional fields need to be set. The following example showcases a hedera-local-node instance (where values match those noted on Local Node Network Variables
HEDERA_NETWORK={"127.0.0.1:50211":"0.0.3"}
OPERATOR_ID_MAIN=0.0.2
OPERATOR_KEY_MAIN=302e020100300506032b65700422042091132178e72057a1d7528025956fe39b0b847f200ab59b2fdd367017f3087137
CHAIN_ID=0x12a
MIRROR_NODE_URL=http://127.0.0.1:5551
LOCAL_NODE=true
SERVER_PORT=7546
E2E_RELAY_HOST=http://127.0.0.1:7546
DEFAULT_RATE_LIMIT = 200
TIER_1_RATE_LIMIT = 100
TIER_2_RATE_LIMIT = 200
TIER_3_RATE_LIMIT = 400
LIMIT_DURATION = 60000
HBAR_RATE_LIMIT_TINYBAR = 6000000000
HBAR_RATE_LIMIT_DURATION = 60000The following table highlights some initial configuration values to consider
| Config | Default | Description |
|---|---|---|
CHAIN_ID |
0x12a |
The network chain id. Local and previewnet envs should use 0x12a (298). Previewnet, Testnet and Mainnet should use 0x129 (297), 0x128 (296) and 0x127 (295) respectively |
NOTE: Acceptance tests can be pointed at a remote location. In this case be sure to appropriately update these values to point away from your local host and to valid deployed services.
Tests may be run using the following command
npm run acceptancetestThe Relay supports Docker image building and Docker Compose container management using the provided Dockerfile and docker-compose files.
NOTE: docker compose is for development purposes only.
A new docker image may be created from a local copy of the repo.
Run the following command, substituting <owner> as desired
docker build -t <owner>/hedera-json-rpc-relay .After building, the image may be tagged by running the following command, substituting <version> as desired
docker tag <owner>/hedera-json-rpc-relay:latest ghcr.io/hashgraph/hedera-json-rpc-relay:mainNOTE: image is tagged using
ghcr.io/hashgraph/hedera-json-rpc-relay:mainto agree with docker compose. Modify build commands or file as needed.
The relay application currently utilizes dotenv to manage configurations.
Key values are pulled from a .env file and reference as process.env.<KEY> in the application.
To modify the default values
- Rename .env.example file to
.env - Populate the expected fields
- Update the
relayservice volumes section in the docker-compose file from./.env.sample:/home/node/app/.env.sampleto./.env:/home/node/app/.env
Custom values provided will now be incorporated on startup of the relay
To start the relay, a docker container may be created using the following command
docker compose up -dNOTE: If you encounter
unauthorizedwhen pulling image, then ensure you're logged in withdocker login ghcr.ioor use a personal access token to authorize your login.
By default the relay will be made accessible on port 7546
The following curl commands may be used to quickly test a running relay instance is function
From a command prompt/terminal run the command
curl -X POST -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":"2","method":"eth_chainId","params":[null]}' http://localhost:7546The expected response should be {"result":"0x12a","jsonrpc":"2.0","id":"2"}
Where the result value matches the .env CHAIN_ID configuration value or the current deault value of 298
curl -X POST -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":"2","method":"eth_gasPrice","params":[null]}' http://localhost:7546The expected response should be of the form {"result":"0x10bc1576c00","jsonrpc":"2.0","id":"2"}
Where result returns a valid hexadecimal number
This repos helm-chart directory contains the templates and values to deploy Hedera's json-rpc relay to a K8s cluster. This directory is packaged and distributed via helm repo.
To get started, first install the helm repo:
helm repo add hedera-json-rpc-relay https://hashgraph.github.io/hedera-json-rpc-relay/charts
helm repo update
now install the helm chart:
helm install [RELEASE_NAME] hedera-json-rpc-relay/hedera-json-rpc-relay -f /path/to/values.yaml
To see the values that have been deployed:
helm show values hedera-json-rpc-relay
Deploy an installation with custom values file:
helm install custom-hedera-json-rpc-relay -f path/to/values/file.yaml ./helm-chart --debug
- Minikube must be running and the set context
- GHCR.io requires authorization to pull the image. This auth will require a Github PAT to be generated
- Acquire PAT, username, and, (primary) email address from Github.
- Manually create a secret on kubernetes with the following command. The $ must be replaced
kubectl create secret docker-registry ghcr-registry-auth \ --docker-server=https://ghcr.io \ --docker-username=$GH_USERNAME \ --docker-password=$GH_PAT \ --docker-email=$GH_EMAIL
- Deploy this helm-chart with the addtional environment/minikube.yaml file
helm upgrade -f environments/minkube.yaml jrpc-test ./
- Port forward the pod IP to localhost
kubectl port-forward $POD_NAME 7546:7546
The hedera-json-rpc-relay ships with a metrics endpoint at /metrics. Here is an example scrape config that can be used by prometheus:
scrape_configs:
- job_name: hedera-json-rpc
honor_timestamps: true
scrape_interval: 15s
scrape_timeout: 10s
scheme: http
metrics_path: /metrics
kubernetes_sd_configs:
- role: pod
relabel_configs:
- source_labels: [__meta_kubernetes_pod_ip, __meta_kubernetes_pod_container_port_number ]
action: replace
target_label: __address__
regex: ([^:]+)(?::\d+)?;(\d+)
replacement: $1:$2
- source_labels: [__meta_kubernetes_namespace]
action: replace
target_label: namespace
- source_labels: [__meta_kubernetes_pod_name]
action: replace
target_label: pod
Please note that the /metrics endpoint is also a default scrape configurations for prometheus. The job_name of kubernetes-pods is generally deployed as a default with prometheus; in the case where this scrape_config is present metrics will start getting populated by that scrape_config and no other configurations are necessary.
If you have a question on how to use the product, please see our support guide.
Contributions are welcome. Please see the contributing guide to see how you can get involved.
This project is governed by the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code of conduct. Please report unacceptable behavior to oss@hedera.com.