web3.eth

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

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

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


// or using the web3 umbrella package

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

// -> web3.eth

Note on checksum addresses

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

Example

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

subscribe

For web3.eth.subscribe see the Subscribe reference documentation


Contract

For web3.eth.Contract see the Contract reference documentation


Iban

For web3.eth.Iban see the Iban reference documentation


personal

For web3.eth.personal see the personal reference documentation


accounts

For web3.eth.accounts see the accounts reference documentation


ens

For web3.eth.ens see the ENS reference documentation


abi

For web3.eth.abi see the ABI reference documentation


net

For web3.eth.net see the net reference documentation


setProvider

web3.setProvider(myProvider)
web3.eth.setProvider(myProvider)
web3.shh.setProvider(myProvider)
web3.bzz.setProvider(myProvider)
...

Will change the provider for its module.

Note

When called on the umbrella package web3 it will also set the provider for all sub modules web3.eth, web3.shh, etc EXCEPT web3.bzz which needs a separate provider at all times.

Parameters

  1. Object - myProvider: a valid provider.

Returns

Boolean

Example

var Web3 = require('web3');
var web3 = new Web3('http://localhost:8545');
// or
var web3 = new Web3(new Web3.providers.HttpProvider('http://localhost:8545'));

// change provider
web3.setProvider('ws://localhost:8546');
// or
web3.setProvider(new Web3.providers.WebsocketProvider('ws://localhost:8546'));

// Using the IPC provider in node.js
var net = require('net');
var web3 = new Web3('/Users/myuser/Library/Ethereum/geth.ipc', net); // mac os path
// or
var web3 = new Web3(new Web3.providers.IpcProvider('/Users/myuser/Library/Ethereum/geth.ipc', net)); // mac os path
// on windows the path is: "\\\\.\\pipe\\geth.ipc"
// on linux the path is: "/users/myuser/.ethereum/geth.ipc"

providers

web3.providers
web3.eth.providers
web3.shh.providers
web3.bzz.providers
...

Contains the current available providers.

Value

Object with the following providers:

  • Object - HttpProvider: The HTTP provider is deprecated, as it won’t work for subscriptions.
  • Object - WebsocketProvider: The Websocket provider is the standard for usage in legacy browsers.
  • Object - IpcProvider: The IPC provider is used node.js dapps when running a local node. Gives the most secure connection.

Example

var Web3 = require('web3');
// use the given Provider, e.g in Mist, or instantiate a new websocket provider
var web3 = new Web3(Web3.givenProvider || 'ws://remotenode.com:8546');
// or
var web3 = new Web3(Web3.givenProvider || new Web3.providers.WebsocketProvider('ws://remotenode.com:8546'));

// Using the IPC provider in node.js
var net = require('net');

var web3 = new Web3('/Users/myuser/Library/Ethereum/geth.ipc', net); // mac os path
// or
var web3 = new Web3(new Web3.providers.IpcProvider('/Users/myuser/Library/Ethereum/geth.ipc', net)); // mac os path
// on windows the path is: "\\\\.\\pipe\\geth.ipc"
// on linux the path is: "/users/myuser/.ethereum/geth.ipc"

givenProvider

web3.givenProvider
web3.eth.givenProvider
web3.shh.givenProvider
web3.bzz.givenProvider
...

When using web3.js in an Ethereum compatible browser, it will set with the current native provider by that browser. Will return the given provider by the (browser) environment, otherwise null.

Returns

Object: The given provider set or null;

Example


currentProvider

web3.currentProvider
web3.eth.currentProvider
web3.shh.currentProvider
web3.bzz.currentProvider
...

Will return the current provider, otherwise null.

Returns

Object: The current provider set or null;

Example


BatchRequest

new web3.BatchRequest()
new web3.eth.BatchRequest()
new web3.shh.BatchRequest()
new web3.bzz.BatchRequest()

Class to create and execute batch requests.

Parameters

none

Returns

Object: With the following methods:

  • add(request): To add a request object to the batch call.
  • execute(): Will execute the batch request.

Example

var contract = new web3.eth.Contract(abi, address);

var batch = new web3.BatchRequest();
batch.add(web3.eth.getBalance.request('0x0000000000000000000000000000000000000000', 'latest', callback));
batch.add(contract.methods.balance(address).call.request({from: '0x0000000000000000000000000000000000000000'}, callback2));
batch.execute();

extend

web3.extend(methods)
web3.eth.extend(methods)
web3.shh.extend(methods)
web3.bzz.extend(methods)
...

