Skip to content

Commit

Permalink
Add RPC API endpoint table (#354)
Browse files Browse the repository at this point in the history 
* 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 <[email protected]>
  • Loading branch information
@Nana-EC
Nana-EC committed Jul 20, 2022
1 parent 735578d commit 713567f
Show file tree
Hide file tree
Showing 2 changed files with 114 additions and 5 deletions.
21 changes: 16 additions & 5 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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"}
Expand All @@ -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.
Expand Down Expand Up @@ -123,19 +123,30 @@ 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
```

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.
Expand Down
98 changes: 98 additions & 0 deletions docs/rpc-api.md
View file
Original file line number Diff line number Diff line change
@@ -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/<semanticVersion>` | Relay Only |



0 comments on commit 713567f

Please sign in to comment.