Web3.js 中文Api文档

🌙
手机阅读
本文目录结构

.. _eth-subscribe:

========= web3.eth.subscribe

The web3.eth.subscribe function lets you subscribe to specific events in the blockchain.

subscribe


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

参数

  1. String - The subscription you want to subscribe to.
  2. Mixed - (optional) Optional additional parameters, depending on the subscription type.
  3. Function - (optional) Optional callback, returns an error object as first parameter and the result as second. Will be called for each incoming subscription, and the subscription itself as the 3rd parameter.

.. _eth-subscription-return:


返回值

EventEmitter - A Subscription instance

- `subscription.id`: The subscription id, used to identify and unsubscribing the subscription.
- `subscription.subscribe([callback])`: Can be used to re-subscribe with the same parameters.
- `subscription.unsubscribe([callback])`: Unsubscribes the subscription and returns `TRUE` in the callback if successful.
- `subscription.arguments`: The subscription arguments, used when re-subscribing.
- `on("data")` returns `Object`: Fires on each incoming log with the log object as argument.
- `on("changed")` returns `Object`: Fires on each log which was removed from the blockchain. The log will have the additional property `"removed: true"`.
- `on("error")` returns `Object`: Fires when an error in the subscription occurs.
- `on("connected")` returns `String`: Fires once after the subscription successfully connected. Returns the subscription id.

Notification returns

  • Mixed - depends on the subscription, see the different subscriptions for more.

例子


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

    // unsubscribes the subscription
    subscription.unsubscribe(function(error, success){
        if(success)
            console.log('Successfully unsubscribed!');
    });

clearSubscriptions


    web3.eth.clearSubscriptions()

Resets subscriptions.

.. note:: This will not reset subscriptions from other packages like web3-shh, as they use their own requestManager.


参数

  1. Boolean: If true it keeps the "syncing" subscription.

返回值

Boolean


例子


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

    ...

    web3.eth.clearSubscriptions();

subscribe(“pendingTransactions”)


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

Subscribes to incoming pending transactions.


参数

  1. String - "pendingTransactions", the type of the subscription.
  2. Function - (optional) Optional callback, returns an error object as first parameter and the result as second. Will be called for each incoming subscription.

返回值

EventEmitter: An :ref:subscription instance <eth-subscription-return> as an event emitter with the following events:

  • "data" returns String: Fires on each incoming pending transaction and returns the transaction hash.
  • "error" returns Object: Fires when an error in the subscription occurs.

Notification returns

  1. Object|Null - First parameter is an error object if the subscription failed.
  2. String - Second parameter is the transaction hash.

例子


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

    // unsubscribes the subscription
    subscription.unsubscribe(function(error, success){
        if(success)
            console.log('Successfully unsubscribed!');
    });

subscribe(“newBlockHeaders”)


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

Subscribes to incoming block headers. This can be used as timer to check for changes on the blockchain.


参数

  1. String - "newBlockHeaders", the type of the subscription.
  2. Function - (optional) Optional callback, returns an error object as first parameter and the result as second. Will be called for each incoming subscription.

返回值

EventEmitter: An :ref:subscription instance <eth-subscription-return> as an event emitter with the following events:

  • "data" returns Object: Fires on each incoming block header.
  • "error" returns Object: Fires when an error in the subscription occurs.
  • "connected" returns Number: Fires once after the subscription successfully connected. Returns the subscription id.

The structure of a returned block header is as follows:

- `number` - `Number`: The block number. `null` when its pending block.
- `hash` 32 Bytes - `String`: Hash of the block. `null` when its pending block.
- `parentHash` 32 Bytes - `String`: Hash of the parent block.
- `nonce` 8 Bytes - `String`: Hash of the generated proof-of-work. `null` when its pending block.
- `sha3Uncles` 32 Bytes - `String`: SHA3 of the uncles data in the block.
- `logsBloom` 256 Bytes - `String`: The bloom filter for the logs of the block. `null` when its pending block.
- `transactionsRoot` 32 Bytes - `String`: The root of the transaction trie of the block
- `stateRoot` 32 Bytes - `String`: The root of the final state trie of the block.
- `receiptsRoot` 32 Bytes - `String`: The root of the receipts.
- `miner` - `String`: The address of the beneficiary to whom the mining rewards were given.
- `extraData` - `String`: The "extra data" field of this block.
- `gasLimit` - `Number`: The maximum gas allowed in this block.
- `gasUsed` - `Number`: The total used gas by all transactions in this block.
- `timestamp` - `Number`: The unix timestamp for when the block was collated.

