web3.js/docs/web3-eth.rst

.. _eth:

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

The ``web3-eth`` package allows you to interact with an Ethereum blockchain and Ethereum smart contracts.


.. code-block:: javascript

    var Eth = require('web3-eth');

    // "Eth.providers.givenProvider" will be set if in an Ethereum supported browser.
    var eth = new Eth(Eth.givenProvider || new Eth.providers.WebsocketProvider('ws://some.local-or-remote.node:8546'));


    // or using the web3 umbrella package

    var Web3 = require('web3');
    var web3 = new Web3(Web3.givenProvider || new Web3.providers.WebsocketProvider('ws://some.local-or-remote.node:8546'));

    // -> web3.eth


Note on checksum addresses
=======

All Ethereum addresses returned by function of this package are checksum addresses.
This means some letters are uppercase and some are lowercase.
Based on that it will calculate a checksum for the address and prove its correctness.
Incorrect checksum address will throw an error when passed into a function.
If you want to circumvent the checksum check you can make an address all lowercase or uppercase.


-------
Example
-------

.. code-block:: javascript

    web3.eth.getAccounts(console.log);
    > ["0x11f4d0A3c12e86B4b5F39B213F7E19D048276DAe"]


------------------------------------------------------------------------------


subscribe
=====================

For ``web3.eth.subscribe`` see the :ref:`Subscribe reference documentation <eth-subscribe>`


------------------------------------------------------------------------------


Contract
=====================

For ``web3.eth.Contract`` see the :ref:`Contract reference documentation <eth-contract>`


------------------------------------------------------------------------------


Iban
=====================

For ``web3.eth.Iban`` see the :ref:`Iban reference documentation <eth-iban>`


------------------------------------------------------------------------------


personal
=====================

For ``web3.eth.personal`` see the :ref:`personal reference documentation <eth-personal>`


------------------------------------------------------------------------------


net
=====================

For ``web3.eth.net`` see the :ref:`net reference documentation <eth-net>`


------------------------------------------------------------------------------


.. include:: include_package-core.rst


------------------------------------------------------------------------------


defaultAccount
=====================

.. code-block:: javascript

    web3.eth.defaultAccount

This default address is used as the default ``"from"`` property, if no ``"from"`` property is specified in for the following methods:

- :ref:`web3.eth.sendTransaction() <eth-sendtransaction>`
- :ref:`web3.eth.call() <eth-call>`
- :ref:`new web3.eth.Contract() -> myContract.methods.myMethod().call() <eth-contract-call>`
- :ref:`new web3.eth.Contract() -> myContract.methods.myMethod().send() <eth-contract-send>`

--------
Property
--------


``String`` - 20 Bytes: Any ethereum address. You should have the private key for that address in your node or keystore. (Default is ``undefined``)


-------
Example
-------


.. code-block:: javascript

    web3.eth.defaultAccount;
    > undefined

    // set the default account
    web3.eth.defaultAccount = '0x11f4d0A3c12e86B4b5F39B213F7E19D048276DAe';


------------------------------------------------------------------------------

.. _eth-defaultblock:

defaultBlock
=====================

.. code-block:: javascript

    web3.eth.defaultBlock

The default block is used for certain methods. You can override it by passing in the defaultBlock as last parameter.
The default value is "latest".

- :ref:`web3.eth.getBalance() <eth-getbalance>`
- :ref:`web3.eth.getCode() <eth-getcode>`
- :ref:`web3.eth.getTransactionCount() <eth-gettransactioncount>`
- :ref:`web3.eth.getStorageAt() <eth-getstorageat>`
- :ref:`web3.eth.call() <eth-call>`
- :ref:`new web3.eth.Contract() -> myContract.methods.myMethod().call() <eth-contract-call>`

----------
Property
----------


Default block parameters can be one of the following:

- ``Number``: A block number
- ``"genesis"`` - ``String``: The genesis block
- ``"latest"`` - ``String``: The latest block (current head of the blockchain)
- ``"pending"`` - ``String``: The currently mined block (including pending transactions)

Default is ``"latest"``


-------
Example
-------

.. code-block:: javascript

    web3.eth.defaultBlock;
    > "latest"

    // set the default block
    web3.eth.defaultBlock = 231;


------------------------------------------------------------------------------

getProtocolVersion
=====================

.. code-block:: javascript

    web3.eth.getProtocolVersion([callback])

Returns the ethereum protocol version of the node.

-------
Returns
-------

``Promise`` returns ``String``: the protocol version.


-------
Example
-------

.. code-block:: javascript

    web3.eth.getProtocolVersion()
    .then(console.log);
    > "63"


------------------------------------------------------------------------------


isSyncing
=====================

.. code-block:: javascript

    web3.eth.isSyncing([callback])

Checks if the node is currently syncing and returns either a syncing object, or ``false``.

.. _eth-issyncing-return:

-------
Returns
-------

