web3.eth.subscribe

web3.eth.subscribe 方法让你可以订阅区块链中的指定事件

订阅调用

web3.eth.subscribe(type [, options] [, callback]);

参数

  1. String - 订阅类型

  2. Mixed - (可选) 依赖于订阅类型的可选额外参数

  3. Function - (可选) 可选的回调函数,其第一个参数为错误对象,第二个参数为结果。该函数在每次订阅事件发生时都会被调用,订阅实例会作为第三个参数传递进来。

返回值

EventEmitter - 一个订阅实例

  • subscription.id: 订阅 id 编号,用于标识一个订阅以及进行后续的取消订阅操作

  • subscription.subscribe([callback]): 可用于使用相同的参数进行再次订阅

  • subscription.unsubscribe([callback]): 取消订阅,如果成功取消的话,在回调函数中返回 TRUE

  • subscription.arguments: 订阅参数,在重新订阅时使用

  • on("data") 返回 Object: 每次有新的日志时都触发该事件,参数为日志对象

  • on("changed") 返回 Object: 每次有日志从区块链上移除时触发该事件,被移除的日志对象将添加额外的属性: "removed: true"

  • on("error") 返回 Object: 当订阅发生错误时,触发此事件

  • on("connected") 返回 String: 一旦订阅成功就会触发该事件,返回订阅 id

通知返回值

  • Mixed - 取决于订阅具体是什么,可以参考文档后面提到的不同订阅获取更多相关信息

例子

var subscription = web3.eth.subscribe('logs', {
    address: '0x123456..',
    topics: ['0x12345...']
}, function(error, result){
    if (!error)
        console.log(result);
});

// 取消订阅
subscription.unsubscribe(function(error, success){
    if(success)
        console.log('Successfully unsubscribed!');
});

clearSubscriptions

web3.eth.clearSubscriptions()

重置订阅

注解

这不会重置像 web3-shh 这样其它包的订阅,因为这些包有自己的请求管理器

参数

1. Boolean: If true it keeps the "syncing" subscription. 1. Boolean: 值为 true 则表示保持 同步 订阅

返回值

Boolean

例子

web3.eth.subscribe('logs', {} ,function(){ ... });

...

web3.eth.clearSubscriptions();

subscribe(“pendingTransactions”)

web3.eth.subscribe('pendingTransactions' [, callback]);

订阅 pending 状态的交易。

参数

  1. String - "pendingTransactions", 订阅类型

  2. Function - (可选) 可选的回调函数,其第一个参数为错误对象,第二个参数为结果。

返回值

EventEmitter: 下面事件的一个 订阅实例 事件发生器:

  • "data" 返回 String: 当接收到 pending 状态的交易时触发并返回交易哈希

  • "error" 返回 Object: 当订阅中发生错误时触发

通知返回值

  1. Object|Null - 如果订阅失败第一个参数为错误对象

  2. String - 第二个参数为交易哈希

例子

var subscription = web3.eth.subscribe('pendingTransactions', function(error, result){
    if (!error)
        console.log(result);
})
.on("data", function(transaction){
    console.log(transaction);
});

// 取消订阅
subscription.unsubscribe(function(error, success){
    if(success)
        console.log('Successfully unsubscribed!');
});

subscribe(“newBlockHeaders”)

web3.eth.subscribe('newBlockHeaders' [, callback]);

订阅新的区块头生成事件, 可用作检查链上变化的计时器。

参数

  1. String - "newBlockHeaders", 订阅类型。

  2. Function - (可选) 可选的回调函数,其第一个参数为错误对象,第二个参数为结果。每当有订阅事件发生时都会被调用。

返回值

EventEmitter: 带有下面事件的一个 订阅实例 事件发生器:

  • "data" 返回 Object: 当收到新的区块头时触发

  • "error" 返回 Object: 当订阅中出现错误时触发

  • "connected" 返回 Number: 订阅成功后触发,返回订阅 id

返回的区块头对象结构如下:

  • number - Number: 区块编号,对于 pending 状态的块该值为``null``。

  • hash 32 Bytes - String: 块的哈希值,对于 pending 状态的块该值为``null``。

  • parentHash 32 Bytes - String: 父区块哈希值。

  • nonce 8 Bytes - String: 用来生成工作量证明的 nonce 值. 对于 pending 状态的块该值为``null``。

  • sha3Uncles 32 Bytes - String: 区块中叔块数据的 sha3哈希值。

  • logsBloom 256 Bytes - String: 区块日志数据的布隆过滤器。对于 pending 状态的块该值为``null``。

  • transactionsRoot 32 Bytes - String: 区块中交易 trie 树的根节点。

  • stateRoot 32 Bytes - String: 区块中状态 trie 树的根节点。

  • receiptsRoot 32 Bytes - String: 收据根节点。

  • miner - String: 接收挖矿奖励的矿工地址。

  • extraData - String: 区块的额外数据字段。

  • gasLimit - Number: 该块允许的最大 gas 用量。

  • gasUsed - Number: 该块中所有交易使用的 gas 总量。

  • timestamp - Number: 区块时间戳。

