diff --git a/.github/workflows/codeql-analysis.yml b/.github/workflows/codeql-analysis.yml index 9d1cd448..b140d347 100644 --- a/.github/workflows/codeql-analysis.yml +++ b/.github/workflows/codeql-analysis.yml @@ -66,6 +66,7 @@ jobs: - name: Autobuild uses: github/codeql-action/autobuild@v2 + if: env.GIT_DIFF # ℹ️ Command-line programs to run using the OS shell. # πŸ“š https://git.io/JvXDl diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 9e480cf8..26021e44 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -136,9 +136,9 @@ module.exports = { path: '/developers/connect' }, { - title: 'Developer APIs', + title: 'Evmos Clients', directory: false, - path: '/developers/apis' + path: '/developers/clients' }, { title: 'Testnet Faucet', diff --git a/docs/developers/apis.md b/docs/developers/apis.md deleted file mode 100644 index 62cc1883..00000000 --- a/docs/developers/apis.md +++ /dev/null @@ -1,57 +0,0 @@ - - -# Evmos APIs - -Learn about all the available services for clients {synopsis} - -::: tip -🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 - -This documentation page is currently under work in progress. - -🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 🚧 -::: - -The Evmos client supports - -- Cosmos [gRPC](#cosmos-grpc): -- Cosmos REST ([gRPC-Gateway](#cosmos-grpc-gateway)): -- Ethereum [JSON-RPC](#ethereum-json-rpc): -- Ethereum [Websocket](#ethereum-websocket): -- Tendermint [RPC](#tendermint-rpc): -- Tendermint [Websocket](#tendermint-websocket): - - - -## Ethereum JSON-RPC - - - -Evmos also supports most of the standard [JSON-RPC APIs](./json-rpc/running_server) to connect with existing Ethereum-compatible web3 tooling. - -::: tip -Check out the list of supported JSON-RPC API [endpoints](./json-rpc/endpoints) and [namespaces](./../api/json-rpc/namespaces). -::: - -## Ethereum Websocket - - - -## Cosmos gRPC - -Evmos exposes gRPC endpoints for all the integrated Cosmos SDK modules. This makes it easier for -wallets and block explorers to interact with the Proof-of-Stake logic and native Cosmos transactions and queries. - -### Cosmos gRPC-Gateway (HTTP REST) - -[gRPC-Gateway](https://grpc-ecosystem.github.io/grpc-gateway/) reads a gRPC service definition and -generates a reverse-proxy server which translates RESTful JSON API into gRPC. With gRPC-Gateway, -users can use REST to interact the Cosmos gRPC service. - -See the list of supported gRPC-Gateway API endpoints for the Evmos testnet [here](https://api.evmos.dev/). - -## Tendermint Websocket - -## Command Line Interface (CLI) diff --git a/docs/developers/clients.md b/docs/developers/clients.md new file mode 100644 index 00000000..7d51c7de --- /dev/null +++ b/docs/developers/clients.md @@ -0,0 +1,232 @@ + + +# Evmos Clients + +Learn about all the available services for clients {synopsis} + +The Evmos supports different clients in order to support Cosmos and Ethereum transactions +and queries: + +| | Description | Default Port | +| ------------------------------------------------------ | ------------------------------------------------------------------------------------ | ------------ | +| **Cosmos [gRPC](#cosmos-grpc)** | Query or send Evmos transactions using gRPC | `9090` | +| **Cosmos REST ([gRPC-Gateway](#cosmos-grpc-gateway))** | Query or send Evmos transactions using an HTTP RESTful API | `9091` | +| **Ethereum [JSON-RPC](#ethereum-json-rpc)** | Query Ethereum-formatted transactions and blocks or send Ethereum txs using JSON-RPC | `8545` | +| **Ethereum [Websocket](#ethereum-websocket)** | Subscribe to Ethereum logs and events emitted in smart contracts. | `8586` | +| **Tendermint [RPC](#tendermint-rpc)** | Subscribe to Ethereum logs and events emitted in smart contracts. | `26657` | +| **Tendermint [Websocket](#tendermint-websocket)** | Query transactions, blocks, consensus state, broadcast transactions, etc. | `26657` | +| **Command Line Interface ([CLI](#cli))** | Query or send Evmos transactions using your Terminal or Console. | N/A | + +## Cosmos gRPC + +Evmos exposes gRPC endpoints for all the integrated Cosmos SDK modules. This makes it easier for +wallets and block explorers to interact with the Proof-of-Stake logic and native Cosmos transactions and queries. + +### Cosmos gRPC-Gateway (HTTP REST) + +[gRPC-Gateway](https://grpc-ecosystem.github.io/grpc-gateway/) reads a gRPC service definition and +generates a reverse-proxy server which translates RESTful JSON API into gRPC. With gRPC-Gateway, +users can use REST to interact the Cosmos gRPC service. + +See the list of supported gRPC-Gateway API endpoints for the Evmos testnet [here](https://api.evmos.dev/). + +## Ethereum JSON-RPC + + + +Evmos supports most of the standard [JSON-RPC APIs](./json-rpc/server) to connect with existing Ethereum-compatible web3 tooling. + +::: tip +Check out the list of supported JSON-RPC API [endpoints](./json-rpc/endpoints) and [namespaces](./../api/json-rpc/namespaces). +::: + +## Ethereum Websocket + + + +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} +``` + +## Tendermint Websocket + +Tendermint Core provides a Websocket connection to subscribe or unsubscribe to Tendermint ABCI events. + +::: tip +For more info about the how to subscribe to events, please refer to the official [Tendermint documentation](https://docs.tendermint.com/v0.34/tendermint-core/subscription.html). +::: + +```json +{ + "jsonrpc": "2.0", + "method": "subscribe", + "id": "0", + "params": { + "query": "tm.event='' AND eventType.eventAttribute=''" + } +} +``` + +### List of Tendermint Events + +The main events 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. + +::: tip +πŸ‘‰ The list of events types and values for each Cosmos SDK module can be found in the [Modules Specification](./modules) section. +Check the `Events` page to obtain the event list of each supported module on Evmos. +::: + +List of all Tendermint event keys: + +| | Event Type | Categories | +| ---------------------------------------------------- | ---------------- | ----------- | +| Subscribe to a specific event | `"tm.event"` | `block` | +| Subscribe to a specific transaction | `"tx.hash"` | `block` | +| Subscribe to transactions at a specific block height | `"tx.height"` | `block` | +| Index `BeginBlock` and `Endblock` events | `"block.height"` | `block` | +| Subscribe to ABCI `BeginBlock` events | `"begin_block"` | `block` | +| Subscribe to ABCI `EndBlock` events | `"end_block"` | `consensus` | + +Below is a list of values that you can use to subscribe for the `tm.event` type: + +| | Event Value | Categories | +| ---------------------- | ----------------------- | ----------- | +| New block | `"NewBlock"` | `block` | +| New block header | `"NewBlockHeader"` | `block` | +| New Byzantine Evidence | `"NewEvidence"` | `block` | +| New transaction | `"Tx"` | `block` | +| Validator set updated | `"ValidatorSetUpdates"` | `block` | +| Block sync status | `"BlockSyncStatus"` | `consensus` | +| lock | `"Lock"` | `consensus` | +| New consensus round | `"NewRound"` | `consensus` | +| Polka | `"Polka"` | `consensus` | +| Relock | `"Relock"` | `consensus` | +| State sync status | `"StateSyncStatus"` | `consensus` | +| Timeout propose | `"TimeoutPropose"` | `consensus` | +| Timeout wait | `"TimeoutWait"` | `consensus` | +| Unlock | `"Unlock"` | `consensus` | +| Block is valid | `"ValidBlock"` | `consensus` | +| Consensus vote | `"Vote"` | `consensus` | + +### Example + +```bash +ws ws://localhost:26657/websocket +> { "jsonrpc": "2.0", "method": "subscribe", "params": ["tm.event='ValidatorSetUpdates'"], "id": 1 } +``` + +Example response: + +```json +{ + "jsonrpc": "2.0", + "id": 0, + "result": { + "query": "tm.event='ValidatorSetUpdates'", + "data": { + "type": "tendermint/event/ValidatorSetUpdates", + "value": { + "validator_updates": [ + { + "address": "09EAD022FD25DE3A02E64B0FE9610B1417183EE4", + "pub_key": { + "type": "tendermint/PubKeyEd25519", + "value": "ww0z4WaZ0Xg+YI10w43wTWbBmM3dpVza4mmSQYsd0ck=" + }, + "voting_power": "10", + "proposer_priority": "0" + } + ] + } + } + } +} +``` + +## CLI + +Users can use the `{{ $themeConfig.project.binary }}` binary to interact directly with an Evmos node +though the CLI. + +::: tip +πŸ‘‰ To use the CLI, you will need to provide a Tendermint RPC address for the `--node` flag. +Look for a publicly available addresses for testnet and mainnet in the [Quick Connect](./connect) page. +::: + +- **Transactions**: `{{ $themeConfig.project.binary }} tx` + + The list of available commands, as of `v3.0.0`, are: + + ```bash + Available Commands: + authz Authorization transactions subcommands + bank Bank transaction subcommands + broadcast Broadcast transactions generated offline + crisis Crisis transactions subcommands + decode Decode a binary encoded transaction string + distribution Distribution transactions subcommands + encode Encode transactions generated offline + erc20 erc20 subcommands + evidence Evidence transaction subcommands + evm evm transactions subcommands + feegrant Feegrant transactions subcommands + gov Governance transactions subcommands + ibc IBC transaction subcommands + ibc-transfer IBC fungible token transfer transaction subcommands + multisign Generate multisig signatures for transactions generated offline + multisign-batch Assemble multisig transactions in batch from batch signatures + sign Sign a transaction generated offline + sign-batch Sign transaction batch files + slashing Slashing transaction subcommands + staking Staking transaction subcommands + validate-signatures validate transactions signatures + vesting Vesting transaction subcommands + ``` + +- **Queries**: `{{ $themeConfig.project.binary }} query` + + The list of available commands, as of `v3.0.0`, are: + + ```bash + Available Commands: + account Query for account by address + auth Querying commands for the auth module + authz Querying commands for the authz module + bank Querying commands for the bank module + block Get verified data for a the block at given height + claims Querying commands for the claims module + distribution Querying commands for the distribution module + epochs Querying commands for the epochs module + erc20 Querying commands for the erc20 module + evidence Query for evidence by hash or for all (paginated) submitted evidence + evm Querying commands for the evm module + feegrant Querying commands for the feegrant module + feemarket Querying commands for the fee market module + gov Querying commands for the governance module + ibc Querying commands for the IBC module + ibc-transfer IBC fungible token transfer query subcommands + incentives Querying commands for the incentives module + inflation Querying commands for the inflation module + params Querying commands for the params module + recovery Querying commands for the recovery module + slashing Querying commands for the slashing module + staking Querying commands for the staking module + tendermint-validator-set Get the full tendermint validator set at given height + tx Query for a transaction by hash, "/" combination or comma-separated signatures in a committed block + txs Query for paginated transactions that match a set of events + upgrade Querying commands for the upgrade module + vesting Querying commands for the vesting module + ``` diff --git a/docs/developers/json-rpc/events.md b/docs/developers/json-rpc/events.md index 1543ac3c..b2320968 100644 --- a/docs/developers/json-rpc/events.md +++ b/docs/developers/json-rpc/events.md @@ -15,9 +15,13 @@ messages and index transactions. {synopsis} ## Subscribing to Events -### SDK and Tendermint Events +### Cosmos 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). +::: tip +Check the [Tendermint Websocket](./../clients#tendermint-websocket) in the Clients documentation for reference. +::: + +It is possible to subscribe to `Events` via Tendermint's [Websocket](https://docs.tendermint.com/v0.34/tendermint-core/subscription.html). This is done by calling the `subscribe` RPC method via Websocket: ```json @@ -26,23 +30,15 @@ This is done by calling the `subscribe` RPC method via Websocket: "method": "subscribe", "id": "0", "params": { - "query": "tm.event='eventCategory' AND eventType.eventAttribute='attributeValue'" + "query": "tm.event='' AND eventType.eventAttribute=''" } } ``` -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). +These events are triggered after a block is committed. You can get the full list of `event` categories and values [here](./../clients#list-of-tendermint-events). 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 +looking for. For example, a an Ethereum transaction on Evmos (`MsgEthereumTx`) triggers an `event` of type `ethermint` and has `sender` and `recipient` as `attributes`. Subscribing to this `event` would be done like so: ```json @@ -58,12 +54,11 @@ has `sender` and `recipient` as `attributes`. Subscribing to this `event` would where `hexAddress` is an Ethereum hex address (eg: `0x1122334455667788990011223344556677889900`). -### Ethereum JSON-RPC Events +### Ethereum Events -Evmos also supports the Ethereum [JSON-RPC](https://eth.wiki/json-rpc/API) filters calls to +Evmos also supports the Ethereum [JSON-RPC](./server) 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. +[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. @@ -107,8 +102,7 @@ ws ws://localhost:8080/websocket Since Evmos 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), Evmos needs to cast the Tendermint +compatibility for websockets of the [Ethereum's PubSubAPI](https://geth.ethereum.org/docs/rpc/pubsub), Evmos 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 diff --git a/docs/developers/json-rpc/namespaces.md b/docs/developers/json-rpc/namespaces.md index a53ca4e3..247ccf07 100644 --- a/docs/developers/json-rpc/namespaces.md +++ b/docs/developers/json-rpc/namespaces.md @@ -12,15 +12,15 @@ Check the JSON-RPC namespaces supported on Evmos. {synopsis} ## Ethereum Namespaces -| Namespace | Description | Supported | Enabled by Default | -|--------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|--------------------| -| [`eth`](./endpoints.md#eth-methods) | Evmos 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. | βœ” | ❌ | +| Namespace | Description | Supported | Enabled by Default | +| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------------------ | +| [`eth`](./endpoints.md#eth-methods) | Evmos 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. | βœ” | ❌ |