Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs add events and msg #69

Merged
merged 2 commits into from
Jul 25, 2022
Merged

docs add events and msg #69

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2a52782
update snapshot height
seedlings-calm Jul 20, 2022
693aba4
add events
seedlings-calm Jul 25, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 0 additions & 57 deletions docs/endpoints/action.md
View file
Open in desktop

This file was deleted.

37 changes: 31 additions & 6 deletions docs/endpoints/grpc-rest.md
View file
Open in desktop
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
View file
Open in desktop
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
View file
Open in desktop
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