``Promise`` returns ``Object|Boolean`` - A sync object when the node is currently syncing or ``false``:

    - ``startingBlock`` - ``Number``: The block number where the sync started.
    - ``currentBlock`` - ``Number``: The block number where at which block the node currently synced to already.
    - ``highestBlock`` - ``Number``: The estimated block number to sync to.
    - ``knownStates`` - ``Number``: The estimated states to download
    - ``pulledStates`` - ``Number``: The already downloaded states


-------
Example
-------

.. code-block:: javascript

    web3.eth.isSyncing()
    .then(console.log);

    > {
        startingBlock: 100,
        currentBlock: 312,
        highestBlock: 512,
        knownStates: 234566,
        pulledStates: 123455
    }


------------------------------------------------------------------------------


getCoinbase
=====================

.. code-block:: javascript

    getCoinbase([callback])

Returns the coinbase address to which mining rewards will go.

-------
Returns
-------

``Promise`` returns ``String`` - bytes 20: The coinbase address set in the node for mining rewards.


-------
Example
-------

.. code-block:: javascript

    web3.eth.getCoinbase()
    .then(console.log);
    > "0x11f4d0A3c12e86B4b5F39B213F7E19D048276DAe"


------------------------------------------------------------------------------

isMining
=====================

.. code-block:: javascript

    web3.eth.isMining([callback])


Checks whether the node is mining or not.

-------
Returns
-------

``Promise`` returns ``Boolean``: ``true`` if the node is mining, otherwise ``false``.


-------
Example
-------

.. code-block:: javascript

    web3.eth.isMining()
    .then(console.log);
    > true


------------------------------------------------------------------------------

getHashrate
=====================

.. code-block:: javascript

    web3.eth.getHashrate([callback])

Returns the number of hashes per second that the node is mining with.

-------
Returns
-------

``Promise`` returns ``Number``: Number of hashes per second.

-------
Example
-------


.. code-block:: javascript

    web3.eth.getHashrate()
    .then(console.log);
    > 493736


------------------------------------------------------------------------------

getGasPrice
=====================

.. code-block:: javascript

    web3.eth.getGasPrice([callback])


Returns the current gas price oracle.
The gas price is determined by the last few blocks median gas price.

-------
Returns
-------

``Promise`` returns ``String`` - Number string of the current gas price in :ref:`wei <what-is-wei>`.

See the :ref:`A note on dealing with big numbers in JavaScript <big-numbers-in-javascript>`.

-------
Example
-------


.. code-block:: javascript

    web3.eth.getGasPrice()
    .then(console.log);
    > "20000000000"


------------------------------------------------------------------------------


getAccounts
=====================

.. code-block:: javascript

    web3.eth.getAccounts([callback])

Returns a list of accounts the node controls.

-------
Returns
-------


``Promise`` returns ``Array`` - An array of addresses controlled by node.

-------
Example
-------


.. code-block:: javascript

    web3.eth.getAccounts()
    .then(console.log);
    > ["0x11f4d0A3c12e86B4b5F39B213F7E19D048276DAe", "0xDCc6960376d6C6dEa93647383FfB245CfCed97Cf"]


------------------------------------------------------------------------------


getBlockNumber
=====================

.. code-block:: javascript

    web3.eth.getBlockNumber([callback])

Returns the current block number.

-------
Returns
-------

``Promise`` returns ``Number`` - The number of the most recent block.

-------
Example
-------


.. code-block:: javascript

    web3.eth.blockNumber()
    .then(console.log);
    > 2744


------------------------------------------------------------------------------



getBalance
=====================

.. code-block:: javascript

    web3.eth.getBalance(address [, defaultBlock] [, callback])

Get the balance of an address at a given block.

----------
Parameters
----------

1. ``String`` - The address to get the balance of.
2. ``Number|String`` - (optional) If you pass this parameter it will not use the default block set with :ref:`web3.eth.defaultBlock <eth-defaultblock>`.
3. ``Function`` - (optional) Optional callback, returns an error object as first parameter and the result as second.

-------
Returns
-------


``Promise`` returns ``String`` - The current balance for the given address in :ref:`wei <what-is-wei>`.

See the :ref:`A note on dealing with big numbers in JavaScript <big-numbers-in-javascript>`.

-------
Example
-------


.. code-block:: javascript

    web3.eth.getBalance("0x407d73d8a49eeb85d32cf465507dd71d507100c1")
    .then(console.log);
    > "1000000000000"


------------------------------------------------------------------------------

getStorageAt
=====================

.. code-block:: javascript

    web3.eth.getStorageAt(address, position [, defaultBlock] [, callback])

Get the storage at a specific position of an address.

----------
Parameters
----------

1. ``String`` - The address to get the storage from.
2. ``Number`` - The index position of the storage.
3. ``Number|String`` - (optional) If you pass this parameter it will not use the default block set with :ref:`web3.eth.defaultBlock <eth-defaultblock>`.
4. ``Function`` - (optional) Optional callback, returns an error object as first parameter and the result as second.


-------
Returns
-------