通知返回值

  1. Object|Null - 如果订阅失败第一个参数为错误对象

  2. Object - 像上面那样的区块头对象

例子

var subscription = web3.eth.subscribe('newBlockHeaders', function(error, result){
    if (!error) {
        console.log(result);

        return;
    }

    console.error(error);
})
.on("connected", function(subscriptionId){
    console.log(subscriptionId);
})
.on("data", function(blockHeader){
    console.log(blockHeader);
})
.on("error", console.error);

// 取消订阅
subscription.unsubscribe(function(error, success){
    if (success) {
        console.log('Successfully unsubscribed!');
    }
});

subscribe(“syncing”)

web3.eth.subscribe('syncing' [, callback]);

订阅同步事件。当节点正在同步数据时将返回一个同步对象,同步结束后返回 FALSE

参数

  1. String - "syncing", 订阅类型

  2. Function - (可选) 可选的回调函数,其第一个参数为错误对象,第二个参数为结果。每当有订阅事件发生时都会被调用。

返回值

EventEmitter: 带有下面事件的一个 订阅实例 事件发生器:

  • "data" 返回 Object: 收到同步对象时触发

  • "changed" 返回 Object: 当同步状态由 true 变为 false 时触发

  • "error" 返回 Object: 当订阅中出现错误时触发

要了解返回事件对象的结构,可查看 web3.eth.isSyncing 返回值

通知返回值

  1. Object|Null - 如果订阅失败第一个参数为错误对象

  2. Object|Boolean - 同步对象, 同步开始后返回 true,同步结束后返回 false

例子

var subscription = web3.eth.subscribe('syncing', function(error, sync){
    if (!error)
        console.log(sync);
})
.on("data", function(sync){
    // 一些同步状态数据
})
.on("changed", function(isSyncing){
    if(isSyncing) {
        // 暂停应用操作
    } else {
        // 重启应用操作
    }
});

// 取消订阅
subscription.unsubscribe(function(error, success){
    if(success)
        console.log('Successfully unsubscribed!');
});

subscribe(“logs”)

web3.eth.subscribe('logs', options [, callback]);

订阅日志,并按指定条件进行过滤。 如果一个有效的 fromBlock 属性被指定,Web3 会提取从这个点开始的日志,必要时回填返回值。

参数

  1. "logs" - String, 订阅类型

  2. Object - 订阅选项

  • fromBlock - Number: 最早区块编号, 默认为 null

  • address - String|Array: 地址或地址列表,仅订阅来自这些指定账户地址的日志。

  • topics - Array: 一个主题数组,数组中每个元素都应出现在日志项中。 数组中主题的顺序是很重要的, 如果你不想监听某个主题可以用 null 值, 比如 [null, '0x00...']. 你也可以为每个主题传入另外一个数组来表示主题选项, 比如 [null, ['option1', 'option2']]

  1. callback - Function: (可选) 可选的回调函数,其第一个参数为错误对象,第二个参数为结果。每当有订阅事件发生时都会被调用。

返回值

EventEmitter: 带有下面事件的一个 订阅实例 事件发生器:

  • "data" 返回 Object: 接收到新日志时触发,参数为日志对象

  • "changed" 返回 Object: 日志从链上移除时触发,该日志同时带有附加属性 "removed: true"

  • "error" 返回 Object: 当订阅中出现错误时触发

  • "connected" 返回 Number: 订阅成功后触发,返回订阅 id

要了解返回的事件对象结构,可查看 web3.eth.getPastEvents 返回值.

通知返回值

  1. Object|Null - 如果订阅失败第一个参数为错误对象

  2. Object - 日志对象,类似于 web3.eth.getPastEvents 返回值.

例子

var subscription = web3.eth.subscribe('logs', {
    address: '0x123456..',
    topics: ['0x12345...']
}, function(error, result){
    if (!error)
        console.log(result);
})
.on("connected", function(subscriptionId){
    console.log(subscriptionId);
})
.on("data", function(log){
    console.log(log);
})
.on("changed", function(log){
});

// 取消订阅
subscription.unsubscribe(function(error, success){
    if(success)
        console.log('Successfully unsubscribed!');
});