forked from cerc-io/laconicd-deprecated
doc: duplicated documentation removed (#603)
This commit is contained in:
Guillermo Paoletti
@@ -1,12 +0,0 @@
|
||||
<!--
|
||||
order: false
|
||||
parent:
|
||||
order: 1
|
||||
-->
|
||||
|
||||
# API
|
||||
|
||||
This section contains different client and API reference document.
|
||||
|
||||
1. [JSON-RPC](./json-rpc.md)
|
||||
1. [Protobuf Docs](./proto-docs.md)
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,130 +0,0 @@
|
||||
<!--
|
||||
order: 5
|
||||
-->
|
||||
|
||||
# Events
|
||||
|
||||
`Event`s are objects that contain information about the execution of the application. They are
|
||||
mainly used by service providers like block explorers and wallet to track the execution of various
|
||||
messages and index transactions. {synopsis}
|
||||
|
||||
## Pre-requisite Readings
|
||||
|
||||
- [Cosmos SDK Events](https://docs.cosmos.network/master/core/events.html) {prereq}
|
||||
- [Ethereum's PubSub JSON-RPC API](https://geth.ethereum.org/docs/rpc/pubsub) {prereq}
|
||||
|
||||
## Subscribing to Events
|
||||
|
||||
### SDK and Tendermint Events
|
||||
|
||||
It is possible to subscribe to `Events` via Tendermint's [Websocket](https://tendermint.com/docs/app-dev/subscribing-to-events-via-websocket.html#subscribing-to-events-via-websocket).
|
||||
This is done by calling the `subscribe` RPC method via Websocket:
|
||||
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"method": "subscribe",
|
||||
"id": "0",
|
||||
"params": {
|
||||
"query": "tm.event='eventCategory' AND eventType.eventAttribute='attributeValue'"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The main `eventCategory` you can subscribe to are:
|
||||
|
||||
- `NewBlock`: Contains `events` triggered during `BeginBlock` and `EndBlock`.
|
||||
- `Tx`: Contains `events` triggered during `DeliverTx` (i.e. transaction processing).
|
||||
- `ValidatorSetUpdates`: Contains validator set updates for the block.
|
||||
|
||||
These events are triggered from the `state` package after a block is committed. You can get the full
|
||||
list of `event` categories
|
||||
[here](https://godoc.org/github.com/tendermint/tendermint/types#pkg-constants).
|
||||
|
||||
The `type` and `attribute` value of the `query` allow you to filter the specific `event` you are
|
||||
looking for. For example, a `MsgEthereumTx` transaction triggers an `event` of type `ethermint` and
|
||||
has `sender` and `recipient` as `attributes`. Subscribing to this `event` would be done like so:
|
||||
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"method": "subscribe",
|
||||
"id": "0",
|
||||
"params": {
|
||||
"query": "tm.event='Tx' AND ethereum.recipient='hexAddress'"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
where `hexAddress` is an Ethereum hex address (eg: `0x1122334455667788990011223344556677889900`).
|
||||
|
||||
### Ethereum JSON-RPC Events
|
||||
|
||||
Ethermint also supports the Ethereum [JSON-RPC](https://eth.wiki/json-rpc/API) filters calls to
|
||||
subscribe to [state logs](https://eth.wiki/json-rpc/API#eth_newfilter),
|
||||
[blocks](https://eth.wiki/json-rpc/API#eth_newblockfilter) or [pending
|
||||
transactions](https://eth.wiki/json-rpc/API#eth_newpendingtransactionfilter) changes.
|
||||
|
||||
Under the hood, it uses the Tendermint RPC client's event system to process subscriptions that are
|
||||
then formatted to Ethereum-compatible events.
|
||||
|
||||
```bash
|
||||
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_newBlockFilter","params":[],"id":1}' -H "Content-Type: application/json" http://localhost:8545
|
||||
|
||||
{"jsonrpc":"2.0","id":1,"result":"0x3503de5f0c766c68f78a03a3b05036a5"}
|
||||
```
|
||||
|
||||
Then you can check if the state changes with the [`eth_getFilterChanges`](https://eth.wiki/json-rpc/API#eth_getfilterchanges) call:
|
||||
|
||||
```bash
|
||||
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getFilterChanges","params":["0x3503de5f0c766c68f78a03a3b05036a5"],"id":1}' -H "Content-Type: application/json" http://localhost:8545
|
||||
|
||||
{"jsonrpc":"2.0","id":1,"result":["0x7d44dceff05d5963b5bc81df7e9f79b27e777b0a03a6feca09f3447b99c6fa71","0x3961e4050c27ce0145d375255b3cb829a5b4e795ac475c05a219b3733723d376","0xd7a497f95167d63e6feca70f344d9f6e843d097b62729b8f43bdcd5febf142ab","0x55d80a4ba6ef54f2a8c0b99589d017b810ed13a1fda6a111e1b87725bc8ceb0e","0x9e8b92c17280dd05f2562af6eea3285181c562ebf41fc758527d4c30364bcbc4","0x7353a4b9d6b35c9eafeccaf9722dd293c46ae2ffd4093b2367165c3620a0c7c9","0x026d91bda61c8789c59632c349b38fd7e7557e6b598b94879654a644cfa75f30","0x73e3245d4ddc3bba48fa67633f9993c6e11728a36401fa1206437f8be94ef1d3"]}
|
||||
```
|
||||
|
||||
## Websocket Connection
|
||||
|
||||
### Tendermint Websocket
|
||||
|
||||
To start a connection with the Tendermint websocket you need to define the address with the `--rpc.laddr`
|
||||
flag when starting the node (default `tcp://127.0.0.1:26657`):
|
||||
|
||||
```bash
|
||||
ethermintd start --rpc.laddr="tcp://127.0.0.1:26657"
|
||||
```
|
||||
|
||||
Then, start a websocket subscription with [ws](https://github.com/hashrocket/ws)
|
||||
|
||||
```bash
|
||||
# connect to tendermint websocket at port 8080 as defined above
|
||||
ws ws://localhost:8080/websocket
|
||||
|
||||
# subscribe to new Tendermint block headers
|
||||
> { "jsonrpc": "2.0", "method": "subscribe", "params": ["tm.event='NewBlockHeader'"], "id": 1 }
|
||||
```
|
||||
|
||||
### Ethereum Websocket
|
||||
|
||||
Since Ethermint runs uses Tendermint Core as it's consensus Engine and it's built with the Cosmos
|
||||
SDK framework, it inherits the event format from them. However, in order to support the native Web3
|
||||
compatibility for websockets of the [Ethereum's
|
||||
PubSubAPI](https://geth.ethereum.org/docs/rpc/pubsub), Ethermint needs to cast the Tendermint
|
||||
responses retrieved into the Ethereum types.
|
||||
|
||||
You can start a connection with the Ethereum websocket using the `--json-rpc.ws-address` flag when starting
|
||||
the node (default `"0.0.0.0:8546"`):
|
||||
|
||||
```bash
|
||||
ethermintd start --json-rpc.address"0.0.0.0:8545" --json-rpc.ws-address="0.0.0.0:8546" --evm.rpc.api="eth,web3,net,txpool,debug" --json-rpc.enable
|
||||
```
|
||||
|
||||
Then, start a websocket subscription with [`ws`](https://github.com/hashrocket/ws)
|
||||
|
||||
```bash
|
||||
# connect to tendermint websocet at port 8546 as defined above
|
||||
ws ws://localhost:8546/
|
||||
|
||||
# subscribe to new Ethereum-formatted block Headers
|
||||
> {"id": 1, "method": "eth_subscribe", "params": ["newHeads", {}]}
|
||||
< {"jsonrpc":"2.0","result":"0x44e010cb2c3161e9c02207ff172166ef","id":1}
|
||||
```
|
||||
@@ -1,26 +0,0 @@
|
||||
<!--
|
||||
order: 3
|
||||
-->
|
||||
|
||||
# Namespaces
|
||||
|
||||
Check the JSON-RPC namespaces supported on Ethermint. {synopsis}
|
||||
|
||||
## Pre-requisite Readings
|
||||
|
||||
- [Geth JSON-RPC Namespaces](https://geth.ethereum.org/docs/rpc/server) {prereq}
|
||||
|
||||
## Ethereum Namespaces
|
||||
|
||||
| Namespace | Description | Supported | Enabled by Default |
|
||||
|--------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|--------------------|
|
||||
| [`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.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.md#personal-methods) | The `personal` API manages private keys in the key store. | ✔ | ❌ |
|
||||
@@ -1,54 +0,0 @@
|
||||
<!--
|
||||
order: 2
|
||||
-->
|
||||
|
||||
# Running the Server
|
||||
|
||||
Learn how to run and setup the JSON-RPC server on Ethermint. {synopsis}
|
||||
|
||||
## Enable Server
|
||||
|
||||
To enable RPC server use the following flag (set to true by default).
|
||||
|
||||
```bash
|
||||
ethermintd start --json-rpc.enable
|
||||
```
|
||||
|
||||
## Defining Namespaces
|
||||
|
||||
`Eth`,`Net` and `Web3` [namespaces](./namespaces) are enabled by default. In order to enable other namespaces use flag `--json-rpc.api`.
|
||||
|
||||
```bash
|
||||
ethermintd start --json-rpc.api eth,txpool,personal,net,debug,web3,miner
|
||||
```
|
||||
|
||||
## Set a Gas Cap
|
||||
|
||||
`eth_call` and `eth_estimateGas` define a global gas cap over rpc for DoS protection. You can override the default gas cap value of 25,000,000 by passing a custom value when starting the node:
|
||||
|
||||
```bash
|
||||
# set gas cap to 85M
|
||||
ethermintd start --json-rpc.gas-cap 85000000000
|
||||
|
||||
# set gas cap to infinite (=0)
|
||||
ethermintd start --json-rpc.gas-cap 0
|
||||
```
|
||||
|
||||
## CORS
|
||||
|
||||
If accessing the RPC from a browser, CORS will need to be enabled with the appropriate domain set. Otherwise, JavaScript calls are limit by the same-origin policy and requests will fail.
|
||||
|
||||
The CORS setting can be updated from the `app.toml`
|
||||
|
||||
```toml
|
||||
###############################################################################
|
||||
### API Configuration ###
|
||||
###############################################################################
|
||||
|
||||
[api]
|
||||
|
||||
# ...
|
||||
|
||||
# EnableUnsafeCORS defines if CORS should be enabled (unsafe - use it at your own risk).
|
||||
enabled-unsafe-cors = true # default false
|
||||
```
|
||||
@@ -1,73 +0,0 @@
|
||||
<!--
|
||||
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`
|
||||
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user