``Promise`` returns ``String`` - The value in storage at the given position.

-------
Example
-------


.. code-block:: javascript

    web3.eth.getStorageAt("0x407d73d8a49eeb85d32cf465507dd71d507100c1", 0)
    .then(console.log);
    > "0x033456732123ffff2342342dd12342434324234234fd234fd23fd4f23d4234"


------------------------------------------------------------------------------

getCode
=====================

.. code-block:: javascript

    web3.eth.getCode(address [, defaultBlock] [, callback])

Get the code at a specific address.

----------
Parameters
----------

1. ``String`` - The address to get the code from.
2. ``Number|String`` - (optional) If you pass this parameter it will not use the default block set with :ref:`web3.eth.defaultBlock <eth-defaultblock>`.
3. ``Function`` - (optional) Optional callback, returns an error object as first parameter and the result as second.

-------
Returns
-------


``Promise`` returns ``String`` - The data at given address ``address``.

-------
Example
-------


.. code-block:: javascript

    web3.eth.getCode("0xd5677cf67b5aa051bb40496e68ad359eb97cfbf8")
    .then(console.log);
    > "0x600160008035811a818181146012578301005b601b6001356025565b8060005260206000f25b600060078202905091905056"


------------------------------------------------------------------------------

.. _eth-getblock:

getBlock
=====================

.. code-block:: javascript

     web3.eth.getBlock(blockHashOrBlockNumber [, returnTransactionObjects] [, callback])

Returns a block matching the block number or block hash.

----------
Parameters
----------

1. ``String|Number`` - The block number or block hash. Or the string ``"genesis"``, ``"latest"`` or ``"pending"`` as in the :ref:`default block parameter <eth-defaultblock>`.
2. ``Boolean`` - (optional, default ``false``) If ``true``, the returned block will contain all transactions as objects, if ``false`` it will only contains the transaction hashes.
3. ``Function`` - (optional) Optional callback, returns an error object as first parameter and the result as second.

-------
Returns
-------


``Promise`` returns ``Object`` - The block object:

  - ``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.
  - ``miner`` - ``String``: The address of the beneficiary to whom the mining rewards were given.
  - ``difficulty`` - ``String``: Integer of the difficulty for this block.
  - ``totalDifficulty`` - ``String``: Integer of the total difficulty of the chain until this block.
  - ``extraData`` - ``String``: The "extra data" field of this block.
  - ``size`` - ``Number``: Integer the size of this block in bytes.
  - ``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.
  - ``transactions`` - ``Array``: Array of transaction objects, or 32 Bytes transaction hashes depending on the ``returnTransactionObjects`` parameter.
  - ``uncles`` - ``Array``: Array of uncle hashes.

-------
Example
-------


.. code-block:: javascript

    web3.eth.getBlock(3150);
    .then(console.log);

    > {
        "number": 3,
        "hash": "0xef95f2f1ed3ca60b048b4bf67cde2195961e0bba6f70bcbea9a2c4e133e34b46",
        "parentHash": "0x2302e1c0b972d00932deb5dab9eb2982f570597d9d42504c05d9c2147eaf9c88",
        "nonce": "0xfb6e1a62d119228b",
        "sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
        "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
        "transactionsRoot": "0x3a1b03875115b79539e5bd33fb00d8f7b7cd61929d5a3c574f507b8acf415bee",
        "stateRoot": "0xf1133199d44695dfa8fd1bcfe424d82854b5cebef75bddd7e40ea94cda515bcb",
        "miner": "0x8888f1f195afa192cfee860698584c030f4c9db1",
        "difficulty": '21345678965432',
        "totalDifficulty": '324567845321',
        "size": 616,
        "extraData": "0x",
        "gasLimit": 3141592,
        "gasUsed": 21662,
        "timestamp": 1429287689,
        "transactions": [
            "0x9fc76417374aa880d4449a1f7f31ec597f00b1f6f3dd2d66f4c9c6c445836d8b"
        ],
        "uncles": []
    }


------------------------------------------------------------------------------


getBlockTransactionCount
=====================

.. code-block:: javascript

    web3.eth.getBlockTransactionCount(blockHashOrBlockNumber [, callback])

Returns the number of transaction in a given block.

----------
Parameters
----------


1. ``String|Number`` - The block number or hash. Or the string ``"genesis"``, ``"latest"`` or ``"pending"`` as in the :ref:`default block parameter <eth-defaultblock>`.
2. ``Function`` - (optional) Optional callback, returns an error object as first parameter and the result as second.

-------
Returns
-------


``Promise`` returns ``Number`` - The number of transactions in the given block.

-------
Example
-------


.. code-block:: javascript

    web3.eth.getBlockTransactionCount("0x407d73d8a49eeb85d32cf465507dd71d507100c1")
    .then(console.log);
    > 1


------------------------------------------------------------------------------

getUncle
=====================

.. code-block:: javascript

    web3.eth.getUncle(blockHashOrBlockNumber, uncleIndex [, returnTransactionObjects] [, callback])

