Event Subscription

What is Event

In Vite, events are notifications triggered by virtual machine to indicate state change and will be pushed to front-end program such as dApp for further processing. A VmLog will be created in the smart contract's response block when event is triggered.

Taking the following contract as example, when method TransferWithEvent is called, the contract transfers the token received to specified address and then triggers a transferEvent event.

Copy pragma soliditypp ^0.4.1; contract TransferContract { event transferEvent(address indexed addr, uint256 value, tokenId tokenid); onMessage TransferWithEvent(address addr) payable { addr.transfer(msg.tokenid ,msg.value); emit transferEvent(addr, msg.value, msg.tokenid); } }

The transferEvent event contains the following content:

• The hash of contract response block in which the event was created. This information can be used to retrieve contract address, contract account block height, request transaction hash and so on.
• Event signature as the hash of transferEvent(address, uint256, uint256).
• Indexed parameters, which are marked as indexed in event definition. Up to 4 indexed parameters can be defined in an event. Event signature and indexed parameters are stored in topics field of VmLog, where topics[0] is occupied by event signature.
• Non-indexed parameters having no indexed marked. Non-indexed parameters are stored in data field of VmLog.

Below is an example of event logged when sending 1 VITE to vite_9990375e0eaf10426d1d1f9b528b6dee158fd3adb0e1b9de70

Copy { "accountBlockHash":"0edcbbbbbf0d68e5721187c1866029e2f544e00f2f48358a9df5ca18f5d1d5a2", "log": { "topics": [ "f632c631f1cf58a101b09f8fe0262d7c04f04e9b77f255bd2f86fedd1b6af56d", "0000000000000000000000009990375e0eaf10426d1d1f9b528b6dee158fd3ad" ], "data": "0000000000000000000000000000000000000000000000000DE0B6B3A764000000000000000000000000000000000000000000005649544520544f4b454e6e40" } }

What is Subscription

If a certain event is subscribed to, the subscriber will be notified when this certain event occurs. For example, if you subscribe to transferEvent of TransferContract, you will receive a notification when TransferWithEvent method is called.

Event subscription can be used to listen to new transactions that occur on blockchain. It's only allowed to listen to events that have not occurred yet. Historical events cannot be monitored but can only be fetched through query API.

The following parameters need to be specified when subscribing to an event:

• Contract address. Required.
• Contract account height range. Optional. By this parameter, it's possible to subscribe to events happening within a certain height range.
• Event signature or indexed parameter. Optional. For example, you can subscribe to events that transfer to certain accounts.

Two Modes of Event Subscription

In the following part we regard "server" is a full node generating event, and "client" subscribes to the event.

Callback

In callback mode, a WebSocket connection is established between client and server, and then client subscribes to event that occurs at server side. When new event is triggered, it will be pushed to client automatically. Subscription will end once the connection is broken.

Polling

In polling mode, client firstly subscribes to certain event, and then periodically requests for new event from server. New events that were triggered since last request will be returned, otherwise server returns null.

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

Usage Example

See Usage Example

Other Subscriptions

In addition to events generated by smart contracts, it is also possible to subscribe to new transactions on all accounts, new transactions on specified account, un-received transactions on specified account and new snapshot blocks.

Subscriptions in Future

Event will be triggered

• When transaction is confirmed
• When event is confirmed
• When account balance changes