|
| 1 | +# Tendermint RPC |
| 2 | + |
| 3 | +[Tendermint RPC](https://docs.tendermint.com/v0.34/rpc/#) can be used to query application's state and/or [subscribe to Tendermint WebSocket events](https://docs.tendermint.com/v0.34/tendermint-core/subscription.html). |
| 4 | +The default RPC listen address is tcp://0.0.0.0:26657. See the [docs](https://docs.tendermint.com/v0.34/rpc/#) to learn how to configure and customize. |
| 5 | + |
| 6 | +## WebSocket Events |
| 7 | + |
| 8 | +Full list of Tendermint WebSocket events can be found [here](https://pkg.go.dev/github.com/tendermint/tendermint/types#pkg-constants). |
| 9 | + |
| 10 | +### Subscribe |
| 11 | + |
| 12 | +Subscribing to Tendermint WebSocket events can be done using any WS clients like [wscat](https://github.com/websockets/wscat), [Postman](https://www.postman.com/), etc. The following is an example of subscribing to a new `tx` (transaction) event using wscat: |
| 13 | + |
| 14 | +1. Connect to the server: |
| 15 | + |
| 16 | +```bash |
| 17 | +wscat -c ws://<node-ip>:<port>/websocket |
| 18 | +``` |
| 19 | + |
| 20 | +In cases of [Test Net](https://github.com/zigbee-alliance/distributed-compliance-ledger/blob/master/deployment/persistent_chains/testnet-2.0/testnet-2.0-csa-endpoints.md) and [Main Net](https://github.com/zigbee-alliance/distributed-compliance-ledger/blob/master/deployment/persistent_chains/main-net/main-net-csa-endpoints.md) observer nodes, `node-ip`s are `on.test-net.dcl.csa-iot.org` and `on.dcl.csa-iot.org`, respectively, having the same ports `26657` |
| 21 | + |
| 22 | +2. Subscribe to the `tx` event in the wscat command line (refer to the [docs](https://docs.tendermint.com/v0.34/rpc/#) to learn the syntax): |
| 23 | + |
| 24 | +```json |
| 25 | +{"jsonrpc":"2.0","method":"subscribe","id":0,"params":{"query":"tm.event='Tx'"}} |
| 26 | +``` |
| 27 | + |
| 28 | +You should get the following response if everything is OK: |
| 29 | + |
| 30 | +```json |
| 31 | +{ |
| 32 | + "jsonrpc": "2.0", |
| 33 | + "id": 0, |
| 34 | + "result": {} |
| 35 | +} |
| 36 | +``` |
| 37 | + |
| 38 | +3. Wait for the transaction |
| 39 | + |
| 40 | +Consider performing any transaction in another terminal tab to broadcast a `tx` event for the test purposes. For example, the following transaction can be sent in case of a local pool (for Test Net or Main Net pools `dcld` needs to be configured properly and write access needs to be given, see https://github.com/zigbee-alliance/distributed-compliance-ledger/blob/master/docs/how-to.md#cli-configuration) |
| 41 | + |
| 42 | +```bash |
| 43 | +dcld tx auth propose-add-account \ |
| 44 | +--address=cosmos1sdg5vkpz9urcemmw67lnxvzhhuveqe6v70ex2l \ |
| 45 | +--pubkey="{\"@type\":\"/cosmos.crypto.secp256k1.PubKey\",\"key\":\"A4m98FT/tgsMWZuVBlavWmawwXrvv/nUMhDlU8QsHlOM\"}" \ |
| 46 | +--roles=NodeAdmin \ |
| 47 | +--from=jack |
| 48 | +``` |
| 49 | + |
| 50 | +4. Confirm that the subscriber received the event. For the transaction example above: |
| 51 | + |
| 52 | +```json |
| 53 | +{ |
| 54 | + "jsonrpc": "2.0", |
| 55 | + "id": 0, |
| 56 | + "result": { |
| 57 | + "query": "tm.event='Tx'", |
| 58 | + "data": { |
| 59 | + "type": "tendermint/event/Tx", |
| 60 | + "value": { |
| 61 | + "TxResult": { |
| 62 | + "height": "1684", |
| 63 | + "tx": "CocCCoQCCkgvemlnYmVlYWxsaWFuY2UuZGlzdHJpYnV0ZWRjb21wbGlhbmNlbGVkZ2VyLmRjbGF1dGguTXNnUHJvcG9zZUFkZEFjY291bnQStwEKLWNvc21vczE0cG1nMnhnMzd0enI2a3VxNHV4dnp3a3p1ZnRldGQ3dDhhMnN1dRItY29zbW9zMXNkZzV2a3B6OXVyY2VtbXc2N2xueHZ6aGh1dmVxZTZ2NzBleDJsGkYKHy9jb3Ntb3MuY3J5cHRvLnNlY3AyNTZrMS5QdWJLZXkSIwohA4m98FT/tgsMWZuVBlavWmawwXrvv/nUMhDlU8QsHlOMIglOb2RlQWRtaW44lo/YoAYSWApQCkYKHy9jb3Ntb3MuY3J5cHRvLnNlY3AyNTZrMS5QdWJLZXkSIwohApEHaI8+Wj64IQdR/WZDMaWHNd53+9G19zNcWjrAiXMbEgQKAggBGAISBBDAmgwaQJCg0T8phCo70H7VpL2M1C0kQix4LeVOjkXWgK3EHmFobXkBGLH2jJiKTHakVWUO2yj2Tdpc4YoTDw2eKe6UZj8=", |
| 64 | + "result": { |
| 65 | + "data": "CkoKSC96aWdiZWVhbGxpYW5jZS5kaXN0cmlidXRlZGNvbXBsaWFuY2VsZWRnZXIuZGNsYXV0aC5Nc2dQcm9wb3NlQWRkQWNjb3VudA==", |
| 66 | + "log": "[{\"events\":[{\"type\":\"message\",\"attributes\":[{\"key\":\"action\",\"value\":\"/zigbeealliance.distributedcomplianceledger.dclauth.MsgProposeAddAccount\"}]}]}]", |
| 67 | + "gas_used": "25760", |
| 68 | + "events": [ |
| 69 | + { |
| 70 | + "type": "tx", |
| 71 | + "attributes": [ |
| 72 | + { |
| 73 | + "key": "YWNjX3NlcQ==", |
| 74 | + "value": "Y29zbW9zMTRwbWcyeGczN3R6cjZrdXE0dXh2endrenVmdGV0ZDd0OGEyc3V1LzI=", |
| 75 | + "index": true |
| 76 | + } |
| 77 | + ] |
| 78 | + }, |
| 79 | + { |
| 80 | + "type": "tx", |
| 81 | + "attributes": [ |
| 82 | + { |
| 83 | + "key": "c2lnbmF0dXJl", |
| 84 | + "value": "a0tEUlB5bUVLanZRZnRXa3ZZelVMU1JDTEhndDVVNk9SZGFBcmNRZVlXaHRlUUVZc2ZhTW1JcE1kcVJWWlE3YktQWk4ybHpoaWhNUERaNHA3cFJtUHc9PQ==", |
| 85 | + "index": true |
| 86 | + } |
| 87 | + ] |
| 88 | + }, |
| 89 | + { |
| 90 | + "type": "message", |
| 91 | + "attributes": [ |
| 92 | + { |
| 93 | + "key": "YWN0aW9u", |
| 94 | + "value": "L3ppZ2JlZWFsbGlhbmNlLmRpc3RyaWJ1dGVkY29tcGxpYW5jZWxlZGdlci5kY2xhdXRoLk1zZ1Byb3Bvc2VBZGRBY2NvdW50", |
| 95 | + "index": true |
| 96 | + } |
| 97 | + ] |
| 98 | + } |
| 99 | + ] |
| 100 | + } |
| 101 | + } |
| 102 | + } |
| 103 | + }, |
| 104 | + "events": { |
| 105 | + "tm.event": [ |
| 106 | + "Tx" |
| 107 | + ], |
| 108 | + "tx.hash": [ |
| 109 | + "AF831BBE5BF23545447BB2D1B65E49F99B5A22035F7E1FEB3E4BDC8D243F4115" |
| 110 | + ], |
| 111 | + "tx.height": [ |
| 112 | + "1684" |
| 113 | + ], |
| 114 | + "tx.acc_seq": [ |
| 115 | + "cosmos14pmg2xg37tzr6kuq4uxvzwkzuftetd7t8a2suu/2" |
| 116 | + ], |
| 117 | + "tx.signature": [ |
| 118 | + "kKDRPymEKjvQftWkvYzULSRCLHgt5U6ORdaArcQeYWhteQEYsfaMmIpMdqRVZQ7bKPZN2lzhihMPDZ4p7pRmPw==" |
| 119 | + ], |
| 120 | + "message.action": [ |
| 121 | + "/zigbeealliance.distributedcomplianceledger.dclauth.MsgProposeAddAccount" |
| 122 | + ] |
| 123 | + } |
| 124 | + } |
| 125 | +} |
| 126 | +``` |
| 127 | + |
| 128 | +### Decoding The Transaction String |
| 129 | + |
| 130 | +The details of transaction payload encoding can be found [here](https://docs.cosmos.network/main/core/encoding#transaction-encoding). Thus, the transaction payload/string in the example above can be decoded as follows: |
| 131 | + |
| 132 | +```bash |
| 133 | +dcld tx decode CocCCoQCCkgvemlnYmVlYWxsaWFuY2UuZGlzdHJpYnV0ZWRjb21wbGlhbmNlbGVkZ2VyLmRjbGF1dGguTXNnUHJvcG9zZUFkZEFjY291bnQStwEKLWNvc21vczE0cG1nMnhnMzd0enI2a3VxNHV4dnp3a3p1ZnRldGQ3dDhhMnN1dRItY29zbW9zMXNkZzV2a3B6OXVyY2VtbXc2N2xueHZ6aGh1dmVxZTZ2NzBleDJsGkYKHy9jb3Ntb3MuY3J5cHRvLnNlY3AyNTZrMS5QdWJLZXkSIwohA4m98FT/tgsMWZuVBlavWmawwXrvv/nUMhDlU8QsHlOMIglOb2RlQWRtaW44lo/YoAYSWApQCkYKHy9jb3Ntb3MuY3J5cHRvLnNlY3AyNTZrMS5QdWJLZXkSIwohApEHaI8+Wj64IQdR/WZDMaWHNd53+9G19zNcWjrAiXMbEgQKAggBGAISBBDAmgwaQJCg0T8phCo70H7VpL2M1C0kQix4LeVOjkXWgK3EHmFobXkBGLH2jJiKTHakVWUO2yj2Tdpc4YoTDw2eKe6UZj8= |
| 134 | +``` |
| 135 | + |
| 136 | +which gives the result: |
| 137 | + |
| 138 | +```json |
| 139 | +{"body":{"messages":[{"@type":"/zigbeealliance.distributedcomplianceledger.dclauth.MsgProposeAddAccount","signer":"cosmos14pmg2xg37tzr6kuq4uxvzwkzuftetd7t8a2suu","address":"cosmos1sdg5vkpz9urcemmw67lnxvzhhuveqe6v70ex2l","pubKey":{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"A4m98FT/tgsMWZuVBlavWmawwXrvv/nUMhDlU8QsHlOM"},"roles":["NodeAdmin"],"vendorID":0,"info":"","time":"1679165334"}],"memo":"","timeout_height":"0","extension_options":[],"non_critical_extension_options":[]},"auth_info":{"signer_infos":[{"public_key":{"@type":"/cosmos.crypto.secp256k1.PubKey","key":"ApEHaI8+Wj64IQdR/WZDMaWHNd53+9G19zNcWjrAiXMb"},"mode_info":{"single":{"mode":"SIGN_MODE_DIRECT"}},"sequence":"2"}],"fee":{"amount":[],"gas_limit":"200000","payer":"","granter":""}},"signatures":["kKDRPymEKjvQftWkvYzULSRCLHgt5U6ORdaArcQeYWhteQEYsfaMmIpMdqRVZQ7bKPZN2lzhihMPDZ4p7pRmPw=="]} |
| 140 | +``` |
| 141 | + |
| 142 | +Detailed info about subscribing can be found [here](https://docs.tendermint.com/v0.34/rpc/#/Websocket/subscribe). |
| 143 | + |
| 144 | +### Unsubscribe |
| 145 | + |
| 146 | +Unsubscribing is done using a similar command to [subscription](#subscribe): |
| 147 | + |
| 148 | +```json |
| 149 | +{"jsonrpc":"2.0","method":"unsubscribe","id":0,"params":{"query":"tm.event='Tx'"}} |
| 150 | +``` |
| 151 | + |
| 152 | +## Querying Application Components |
| 153 | + |
| 154 | +There are many endpoints available to query various types of information about the nodes. For example, a transaction can be fetched by its hash using any web client like curl as follows: |
| 155 | + |
| 156 | +```bash |
| 157 | +curl -X GET "http://<node-ip>:<port>/tx?hash=0x74504B24ED59A424E436656E5E9A11034C7A7C7ED3BE7C3CDEA1ED387EF62967&prove=true" -H "accept: application/json" |
| 158 | +``` |
| 159 | + |
| 160 | +It returns a response as follows: |
| 161 | + |
| 162 | +```json |
| 163 | +{ |
| 164 | + "jsonrpc": "2.0", |
| 165 | + "id": -1, |
| 166 | + "result": { |
| 167 | + "hash": "74504B24ED59A424E436656E5E9A11034C7A7C7ED3BE7C3CDEA1ED387EF62967", |
| 168 | + "height": "1692", |
| 169 | + "index": 0, |
| 170 | + "tx_result": { |
| 171 | + "code": 0, |
| 172 | + "data": "CkoKSC96aWdiZWVhbGxpYW5jZS5kaXN0cmlidXRlZGNvbXBsaWFuY2VsZWRnZXIuZGNsYXV0aC5Nc2dBcHByb3ZlQWRkQWNjb3VudA==", |
| 173 | + "log": "[{\"events\":[{\"type\":\"message\",\"attributes\":[{\"key\":\"action\",\"value\":\"/zigbeealliance.distributedcomplianceledger.dclauth.MsgApproveAddAccount\"}]}]}]", |
| 174 | + "info": "", |
| 175 | + "gas_wanted": "0", |
| 176 | + "gas_used": "32100", |
| 177 | + "events": [ |
| 178 | + { |
| 179 | + "type": "tx", |
| 180 | + "attributes": [ |
| 181 | + { |
| 182 | + "key": "YWNjX3NlcQ==", |
| 183 | + "value": "Y29zbW9zMXlnejM3am4wdmFkdmV2M3dyODduZ2RkdDl6cG1hcHd3ZzhwMDRrLzQ=", |
| 184 | + "index": true |
| 185 | + } |
| 186 | + ] |
| 187 | + }, |
| 188 | + { |
| 189 | + "type": "tx", |
| 190 | + "attributes": [ |
| 191 | + { |
| 192 | + "key": "c2lnbmF0dXJl", |
| 193 | + "value": "VHltY0YwbE9VNzJTUW1VRDg4ZEdmdldMOUxXcWYzRXgwYldjNEtLdExKSkdoV2hqdTJkbUs1L3BrNHFlQjcwL2wvSm80Mit3MlNoUHc4WUpGemR4M2c9PQ==", |
| 194 | + "index": true |
| 195 | + } |
| 196 | + ] |
| 197 | + }, |
| 198 | + { |
| 199 | + "type": "message", |
| 200 | + "attributes": [ |
| 201 | + { |
| 202 | + "key": "YWN0aW9u", |
| 203 | + "value": "L3ppZ2JlZWFsbGlhbmNlLmRpc3RyaWJ1dGVkY29tcGxpYW5jZWxlZGdlci5kY2xhdXRoLk1zZ0FwcHJvdmVBZGRBY2NvdW50", |
| 204 | + "index": true |
| 205 | + } |
| 206 | + ] |
| 207 | + } |
| 208 | + ], |
| 209 | + "codespace": "" |
| 210 | + }, |
| 211 | + "tx": "CrMBCrABCkgvemlnYmVlYWxsaWFuY2UuZGlzdHJpYnV0ZWRjb21wbGlhbmNlbGVkZ2VyLmRjbGF1dGguTXNnQXBwcm92ZUFkZEFjY291bnQSZAotY29zbW9zMXlnejM3am4wdmFkdmV2M3dyODduZ2RkdDl6cG1hcHd3ZzhwMDRrEi1jb3Ntb3Mxc2RnNXZrcHo5dXJjZW1tdzY3bG54dnpoaHV2ZXFlNnY3MGV4MmwgwY/YoAYSWApQCkYKHy9jb3Ntb3MuY3J5cHRvLnNlY3AyNTZrMS5QdWJLZXkSIwohAv+avtRfIGPCkbToqtJJUO8yX8NsAeW4MPkg3ADUEM0zEgQKAggBGAQSBBDAmgwaQE8pnBdJTlO9kkJlA/PHRn71i/S1qn9xMdG1nOCirSySRoVoY7tnZiuf6ZOKnge9P5fyaONvsNkoT8PGCRc3cd4=", |
| 212 | + "proof": { |
| 213 | + "root_hash": "BB905252C0221042D19C66A8215A7ABF53873C773975E56BEAF946C3B1DC2512", |
| 214 | + "data": "CrMBCrABCkgvemlnYmVlYWxsaWFuY2UuZGlzdHJpYnV0ZWRjb21wbGlhbmNlbGVkZ2VyLmRjbGF1dGguTXNnQXBwcm92ZUFkZEFjY291bnQSZAotY29zbW9zMXlnejM3am4wdmFkdmV2M3dyODduZ2RkdDl6cG1hcHd3ZzhwMDRrEi1jb3Ntb3Mxc2RnNXZrcHo5dXJjZW1tdzY3bG54dnpoaHV2ZXFlNnY3MGV4MmwgwY/YoAYSWApQCkYKHy9jb3Ntb3MuY3J5cHRvLnNlY3AyNTZrMS5QdWJLZXkSIwohAv+avtRfIGPCkbToqtJJUO8yX8NsAeW4MPkg3ADUEM0zEgQKAggBGAQSBBDAmgwaQE8pnBdJTlO9kkJlA/PHRn71i/S1qn9xMdG1nOCirSySRoVoY7tnZiuf6ZOKnge9P5fyaONvsNkoT8PGCRc3cd4=", |
| 215 | + "proof": { |
| 216 | + "total": "1", |
| 217 | + "index": "0", |
| 218 | + "leaf_hash": "u5BSUsAiEELRnGaoIVp6v1OHPHc5deVr6vlGw7HcJRI=", |
| 219 | + "aunts": [ |
| 220 | + |
| 221 | + ] |
| 222 | + } |
| 223 | + } |
| 224 | + } |
| 225 | +} |
| 226 | +``` |
| 227 | + |
| 228 | +The `proof` property can be excluded from the response by setting the `prove` property in the query string to `false` (or just by omitting it). |
0 commit comments