Subscribe

Event Subscription

To address different scenarios, subscription through polling and callback are both provided in Vite as two options.

Polling API requires client program to create a filter first, then polls subscribe_getFilterChanges method by filterId for new events. Remember, filter will expire if it has not been used for more than 5 minutes, in this case you should create a new filter for further subscription. You can also manually un-subscribe by calling subscribe_uninstallFilter method.

subscribe_newSnapshotBlocksFilter, subscribe_newAccountBlocksFilter, subscribe_newAccountBlocksByAddrFilter, subscribe_newOnroadBlocksByAddrFilter, subscribe_newLogsFilter, subscribe_uninstallFilter and subscribe_getFilterChanges are polling APIs.

Callback API registers new subscription through WebSocket connection. Afterwards, subscribed events will be returned in callbacks when they are generated. This kind of subscription will close automatically when the WebSocket connection is closed.

subscribe_newSnapshotBlocks, subscribe_newAccountBlocks, subscribe_newAccountBlocksByAddr, subscribe_newOnroadBlocksByAddr and subscribe_newLogs are callback APIs.

5 kinds of events are supported: new snapshot event, new transaction event, new transaction event on certain account, un-received transaction event on certain account and new log event. Event supports rollback. When rollback occurs, removed field in the event content is set to true.

To enable event subscription, you should

• Install a minimum 2.1.4 version of 'gvite' software
• Add "subscribe" into "PublicModules" and set "SubscribeEnabled":true in node_config.json

Usage Example

Subscribe via Callback

First, register a new subscription on address vite_f48f811a1800d9bde268e3d2eacdc4b4f8b9110e017bd7a76f by calling subscribe_subscribe method with name newLogs.

Copy { "jsonrpc": "2.0", "id": 1, "method": "subscribe_subscribe", "params": [ "newLogs", { "addrRange":{ "vite_f48f811a1800d9bde268e3d2eacdc4b4f8b9110e017bd7a76f":{ "fromHeight":"0", "toHeight":"0" } } } ] }

This will return a new subscription id 0x4b97e0674a5ebef942dbb07709c4a608

Copy { "jsonrpc":"2.0", "id":1, "result":"0x4b97e0674a5ebef942dbb07709c4a608" }

New logs will be sent to subscriber in callback's result field when generated

Copy { "jsonrpc":"2.0", "method":"subscribe_subscription", "params":{ "subscription":"0x4b97e0674a5ebef942dbb07709c4a608", "result":[ { "log":{ "topics":[ "aa65281f5df4b4bd3c71f2ba25905b907205fce0809a816ef8e04b4d496a85bb", "000000000000000000000000bb6ad02107a4422d6a324fd2e3707ad53cfed935" ], "data":"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAo=" }, "accountBlockHash":"23ea04b0dea4b9d0aa4d1f84b246b298a30faba753fa48303ad2deb29cd27f40", "accountHeight": "10", "addr":"vite_f48f811a1800d9bde268e3d2eacdc4b4f8b9110e017bd7a76f", "removed":false } ] } }

Subscription under callback is not necessarily cancelled explicitly, but will end once the connection is closed.

Subscribe via Polling

Create a log filter on address vite_f48f811a1800d9bde268e3d2eacdc4b4f8b9110e017bd7a76f

Copy { "jsonrpc": "2.0", "id": 1, "method": "subscribe_newLogsFilter", "params": [{ "addrRange":{ "vite_f48f811a1800d9bde268e3d2eacdc4b4f8b9110e017bd7a76f":{"fromHeight":"0","toHeight":"0"} } }] }

This will return a new filter id 0x61d780619649fb0872e1f94a40cec713

Copy { "jsonrpc": "2.0", "id": 1, "result": "0x61d780619649fb0872e1f94a40cec713" }

Now poll for new events periodically by filter id

Copy { "jsonrpc": "2.0", "id": 2, "method": "subscribe_getFilterChanges", "params": ["0x61d780619649fb0872e1f94a40cec713"] }

New logs generated after last poll will be returned

