pubsub.md

title
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

Filter	Description	Applicable to Event Type	Example
Package	Move package ID	MoveEvent Publish TransferObject DeleteObject NewObject	{"Package":"0x2"}
Module	Move module name	MoveEvent TransferObject DeleteObject NewObject	{"Module":"devnet_nft"}
MoveEventType	Move event type defined in the move code	MoveEvent	{"MoveEventType":"0x2::devnet_nft::MintNFTEvent"}
MoveEventField	Filter using the data fields in the move event object	MoveEvent	{"MoveEventField":{ "path":"/name", "value":"Example NFT"}}
SenderAddress	Address that started the transaction	MoveEvent Publish TransferObject DeleteObject NewObject	{"SenderAddress": "0x70613f4f17ae1363f7a7e7251daab5c5b06f68c1"}
EventType	Type of event described in the Events section	MoveEvent Publish TransferObject DeleteObject NewObject EpochChange Checkpoint	"{EventType":"Publish"}
ObjectId	Object ID	TransferObject DeleteObject NewObject	{"ObjectId":"0xe3a6bc7bf1dba4d17a91724009c461bd69870719"}

Combining filters

We provide a few operators for combining filters:

Operator	Description	Example
And	Combine two filters; behaves the same as boolean And operator	{"And":[{"Package":"0x2"}, {"Module":"devnet_nft"}]}
Or	Combine two filters; behaves the same as boolean Or operator	{"Or":[{"Package":"0x2"}, {"Package":"0x1"}]}
All	Combine a list of filters; returns true if all filters match the event	{"All":[{"EventType":"MoveEvent"}, {"Package":"0x2"}, {"Module":"devnet_nft"}]}
Any	Combine 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}