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 populate and linknode_modules. - 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 install, 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.
- It is highly recommended to read the Testing Guide for detailed testing strategies and best practices.
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:7546To enable Postman test to run via helm deployment add
test:
enabled: true
schedule: '@daily' #How often to run the Postman test
baseUrl: "http://127.0.0.1:7546" # Relay URL to run the test against
The 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.
The JSON RPC Relay offers multiple environment variable configuration porperties to configure the relay for appropriate use.
More details can be found at Configuration
As in the case of a fully deployed relay the acceptance tests utilize the .env file. See the Configuration for setup details.
Note: Read more about DEV_MODE which provides optimal local and developer testing configurations here
The 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 |
HEDERA_NETWORK |
`` | Which network to connect to. Automatically populates the main node & mirror node endpoints. Can be MAINNET, PREVIEWNET, TESTNET or OTHER |
MIRROR_NODE_URL |
`` | The Mirror Node API endpoint. Official endpoints are Previewnet (https://previewnet.mirrornode.hedera.com), Testnet (https://testnet.mirrornode.hedera.com), Mainnet (https://mainnet-public.mirrornode.hedera.com). See Mirror Node REST API |
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.
In order to bump version for all packages and files altogether there is an npm task called 'bump-version' that needs a parameter called semver and optional parameter snapshot with the version to bump and boolean respectively:
npm run bump-version --semver=0.21.0-rc1 --snapshot=true
snapshot parameter is false by default.
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 and the websocket server - on port 8546
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 charts 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] charts/hedera-json-rpc -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 ./charts/hedera-json-rpc --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.
Grafana JSON Dashboards can be used as the dashboard for hedera-json-rpc-relay.
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.