Allows extending the web3 modules.

Note

You also have *.extend.formatters as additional formatter functions to be used for in and output formatting. Please see the source file for function details.

Parameters

  1. methods - Object: Extension object with array of methods description objects as follows:
    • property - String: (optional) The name of the property to add to the module. If no property is set it will be added to the module directly.
    • methods - Array: The array of method descriptions:
      • name - String: Name of the method to add.
      • call - String: The RPC method name.
      • params - Number: (optional) The number of parameters for that function. Default 0.
      • inputFormatter - Array: (optional) Array of inputformatter functions. Each array item responds to a function parameter, so if you want some parameters not to be formatted, add a null instead.
      • outputFormatter - ``Function: (optional) Can be used to format the output of the method.

Returns

Object: The extended module.

Example

web3.extend({
    property: 'myModule',
    methods: [{
        name: 'getBalance',
        call: 'eth_getBalance',
        params: 2,
        inputFormatter: [web3.extend.formatters.inputAddressFormatter, web3.extend.formatters.inputDefaultBlockNumberFormatter],
        outputFormatter: web3.utils.hexToNumberString
    },{
        name: 'getGasPriceSuperFunction',
        call: 'eth_gasPriceSuper',
        params: 2,
        inputFormatter: [null, web3.utils.numberToHex]
    }]
});

web3.extend({
    methods: [{
        name: 'directCall',
        call: 'eth_callForFun',
    }]
});

console.log(web3);
> Web3 {
    myModule: {
        getBalance: function(){},
        getGasPriceSuperFunction: function(){}
    },
    directCall: function(){},
    eth: Eth {...},
    bzz: Bzz {...},
    ...
}


defaultAccount

web3.eth.defaultAccount

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

  • web3.eth.sendTransaction()
  • web3.eth.call()
  • new web3.eth.Contract() -> myContract.methods.myMethod().call()
  • 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

web3.eth.defaultAccount;
> undefined

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

defaultBlock

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”.

  • web3.eth.getBalance()
  • web3.eth.getCode()
  • web3.eth.getTransactionCount()
  • web3.eth.getStorageAt()
  • web3.eth.call()
  • new web3.eth.Contract() -> myContract.methods.myMethod().call()

Property

Default block parameters can be one of the following:

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

Default is "latest"

Example

web3.eth.defaultBlock;
> "latest"

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

defaultHardfork

web3.eth.defaultHardfork

The default hardfork property is used for signing transactions locally.

Property

The default hardfork property can be one of the following:

  • "chainstart" - String
  • "homestead" - String
  • "dao" - String
  • "tangerineWhistle" - String
  • "spuriousDragon" - String
  • "byzantium" - String
  • "constantinople" - String
  • "petersburg" - String
  • "istanbul" - String

Default is "petersburg"

Example

web3.eth.defaultHardfork;
> "petersburg"

// set the default block
web3.eth.defaultHardfork = 'istanbul';

defaultChain

web3.eth.defaultChain

The default chain property is used for signing transactions locally.

Property

The default chain property can be one of the following:

  • "mainnet" - String
  • "goerli" - String
  • "kovan" - String
  • "rinkeby" - String
  • "ropsten" - String

Default is "mainnet"

Example

web3.eth.defaultChain;
> "mainnet"

// set the default chain
web3.eth.defaultChain = 'goerli';

defaultCommon

web3.eth.defaultCommon

The default common property is used for signing transactions locally.

Property

The default common property does contain the following Common object:

  • customChain - Object: The custom chain properties
    • name - string: (optional) The name of the chain
    • networkId - number: Network ID of the custom chain
    • chainId - number: Chain ID of the custom chain
  • baseChain - string: (optional) mainnet, goerli, kovan, rinkeby, or ropsten
  • hardfork - string: (optional) chainstart, homestead, dao, tangerineWhistle, spuriousDragon, byzantium, constantinople, petersburg, or istanbul

Default is undefined.

Example

web3.eth.defaultCommon;
> {customChain: {name: 'custom-network', chainId: 1, networkId: 1}, baseChain: 'mainnet', hardfork: 'petersburg'}

// set the default common
web3.eth.defaultCommon = {customChain: {name: 'custom-network', chainId: 1, networkId: 1}, baseChain: 'mainnet', hardfork: 'petersburg'};

transactionBlockTimeout

web3.eth.transactionBlockTimeout