Returns a blocks uncle by a given uncle index position.

----------
Parameters
----------

1. ``String|Number`` - The block number or hash. Or the string ``"genesis"``, ``"latest"`` or ``"pending"`` as in the :ref:`default block parameter <eth-defaultblock>`.
2. ``Number`` - The index position of the uncle.
3. ``Boolean`` - (optional, default ``false``) If ``true``, the returned block will contain all transactions as objects, if ``false`` it will only contains the transaction hashes.
4. ``Function`` - (optional) Optional callback, returns an error object as first parameter and the result as second.


-------
Returns
-------


``Promise`` returns ``Object`` - the returned uncle. For a return value see :ref:`web3.eth.getBlock() <eth-getblock>`.

.. note:: An uncle doesn't contain individual transactions.

-------
Example
-------


.. code-block:: javascript

    web3.eth.getUncle(500, 0)
    .then(console.log);
    > // see web3.eth.getBlock



------------------------------------------------------------------------------


getTransaction
=====================

.. code-block:: javascript

    web3.eth.getTransaction(transactionHash [, callback])

Returns a transaction matching the given transaction hash.

----------
Parameters
----------

1. ``String`` - The transaction hash.
2. ``Function`` - (optional) Optional callback, returns an error object as first parameter and the result as second.


.. _eth-gettransaction-return:

-------
Returns
-------


``Promise`` returns ``Object`` - A transaction object its hash ``transactionHash``:

  - ``hash`` 32 Bytes - ``String``: Hash of the transaction.
  - ``nonce`` - ``Number``: The number of transactions made by the sender prior to this one.
  - ``blockHash`` 32 Bytes - ``String``: Hash of the block where this transaction was in. ``null`` when its pending.
  - ``blockNumber`` - ``Number``: Block number where this transaction was in. ``null`` when its pending.
  - ``transactionIndex`` - ``Number``: Integer of the transactions index position in the block. ``null`` when its pending.
  - ``from`` - ``String``: Address of the sender.
  - ``to`` - ``String``: Address of the receiver. ``null`` when its a contract creation transaction.
  - ``value`` - ``String``: Value transferred in :ref:`wei <what-is-wei>`.
  - ``gasPrice`` - ``String``: Gas price provided by the sender in :ref:`wei <what-is-wei>`.
  - ``gas`` - ``Number``: Gas provided by the sender.
  - ``input`` - ``String``: The data sent along with the transaction.


-------
Example
-------


.. code-block:: javascript

    web3.eth.getTransaction('0x9fc76417374aa880d4449a1f7f31ec597f00b1f6f3dd2d66f4c9c6c445836d8b§234')
    .then(console.log);

    > {
        "hash": "0x9fc76417374aa880d4449a1f7f31ec597f00b1f6f3dd2d66f4c9c6c445836d8b",
        "nonce": 2,
        "blockHash": "0xef95f2f1ed3ca60b048b4bf67cde2195961e0bba6f70bcbea9a2c4e133e34b46",
        "blockNumber": 3,
        "transactionIndex": 0,
        "from": "0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b",
        "to": "0x6295ee1b4f6dd65047762f924ecd367c17eabf8f",
        "value": '123450000000000000',
        "gas": 314159,
        "gasPrice": '2000000000000',
        "input": "0x57cb2fc4"
    }



------------------------------------------------------------------------------

getTransactionFromBlock
=====================

.. code-block:: javascript

    getTransactionFromBlock(hashStringOrNumber, indexNumber [, callback])

Returns a transaction based on a block hash or number and the transactions index position.

----------
Parameters
----------


1. ``String`` - A block number or hash. Or the string ``"genesis"``, ``"latest"`` or ``"pending"`` as in the :ref:`default block parameter <eth-defaultblock>`.
2. ``Number`` - The transactions index position.
3. ``Function`` - (optional) Optional callback, returns an error object as first parameter and the result as second.

-------
Returns
-------


``Promise`` returns ``Object`` - A transaction object, see :ref:`web3.eth.getTransaction <eth-gettransaction-return>`:


-------
Example
-------


.. code-block:: javascript

    var transaction = web3.eth.getTransactionFromBlock('0x4534534534', 2)
    .then(console.log);
    > // see web3.eth.getTransaction



------------------------------------------------------------------------------


getTransactionReceipt
=====================

.. code-block:: javascript

    web3.eth.getTransactionReceipt(hash [, callback])

Returns the receipt of a transaction by transaction hash.

.. note:: The receipt is not available for pending transactions and returns ``null``.


----------
Parameters
----------

1. ``String`` - The transaction hash.
2. ``Function`` - (optional) Optional callback, returns an error object as first parameter and the result as second.


.. _eth-gettransactionreceipt-return:

-------
Returns
-------


