事件订阅

什么是事件

事件( Event )是以太坊虚拟机( EVM )中提供的一种智能合约向前端发送通知的功能。当一个智能合约的响应交易中触发了事件时,这个事件相关的日志( VmLog )会被记录到这个响应块中。

以下面这个合约为例,当 TransferWithEvent 方法被调用时,合约将收到的代币转账给指定地址,并触发一个 transferEvent 事件。

pragma soliditypp ^0.4.0;
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);      
   }
}

一个 transferEvent 事件包含以下信息:

  • 触发事件的合约账户响应块哈希,这个哈希表明了事件的触发场景,即合约账户地址、合约账户高度、请求交易哈希等。
  • 事件签名,即 transferEvent(address,uint256,uint256) 的哈希。
  • 索引参数,即事件定义中标记为 indexed 的参数,一个事件最多有 4 个索引参数。事件签名和索引参数存储在 VmLogtopics 字段中,其中事件签名存在 topics[0]
  • 非索引参数,即事件定义中未标记为 indexed 的参数。非索引参数存储在 VmLogdata 字段中。

例如,给 vite_9990375e0eaf10426d1d1f9b528b6dee158fd3adb0e1b9de701vite 时,触发的事件如下:

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

什么是事件订阅

如果订阅了某一个类型的事件,那么当事件发生时,会收到通知。例如,如果订阅了 TransferContract 合约的 transferEvent 事件,那么当 TransferWithEvent 接口被调用时,就会收到 transferEvent 的通知。

可以通过事件订阅来持续监听区块链上发生的指定类型的交易。只能订阅当前未发生的事件,不能订阅已发生的历史事件,历史事件只能通过查询接口查询。

订阅事件时需要指定以下参数:

  • 合约账户地址,必填。
  • 合约账户高度范围,非必填,可以只订阅某一个高度范围的事件,也可以订阅所有事件。
  • 事件签名或者索引参数,非必填。例如:可以只订阅给某些账户转账的事件,也可以订阅所有事件。

事件订阅的两种订阅模式

下文中,服务端为一个支持事件订阅服务的全节点,客户端为一个需要订阅事件的终端。

长连接模式

长连接模式下,客户端和服务端之间先建立长连接,然后客户端向服务端订阅事件,当触发新事件时,服务端主动向客户端推送新事件。如果长连接断开,则订阅结束。

轮询模式

轮询模式下,客户端直接向服务端订阅事件,订阅成功后,客户端定期向服务端请求新事件,如果上一次请求之后触发了新事件,则返回所有的新事件,否则返回空。

轮询模式下,如果客户端超过 5 分钟不向服务器请求新事件,则订阅自动结束。此时客户端需要重新向服务端订阅事件。

事件订阅使用说明

事件订阅使用说明

其他订阅类型

在 Vite 测试网络中,除了智能合约产生的事件,还可以订阅新交易、新快照块。订阅交易和快照块时不需要指定过滤参数,订阅成功后会收到所有的新交易和新快照块信息。

未来可能会支持的订阅类型

  • 交易被确认
  • 事件被确认
  • 账户余额变动
  • ……