Skip to content

Commit

Permalink
Merge pull request #69 from oracleNetworkProtocol/worry-free
Browse files Browse the repository at this point in the history
docs add events and msg
  • Loading branch information
soooc authored Jul 25, 2022
2 parents 489d76e + 693aba4 commit 575900b
Show file tree
Hide file tree
Showing 11 changed files with 378 additions and 465 deletions.
57 changes: 0 additions & 57 deletions docs/endpoints/action.md

This file was deleted.

37 changes: 31 additions & 6 deletions docs/endpoints/grpc-rest.md
Original file line number Diff line number Diff line change
Expand Up @@ -155,12 +155,37 @@ The following example shows how to query events using the Cosmos SDK.
| ------------------------- | ------------------------------- |
| tx.height=23 | Query all transactions with height 23 |
| tx.hash='DF9738772AAECE776187EFF106190FF169F00C725968A15D23FA1DC9B4A1B651' | Query the specified hash transaction |
| [message.action](./action.md#messageaction)=='/cosmos.bank.v1beta1.MsgSend' | Query all transactions containing x/bank `Send`. |
| [message.module](./action.md#messagemodule)='bank' | Query all transactions that contain messages from the `x/bank` module. |
| message.action='/cosmos.bank.v1beta1.MsgSend' | Query all transactions containing x/bank `Send`. |
| message.module='bank' | Query all transactions that contain messages from the `x/bank` module. |
| message.module | message.action |
| ------ | ------------- |
| bank | /cosmos.bank.v1beta1.MsgSend |
| bank | /cosmos.bank.v1beta1.MsgMultiSend |
| distribution | /cosmos.distribution.v1beta1.MsgFundCommunityPool |
| distribution | /cosmos.distribution.v1beta1.MsgSetWithdrawAddress |
| distribution | /cosmos.distribution.v1beta1.MsgWithdrawDelegatorReward |
| distribution | /cosmos.distribution.v1beta1.MsgWithdrawValidatorCommission |
| governance | /cosmos.gov.v1beta1.MsgVote |
| governance | /cosmos.gov.v1beta1.MsgVoteWeighted |
| governance | /cosmos.gov.v1beta1.MsgSubmitProposal |
| governance | /cosmos.gov.v1beta1.MsgDeposit |
| staking | /cosmos.staking.v1beta1.MsgBeginRedelegate |
| staking | /cosmos.staking.v1beta1.MsgCreateValidator |
| staking | /cosmos.staking.v1beta1.MsgDelegate |
| staking | /cosmos.staking.v1beta1.MsgEditValidator |
| staking | /cosmos.staking.v1beta1.MsgUndelegate |
| slashing | /cosmos.slashing.v1beta1.MsgUnjail |
| token | /plugchain.prc10.MsgBurnToken |
| token | /plugchain.prc10.MsgEditToken |
| token | /plugchain.prc10.MsgIssueToken |
| token | /plugchain.prc10.MsgMintToken |
| evm | /ethermint.evm.v1.MsgEthereumTx |
| liquidity | /tendermint.liquidity.v1beta1.MsgCreatePool |
| liquidity | /tendermint.liquidity.v1beta1.MsgDepositWithinBatch |
| liquidity | /tendermint.liquidity.v1beta1.MsgSwapWithinBatch |
| liquidity | /tendermint.liquidity.v1beta1.MsgWithdrawWithinBatch |
Expand Down
180 changes: 140 additions & 40 deletions docs/endpoints/subscription.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,67 +2,167 @@
order: 6
---

# Subscribing to events via Websocket
# Subscribe

Tendermint emits different events, which you can subscribe to via
[Websocket](https://en.wikipedia.org/wiki/WebSocket). This can be useful
for third-party applications (for analysis) or for inspecting state.
`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.

[List of events](https://godoc.org/github.com/tendermint/tendermint/types#pkg-constants)
## Pre-requisite Readings

To connect to a node via websocket from the CLI, you can use a tool such as
[wscat](https://github.com/websockets/wscat) and run:
- [Cosmos SDK Events](https://docs.cosmos.network/master/core/events.html)
- [Ethereum's PubSub JSON-RPC API](https://geth.ethereum.org/docs/rpc/pubsub)

```sh
wscat ws://127.0.0.1:26657/websocket
```
## SDK and Tendermint Events

You can subscribe to any of the events above by calling the `subscribe` RPC
method via Websocket along with a valid query.
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,
"id": "0",
"params": {
"query": "tm.event='NewBlock'"
"query": "tm.event='eventCategory' AND eventType.eventAttribute='attributeValue'"
}
}
```

## ValidatorSetUpdates
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.

When validator set changes, ValidatorSetUpdates event is published. The
event carries a list of pubkey/power pairs. The list is the same
Tendermint receives from ABCI application (see [EndBlock
section](https://github.com/tendermint/spec/blob/master/spec/abci/abci.md#endblock) in
the ABCI spec).
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).

Response:
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",
"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"
}
]
}
}
"method": "subscribe",
"id": "0",
"params": {
"query": "tm.event='Tx' AND ethereum.recipient='hexAddress'"
}
}
```

where `hexAddress` is an EIP-55 address (eg: `0x1122334455667788990011223344556677889900`).

### 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
plugchaind 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 }
```
### 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.
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` |
## Ethereum JSON-RPC Events
Plug Chain 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"]}
```
### Ethereum Websocket
Since Plug Chain 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), Plug Chain 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
plugchaind 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}
```
2 changes: 1 addition & 1 deletion docs/get-started/mainnet.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ Depending on the snapshot height, lock the `plugchaind` binary version to use

| Block height | Database | plugchaind version | Download address |
| ---- | --------- | -------- | ----|
| 4451314 | goleveldb (default) | [v1.5](https://github.com/oracleNetworkProtocol/plugchain/releases/tag/v1.5.0) | [mainnet-4451314-20220614-goleveldb](https://snapshot-node-mainnet.oss-cn-hangzhou.aliyuncs.com/mainnet-4451314-20220614-goleveldb.zip) |
| 4879326 | goleveldb (default) | [v1.5](https://github.com/oracleNetworkProtocol/plugchain/releases/tag/v1.5.0) | [mainnet-4879326-20220712-goleveldb.zip](https://snapshot-node-mainnet.oss-cn-hangzhou.aliyuncs.com/mainnet-4879326-20220712-goleveldb.zip.zip) |

1. Download snapshot data

Expand Down
Loading

0 comments on commit 575900b

Please sign in to comment.