Notification returns

  1. Object|Null - First parameter is an error object if the subscription failed.
  2. Object - The block header object like above.

例子


    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);

    // unsubscribes the subscription
    subscription.unsubscribe(function(error, success){
        if (success) {
            console.log('Successfully unsubscribed!');
        }
    });

subscribe(“syncing”)


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

Subscribe to syncing events. This will return an object when the node is syncing and when it’s finished syncing will return FALSE.


参数

  1. String - "syncing", the type of the subscription.
  2. Function - (optional) Optional callback, returns an error object as first parameter and the result as second. Will be called for each incoming subscription.

返回值

EventEmitter: An :ref:subscription instance <eth-subscription-return> as an event emitter with the following events:

  • "data" returns Object: Fires on each incoming sync object as argument.
  • "changed" returns Object: Fires when the synchronisation is started with true and when finished with false.
  • "error" returns Object: Fires when an error in the subscription occurs.

For the structure of a returned event Object see :ref:web3.eth.isSyncing return values <eth-issyncing-return>.


Notification returns

  1. Object|Null - First parameter is an error object if the subscription failed.
  2. Object|Boolean - The syncing object, when started it will return true once or when finished it will return false once.

例子


    var subscription = web3.eth.subscribe('syncing', function(error, sync){
        if (!error)
            console.log(sync);
    })
    .on("data", function(sync){
        // show some syncing stats
    })
    .on("changed", function(isSyncing){
        if(isSyncing) {
            // stop app operation
        } else {
            // regain app operation
        }
    });

    // unsubscribes the subscription
    subscription.unsubscribe(function(error, success){
        if(success)
            console.log('Successfully unsubscribed!');
    });

subscribe(“logs”)


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

Subscribes to incoming logs, filtered by the given options. If a valid numerical fromBlock options property is set, Web3 will retrieve logs beginning from this point, backfilling the response as necessary.


参数

  1. "logs" - String, the type of the subscription.
  2. Object - The subscription options
  • fromBlock - Number: The number of the earliest block. By default null.
  • address - String|Array: An address or a list of addresses to only get logs from particular account(s).
  • topics - Array: An array of values which must each appear in the log entries. The order is important, if you want to leave topics out use null, e.g. [null, '0x00...']. You can also pass another array for each topic with options for that topic e.g. [null, ['option1', 'option2']]
  1. callback - Function: (optional) Optional callback, returns an error object as first parameter and the result as second. Will be called for each incoming subscription.

返回值

EventEmitter: A :ref:subscription instance <eth-subscription-return> as an event emitter with the following events:

  • "data" returns Object: Fires on each incoming log with the log object as argument.
  • "changed" returns Object: Fires on each log which was removed from the blockchain. The log will have the additional property "removed: true".
  • "error" returns Object: Fires when an error in the subscription occurs.
  • "connected" returns Number: Fires once after the subscription successfully connected. Returns the subscription id.

For the structure of a returned event Object see :ref:web3.eth.getPastEvents return values <eth-getpastlogs-return>.


Notification returns

  1. Object|Null - First parameter is an error object if the subscription failed.
  2. Object - The log object like in :ref:web3.eth.getPastEvents return values <eth-getpastlogs-return>.

例子


    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){
    });

    // unsubscribes the subscription
    subscription.unsubscribe(function(error, success){
        if(success)
            console.log('Successfully unsubscribed!');
    });

AXIHE / 精选资源

浏览全部教程

面试题

学习网站

前端培训
自己甄别

前端书籍

关于朱安邦

我叫 朱安邦,阿西河的站长,在杭州。

以前是一名平面设计师,后来开始接接触前端开发,主要研究前端技术中的JS方向。

业余时间我喜欢分享和交流自己的技术,欢迎大家关注我的 Bilibili

关注我: Github / 知乎

于2021年离开前端领域,目前重心放在研究区块链上面了

我叫朱安邦,阿西河的站长

目前在杭州从事区块链周边的开发工作,机械专业,以前从事平面设计工作。

2014年底脱产在老家自学6个月的前端技术,自学期间几乎从未出过家门,最终找到了满意的前端工作。更多>

于2021年离开前端领域,目前从事区块链方面工作了