Subscription API

Vite node provides two kinds of subscription RPC API: Polling API and Websocket API

• Polling API returns a subscription filter. The client should periodically call subscribe_getChangesByFilterId with the filter id to request for new events. New events that were triggered since last request will be returned, otherwise server returns null.

Note: Filter will expire if not used for more than 5 minutes. If client does not send request for more than 5 minutes, subscription will close. Client must re-subscribe to the event in this situation.

The following API are Polling API:

• subscribe_newSnapshotBlockFilter
• subscribe_newAccountBlockFilter
• subscribe_newAccountBlockByAddressFilter
• subscribe_newUnreceivedBlockByAddressFilter
• subscribe_newVmLogFilter
• subscribe_uninstallFilter
• subscribe_getChangesByFilterId

• Websocket API subscribes to new events through websocket connection. When new event is triggered, it will be automatically pushed to client through callbacks. Subscription will end once the connection is broken.

Note: Websocket API relies on "ws" or "wss" RPC endpoint. It cannot be used with HTTP.

subscribe_subscribe is Websocket API. It support for the following events:

• newSnapshotBlock
• newAccountBlock
• newAccountBlockByAddress
• newUnreceivedBlockByAddress
• newVmLog

Note that events might be reverted. If an event was reverted, the removed field of the event is marked true.

Add "subscribe" namespace in "PublicModules" and set "SubscribeEnabled":true in node_config.json to enable subscription API

Topics

Topics are 32 bytes event signature or indexed parameters of smart contract. For a non-anonymous Solidity++ event, the first topic is the event signature, and the rest (if has) are encoded indexed fields.

Topics are often used to search for certain event logs.

Topic Matching Rules

• [] matches all event logs
• [[A]] matches event logs having "A" as the first topic
• [[], [B]] matches event logs having "B" as the second topic
• [[A], [B]] matches event logs having "A" as the first topic and "B" as the second topic
• [[A, B], [C, D]] matches event logs having "A" or "B" as the first topic, and "C" or "D" as the second topic
• [[A, B], [C, D], [E]] matches event logs having "A" or "B" as the first topic, "C" or "D" as the second topic, and "E" as the third topic
• [[T11, T12, ... , T1M], [T21, T22, ... , T2M], ... , [TN1, TN2, ... , TNM]] matches event logs having T₁₁, T₁₂ ... or T_1M as the first topic, T₂₁, T₂₂ ... or T_2M as the second topic, ... and T_N1, T_N2 ... or T_NM as the N topic (N <= 4)

Note: Solidity++ allows maximum 4 topics including one event signature and three indexed parameters

Tips

Use an SDK e.g. Vite.js to generate topic filters

Example

Assume address "vite_f48f811a1800d9bde268e3d2eacdc4b4f8b9110e017bd7a76f" is a smart contract and we want to obtain its event logs.

Using Websocket API

Create a newVmLog subscription on the contract address by calling subscribe_subscribe with event type newVmLog.

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

It returns a subscription id "0x4b97e0674a5ebef942dbb07709c4a608"

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

When a new event log is generated, it will be returned in callback named subscribe_subscription

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

Subscription Broken

Broken network connection may cause websocket subscription accidentally closed. In this situation, you should resume the subscription first, and in order to get the missing blocks or events, you need to call the corresponding Ledger API ledger_getSnapshotBlocks, ledger_getAccountBlocks, ledger_getUnreceivedBlocksByAddress or ledger_getVmLogsByFilter to fetch the missing blocks during the time.

Using Polling API

First create a filter for the contract address

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

It returns a filter id "0x61d780619649fb0872e1f94a40cec713"

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

We call subscribe_getChangesByFilterId to poll for new events with the filter id

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

If there are new event logs generated since last polling, the logs will be returned

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

Note that if subscribe_getChangesByFilterId is not be called for more than 5 minutes, the filter will expire. Always remember to call the API within every 5 minutes to keep it alive.

In addition, we can also call subscribe_uninstallFilter to stop a filter if necessary.

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

---

subscribe_newSnapshotBlockFilter

Create a filter for new snapshot blocks.

• Parameters: none

• Returns:

  • string Filter Id

subscribe_newAccountBlockFilter

Create a filter for new transactions (account blocks) for all accounts

• Parameters: none

• Returns:

  • string Filter Id

subscribe_newAccountBlockByAddressFilter

Create a filter for new account blocks by address

• Parameters:

  • address: address Address of account

• Returns:

  • string Filter Id

subscribe_newUnreceivedBlockByAddressFilter

Create a filter for new unreceived blocks by address

• Parameters:

  • address: address Address of account

• Returns:

  • string Filter Id

subscribe_newVmLogFilter

Create a filter for new event logs