``Promise`` returns ``Object`` - A transaction receipt object, or ``null`` when no receipt was found:

  - ``blockHash`` 32 Bytes - ``String``: Hash of the block where this transaction was in.
  - ``blockNumber`` - ``Number``: Block number where this transaction was in.
  - ``transactionHash`` 32 Bytes - ``String``: Hash of the transaction.
  - ``transactionIndex``- ``Number``: Integer of the transactions index position in the block.
  - ``from`` - ``String``: Address of the sender.
  - ``to`` - ``String``: Address of the receiver. ``null`` when its a contract creation transaction.
  - ``contractAddress`` - ``String``: The contract address created, if the transaction was a contract creation, otherwise ``null``.
  - ``cumulativeGasUsed`` - ``Number``: The total amount of gas used when this transaction was executed in the block.
  - ``gasUsed``- ``Number``:  The amount of gas used by this specific transaction alone.
  - ``logs`` - ``Array``: Array of log objects, which this transaction generated.

-------
Example
-------

.. code-block:: javascript

    var receipt = web3.eth.getTransactionReceipt('0x9fc76417374aa880d4449a1f7f31ec597f00b1f6f3dd2d66f4c9c6c445836d8b')
    .then(console.log);

    > {
      "transactionHash": "0x9fc76417374aa880d4449a1f7f31ec597f00b1f6f3dd2d66f4c9c6c445836d8b",
      "transactionIndex": 0,
      "blockHash": "0xef95f2f1ed3ca60b048b4bf67cde2195961e0bba6f70bcbea9a2c4e133e34b46",
      "blockNumber": 3,
      "contractAddress": "0x11f4d0A3c12e86B4b5F39B213F7E19D048276DAe",
      "cumulativeGasUsed": 314159,
      "gasUsed": 30234,
      "logs": [{
             // logs as returned by getPastLogs, etc.
         }, ...]
    }


------------------------------------------------------------------------------


getTransactionCount
=====================

.. code-block:: javascript

    web3.eth.getTransactionCount(address [, defaultBlock] [, callback])

Get the numbers of transactions sent from this address.

----------
Parameters
----------

1. ``String`` - The address to get the numbers of transactions from.
2. ``Number|String`` - (optional) If you pass this parameter it will not use the default block set with :ref:`web3.eth.defaultBlock <eth-defaultblock>`.
3. ``Function`` - (optional) Optional callback, returns an error object as first parameter and the result as second.

-------
Returns
-------


``Promise`` returns ``Number`` - The number of transactions sent from the given address.

-------
Example
-------


.. code-block:: javascript

    web3.eth.getTransactionCount("0x11f4d0A3c12e86B4b5F39B213F7E19D048276DAe")
    .then(console.log);
    > 1


------------------------------------------------------------------------------


sendTransaction
=====================

.. code-block:: javascript

    web3.eth.sendTransaction(transactionObject [, callback])

Sends a transaction to the network.

----------
Parameters
----------


1. ``Object`` - The transaction object to send:
  - ``from`` - ``String``: The address for the sending account. Uses the :ref:`web3.eth.defaultAccount <eth-defaultaccount>` property, if not specified.
  - ``to`` - ``String``: (optional) The destination address of the message, left undefined for a contract-creation transaction.
  - ``value`` - ``Number|String|BN|BigNumber``: (optional) The value transferred for the transaction in :ref:`wei <what-is-wei>`, also the endowment if it's a contract-creation transaction.
  - ``gas``  - ``Number``: (optional, default: To-Be-Determined) The amount of gas to use for the transaction (unused gas is refunded).
  - ``gasPrice`` - ``Number|String|BN|BigNumber``: (optional, default: To-Be-Determined) The price of gas for this transaction in :ref:`wei <what-is-wei>`, defaults to the mean network gas price.
  - ``data`` - ``String``: (optional) Either a `ABI byte string <https://github.com/ethereum/wiki/wiki/Solidity,-Docs-and-ABI`_ containing the data of the function call on a contract, or in the case of a contract-creation transaction the initialisation code.
  - ``nonce`` - ``Number``: (optional) Integer of a nonce. This allows to overwrite your own pending transactions that use the same nonce.
2. ``callback`` - ``Function``: (optional) Optional callback, returns an error object as first parameter and the result as second.

.. _eth-sendtransaction-return:

-------
Returns
-------

The **callback** will return the 32 bytes transaction hash.

``PromiEvent``: A :ref:`promise combined event emitter <promiEvent>`. Will be resolved when the transaction :ref:`receipt <eth-gettransactionreceipt-return>` is available. Additionally the following events are available:

- ``"transactionHash"`` returns ``String``: Is fired right after the transaction is send and a transaction hash is available.
- ``"receipt"`` returns ``Object``: Is fired when the transaction receipt is available.
- ``"confirmation"`` returns ``Number``, ``Object``: Is fired for every confirmation up to the 12th confirmation. Receives the confirmation number as the first and the :ref:`receipt <eth-gettransactionreceipt-return>` as the second argument. Fired from confirmation 0 on, which is the block where its minded.
- ``"error"`` returns ``Error``: Is fired if an error occurs during sending. If a out of gas error, the second parameter is the receipt.