The transactionBlockTimeout will be used over a socket based connection. This option does define the amount of new blocks it should wait until the first confirmation happens. This means the PromiEvent rejects with a timeout error when the timeout got exceeded.

Returns

number: The current value of transactionBlockTimeout (default: 50)


transactionConfirmationBlocks

web3.eth.transactionConfirmationBlocks

This defines the number of blocks it requires until a transaction will be handled as confirmed.

Returns

number: The current value of transactionConfirmationBlocks (default: 24)


transactionPollingTimeout

web3.eth.transactionPollingTimeout

The transactionPollingTimeout will be used over a HTTP connection. This option defines the number of seconds Web3 will wait for a receipt which confirms that a transaction was mined by the network. NB: If this method times out, the transaction may still be pending.

Returns

number: The current value of transactionPollingTimeout (default: 750)


getProtocolVersion

web3.eth.getProtocolVersion([callback])

Returns the ethereum protocol version of the node.

Returns

Promise returns String: the protocol version.

Example

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

isSyncing

web3.eth.isSyncing([callback])

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

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

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

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

getCoinbase

getCoinbase([callback])

Returns the coinbase address to which mining rewards will go.

Returns

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

Example

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

isMining

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

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

getHashrate

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

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

getGasPrice

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 wei.

See the A note on dealing with big numbers in JavaScript.

Example

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

getAccounts

web3.eth.getAccounts([callback])

Returns a list of accounts the node controls.

Returns

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

Example

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

getBlockNumber

web3.eth.getBlockNumber([callback])

Returns the current block number.

Returns

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

Example

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

getBalance

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|BN|BigNumber - (optional) If you pass this parameter it will not use the default block set with web3.eth.defaultBlock. Pre-defined block numbers as "latest", "earlist", "pending", and "genesis" can also be used.
  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 wei.

See the A note on dealing with big numbers in JavaScript.

Example

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

getStorageAt

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|String|BN|BigNumber - The index position of the storage.
  3. Number|String|BN|BigNumber - (optional) If you pass this parameter it will not use the default block set with web3.eth.defaultBlock. Pre-defined block numbers as "latest", "earlist", "pending", and "genesis" can also be used.
  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

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

getCode

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|BN|BigNumber - (optional) If you pass this parameter it will not use the default block set with web3.eth.defaultBlock. Pre-defined block numbers as "latest", "earlist", "pending", and "genesis" can also be used.
  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

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

getBlock

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

Returns a block matching the block number or block hash.

Parameters

  1. String|Number|BN|BigNumber - The block number or block hash. Or the string "genesis", "latest", "earliest", or "pending" as in the default block parameter.
  2. Boolean - (optional, default false) If specified true, the returned block will contain all transactions as objects. By default it is false so, there is no need to explictly specify false. And, if false it will only contains the transaction hashes.
  3. Function - (optional) Optional callback, returns an error object as first parameter and the result as second.

Returns

Promise returns Object - The block object:

  • number - Number: The block number. null when its pending block.
  • hash 32 Bytes - String: Hash of the block. null when its pending block.
  • parentHash 32 Bytes - String: Hash of the parent block.
  • nonce 8 Bytes - String: Hash of the generated proof-of-work. null when its pending block.
  • sha3Uncles 32 Bytes - String: SHA3 of the uncles data in the block.
  • logsBloom 256 Bytes - String: The bloom filter for the logs of the block. null when its pending block.
  • transactionsRoot 32 Bytes - String: The root of the transaction trie of the block
  • stateRoot 32 Bytes - String: The root of the final state trie of the block.
  • miner - String: The address of the beneficiary to whom the mining rewards were given.
  • difficulty - String: Integer of the difficulty for this block.
  • totalDifficulty - String: Integer of the total difficulty of the chain until this block.
  • extraData - String: The “extra data” field of this block.
  • size - Number: Integer the size of this block in bytes.
  • gasLimit - Number: The maximum gas allowed in this block.
  • gasUsed - Number: The total used gas by all transactions in this block.
  • timestamp - Number: The unix timestamp for when the block was collated.
  • transactions - Array: Array of transaction objects, or 32 Bytes transaction hashes depending on the returnTransactionObjects parameter.
  • uncles - Array: Array of uncle hashes.

Example

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

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

Returns the number of transaction in a given block.

Parameters

  1. String|Number|BN|BigNumber - The block number or hash. Or the string "genesis", "latest", "earliest", or "pending" as in the 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

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

getBlockUncleCount

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