• Parameters:

  • VmLogFilterParam
    • addressHeightRange: map<address, Range> Map of address and account block height range. At least one address should be specified.
      • fromHeight: uint64 string Start height. 0 means starting from the latest account block
      • toHeight: uint64 string End height. 0 means no ending account block height
    • topics: Array<Array<hash>> Event topics to match. See here for details.

• Returns:

  • string Filter Id

subscribe_uninstallFilter

Uninstall the filter and stop subscription

• Parameters:

  • string Filter id

• Returns:

  • bool true means the subscription is stopped

subscribe_getChangesByFilterId

Poll for new snapshot blocks, account blocks, unreceived blocks, or event logs by filter id. Returns empty array if no update.

• Parameters:

  • string Filter id

• Returns for case subscribe_newSnapshotBlockFilter:

  • subscription: string Filter id
  • result: Array<SnapshotBlockMessage>
    • hash: hash Hash of snapshot block
    • height: uint64 string Height of snapshot block
    • removed: bool true means the snapshot block was reverted. For new snapshot blocks, the field is false

• Returns for case subscribe_newAccountBlockFilter:

  • subscription: string Filter id
  • result: Array<AccountBlockMessage>
    • hash: hash Hash of account block
    • removed: bool true means the account block was reverted. For new account block, the field is false

• Returns for case subscribe_newAccountBlockByAddressFilter:

  • subscription: string Filter id
  • result: Array<AccountBlockWithHeightMessage>
    • hash: hash Hash of account block
    • height: uint64 string Height of account block
    • removed: bool true means the account block was reverted. For new account block, the field is false

• Returns for case subscribe_newUnreceivedBlockByAddressFilter:

  • subscription: string Filter id
  • result: Array<UnreceivedBlockMessage>
    • hash: hash Hash of unreceived block
    • received: bool true means the block has been received
    • removed: bool true means the unreceived block was reverted. For new unreceived blocks, both removed and received is false.

• Returns for case subscribe_newVmLogFilter:

  • subscription: string Filter id
  • result: Array<VmlogMessage>
    • accountBlockHash: hash Hash of account block
    • accountBlockHeight: uint64 string Height of account block
    • address: address Address of account
    • vmlog: VmLog Event logs
      • topics: Array<hash> Event signature and indexed fields
      • data: base64 Encoded non-indexed parameters in base64 format
    • removed: bool true means the event log was reverted

subscribe_subscribe

This Websocket API should be used with the following event types. A single callback returns up to 128 blocks or logs.

newSnapshotBlock

Subscribe to new snapshot blocks. New snapshot blocks will be returned in callback

• Parameters: none

• Returns:

  • string Subscription id

• Callback:

  • subscription: string Subscription id
  • result: Array<SnapshotBlockMessage>
    • hash: hash Hash of snapshot block
    • height: uint64 string Height of snapshot block
    • removed: bool true means the snapshot block was reverted. For new snapshot block, the field is false

newAccountBlock

Subscribe to new account blocks. New account blocks will be returned in callback

• Parameters: none

• Returns:

  • string Subscription id

• Callback:

  • subscription: string Subscription id
  • result: Array<AccountBlockMessage>
    • hash: hash Hash of account block
    • removed: bool true means the account block was reverted. For new account block, the field is false

newAccountBlockByAddress

Subscribe to new account blocks by address. New account blocks will be returned in callback

• Parameters:

  • address Address of account

• Returns:

  • string Subscription id

• Callback:

  • subscription: string Subscription id
  • result: Array<AccountBlockWithHeightMessage>
    • hash: hash Hash of account block
    • height: uint64 string Height of account block
    • removed: bool true means the account block was reverted. For new account block, the field is false

newUnreceivedBlockByAddress

Subscribe to unreceived blocks by address. New unreceived blocks will be returned in callback

• Parameters:

  • address Address of account

• Returns:

  • string Subscription id

• Callback:

  • subscription: string Subscription id
  • result: Array<UnreceivedBlockMessage>
    • hash: string hash Hash of unreceived block
    • received: bool true means the block was received
    • removed: bool true means the unreceived block was reverted. For new unreceived blocks, both removed and received is false.

newVmLog

Subscribe to smart contract event logs. New event logs will be returned in callback

• Parameters:

  • VmLogFilterParam
    • addressHeightRange: map<address, Range> Map of address and account block height range. At least one address should be specified.
      • fromHeight: uint64 string Start height. 0 means starting from the latest account block
      • toHeight: uint64 string End height. 0 means no ending account block height
    • topics: Array<Array<hash>> Event topics to match. See here for details.

• Returns:

  • string Subscription id

• Callback:

  • subscription: string Subscription id
  • result: Array<VmlogMessage>
    • accountBlockHash: hash Hash of account block
    • accountBlockHeight: uint64 string Height of account block
    • address: address Address of account
    • vmlog: VmLog Event logs
      • topics: Array<hash> Event signature and indexed fields
      • data: base64 Encoded non-indexed parameters in base64 string
    • removed: bool true means the event log was reverted