-------
Example
-------

.. code-block:: javascript

    // compiled solidity source code using https://remix.ethereum.org
    var code = "603d80600c6000396000f3007c01000000000000000000000000000000000000000000000000000000006000350463c6888fa18114602d57005b6007600435028060005260206000f3";


    // using the callback
    web3.eth.sendTransaction({
        from: '0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe',
        data: code // deploying a contracrt
    }, function(error, hash){
        ...
    });

    // using the promise
    web3.eth.sendTransaction({
        from: '0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe',
        to: '0x11f4d0A3c12e86B4b5F39B213F7E19D048276DAe',
        value: '1000000000000000'
    })
    .then(function(receipt){
        ...
    });


    // using the event emitter
    web3.eth.sendTransaction({
        from: '0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe',
        to: '0x11f4d0A3c12e86B4b5F39B213F7E19D048276DAe',
        value: '1000000000000000'
    })
    .on('transactionHash', function(hash){
        ...
    })
    .on('receipt', function(receipt){
        ...
    })
    .on('confirmation', function(confirmationNumber, receipt){ ... })
    .on('error', console.error); // If a out of gas error, the second parameter is the receipt.


------------------------------------------------------------------------------


sendSignedTransaction
=====================

.. code-block:: javascript

    web3.eth.sendSignedTransaction(signedTransactionData [, callback])

Sends an already signed transaction. For example can be signed using: `ethereumjs-accounts <https://github.com/SilentCicero/ethereumjs-accounts>`_

----------
Parameters
----------

1. ``String`` - Signed transaction data in HEX format
2. ``Function`` - (optional) Optional callback, returns an error object as first parameter and the result as second.

-------
Returns
-------


``PromiEvent``: A :ref:`promise combined event emitter <promiEvent>`. Will be resolved when the transaction :ref:`receipt <eth-gettransactionreceipt-return>` is available.

Please see the return values for :ref:`web3.eth.sendTransaction <eth-sendtransaction-return>` for details.

-------
Example
-------


.. code-block:: javascript

    var Tx = require('ethereumjs-tx');
    var privateKey = new Buffer('e331b6d69882b4cb4ea581d88e0b604039a3de5967688d3dcffdd2270c0fd109', 'hex')

    var rawTx = {
      nonce: '0x00',
      gasPrice: '0x09184e72a000',
      gasLimit: '0x2710',
      to: '0x0000000000000000000000000000000000000000',
      value: '0x00',
      data: '0x7f7465737432000000000000000000000000000000000000000000000000000000600057'
    }

    var tx = new Tx(rawTx);
    tx.sign(privateKey);

    var serializedTx = tx.serialize();

    // console.log(serializedTx.toString('hex'));
    // 0xf889808609184e72a00082271094000000000000000000000000000000000000000080a47f74657374320000000000000000000000000000000000000000000000000000006000571ca08a8bbf888cfa37bbf0bb965423625641fc956967b81d12e23709cead01446075a01ce999b56a8a88504be365442ea61239198e23d1fce7d00fcfc5cd3b44b7215f

    web3.eth.sendSignedTransaction(serializedTx.toString('hex'))
    .on('receipt', console.log);

    > // see eth.getTransactionReceipt() for details


------------------------------------------------------------------------------


sign
=====================

.. code-block:: javascript

    web3.eth.sign(address, dataToSign, [, callback])

Signs data from a specific account. This account needs to be unlocked.

----------
Parameters
----------


1. ``String`` - Address to sign data with.
2. ``String`` - Data to sign.
3. ``Function`` - (optional) Optional callback, returns an error object as first parameter and the result as second.

After the hex prefix, characters correspond to ECDSA values like this:

.. code-block:: javascript
    r = signature[0:64]
    s = signature[64:128]
    v = signature[128:130]

-------
Returns
-------


``Promise`` returns ``String`` - The signed data.


Note that if you are using ``ecrecover``, ``v`` will be either `"00"` or `"01"`. As a result, in order to use this value, you will have to parse it to an integer and then add `27`. This will result in either a `27` or a `28`.


-------
Example
-------


.. code-block:: javascript

    web3.eth.sign("0x11f4d0A3c12e86B4b5F39B213F7E19D048276DAe", "0x9dd2c369a187b4e6b9c402f030e50743e619301ea62aa4c0737d4ef7e10a3d49")
    .then(console.log);
    > "0x30755ed65396facf86c53e6217c52b4daebe72aa4941d89635409de4c9c7f9466d4e9aaec7977f05e923889b33c0d0dd27d7226b6e6f56ce737465c5cfd04be400"


------------------------------------------------------------------------------


call
=====================

.. code-block:: javascript

    web3.eth.call(callObject [, defaultBlock] [, callback])

Executes a message call transaction, which is directly executed in the VM of the node, but never mined into the blockchain.

----------
Parameters
----------