Returns the number of uncles in a block from a block matching the given block hash.

Parameters

  1. String|Number|BN|BigNumber - The block number or hash. Or the string "genesis", "latest", "earliest", or "pending" as in the 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

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

getUncle

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

Returns a blocks uncle by a given uncle index position.

Parameters

  1. String|Number|BN|BigNumber - The block number or hash. Or the string "genesis", "latest", "earliest", or "pending" as in the default block parameter.
  2. Number - The index position of the uncle.
  3. Boolean - (optional, default false) If specified true, the returned block will contain all transactions as objects. By default it is false so, there is no need to explictly specify false. And, 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 web3.eth.getBlock().

Note

An uncle doesn’t contain individual transactions.

Example

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

getTransaction

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.

Returns

Promise returns Object - A transaction object its hash transactionHash:

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

Example

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

getTransactionFromBlock(hashStringOrNumber, indexNumber [, callback])

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

Parameters

  1. String|Number|BN|BigNumber - A block number or hash. Or the string "genesis", "latest", "earliest", or "pending" as in the 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 web3.eth.getTransaction:

Example

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

getTransactionReceipt

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

Returns the receipt of a transaction by transaction hash.

Note

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

Parameters

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

Returns

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

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

Example

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

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

getTransactionCount

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|BN|BigNumber - (optional) If you pass this parameter it will not use the default block set with web3.eth.defaultBlock. Pre-defined block numbers as "latest", "earlist", "pending", and "genesis" can also be used.
  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

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

sendTransaction

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

Sends a transaction to the network.

Parameters

  1. Object - The transaction object to send:
    • from - String|Number: The address for the sending account. Uses the web3.eth.defaultAccount property, if not specified. Or an address or index of a local wallet in web3.eth.accounts.wallet.
    • to - String: (optional) The destination address of the message, left undefined for a contract-creation transaction.
    • value - Number|String|BN|BigNumber: (optional) The value transferred for the transaction in wei, also the endowment if it’s a contract-creation transaction.
    • gas - Number: (optional, default: To-Be-Determined) The amount of gas to use for the transaction (unused gas is refunded).
    • gasPrice - Number|String|BN|BigNumber: (optional) The price of gas for this transaction in wei, defaults to web3.eth.gasPrice.
    • data - String: (optional) Either a ABI byte string containing the data of the function call on a contract, or in the case of a contract-creation transaction the initialisation code.
    • nonce - Number: (optional) Integer of a nonce. This allows to overwrite your own pending transactions that use the same nonce.
    • chain - String: (optional) Defaults to mainnet.
    • hardfork - String: (optional) Defaults to petersburg.
    • common - Object: (optional) The common object
      • customChain - Object: The custom chain properties
        • name - string: (optional) The name of the chain
        • networkId - number: Network ID of the custom chain
        • chainId - number: Chain ID of the custom chain
      • baseChain - string: (optional) mainnet, goerli, kovan, rinkeby, or ropsten
      • hardfork - string: (optional) chainstart, homestead, dao, tangerineWhistle, spuriousDragon, byzantium, constantinople, petersburg, or istanbul
  2. callback - Function: (optional) Optional callback, returns an error object as first parameter and the result as second.

Note

The from property can also be an address or index from the web3.eth.accounts.wallet. It will then sign locally using the private key of that account, and send the transaction via web3.eth.sendSignedTransaction(). If the properties chain and hardfork or common are not set, Web3 will try to set appropriate values by

querying the network for its chainId and networkId.

Returns

The callback will return the 32 bytes transaction hash.

PromiEvent: A promise combined event emitter. Will be resolved when the transaction receipt is available. Additionally the following events are available:

  • "transactionHash" returns String: Is fired right after the transaction is sent 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 receipt as the second argument. Fired from confirmation 0 on, which is the block where its minded.

"error" returns Error and Object|undefined: Is fired if an error occurs during sending. If the transaction was rejected by the network with a receipt, the second parameter will be the receipt.

Example

// 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

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

Sends an already signed transaction, generated for example using web3.eth.accounts.signTransaction.

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 promise combined event emitter. Will be resolved when the transaction receipt is available.

Please see the return values for web3.eth.sendTransaction for details.

Example

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

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

var tx = new Tx(rawTx, {'chain':'ropsten'});
tx.sign(privateKey);

var serializedTx = tx.serialize();

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

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

> // see eth.getTransactionReceipt() for details

Note

