status-im/web3.js
2
0
Fork 0
mirror of https://github.com/status-im/web3.js.git synced 2025-02-23 11:38:12 +00:00
Code Issues Projects Releases Wiki Activity
web3.js/docs/web3-eth.rst
Fabian Vogelsteller 5079db35ab
fixed subscription title
2017-02-08 20:00:25 +01:00

2031 lines
49 KiB
ReStructuredText
Raw Blame History

========
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 <eth-subscribe>`
------------------------------------------------------------------------------
Contract
=====================
For ``web3.eth.Contract`` see the :ref:`eth.Contract reference documentation <eth-contract>`
------------------------------------------------------------------------------
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 <web3-providers>`.
-------
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() <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
- ``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 <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.
- ``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 <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``:
- ``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 <what-is-wei>`.
- ``String`` - **gasPrice**: Gas price provided by the sender in :ref:`wei <what-is-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 <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** 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 <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 <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 <what-is-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 <what-is-wei>`, defaults to the mean network gas price.
- ``String`` - **data**: (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.
- ``Number`` -**nonce**: (optional) Integer of a nonce. This allows to overwrite your own pending transactions that use the same nonce.
2. ``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:
- ``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'
Reference in New Issue View Git Blame Copy Permalink