Copy { "jsonrpc": "2.0", "id": 2, "result": { "result": [ { "log": { "topics": [ "96a65b1cd08da045d0318cafda7b8c8436092851d5a4b7e75054c005a296e3fb", "0000000000000000000000ab24ef68b84e642c0ddca06beec81c9acb1977bb00" ], "data": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAHsAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAN4Lazp2QAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAF" }, "accountBlockHash": "802b82821ec52bdadb8b79a53363bf2f90645caef95a83c34af20c640a6c320b", "addr": "vite_f48f811a1800d9bde268e3d2eacdc4b4f8b9110e017bd7a76f", "removed": false } ], "subscription": "0x61d780619649fb0872e1f94a40cec713" } }

You should cancel subscription by calling subscribe_uninstallFilter explicitly under polling mode

Copy { "jsonrpc": "2.0", "id": 17, "method": "subscribe_uninstallFilter", "params": ["0x61d780619649fb0872e1f94a40cec713"] }

Log Completion

Accidental connection interrupt may cause subscription closed. Under this situation, historical snapshot blocks, account blocks or un-received blocks can be fetched by ledger_getSnapshotBlocks, ledger_getBlocksByHeight or onroad_getOnroadBlocksByAddress, while historical logs can be retrieved by subscribe_getLogs method.

For example, in order to re-subscribe to new snapshot event, you should call subscribe_newSnapshotBlocks to resume subscription first, then obtain latest snapshot block height by ledger_getSnapshotChainHeight, finally call ledger_getSnapshotBlocks to get all snapshot blocks missed.

subscribe_newSnapshotBlocksFilter

Create a filter for polling for new snapshot blocks by passing into subscribe_getFilterChanges as parameter

• Returns:
  • string filterId

subscribe_newAccountBlocksFilter

Create a filter for polling for new transactions on all accounts by passing into subscribe_getFilterChanges as parameter

• Returns:
  • string filterId

subscribe_newAccountBlocksByAddrFilter

Create a filter for polling for new transactions on specified account by passing into subscribe_getFilterChanges as parameter

• Parameters:

  • string address: Address of account

• Returns:

  • string filterId

subscribe_newOnroadBlocksByAddrFilter

Create a filter for polling for un-received transactions on specified account by passing into subscribe_getFilterChanges as parameter. The events include new un-received transaction, transaction is received and un-received transaction is rolled back.

• Parameters:

  • string address: Address of account

• Returns:

  • string filterId

subscribe_newLogsFilter

Create a filter for polling for new logs by passing into subscribe_getFilterChanges as parameter

• Parameters:

  • FilterParam
    1. addrRange: map[Address]Range Query logs of the specified account address with given query range. Addresses and height ranges are filled in a map. At least one address must be specified.
    2. topics: [][]Hash Subscribed topics, see below example for usage.

Range

1. fromHeight: uint64 Start height. 0 means starting from the first block
2. toHeight: uint64 End height. 0 means the latest block

Copy Topic examples： {} matches all logs {{A}} matches the logs having "A" as the first element {{},{B}} matches the logs having "B" as the second element {{A},{B}} matches the logs having "A" as the first element and "B" as the second element {{A,B},{C,D}} matches the logs having "A" or "B" as the first element, and "C" or "D" as the second element

subscribe_uninstallFilter

Cancel event polling by removing specified filter

• Parameters:

  • string: filterId

• Returns:

  • bool result

subscribe_getFilterChanges

Poll for new events. The content of return value depends on the specific subscription. If no event is generated since last poll, an empty array will be returned.

• Parameters:

  • string: filterId

• Return in subscribe_newSnapshotBlocksFilter:

  • subscription: string filterId
  • result: Array<SnapshotBlocksMsg>
    1. hash: Hash The hash of snapshot block
    2. heightStr: string The height of snapshot block
    3. removed: bool Whether the block was rolled back. New transaction will be marked as false

• Return in subscribe_newAccountBlocksFilter:
  • subscription: string filterId
  • result: Array<AccountBlocksMsg>
    1. hash: Hash The hash of account block
    2. removed: bool Whether the block was rolled back. New transaction will be marked as false

• Return in subscribe_newAccountBlocksByAddrFilter:
  • subscription: string filterId
  • result: Array<AccountBlocksWithHeightMsg>
    1. hash: Hash The hash of account block
    2. heightStr: string The height of account block
    3. removed: bool Whether the block was rolled back. New transaction will be marked as false

• Return in subscribe_newOnroadBlocksByAddrFilter:
  • subscription: string filterId
  • result: Array<OnroadMsg>
    1. hash: Hash The hash of account block
    2. closed: bool Whether the transaction was received
    3. removed: bool Whether the un-received transaction was rolled back

• Return in subscribe_newLogsFilter:
  • subscription: string filterId
  • result: Array<LogsMsg>
    1. accountBlockHash: Hash The hash of account block
    2. addr: Address Account address
    3. log: VmLog Log
    4. removed: bool Whether the log was rolled back. New log will be marked as false

subscribe_newSnapshotBlocks

Start listening for new snapshot blocks via callback

• Returns:

  • string Subscription id

• Callback:
  Object

  • subscription: string Subscription id
  • result: Array<SnapshotBlocksMsg>
    1. hash: Hash The hash of snapshot block
    2. height: uint64 The height of snapshot block
    3. removed: bool Whether the block was rolled back. New transaction will be marked as false

subscribe_newAccountBlocks

Start listening for new transactions via callback

• Returns:

  • string Subscription id

• Callback:
  Object

  • subscription: string Subscription id
  • result: Array<AccountBlocksMsg>
    1. hash: Hash The hash of account block
    2. removed: bool Whether the block was rolled back. New transaction will be marked as false

subscribe_newAccountBlocksByAddr

Start listening for new transactions on specified account via callback

• Parameters:

  • address Account address

• Returns:

  • string Subscription id

• Callback:
  Object

  • subscription: string Subscription id
  • result: Array<AccountBlocksWithHeightMsg>
    1. hash: Hash The hash of account block
    2. heightStr: string The height of account block
    3. removed: bool Whether the block was rolled back. New transaction will be marked as false

subscribe_newOnroadBlocksByAddr

Start listening for un-received transactions on specified account via callback

• Parameters:

  • address Account address

• Returns:

  • string Subscription id

• Callback:
  Object

  • subscription: string Subscription id
  • result: Array<OnroadMsg>
    1. hash: Hash The hash of account block
    2. closed: bool Whether the transaction was received
    3. removed: bool Whether the un-received transaction was rolled back

subscribe_newLogs

Start listening for new logs via callback

• Parameters:

  • FilterParam
    1. addrRange: map[Address]Range Query logs of the specified account address with given query range. Addresses and height ranges are filled in a map. At least one address must be specified.
    2. topics: [][]Hash Subscribed topics, see example in subscribe_newLogsFilter for usage.

Range

1. fromHeight: uint64 Start height. 0 means starting from the first block
2. toHeight: uint64 End height. 0 means the latest block

• Returns:

  • string Subscription id

• Callback:
  Object

  • subscription: string Subscription id
  • result: Array<LogsMsg>
    1. accountBlockHash: Hash The hash of account block
    2. addr: Address Account address
    3. log: VmLog Log
    4. removed: bool Whether the log was rolled back. New log will be marked as false

subscribe_getLogs

Return historical logs

• Parameters:

  • FilterParam
    1. addrRange: map[Address]Range Query logs of the specified account address with given query range. Addresses and height ranges are filled in a map. At least one address must be specified.
    2. topics: [][]Hash Subscribed topics, see example in subscribe_newLogsFilter for usage.

Range

1. fromHeight: uint64 Start height. 0 means starting from the first block
2. toHeight: uint64 End height. 0 means the latest block

• Returns:
  • result: Array<LogsMsg>
    1. accountBlockHash: Hash The hash of account block
    2. addr: Address Account address
    3. log: VmLog Log
    4. removed: bool Whether the log was rolled back. New log will be marked as false