Sui Events API

Sui Full nodes support 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.

Type of events

List of events emitted by the Sui node.

Move event

Move event are emitted from move call, user can define custom events in the move contract.

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
}

Sui event query

Event query criteria

Users can query the full node using EventQuery criteria object to get the exact event relevant to the client.

List of queryable criteria

QueryDescriptionJSON-RPC Parameter Example
AllAll events{"All"}
TransactionEvents emitted by the given transaction.{"Transaction":"DGUe2TXiJdN3FI6MH1FwghYbiHw+NKu8Nh579zdFtUk="}
MoveModuleEvents emitted in a specified Move module{"MoveModule":{"package":"0x2", "module":"devnet_nft"}}
MoveEventMove struct name of the event{"MoveEvent":"0x2::event_nft::MintNFTEvent"}
EventTypeType of event described in the Events section{"EventType": "NewObject"}
SenderQuery by sender address{"Sender":"0x70613f4f17ae1363f7a7e7251daab5c5b06f68c1"}
RecipientQuery by recipient{"Recipient":{"AddressOwner":"0x70613f4f17ae1363f7a7e7251daab5c5b06f68c1"}}
ObjectReturn events associated with the given object{"Object":"0xe3a6bc7bf1dba4d17a91724009c461bd69870719"}
TimeRangeReturn events emitted in [start_time, end_time] interval{"TimeRange":{"startTime":1669039504014, "endTime":1669039604014}}

Pagination

The Event Query API provide cursor based pagination to make returning large result sets more efficient. User can provide a cursor parameter to the paginated query to indicate the starting position of the query, the query will return the query result with item size up to the set limit and a next_cursor value will be returned if there are more item. The maximum item size limit is 1000 per query.

Examples

1. Get all event emitted by devnet_nft module in descending time order

Request

curl --location --request POST '127.0.0.1:9000' \
--header 'Content-Type: application/json' \
--data-raw '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "sui_getEvents",
  "params": [
    {"MoveModule":{"package":"0x2", "module":"devnet_nft"}},
    null,
    null,
    true
  ]
}'

Response

{
    "jsonrpc": "2.0",
    "result": {
        "data": [
            {
                "timestamp": 1666699837426,
                "txDigest": "cZXsToU6r0Uia6HIAwvr1eMlGsrg6b9+2oYZAskJ0wc=",
                "id": {
                    "txSeq": 1001,
                    "eventSeq": 1,
                },
                "event": {
                    "moveEvent": {
                        "packageId": "0x0000000000000000000000000000000000000002",
                        "transactionModule": "devnet_nft",
                        "sender": "0xfed4906d71b8a583fffd8e95676027b6bb81d7cf",
                        "type": "0x2::devnet_nft::MintNFTEvent",
                        "fields": {
                            "creator": "0xfed4906d71b8a583fffd8e95676027b6bb81d7cf",
                            "name": "Example NFT",
                            "object_id": "0x2ee80b4a2d203365dfbd68a90a8ad9a0dca19155"
                        },
                        "bcs": "LugLSi0gM2XfvWipCorZoNyhkVX+1JBtcbilg//9jpVnYCe2u4HXzwtFeGFtcGxlIE5GVA=="
                    }
                }
            },
            {
                "timestamp": 1666699837426,
                "txDigest": "cZXsToU6r0Uia6HIAwvr1eMlGsrg6b9+2oYZAskJ0wc=",
                "id": {
                    "txSeq": 1001,
                    "eventSeq": 0,
                },
                "event": {
                    "newObject": {
                        "packageId": "0x0000000000000000000000000000000000000002",
                        "transactionModule": "devnet_nft",
                        "sender": "0xfed4906d71b8a583fffd8e95676027b6bb81d7cf",
                        "recipient": {
                            "AddressOwner": "0xfed4906d71b8a583fffd8e95676027b6bb81d7cf"
                        },
                        "objectId": "0x2ee80b4a2d203365dfbd68a90a8ad9a0dca19155"
                    }
                }
            },
            {
                "timestamp": 1666698739180,
                "txDigest": "WF2V6FM6y/kpAgRqzsQmR/osy4pmTgVVbE6qvSJxWh4=",
                "id": {
                    "txSeq": 998,
                    "eventSeq": 1,
                },
                "event": {
                    "moveEvent": {
                        "packageId": "0x0000000000000000000000000000000000000002",
                        "transactionModule": "devnet_nft",
                        "sender": "0xfed4906d71b8a583fffd8e95676027b6bb81d7cf",
                        "type": "0x2::devnet_nft::MintNFTEvent",
                        "fields": {
                            "creator": "0xfed4906d71b8a583fffd8e95676027b6bb81d7cf",
                            "name": "Example NFT",
                            "object_id": "0xd5657cf6acaba958c5b01ec0516f4f0dac77c7d2"
                        },
                        "bcs": "1WV89qyrqVjFsB7AUW9PDax3x9L+1JBtcbilg//9jpVnYCe2u4HXzwtFeGFtcGxlIE5GVA=="
                    }
                }
            },
            {
                "timestamp": 1666698739180,
                "txDigest": "WF2V6FM6y/kpAgRqzsQmR/osy4pmTgVVbE6qvSJxWh4=",
                "id": {
                    "txSeq": 998,
                    "eventSeq": 0,
                },
                "event": {
                    "newObject": {
                        "packageId": "0x0000000000000000000000000000000000000002",
                        "transactionModule": "devnet_nft",
                        "sender": "0xfed4906d71b8a583fffd8e95676027b6bb81d7cf",
                        "recipient": {
                            "AddressOwner": "0xfed4906d71b8a583fffd8e95676027b6bb81d7cf"
                        },
                        "objectId": "0xd5657cf6acaba958c5b01ec0516f4f0dac77c7d2"
                    }
                }
            }
        ],
        "nextCursor": null
    },
    "id": 1
}