1. ``Object`` - A transaction object see :ref:`web3.eth.sendTransaction <eth-sendtransaction-return>`, with the difference that for calls the ``from`` property is optional as well.
2. ``Number|String`` - (optional) If you pass this parameter it will not use the default block set with :ref:`web3.eth.defaultBlock <eth-defaultblock>`.
3. ``Function`` - (optional) Optional callback, returns an error object as first parameter and the result as second.

-------
Returns
-------

``Promise`` returns ``String``: The returned data of the call, e.g. a smart contract functions return value.

-------
Example
-------


.. code-block:: javascript

    web3.eth.call({
        to: "0x11f4d0A3c12e86B4b5F39B213F7E19D048276DAe", // contract address
        data: "0xc6888fa10000000000000000000000000000000000000000000000000000000000000003"
    })
    .then(console.log);
    > "0x000000000000000000000000000000000000000000000000000000000000000a"


------------------------------------------------------------------------------


estimateGas
=====================

.. code-block:: javascript

    web3.eth.estimateGas(callObject [, callback])

Executes a message call or transaction and returns the amount of the gas used.

----------
Parameters
----------


1. ``Object`` - A transaction object see :ref:`web3.eth.sendTransaction <eth-sendtransaction-return>`, with the difference that for calls the ``from`` property is optional as well.
2. ``Function`` - (optional) Optional callback, returns an error object as first parameter and the result as second.


-------
Returns
-------

``Promise`` returns ``Number`` - the used gas for the simulated call/transaction.

-------
Example
-------


.. code-block:: javascript

    web3.eth.estimateGas({
        to: "0x11f4d0A3c12e86B4b5F39B213F7E19D048276DAe",
        data: "0xc6888fa10000000000000000000000000000000000000000000000000000000000000003"
    })
    .then(console.log);
    > "0x0000000000000000000000000000000000000000000000000000000000000015"


------------------------------------------------------------------------------


getPastLogs
=====================

.. code-block:: javascript

    web3.eth.getPastLogs(options [, callback])

Gets past logs, matching the given options.

----------
Parameters
----------

1. ``Object`` - The filter options as follows:
  - ``fromBlock`` - ``Number|String``: The number of the earliest block (``"latest"`` may be given to mean the most recent and ``"pending"`` currently mining, block). By default ``"latest"``.
  - ``toBlock`` -  ``Number|String``: The number of the latest block (``"latest"`` may be given to mean the most recent and ``"pending"`` currently mining, block). By default ``"latest"``.
  - ``address`` -  ``String``: 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, '0x12...']``. You can also pass an array for each topic with options for that topic e.g. ``[null, ['option1', 'option2']]``


.. _eth-getpastlogs-return:

-------
Returns
-------

``Promise`` returns ``Array`` - Array of log objects.

The structure of the returned event ``Object`` in the ``Array`` looks as follows:

- ``address`` - ``String``: From which this event originated from.
- ``data`` - ``String``: The data containing non-indexed log parameter.
- ``topics`` - ``Array``: An array with max 4 32 Byte topics, topic 1-3 contains indexed parameters of the log.
- ``logIndex`` - ``Number``: Integer of the event index position in the block.
- ``transactionIndex`` - ``Number``: Integer of the transaction's index position, the event was created in.
- ``transactionHash`` 32 Bytes - ``String``: Hash of the transaction this event was created in.
- ``blockHash`` 32 Bytes - ``String``: Hash of the block where this event was created in. ``null`` when its still pending.
- ``blockNumber`` - ``Number``: The block number where this log was created in. ``null`` when still pending.

-------
Example
-------

.. code-block:: javascript

    web3.eth.getPastLogs({
        address: "0x11f4d0A3c12e86B4b5F39B213F7E19D048276DAe",
        topics: ["0x033456732123ffff2342342dd12342434324234234fd234fd23fd4f23d4234"]
    })
    .then(console.log);

    > [{
        data: '0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385',
        topics: ['0xfd43ade1c09fade1c0d57a7af66ab4ead7c2c2eb7b11a91ffdd57a7af66ab4ead7', '0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385']
        logIndex: 0,
        transactionIndex: 0,
        transactionHash: '0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385',
        blockHash: '0xfd43ade1c09fade1c0d57a7af66ab4ead7c2c2eb7b11a91ffdd57a7af66ab4ead7',
        blockNumber: 1234,
        address: '0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe'
    },{...}]


------------------------------------------------------------------------------


getCompilers
=====================

.. code-block:: javascript

    web3.eth.getCompilers([callback])

Gets a list of available compilers.

----------
Parameters
----------

1. ``Function`` - (optional) Optional callback, returns an error object as first parameter and the result as second.

-------
Returns
-------

``Promise`` returns ``Array`` - An array of strings of available compilers.

-------
Example
-------


.. code-block:: javascript

    web3.eth.getCompilers();
    .then(console.log);
    > ["lll", "solidity", "serpent"]


------------------------------------------------------------------------------

compile.solidity
=====================

.. code-block:: javascript

    web3.eth.compile.solidity(sourceCode [, callback])

