From 713567f979c85cc01baf7b50bcbd9e4d0b6be19a Mon Sep 17 00:00:00 2001 From: Nana Essilfie-Conduah <56320167+Nana-EC@users.noreply.github.com> Date: Wed, 20 Jul 2022 13:56:58 -0500 Subject: [PATCH] Add RPC API endpoint table (#354) * Add RPC API endpoint table The Relay currently doesn't have a quick non dev-centric reference of support endpoints and request steps. An Open RPC spec will be added for greater detail but a simple table with basic information may be useful Add an `rpc-api.md` to highlight - types of methods - basic request and response structure - endpoint table Signed-off-by: Nana-EC --- README.md | 21 ++++++++--- docs/rpc-api.md | 98 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 114 insertions(+), 5 deletions(-) create mode 100644 docs/rpc-api.md diff --git a/README.md b/README.md index a48f05335..0f7ce692f 100644 --- a/README.md +++ b/README.md @@ -55,7 +55,7 @@ The relay has a suite of acceptance tests that may be run to confirm E2E operati As in the case of a fully deployed relay the acceptance tests utilize the `.env` file. See the [Configuration](#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](https://github.com/hashgraph/hedera-local-node#network-variables)) +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](https://github.com/hashgraph/hedera-local-node#network-variables) ```.env HEDERA_NETWORK={"127.0.0.1:50211":"0.0.3"} @@ -71,8 +71,8 @@ E2E_RELAY_HOST=http://127.0.0.1:7546 The following table highlights some initial configuration values to consider | Config | Default | Description | -| ------------|-------|---------------------------------------------------------------------------------------------------------------------------------------------------| -| `CHAIN_ID` | `0x12a` | The netowrk chain id. Local and previewnet envs should use `0x12a`. Mainnet, Testnet and Previewnet should use `0x127`, `0x128` and `0x129` respectively | +| ------------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------| +| `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. @@ -123,12 +123,15 @@ To start the relay, a docker container may be created using the following comman docker compose up -d ``` -> **_NOTE:_** If you encounter `unauthorized` when pulling iamge, then ensure you're loggeed in with `docker login ghcr.io` or use a [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) to authorize your login. +> **_NOTE:_** If you encounter `unauthorized` when pulling image, then ensure you're logged in with `docker login ghcr.io` or use a [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) to authorize your login. By default the relay will be made accessible on port `7546` -A quick tests can be performed to verify the container is up and running + +#### Request Test +The following curl commands may be used to quickly test a running relay instance is function From a command prompt/terminal run the command + ```shell curl -X POST -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":"2","method":"eth_chainId","params":[null]}' http://localhost:7546 ``` @@ -136,6 +139,14 @@ curl -X POST -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":"2"," The 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` + +```shell +curl -X POST -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":"2","method":"eth_gasPrice","params":[null]}' http://localhost:7546 +``` + +The expected response should be of the form `{"result":"0x10bc1576c00","jsonrpc":"2.0","id":"2"}` +Where result returns a valid hexadecimal number + ### Helm Chart 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. diff --git a/docs/rpc-api.md b/docs/rpc-api.md new file mode 100644 index 000000000..e43c7fca9 --- /dev/null +++ b/docs/rpc-api.md @@ -0,0 +1,98 @@ +As an implementation of [HIP 419](https://hips.hedera.com/hip/hip-482), the Hedera JSON RPC Relay provides some [Ethereum JSON-RPC APIs](https://ethereum.github.io/execution-apis/api-documentation/) which implement the [JSON-RPC 2.0 Specification](https://www.jsonrpc.org/specification) to support Ethereum tools interacting with Hedera nodes e.g. wallets, developer tools. + +## Requests +Requests to the Relay will take the form of HTTP calls to an endpoints method. +A curl example to the `eth_chainId` takes the form + Request + ```shell + curl ${RELAY_ENDPOINT_URL} -X POST -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":"2","method":"eth_chainId","params":[null]}' + ``` + +Where +- RELAY_ENDPOINT_URL - HTTP url endpoint, default `http://localhost:7546` + + +## Result Schema + +Result responses can take the form of success or error. + + Success Response + ```json + { + "id": 1, + "jsonrpc": "2.0", + "result": "0x4b7" + } + ``` + +Error Response + ```json + { + "id": 2, + "jsonrpc": "2.0", + "error": { + "code": -32602, + "message": "Invalid params" + } + } + ``` + +The values can range from regular data types (String, int, array) to defined Ethereum objects such as: + +- [Block](https://besu.hyperledger.org/en/stable/Reference/API-Objects/#block-object) +- [Log](https://besu.hyperledger.org/en/stable/Reference/API-Objects/#log-object) +- [Transaction](https://besu.hyperledger.org/en/stable/Reference/API-Objects/#transaction-object) + +## Endpoints + +The JSON RPC Relay methods implements a subset of the standard method: + +- [Gossip Methods](https://ethereum.org/en/developers/docs/apis/json-rpc/#gossip-methods) +- [State Methods](https://ethereum.org/en/developers/docs/apis/json-rpc/#state_methods) +- [History Methods](https://ethereum.org/en/developers/docs/apis/json-rpc/#history_methods) + + +Below is a table of provided methods. + +| Method | Static Response Value | Hedera Nodes (Relay Only, Mirror Node, Consensus Node, Both Nodes) | +| ----------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | --------------------------------------------------------------------- | +| [eth_accounts](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_accounts) | `[]` | N/A | +| [eth_blockNumber](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_blocknumber) | N/A | Mirror Node | +| [eth_call](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_call) | N/A | Consensus Node | +| [eth_chainId](https://besu.hyperledger.org/en/stable/Reference/API-Methods/#eth_chainid) | [Chain_ID](../README.md#configuration) | Relay Only | +| [eth_coinbase](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_coinbase) | `-32601` | N/A | +| [eth_estimateGas](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_estimategas) | N/A | Both Nodes | +| [eth_feeHistory](https://besu.hyperledger.org/en/stable/Reference/API-Methods/#eth_feehistory) | N/A | Both Nodes | +| [eth_gasPrice](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_gasprice) | N/A | Both Nodes | +| [eth_getBalance](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getbalance) | N/A | Consensus Node | +| [eth_getBlockByHash](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getblockbyhash) | N/A | Mirror Node | +| [eth_getBlockByNumber](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getblockbynumber) | N/A | Mirror Node | +| [eth_getBlockTransactionCountByHash](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getblocktransactioncountbyhash) | N/A | Mirror Node | +| [eth_getBlockTransactionCountByNumber](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getblocktransactioncountbynumber) | N/A | Mirror Node | +| [eth_getLogs](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getlogs) | N/A | Mirror Node | +| [eth_getTransactionByBlockHashAndIndex](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_gettransactionbyblockhashandindex) | N/A | Mirror Node | +| [eth_getTransactionByBlockNumberAndIndex](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_gettransactionbyblocknumberandindex) | N/A | Mirror Node | +| [eth_getTransactionByHash](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_gettransactionbyhash) | N/A | Mirror Node | +| [eth_getTransactionCount](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_gettransactioncount) | N/A | Mirror Node | +| [eth_getTransactionReceipt](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_gettransactionreceipt) | N/A | Mirror Node +| [eth_getUncleByBlockHashAndIndex](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getunclebyblockhashandindex) | `null` | N/A | +| [eth_getUncleByBlockNumberAndIndex](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getunclebyblocknumberandindex) | `null` | N/A | +| [eth_getUncleCountByBlockHash](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getunclecountbyblockhash) | `null` | N/A | +| [eth_getUncleCountByBlockNumber](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getunclecountbyblocknumber) | `0x0` | N/A | +| [eth_getWork](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getwork) | `-32601` | N/A | +| [eth_hashrate](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_hashrate) | `0x0` | N/A | +| [eth_mining](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_mining) | `false` | N/A | +| [eth_protocolVersion](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_protocolversion) | `-32601` | N/A | +| [eth_sendRawTransaction](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_sendrawtransaction) | N/A | Consensus Node | +| [eth_sendTransaction](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_sendtransaction) | `-32601` | N/A | +| [eth_signTransaction](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_signtransaction) | `-32601` | N/A | +| [eth_sign](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_sign) | `-32601` | N/A | +| [eth_submitHashrate](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_submithashrate) | `-32601` | N/A | +| [eth_submitWork](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_submitwork) | `false` | N/A | +| [eth_syncing](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_syncing) | `false` | N/A | +| [net_listening](https://ethereum.org/en/developers/docs/apis/json-rpc/#net_listening) | `false` | N/A | +| [net_version](https://ethereum.org/en/developers/docs/apis/json-rpc/#net_version) | [Chain_ID](../README.md#configuration) | Relay Only | +| [web3_clientVersion](https://ethereum.org/en/developers/docs/apis/json-rpc/#web3_clientversion) | `relay/` | Relay Only | + + +