2. Get all 0x2::devnet_nft::MintNFTEvent

Request

curl --location --request POST '127.0.0.1:9000' \
--header 'Content-Type: application/json' \
--data-raw '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "sui_getEvents",
  "params": [
    {"MoveEvent":"0x2::devnet_nft::MintNFTEvent"},
    null,
    null,
    "Ascending"
  ]
}'

Response

{
    "jsonrpc": "2.0",
    "result": {
        "data": [
            {
                "timestamp": 1666699837426,
                "txDigest": "cZXsToU6r0Uia6HIAwvr1eMlGsrg6b9+2oYZAskJ0wc=",
                "id": {
                    "txSeq": 1001,
                    "eventSeq": 1,
                },
                "event": {
                    "moveEvent": {
                        "packageId": "0x0000000000000000000000000000000000000002",
                        "transactionModule": "devnet_nft",
                        "sender": "0xfed4906d71b8a583fffd8e95676027b6bb81d7cf",
                        "type": "0x2::devnet_nft::MintNFTEvent",
                        "fields": {
                            "creator": "0xfed4906d71b8a583fffd8e95676027b6bb81d7cf",
                            "name": "Example NFT",
                            "object_id": "0x2ee80b4a2d203365dfbd68a90a8ad9a0dca19155"
                        },
                        "bcs": "LugLSi0gM2XfvWipCorZoNyhkVX+1JBtcbilg//9jpVnYCe2u4HXzwtFeGFtcGxlIE5GVA=="
                    }
                }
            },
            {
                "timestamp": 1666698739180,
                "txDigest": "WF2V6FM6y/kpAgRqzsQmR/osy4pmTgVVbE6qvSJxWh4=",
                "id": {
                    "txSeq": 998,
                    "eventSeq": 1,
                },
                "event": {
                    "moveEvent": {
                        "packageId": "0x0000000000000000000000000000000000000002",
                        "transactionModule": "devnet_nft",
                        "sender": "0xfed4906d71b8a583fffd8e95676027b6bb81d7cf",
                        "type": "0x2::devnet_nft::MintNFTEvent",
                        "fields": {
                            "creator": "0xfed4906d71b8a583fffd8e95676027b6bb81d7cf",
                            "name": "Example NFT",
                            "object_id": "0xd5657cf6acaba958c5b01ec0516f4f0dac77c7d2"
                        },
                        "bcs": "1WV89qyrqVjFsB7AUW9PDax3x9L+1JBtcbilg//9jpVnYCe2u4HXzwtFeGFtcGxlIE5GVA=="
                    }
                }
            }
        ],
        "nextCursor": null
    },
    "id": 1
}

3. Get all event 2 items per paged, in descending time order

Request

curl --location --request POST '127.0.0.1:9000' \
--header 'Content-Type: application/json' \
--data-raw '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "sui_getEvents",
  "params": [
    "All",
    null,
    2,
    "Ascending"
  ]
}'

Response

{
    "jsonrpc": "2.0",
    "result": {
        "data": [
            {
                "timestamp": 1666698739180,
                "txDigest": "WF2V6FM6y/kpAgRqzsQmR/osy4pmTgVVbE6qvSJxWh4=",
                "id": {
                    "txSeq": 998,
                    "eventSeq": 0,
                },
                "event": {
                    "newObject": {
                        "packageId": "0x0000000000000000000000000000000000000002",
                        "transactionModule": "devnet_nft",
                        "sender": "0xfed4906d71b8a583fffd8e95676027b6bb81d7cf",
                        "recipient": {
                            "AddressOwner": "0xfed4906d71b8a583fffd8e95676027b6bb81d7cf"
                        },
                        "objectId": "0xd5657cf6acaba958c5b01ec0516f4f0dac77c7d2"
                    }
                }
            },
            {
                "timestamp": 1666698739180,
                "txDigest": "WF2V6FM6y/kpAgRqzsQmR/osy4pmTgVVbE6qvSJxWh4=",
                "id": {
                    "txSeq": 998,
                    "eventSeq": 1,
                },
                "event": {
                    "moveEvent": {
                        "packageId": "0x0000000000000000000000000000000000000002",
                        "transactionModule": "devnet_nft",
                        "sender": "0xfed4906d71b8a583fffd8e95676027b6bb81d7cf",
                        "type": "0x2::devnet_nft::MintNFTEvent",
                        "fields": {
                            "creator": "0xfed4906d71b8a583fffd8e95676027b6bb81d7cf",
                            "name": "Example NFT",
                            "object_id": "0xd5657cf6acaba958c5b01ec0516f4f0dac77c7d2"
                        },
                        "bcs": "1WV89qyrqVjFsB7AUW9PDax3x9L+1JBtcbilg//9jpVnYCe2u4HXzwtFeGFtcGxlIE5GVA=="
                    }
                }
            }
        ],
        "nextCursor": 3
    },
    "id": 1
}

Subscribe to Sui events

Sui full node 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 the event subscription. For each event that matches the filter, a notification with the event data and subscription ID is returned to the client.

Event filters

Sui event publish / subscribe 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 TypeJSON-RPC Parameter Example
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:

OperatorDescriptionz JSON-RPC Parameter Example
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 11/21/2022, 6:01:41 PM

Contributor(s)