When use the package ethereumjs-tx at the version of 2.0.0, if we don’t specify the parameter chain, it will use mainnet, so if you wan to use at the other network, you should add this parameter chain to specify.


sign

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

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

Parameters

  1. String - Data to sign. If String it will be converted using web3.utils.utf8ToHex.
  2. String|Number - Address to sign data with. Or an address or index of a local wallet in web3.eth.accounts.wallet.
  3. Function - (optional) Optional callback, returns an error object as first parameter and the result as second.

Note

The 2. address parameter can also be an address or index from the web3.eth.accounts.wallet. It will then sign locally using the private key of this account.

Returns

Promise returns String - The signature.

Example

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

// the below is the same
web3.eth.sign(web3.utils.utf8ToHex("Hello world"), "0x11f4d0A3c12e86B4b5F39B213F7E19D048276DAe")
.then(console.log);
> "0x30755ed65396facf86c53e6217c52b4daebe72aa4941d89635409de4c9c7f9466d4e9aaec7977f05e923889b33c0d0dd27d7226b6e6f56ce737465c5cfd04be400"

signTransaction

web3.eth.signTransaction(transactionObject, address [, callback])

Signs a transaction. This account needs to be unlocked.

Parameters

  1. Object - The transaction data to sign web3.eth.sendTransaction() for more.
  2. String - Address to sign transaction with.
  3. Function - (optional) Optional callback, returns an error object as first parameter and the result as second.

Returns

Promise returns Object - The RLP encoded transaction. The raw property can be used to send the transaction using web3.eth.sendSignedTransaction.

Example

web3.eth.signTransaction({
    from: "0xEB014f8c8B418Db6b45774c326A0E64C78914dC0",
    gasPrice: "20000000000",
    gas: "21000",
    to: '0x3535353535353535353535353535353535353535',
    value: "1000000000000000000",
    data: ""
}).then(console.log);
> {
    raw: '0xf86c808504a817c800825208943535353535353535353535353535353535353535880de0b6b3a76400008025a04f4c17305743700648bc4f6cd3038ec6f6af0df73e31757007b7f59df7bee88da07e1941b264348e80c78c4027afc65a87b0a5e43e86742b8ca0823584c6788fd0',
    tx: {
        nonce: '0x0',
        gasPrice: '0x4a817c800',
        gas: '0x5208',
        to: '0x3535353535353535353535353535353535353535',
        value: '0xde0b6b3a7640000',
        input: '0x',
        v: '0x25',
        r: '0x4f4c17305743700648bc4f6cd3038ec6f6af0df73e31757007b7f59df7bee88d',
        s: '0x7e1941b264348e80c78c4027afc65a87b0a5e43e86742b8ca0823584c6788fd0',
        hash: '0xda3be87732110de6c1354c83770aae630ede9ac308d9f7b399ecfba23d923384'
    }
}

call

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 web3.eth.sendTransaction, with the difference that for calls the from property is optional as well.
  2. Number|String|BN|BigNumber - (optional) If you pass this parameter it will not use the default block set with web3.eth.defaultBlock. Pre-defined block numbers as "latest", "earlist", "pending", and "genesis" can also be used.
  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

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

estimateGas

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

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

getPastLogs

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

Gets past logs, matching the given options.

Parameters

  1. Object - The filter options as follows:
  • fromBlock - Number|String: The number of the earliest block ("latest" may be given to mean the most recent and "pending" currently mining, block). By default "latest".
  • toBlock - Number|String: The number of the latest block ("latest" may be given to mean the most recent and "pending" currently mining, block). By default "latest".
  • address - String|Array: An address or a list of addresses to only get logs from particular account(s).
  • topics - Array: An array of values which must each appear in the log entries. The order is important, if you want to leave topics out use null, e.g. [null, '0x12...']. You can also pass an array for each topic with options for that topic e.g. [null, ['option1', 'option2']]

Returns

Promise returns Array - Array of log objects.

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

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

Example

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'
},{...}]

getWork

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

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

submitWork

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

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

getChainId

web3.eth.getChainId([callback])

Returns the chain ID of the current connected node as described in the EIP-695.

Returns

Promise<Number> - Returns chain ID.

Example

web3.eth.getChainId().then(console.log);
> 61

getNodeInfo

web3.eth.getNodeInfo([callback])

Returns

Promise<String> - The current client version.

Example

web3.eth.getNodeInfo().then(console.log);
> "Mist/v0.9.3/darwin/go1.4.1"