Subscribe to JSON-RPC Real-Time Events

Sui fullnode supports publish / subscribe using JSON-RPC notifications via the WebSocket API. This service allows clients to filter and subscribe to a real-time event stream generated from Move or from the Sui network.

The client can provide an event filter to narrow the scope of events. For each event that matches the filter, a notification with the event data and subscription ID is returned to the client.

Events

List of events emitted by the Sui node.

Move event

Attributes : packageId, transactionModule, sender, type, fields, bcs
Example :

{
  "moveEvent": {
    "packageId": "0x0000000000000000000000000000000000000002",
    "transactionModule": "devnet_nft",
    "sender": "0x70613f4f17ae1363f7a7e7251daab5c5b06f68c1",
    "type": "0x2::devnet_nft::MintNFTEvent",
    "fields": {
      "creator": "0x70613f4f17ae1363f7a7e7251daab5c5b06f68c1",
      "name": "Example NFT",
      "object_id": "0x497913a47dc0028a85f24c70d825991b71c60001"
    },
    "bcs": "SXkTpH3AAoqF8kxw2CWZG3HGAAFwYT9PF64TY/en5yUdqrXFsG9owQtFeGFtcGxlIE5GVA=="
  }
}

Publish

Attributes: sender, packageId
Example:

{
  "publish": {
    "sender": "0x70613f4f17ae1363f7a7e7251daab5c5b06f68c1",
    "packageId": "0x2d052c9de3dd02f28ec0f8e4dfdee175a5c597c3"
  }
}

Transfer object

Attributes: packageId, transactionModule, sender, recipient, objectId, version, type
Example:

{
  "transferObject": {
    "packageId": "0x0000000000000000000000000000000000000002",
    "transactionModule": "native",
    "sender": "0x70613f4f17ae1363f7a7e7251daab5c5b06f68c1",
    "recipient": {
      "AddressOwner": "0x741a9a7ea380aed286341fcf16176c8653feb667"
    },
    "objectId": "0x591fbb00a6c9676186cb44402040a8350520cbe9",
    "version": 1,
    "type": "Coin"
  }
}

Delete object

Attributes: packageId, transactionModule, sender, objectId
Example:

{
  "deleteObject": {
    "packageId": "0x2d052c9de3dd02f28ec0f8e4dfdee175a5c597c3",
    "transactionModule": "discount_coupon",
    "sender": "0x70613f4f17ae1363f7a7e7251daab5c5b06f68c1",
    "objectId": "0xe3a6bc7bf1dba4d17a91724009c461bd69870719"
  }
}

New object

Attributes: packageId, transactionModule, sender, recipient, objectId
Example:

{
  "newObject": {
    "packageId": "0x0000000000000000000000000000000000000002",
    "transactionModule": "devnet_nft",
    "sender": "0x70613f4f17ae1363f7a7e7251daab5c5b06f68c1",
    "recipient": {
      "AddressOwner": "0x70613f4f17ae1363f7a7e7251daab5c5b06f68c1"
    },
    "objectId": "0x497913a47dc0028a85f24c70d825991b71c60001"
  }
}

Epoch change

Value: Epoch Id
Example:

{
  "epochChange": 20
}

Checkpoint

Value: Checkpoint Sequence Number
Example:

{
  "checkpoint": 10
}

Event filters

Sui event pubsub uses EventFilter to enable fine control of the event subscription stream; the client can subscribe to the event stream using one or a combination of event attribute filters to get the exact event relevant to the client.

List of filterable attributes

FilterDescriptionApplicable to Event TypeExample
PackageMove package IDMoveEvent
Publish
TransferObject
DeleteObject
NewObject
{"Package":"0x2"}
ModuleMove module nameMoveEvent
TransferObject
DeleteObject
NewObject
{"Module":"devnet_nft"}
MoveEventTypeMove event type defined in the move codeMoveEvent{"MoveEventType":"0x2::devnet_nft::MintNFTEvent"}
MoveEventFieldFilter using the data fields in the move event objectMoveEvent{"MoveEventField":{ "path":"/name", "value":"Example NFT"}}
SenderAddressAddress that started the transactionMoveEvent
Publish
TransferObject
DeleteObject
NewObject
{"SenderAddress": "0x70613f4f17ae1363f7a7e7251daab5c5b06f68c1"}
EventTypeType of event described in the Events sectionMoveEvent
Publish
TransferObject
DeleteObject
NewObject
EpochChange
Checkpoint
"{EventType":"Publish"}
ObjectIdObject IDTransferObject
DeleteObject
NewObject
{"ObjectId":"0xe3a6bc7bf1dba4d17a91724009c461bd69870719"}

Combining filters

We provide a few operators for combining filters:

OperatorDescriptionExample
AndCombine two filters; behaves the same as boolean And operator{"And":[{"Package":"0x2"}, {"Module":"devnet_nft"}]}
OrCombine two filters; behaves the same as boolean Or operator{"Or":[{"Package":"0x2"}, {"Package":"0x1"}]}
AllCombine a list of filters; returns true if all filters match the event{"All":[{"EventType":"MoveEvent"}, {"Package":"0x2"}, {"Module":"devnet_nft"}]}
AnyCombine a list of filters; returns true if any filter matches the event{"Any":[{"EventType":"MoveEvent"}, {"EventType":"TransferObject"}, {"EventType":"DeleteObject"}]}

Examples

Subscribe

Here is an example of subscribing to a stream of MoveEvent emitted by the 0x2::devnet_nft package, which is created by the Sui CLI client create-example-nft command:

>> {"jsonrpc":"2.0", "id": 1, "method": "sui_subscribeEvent", "params": [{"All":[{"EventType":"MoveEvent"}, {"Package":"0x2"}, {"Module":"devnet_nft"}]}}
<< {"jsonrpc":"2.0","result":3121662727959200,"id":1}

Unsubscribe

To unsubscribe from this stream, use:

>> {"jsonrpc":"2.0", "id": 1, "method": "sui_unsubscribeEvent", "params": [3121662727959200]}
<< {"jsonrpc":"2.0","result":true,"id":1}
Last update 8/4/2022, 5:36:04 PM

Contributor(s)