Compiles solidity source code.

----------
Parameters
----------

1. ``String`` - The solidity source code.
2. ``Function`` - (optional) Optional callback, returns an error object as first parameter and the result as second.

-------
Returns
-------

``Promise`` returns ``Object`` - Contract and compiler info.

-------
Example
-------


.. code-block:: javascript

    var source = "" +
        "contract test {\n" +
        "   function multiply(uint a) returns(uint d) {\n" +
        "       return a * 7;\n" +
        "   }\n" +
        "}\n";

    web3.eth.compile.solidity(source);
    .then(console.log);

    > {
      "test": {
        "code": "0x605280600c6000396000f3006000357c010000000000000000000000000000000000000000000000000000000090048063c6888fa114602e57005b60376004356041565b8060005260206000f35b6000600782029050604d565b91905056",
        "info": {
          "source": "contract test {\n\tfunction multiply(uint a) returns(uint d) {\n\t\treturn a * 7;\n\t}\n}\n",
          "language": "Solidity",
          "languageVersion": "0",
          "compilerVersion": "0.8.2",
          "abiDefinition": [
            {
              "constant": false,
              "inputs": [
                {
                  "name": "a",
                  "type": "uint256"
                }
              ],
              "name": "multiply",
              "outputs": [
                {
                  "name": "d",
                  "type": "uint256"
                }
              ],
              "type": "function"
            }
          ],
          "userDoc": {
            "methods": {}
          },
          "developerDoc": {
            "methods": {}
          }
        }
      }
    }


------------------------------------------------------------------------------


compile.lll
=====================

.. code-block:: javascript

    web3. eth.compile.lll(sourceCode [, callback])

Compiles LLL source code.

----------
Parameters
----------

1. ``String`` - The LLL source code.
2. ``Function`` - (optional) Optional callback, returns an error object as first parameter and the result as second.

-------
Returns
-------


``Promise`` returns ``String`` - The compiled LLL code as HEX string.


-------
Example
-------


.. code-block:: javascript

    var source = "...";

    web3.eth.compile.lll(source);
    .then(console.log);
    > "0x603880600c6000396000f3006001600060e060020a600035048063c6888fa114601857005b6021600435602b565b8060005260206000f35b600081600702905091905056"


------------------------------------------------------------------------------

compile.serpent
=====================

.. code-block:: javascript

    web3.eth.compile.serpent(sourceCode [, callback])

Compiles serpent source code.

----------
Parameters
----------

1. ``String`` - The serpent source code.
2. ``Function`` - (optional) Optional callback, returns an error object as first parameter and the result as second.

-------
Returns
-------


``Promise`` returns ``String`` - The compiled serpent code as HEX string.


.. code-block:: javascript

    var source = "...";

    var code = web3.eth.compile.serpent(source);
    .then(console.log);
    > "0x603880600c6000396000f3006001600060e060020a600035048063c6888fa114601857005b6021600435602b565b8060005260206000f35b600081600702905091905056"



------------------------------------------------------------------------------

getWork
=====================

.. code-block:: javascript

    web3.eth.getWork([callback])

Gets work for miners to mine on. Returns the hash of the current block, the seedHash, and the boundary condition to be met ("target").

----------
Parameters
----------

1. ``Function`` - (optional) Optional callback, returns an error object as first parameter and the result as second.

-------
Returns
-------

``Promise`` returns ``Array`` - the mining work with the following structure:

    - ``String`` 32 Bytes - at **index 0**: current block header pow-hash
    - ``String`` 32 Bytes - at **index 1**: the seed hash used for the DAG.
    - ``String`` 32 Bytes - at **index 2**: the boundary condition ("target"), 2^256 / difficulty.

-------
Example
-------


.. code-block:: javascript

    web3.eth.getWork();
    .then(console.log);
    > [
      "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
      "0x5EED00000000000000000000000000005EED0000000000000000000000000000",
      "0xd1ff1c01710000000000000000000000d1ff1c01710000000000000000000000"
    ]


------------------------------------------------------------------------------

submitWork
=====================

.. code-block:: javascript

    web3.eth.submitWork(nonce, powHash, digest, [callback])

Used for submitting a proof-of-work solution.

----------
Parameters
----------

1. ``String`` 8 Bytes: The nonce found (64 bits)
2. ``String`` 32 Bytes: The header's pow-hash (256 bits)
3. ``String`` 32 Bytes: The mix digest (256 bits)
4. ``Function`` - (optional) Optional callback, returns an error object as first parameter and the result as second.

-------
Returns
-------

``Promise`` returns ``Boolean`` - Returns ``TRUE`` if the provided solution is valid, otherwise false.

-------
Example
-------


.. code-block:: javascript

    web3.eth.submitWork([
        "0x0000000000000001",
        "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
        "0xD1FE5700000000000000000000000000D1FE5700000000000000000000000000"
    ]);
    .then(console.log);
    > true


------------------------------------------------------------------------------