rpc, docs: private APIs (#525)

evmos · Sep 4, 2021 · 6794daf · 6794daf
1 parent c73ce0f
commit 6794daf
Show file tree

Hide file tree

Showing 13 changed files with 495 additions and 273 deletions.
diff --git a/docs/api/README.md b/docs/api/README.md
@@ -8,5 +8,5 @@ parent:
 
 This section contains different client and API reference document.
 
-1. [JSON-RPC](./json-rpc)
-1. [Protobuf Docs](./proto-docs)
+1. [JSON-RPC](./json-rpc.md)
+1. [Protobuf Docs](./proto-docs.md)
diff --git a/docs/api/json-rpc/endpoints.md b/docs/api/json-rpc/endpoints.md
diff --git a/docs/api/json-rpc/events.md b/docs/api/json-rpc/events.md
@@ -1,5 +1,5 @@
 <!--
-order: 4
+order: 5
 -->
 
 # Events

diff --git a/docs/api/json-rpc/namespaces.md b/docs/api/json-rpc/namespaces.md
@@ -1,5 +1,5 @@
 <!--
-order: 2
+order: 3
 -->
 
 # Namespaces
@@ -14,13 +14,13 @@ Check the JSON-RPC namespaces supported on Ethermint. {synopsis}
 
 | Namespace                                  | Description                                                                                                                                                                                                                  | Supported | Enabled by Default |
 |--------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|--------------------|
-| [`eth`](./endpoints#eth-methods)           | Ethermint provides several extensions to the standard `eth` JSON-RPC namespace.                                                                                                                                              | ✔         | ✔                  |
-| [`web3`](./endpoints#web3-methods)         | The `web3` API provides utility functions for the web3 client.                                                                                                                                                               | ✔         | ✔                  |
-| [`net`](./endpoints#net-methods)           | The `net` API provides access to network information of the node                                                                                                                                                             | ✔         | ✔                  |
+| [`eth`](./endpoints.md#eth-methods)           | Ethermint provides several extensions to the standard `eth` JSON-RPC namespace.                                                                                                                                              | ✔         | ✔                  |
+| [`web3`](./endpoints.md#web3-methods)         | The `web3` API provides utility functions for the web3 client.                                                                                                                                                               | ✔         | ✔                  |
+| [`net`](./endpoints.md#net-methods)           | The `net` API provides access to network information of the node                                                                                                                                                             | ✔         | ✔                  |
 | `clique`                                   | The `clique` API provides access to the state of the clique consensus engine. You can use this API to manage signer votes and to check the health of a private network.                                                      | ❌         |                    |
 | `debug`                                    | The `debug` API gives you access to several non-standard RPC methods, which will allow you to inspect, debug and set certain debugging flags during runtime.                                                                 | ✔         |                    |
 | `les`                                      | The `les` API allows you to manage LES server settings, including client parameters and payment settings for prioritized clients. It also provides functions to query checkpoint information in both server and client mode. | ❌         |                    |
-| [`miner`](./endpoints#miner-methods)       | The `miner` API allows you to remote control the node’s mining operation and set various mining specific settings.                                                                                                           | ✔         | ❌                  |
-| [`txpool`](./endpoints#txpool-methods)     | The `txpool` API gives you access to several non-standard RPC methods to inspect the contents of the transaction pool containing all the currently pending transactions as well as the ones queued for future processing.    | ✔         | ❌                  |
+| [`miner`](./endpoints.md#miner-methods)       | The `miner` API allows you to remote control the node’s mining operation and set various mining specific settings.                                                                                                           | ✔         | ❌                  |
+| [`txpool`](./endpoints.md#txpool-methods)     | The `txpool` API gives you access to several non-standard RPC methods to inspect the contents of the transaction pool containing all the currently pending transactions as well as the ones queued for future processing.    | ✔         | ❌                  |
 | `admin`                                    | The `admin` API gives you access to several non-standard RPC methods, which will allow you to have a fine grained control over your nodeinstance, including but not limited to network peer and RPC endpoint management.     | ❌         |                    |
-| [`personal`](./endpoints#personal-methods) | The `personal` API manages private keys in the key store.                                                                                                                                                                    | ✔         | ❌                  |
+| [`personal`](./endpoints.md#personal-methods) | The `personal` API manages private keys in the key store.                                                                                                                                                                    | ✔         | ❌                  |
diff --git a/docs/api/json-rpc/running_server.md b/docs/api/json-rpc/running_server.md
@@ -1,5 +1,5 @@
 <!--
-order: 1
+order: 2
 -->
 
 # Running the Server

diff --git a/docs/api/json-rpc/server.md b/docs/api/json-rpc/server.md
@@ -0,0 +1,73 @@
+<!--
+order: 1
+-->
+
+# JSON-RPC Server
+
+Learn about the JSON-RPC server to interact with the EVM. {synopsis}
+
+## Pre-requisite Readings
+
+- [EthWiki JSON-RPC API](https://eth.wiki/json-rpc/API) {prereq}
+- [Geth JSON-RPC Server](https://geth.ethereum.org/docs/rpc/server) {prereq}
+
+## JSON-RPC API
+
+[JSON](https://json.org/) is a lightweight data-interchange format. It can represent numbers, strings, ordered sequences of values, and collections of name/value pairs.
+
+[JSON-RPC](http://www.jsonrpc.org/specification) is a stateless, light-weight remote procedure call (RPC) protocol. Primarily this specification defines several data structures and the rules around their processing. It is transport agnostic in that the concepts can be used within the same process, over sockets, over HTTP, or in many various message passing environments. It uses JSON ([RFC 4627](https://www.ietf.org/rfc/rfc4627.txt)) as data format.
+
+## JSON-RPC Support
+
+Ethermint supports all standard web3 JSON-RPC APIs. You can find documentation for these APIs on the [`JSON-RPC Methods`](./endpoints.md) page.
+
+JSON-RPC is provided on multiple transports. Ethermint supports JSON-RPC over HTTP and WebSocket. Transports must be enabled through command-line flags or through the `app.toml` configuration file. For more details see the []
+
+Ethereum JSON-RPC APIs use a name-space system. RPC methods are grouped into several categories depending on their purpose. All method names are composed of the namespace, an underscore, and the actual method name within the namespace. For example, the eth_call method resides in the eth namespace.
+
+Access to RPC methods can be enabled on a per-namespace basis. Find documentation for individual namespaces in the [Namespaces](./namespaces.md) page.
+
+## HEX value encoding
+
+At present there are two key datatypes that are passed over JSON: unformatted byte arrays and quantities. Both are passed with a hex encoding, however with different requirements to formatting:
+
+When encoding **QUANTITIES** (integers, numbers): encode as hex, prefix with `"0x"`, the most compact representation (slight exception: zero should be represented as `"0x0"`). Examples:
+
+- `0x41` (65 in decimal)
+- `0x400` (1024 in decimal)
+- WRONG: `0x` (should always have at least one digit - zero is `"0x0"`)
+- WRONG: `0x0400` (no leading zeroes allowed)
+- WRONG: `ff` (must be prefixed `0x`)
+
+When encoding **UNFORMATTED DATA** (byte arrays, account addresses, hashes, bytecode arrays): encode as hex, prefix with `"0x"`, two hex digits per byte. Examples:
+
+- `0x41` (size 1, `"A"`)
+- `0x004200` (size 3, `"\0B\0"`)
+- `0x` (size 0, `""`)
+- WRONG: `0xf0f0f` (must be even number of digits)
+- WRONG: `004200` (must be prefixed `0x`)
+
+## Default block parameter
+
+The following methods have an extra default block parameter:
+
+- [`eth_getBalance`](./endpoints.md#eth-getbalance)
+- [`eth_getCode`](./endpoints.md#eth-getcode)
+- [`eth_getTransactionCount`](./endpoints.md#eth-gettransactioncount)
+- [`eth_getStorageAt`](./endpoints.md#eth-getstorageat)
+- [`eth_call`](./endpoints.md#eth-call)
+
+When requests are made that act on the state of Ethermint, the last default block parameter determines the height of the block.
+
+The following options are possible for the `defaultBlock` parameter:
+
+- `HEX String` - an integer block number
+- `String "earliest"` for the earliest/genesis block
+- `String "latest"` - for the latest mined block
+- `String "pending"` - for the pending state/transactions
+
+## Curl Examples Explained
+
+The curl options below might return a response where the node complains about the content type, this is because the `--data` option sets the content type to `application/x-www-form-urlencoded`. If your node does complain, manually set the header by placing `-H "Content-Type: application/json"` at the start of the call.
+
+The examples also do not include the URL/IP & port combination which must be the last argument given to curl e.x. `127.0.0.1:8545`
diff --git a/docs/basics/README.md b/docs/basics/README.md
@@ -8,10 +8,10 @@ parent:
 
 This repository contains reference documentation on the basic concepts of Ethermint.
 
-1. [Chain ID](./chain_id)
-1. [Accounts](./accounts)
-1. [Gas and Fees](./gas)
-1. [Lifecycle of a transaction](./transactions)
-1. [Tokens](./tokens)
+1. [Chain ID](./chain_id.md)
+1. [Accounts](./accounts.md)
+1. [Gas and Fees](./gas.md)
+1. [Lifecycle of a transaction](./transactions.md)
+1. [Tokens](./tokens.md)
 
-After reading the basics, head on to the [Core Reference](../core/README) for more advanced material.
+After reading the basics, head on to the [Core Reference](../core/README.md) for more advanced material.
diff --git a/docs/basics/accounts.md b/docs/basics/accounts.md
@@ -158,15 +158,11 @@ curl -X GET "http://localhost:10337/cosmos/auth/v1beta1/accounts/ethm14au322k9mu
 
 ### JSON-RPC
 
-To retrieve the Ethereum hex address using Web3, use the JSON-RPC [`eth_accounts`](./../api/json-rpc/endpoints#eth-accounts) or [`personal_listAccounts`](./../api/json-rpc/endpoints#personal-listAccounts) endpoints:
+To retrieve the Ethereum hex address using Web3, use the JSON-RPC [`eth_accounts`](./../api/json-rpc/endpoints.md#eth-accounts) or [`personal_listAccounts`](./../api/json-rpc/endpoints#personal-listAccounts.md) endpoints:
 
 ```bash
 # query against a local node
 curl -X POST --data '{"jsonrpc":"2.0","method":"eth_accounts","params":[],"id":1}' -H "Content-Type: application/json" http://localhost:8545
 
 curl -X POST --data '{"jsonrpc":"2.0","method":"personal_listAccounts","params":[],"id":1}' -H "Content-Type: application/json" http://localhost:8545
 ```
-
-## Next {hide}
-
-Learn about Ethermint [transactions](./transactions.md) {hide}
diff --git a/docs/basics/chain_id.md b/docs/basics/chain_id.md
@@ -34,3 +34,5 @@ The following table provides an example where the second row corresponds to an u
 |--------------------|------------|---------------|----------------|
 | `ethermint_9000-1` | ethermint  | 9000          | 1              |
 | `ethermint_9000-2` | ethermint  | 9000          | 2              |
+| `...`              | ...        | ...           | ...            |
+| `ethermint_9000-N` | ethermint  | 9000          | N              |
diff --git a/docs/basics/gas.md b/docs/basics/gas.md
@@ -25,9 +25,7 @@ usage of operations during execution. Operations on Cosmos are represented as re
 In Cosmos, a fee is calculated and charged to the user during a message execution. This fee is
 calculated from the sum of all gas consumed in an message execution:
 
-```
-fee = gas * gas price
-```
+$$fee = gas ~ * ~ gasPrice$$
 
 In both networks, gas is used to make sure that operations do not require an excess amount of
 computational power to complete and as a way to deter bad-acting users from spamming the network.
@@ -86,7 +84,7 @@ as gas is required inherently by the EVM. This check is done by the EVM transact
 
 ## Gas estimation
 
-Ethereum provides a JSON-RPC endpoint `eth_estimateGas` to help users set up a correct gas limit in their transactions. 
+Ethereum provides a JSON-RPC endpoint `eth_estimateGas` to help users set up a correct gas limit in their transactions.
 
 Unfortunately, we cannot make use of the SDK `tx simulation` for gas estimation because the pre-check in the Ante Handlers would require a valid signature, and the sender balance to be enough to pay for the gas. But in Ethereum, this endpoint can be called without specifying any sender address.
 
@@ -96,7 +94,3 @@ transaction might be higher than the value returned by the EVM after applying th
 A cache context will be used during the whole execution to avoid changes be persisted in the state.
 
 +++ https://github.com/tharsis/ethermint/blob/098da6d0cc0e0c4cefbddf632df1057383973e4a/x/evm/keeper/grpc_query.go#L100
-
-## Next {hide}
-
-Learn about the different types of [tokens](./tokens.md) available {hide}
diff --git a/docs/basics/transactions.md b/docs/basics/transactions.md
@@ -6,7 +6,7 @@ order: 3
 
 This document describes the lifecycle of a transaction from creation to committed state changes on the EVM. {synopsis}
 
-### Pre-requisite Readings
+## Pre-requisite Readings
 
 - [SDK transaction lifecycle](https://docs.cosmos.network/master/basics/tx-lifecycle.html) {prereq}
 

diff --git a/ethereum/rpc/apis.go b/ethereum/rpc/apis.go
@@ -85,7 +85,7 @@ func GetRPCAPIs(ctx *server.Context, clientCtx client.Context, tmWSClient *rpccl
 					Namespace: PersonalNamespace,
 					Version:   apiVersion,
 					Service:   personal.NewAPI(ctx.Logger, clientCtx, evmBackend),
-					Public:    true,
+					Public:    false,
 				},
 			)
 		case TxPoolNamespace:
@@ -111,8 +111,8 @@ func GetRPCAPIs(ctx *server.Context, clientCtx client.Context, tmWSClient *rpccl
 				rpc.API{
 					Namespace: MinerNamespace,
 					Version:   apiVersion,
-					Service:   miner.NewMinerAPI(ctx, clientCtx, evmBackend),
-					Public:    true,
+					Service:   miner.NewPrivateAPI(ctx, clientCtx, evmBackend),
+					Public:    false,
 				},
 			)
 		default:

diff --git a/ethereum/rpc/namespaces/miner/api.go b/ethereum/rpc/namespaces/miner/api.go
@@ -26,16 +26,16 @@ import (
 	"github.com/tharsis/ethermint/server/config"
 )
 
-// API is the miner prefixed set of APIs in the Miner JSON-RPC spec.
+// API is the private miner prefixed set of APIs in the Miner JSON-RPC spec.
 type API struct {
 	ctx       *server.Context
 	logger    log.Logger
 	clientCtx client.Context
 	backend   backend.Backend
 }
 
-// NewMinerAPI creates an instance of the Miner API.
-func NewMinerAPI(
+// NewPrivateAPI creates an instance of the Miner API.
+func NewPrivateAPI(
 	ctx *server.Context,
 	clientCtx client.Context,
 	backend backend.Backend,