======== web3.eth ======== TODO: add instantiation code with web3 and Eth package TODO: add note about checksum addresses ------------------------------------------------------------------------------ subscribe ===================== For ``web3.eth.subscribe`` see the :ref:`eth.subscribe reference documentation ` ------------------------------------------------------------------------------ Contract ===================== For ``web3.eth.Contract`` see the :ref:`eth.Contract reference documentation ` ------------------------------------------------------------------------------ setProvider ===================== .. code-block:: javascript web3.eth.setProvider(myProvider) When called changes the current provider for all modules. ---------- Parameters ---------- 1. ``Object`` - **myProvider**: :ref:`a valid provider `. ------- Returns ------- ``Boolean`` ------- Example ------- .. code-block:: javascript eth.setProvider(new eth.providers.HttpProvider('http://localhost:8545')); ------------------------------------------------------------------------------ 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() ` - :ref:`web3.eth.call() ` - :ref:`new web3.eth.Contract() -> myContract.methods.myMethod().call() ` - :ref:`new web3.eth.Contract() -> myContract.methods.myMethod().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() ` - :ref:`web3.eth.getCode() ` - :ref:`web3.eth.getTransactionCount() ` - :ref:`web3.eth.getStorageAt() ` - :ref:`web3.eth.call() ` - :ref:`new web3.eth.Contract() -> myContract.methods.myMethod().call() ` ---------- Property ---------- Default block parameters can be one of the following: - ``Number``: A block number - ``String`` - ``"genesis"``: The genesis block - ``String`` - ``"latest"``: The latest block (current head of the blockchain) - ``String`` - ``"pending"``: 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 were the mining rewards currently go to. ------- 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 `. See the :ref:`A note on dealing with 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 `. 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 `. See the :ref:`A note on dealing with 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 `. 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 `. 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 `. 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. - ``String`` 32 Bytes - **hash**: Hash of the block. ``null`` when its pending block. - ``String`` 32 Bytes - **parentHash**: Hash of the parent block. - ``String`` 8 Bytes - **nonce**: Hash of the generated proof-of-work. ``null`` when its pending block. - ``String`` 32 Bytes - **sha3Uncles**: SHA3 of the uncles data in the block. - ``String`` 256 Bytes - **logsBloom**: The bloom filter for the logs of the block. ``null`` when its pending block. - ``String`` 32 Bytes - **transactionsRoot**: The root of the transaction trie of the block - ``String`` 32 Bytes - **stateRoot**: The root of the final state trie of the block. - ``String`` - **miner**: The address of the beneficiary to whom the mining rewards were given. - ``String`` - **difficulty**: Integer of the difficulty for this block. - ``String`` - **totalDifficulty**: Integer of the total difficulty of the chain until this block. - ``String`` - **extraData**: The "extra data" field of this block. - ``Number`` - **size**: Integer the size of this block in bytes. - ``Number`` - **gasLimit**: The maximum gas allowed in this block. - ``Number`` - **gasUsed**: The total used gas by all transactions in this block. - ``Number`` - **timestamp**: The unix timestamp for when the block was collated. - ``Array`` - **transactions**: Array of transaction objects, or 32 Bytes transaction hashes depending on the ``returnTransactionObjects`` parameter. - ``Array`` - **uncles**: 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 `. 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 `. 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() `. **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``: - ``String`` 32 Bytes - **hash**: Hash of the transaction. - ``Number`` - **nonce**: The number of transactions made by the sender prior to this one. - ``String`` 32 Bytes - **blockHash**: Hash of the block where this transaction was in. ``null`` when its pending. - ``Number`` - **blockNumber**: Block number where this transaction was in. ``null`` when its pending. - ``Number`` - **transactionIndex**: Integer of the transactions index position in the block. ``null`` when its pending. - ``String`` - **from**: Address of the sender. - ``String`` - **to**: Address of the receiver. ``null`` when its a contract creation transaction. - ``String`` - **value**: Value transferred in :ref:`wei `. - ``String`` - **gasPrice**: Gas price provided by the sender in :ref:`wei `. - ``Number`` - **gas**: Gas provided by the sender. - ``String`` - **input**: 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 `. 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 `: ------- 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** That 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: - ``String`` 32 Bytes - **blockHash**: Hash of the block where this transaction was in. - ``Number`` - **blockNumber**: Block number where this transaction was in. - ``String`` 32 Bytes - **transactionHash**: Hash of the transaction. - ``Number``- **transactionIndex**: Integer of the transactions index position in the block. - ``String`` - **from**: Address of the sender. - ``String`` - **to**: Address of the receiver. ``null`` when its a contract creation transaction. - ``String`` - **contractAddress**: The contract address created, if the transaction was a contract creation, otherwise ``null``. - ``Number`` - **cumulativeGasUsed**: The total amount of gas used when this transaction was executed in the block. - ``Number``- **gasUsed**: The amount of gas used by this specific transaction alone. - ``Array`` - **logs**: 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 `. 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: - ``String`` - **from**: The address for the sending account. Uses the :ref:`web3.eth.defaultAccount ` property, if not specified. - ``String`` - **to**: (optional) The destination address of the message, left undefined for a contract-creation transaction. - ``Number|String`` - **value**: (optional) The value transferred for the transaction in :ref:`wei `, also the endowment if it's a contract-creation transaction. - ``Number`` - **gas**: (optional, default: To-Be-Determined) The amount of gas to use for the transaction (unused gas is refunded). - ``Number|String`` - **gasPrice**: (optional, default: To-Be-Determined) The price of gas for this transaction in :ref:`wei `, defaults to the mean network gas price. - ``String`` - **data**: (optional) Either a `ABI byte string `. Will be resolved when the transaction :ref:`receipt ` 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 ` 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 `_ ---------- 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 `. Will be resolved when the transaction :ref:`receipt ` is available. Please see the return values for :ref:`web3.eth.sendTransaction ` 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 `, 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 `. 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 `, 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: - ``Number|String`` - **fromBlock**: The number of the earliest block (`latest` may be given to mean the most recent and `pending` currently mining, block). By default `latest`. - ``Number|String`` - **toBlock**: The number of the latest block (`latest` may be given to mean the most recent and `pending` currently mining, block). By default `latest`. - ``String`` - **address**: An address or a list of addresses to only get logs from particular account(s). - ``Array`` - **topics**: 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: - ``String`` - **address**: From which this event originated from. - ``String`` - **data**: The data containing non-indexed log parameter. - ``Array`` - **topics**: An array with max 4 32 Byte topics, topic 1-3 contains indexed parameters of the log. - ``Number`` - **logIndex**: Integer of the event index position in the block. - ``Number`` - **transactionIndex**: Integer of the transaction's index position, the event was created in. - ``String`` 32 Bytes - **transactionHash**: Hash of the transaction this event was created in. - ``String`` 32 Bytes - **blockHash**: Hash of the block where this event was created in. ``null`` when its still pending. - ``Number`` - **blockNumber**: 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 ------------------------------------------------------------------------------ Iban ===================== .. code-block:: javascript new web3.eth.Iban(ibanAddress) Generates a iban object with conversion methods and vailidity checks. Also has singleton functions for conversion like :ref:`Iban.toAddress() <_eth-iban-toaddress>`, :ref:`Iban.toIban() <_eth-iban-toiban>`, :ref:`Iban.fromEthereumAddress() <_eth-iban-fromethereumaddress>`, :ref:`Iban.fromBban() <_eth-iban-frombban>`, :ref:`Iban.createIndirect() <_eth-iban-createindirect>`, :ref:`Iban.isValid() <_eth-iban-isvalid>`. ---------- Parameters ---------- 1. ``String``: the iban address to instantiate an Iban instance from. ------- Returns ------- ``Object`` - The Iban instance. ------- Example ------- .. code-block:: javascript var iban = new web3.eth.Iban("XE81ETHXREGGAVOFYORK"); ------------------------------------------------------------------------------ .. _eth-iban-toaddress: Iban.toAddress ===================== .. code-block:: javascript web3.eth.Iban.toAddress(ibanAddress) Singleton: Converts a direct IBAN address into an ethereum address. **Note**: This method also exists on the IBAN instance. ---------- Parameters ---------- 1. ``String``: the IBAN address to convert. ------- Returns ------- ``String`` - The ethereum address. ------- Example ------- .. code-block:: javascript web3.eth.Iban.toAddress("XE7338O073KYGTWWZN0F2WZ0R8PX5ZPPZS"); > "0x00c5496aEe77C1bA1f0854206A26DdA82a81D6D8" ------------------------------------------------------------------------------ .. _eth-iban-toiban: Iban.toIban ===================== .. code-block:: javascript web3.eth.Iban.toIban(address) Singleton: Converts an ethereum address to a direct IBAN address. ---------- Parameters ---------- 1. ``String``: the ethereum address to convert. ------- Returns ------- ``String`` - The IBAN address. ------- Example ------- .. code-block:: javascript web3.eth.Iban.toIban("0x00c5496aEe77C1bA1f0854206A26DdA82a81D6D8"); > "XE7338O073KYGTWWZN0F2WZ0R8PX5ZPPZS" ------------------------------------------------------------------------------ .. _eth-iban-fromethereumaddress: Iban.fromEthereumAddress ===================== .. code-block:: javascript web3.eth.Iban.fromEthereumAddress(address) Singleton: Converts an ethereum address to a direct IBAN instance. ---------- Parameters ---------- 1. ``String``: the ethereum address to convert. ------- Returns ------- ``Object`` - The IBAN instance. ------- Example ------- .. code-block:: javascript web3.eth.Iban.fromEthereumAddress("0x00c5496aEe77C1bA1f0854206A26DdA82a81D6D8"); > Iban {_iban: "XE7338O073KYGTWWZN0F2WZ0R8PX5ZPPZS"} ------------------------------------------------------------------------------ .. _eth-iban-frombban: Iban.fromBban ===================== .. code-block:: javascript web3.eth.Iban.fromBban(bbanAddress) Singleton: Converts an BBAN address to a direct IBAN instance. ---------- Parameters ---------- 1. ``String``: the BBAN address to convert. ------- Returns ------- ``Object`` - The IBAN instance. ------- Example ------- .. code-block:: javascript web3.eth.Iban.fromBban('ETHXREGGAVOFYORK'); > Iban {_iban: "XE7338O073KYGTWWZN0F2WZ0R8PX5ZPPZS"} ------------------------------------------------------------------------------ .. _eth-iban-createindirect: Iban.createIndirect ===================== .. code-block:: javascript web3.eth.Iban.createIndirect(options) Singleton: Creates an indirect IBAN address from a institution and identifier. ---------- Parameters ---------- 1. ``Object``: the options object as follows: - ``String`` - **institution**: the institution to be assigned - ``String`` - **identifier**: the identifier to be assigned ------- Returns ------- ``Object`` - The IBAN instance. ------- Example ------- .. code-block:: javascript web3.eth.Iban.createIndirect({ institution: "XREG", identifier: "GAVOFYORK" }); > Iban {_iban: "XE7338O073KYGTWWZN0F2WZ0R8PX5ZPPZS"} ------------------------------------------------------------------------------ .. _eth-iban-isvalid: Iban.isValid ===================== .. code-block:: javascript web3.eth.Iban.isValid(address) Singleton: Checks if an IBAN address is valid. **Note**: This method also exists on the IBAN instance. ---------- Parameters ---------- 1. ``String``: the IBAN address to check. ------- Returns ------- ``Boolean`` ------- Example ------- .. code-block:: javascript web3.eth.Iban.isValid("XE81ETHXREGGAVOFYORK"); > true web3.eth.Iban.isValid("XE82ETHXREGGAVOFYORK"); > false // because the checksum is incorrect var iban = new web3.eth.Iban("XE81ETHXREGGAVOFYORK"); iban.isValid(); > true ------------------------------------------------------------------------------ Iban.isDirect ===================== .. code-block:: javascript web3.eth.Iban.isDirect() Checks if the IBAN instance is direct. ---------- Parameters ---------- none ------- Returns ------- ``Boolean`` ------- Example ------- .. code-block:: javascript var iban = new web3.eth.Iban("XE81ETHXREGGAVOFYORK"); iban.isDirect(); > false ------------------------------------------------------------------------------ Iban.isIndirect ===================== .. code-block:: javascript web3.eth.Iban.isIndirect() Checks if the IBAN instance is indirect. ---------- Parameters ---------- none ------- Returns ------- ``Boolean`` ------- Example ------- .. code-block:: javascript var iban = new web3.eth.Iban("XE81ETHXREGGAVOFYORK"); iban.isIndirect(); > true ------------------------------------------------------------------------------ Iban.checksum ===================== .. code-block:: javascript web3.eth.Iban.checksum() Returns the checksum of the IBAN instance. ---------- Parameters ---------- none ------- Returns ------- ``String``: The checksum of the IBAN ------- Example ------- .. code-block:: javascript var iban = new web3.eth.Iban("XE81ETHXREGGAVOFYORK"); iban.checksum(); > "81" ------------------------------------------------------------------------------ Iban.institution ===================== .. code-block:: javascript web3.eth.Iban.institution() Returns the institution of the IBAN instance. ---------- Parameters ---------- none ------- Returns ------- ``String``: The institution of the IBAN ------- Example ------- .. code-block:: javascript var iban = new web3.eth.Iban("XE81ETHXREGGAVOFYORK"); iban.institution(); > 'XREG' ------------------------------------------------------------------------------ Iban.client ===================== .. code-block:: javascript web3.eth.Iban.client() Returns the client of the IBAN instance. ---------- Parameters ---------- none ------- Returns ------- ``String``: The client of the IBAN ------- Example ------- .. code-block:: javascript var iban = new web3.eth.Iban("XE81ETHXREGGAVOFYORK"); iban.client(); > 'GAVOFYORK' ------------------------------------------------------------------------------ Iban.toAddress ===================== .. code-block:: javascript web3.eth.Iban.toAddress() Returns the ethereum address of the IBAN instance. ---------- Parameters ---------- none ------- Returns ------- ``String``: The ethereum address of the IBAN ------- Example ------- .. code-block:: javascript var iban = new web3.eth.Iban('XE7338O073KYGTWWZN0F2WZ0R8PX5ZPPZS'); iban.toAddress(); > '0x00c5496aEe77C1bA1f0854206A26DdA82a81D6D8' ------------------------------------------------------------------------------ Iban.toString ===================== .. code-block:: javascript web3.eth.Iban.toString() Returns the IBAN address of the IBAN instance. ---------- Parameters ---------- none ------- Returns ------- ``String``: The IBAN address. ------- Example ------- .. code-block:: javascript var iban = new web3.eth.Iban('XE7338O073KYGTWWZN0F2WZ0R8PX5ZPPZS'); iban.toString(); > 'XE7338O073KYGTWWZN0F2WZ0R8PX5ZPPZS'