Note

This documentation is work in progress and web3.js 1.0 stable is not yet released! You can find the current documentation for web3 0.x.x at github.com/ethereum/wiki/wiki/JavaScript-API.

Web3

The Web3 class is a wrapper to house all Ethereum related modules.
import {Web3} from 'web3';

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

> web3.eth
> web3.shh
> web3.bzz
> web3.utils
> web3.version

Web3.modules

Static property of the Web3 class
Web3.modules

Will return an object with the classes of all major sub modules, to be able to instantiate them manually.

Returns

Object: A list of modules:
  • Eth - Function: the Eth module for interacting with the Ethereum network see web3.eth for more.
  • Net - Function: the Net module for interacting with network properties see web3.eth.net for more.
  • Personal - Function: the Personal module for interacting with the Ethereum accounts see web3.eth.personal for more.
  • Shh - Function: the Shh module for interacting with the whisper protocol see web3.shh for more.
  • Bzz - Function: the Bzz module for interacting with the swarm network see web3.bzz for more.

Example

Web3.modules
> {
    Eth: Eth function(provider, options?, net?),
    Net: Net function(provider, options?, net?),
    Personal: Personal function(provider, options?, net?),
    Shh: Shh function(provider, options?, net?),
    Bzz: Bzz function(provider, options?, net?),
}

options

An Web3 module does provide several options for configuring the transaction confirmation worklfow or for defining default values. These are the currently available option properties on a Web3 module:

Example

import Web3 from 'web3';

const options = {
    defaultAccount: '0x0',
    defaultBlock: 'latest',
    defaultGas: 1,
    defaultGasPrice: 0,
    transactionBlockTimeout: 50,
    transactionConfirmationBlocks: 24,
    transactionPollingTimeout: 480,
    transactionSigner: new CustomTransactionSigner()
}

const web3 = new Web3('http://localhost:8545', options);

defaultBlock

web3.defaultBlock
web3.eth.defaultBlock
web3.shh.defaultBlock
...

The default block which will be used for a requests.

Returns

string|number: The current value of the defaultBlock property.


defaultAccount

web3.defaultAccount
web3.eth.defaultAccount
web3.shh.defaultAccount
...

The default account which will be used for a requests.

Returns

null|string: The current value of the defaultAccount property.


defaultGasPrice

web3.defaultGasPrice
web3.eth.defaultGasPrice
web3.shh.defaultGasPrice
...

The default gas price which will be used for a request.

Returns

string|number: The current value of the defaultGasPrice property.


defaultGas

web3.defaultGas
web3.eth.defaultGas
web3.shh.defaultGas
...

The default gas which will be used for a request.

Returns

string|number: The current value of the defaultGas property.


transactionBlockTimeout

web3.transactionBlockTimeout
web3.eth.transactionBlockTimeout
web3.shh.transactionBlockTimeout
...

This can be used with a socket provider and defines the number of blocks until the PromiEvent rejects with a timeout error.

Returns

number: The current value of transactionBlockTimeout


transactionConfirmationBlocks

web3.transactionConfirmationBlocks
web3.eth.transactionConfirmationBlocks
web3.shh.transactionConfirmationBlocks
...

This defines the number of blocks it requires until a transaction will be handled as confirmed. The PromiEvent will resolve with the desired receipt when enough confirmations happened.

Returns

number: The current value of transactionConfirmationBlocks


transactionPollingTimeout

web3.transactionPollingTimeout
web3.eth.transactionPollingTimeout
web3.shh.transactionPollingTimeout
...

This defines the polling cycles amount when you send a transaction with the HttpProvider. The PromiEvent rejects with a timeout error when the timeout got exceeded. (1 cycle == 1sec.).

Returns

number: The current value of transactionPollingTimeout


transactionSigner

web3.eth.transactionSigner
...

The transactionSigner property does provide us the possibility to customize the signing process of the Eth module and the related sub-modules.

The interface of a TransactionSigner:

interface TransactionSigner {
    sign(txObject: Transaction): Promise<SignedTransaction>
}

interface SignedTransaction {
    messageHash: string,
    v: string,
    r: string,
    s: string,
    rawTransaction: string
}

Returns

TransactionSigner: A JavaScript class of type TransactionSigner.


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|String - provider: a valid provider
  2. Net - net: (optional) the node.js Net package. This is only required for the IPC provider.

Returns

Boolean

Example

import Web3 from 'web3';

const web3 = new Web3('http://localhost:8545');

// or
const 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
const net = require('net');
const web3 = new Web3('/Users/myuser/Library/Ethereum/geth.ipc', net); // mac os path

// or
const 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
Eth.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

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

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

const web3 = new Web3('/Users/myuser/Library/Ethereum/geth.ipc', net); // mac os path
// or
const 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

web3.setProvider(Web3.givenProvider || 'ws://localhost:8546');

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

if(!web3.currentProvider) {
    web3.setProvider('http://localhost:8545');
}

BatchRequest

new web3.BatchRequest()
new web3.eth.BatchRequest()
new web3.shh.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

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

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

version

Property of the Web3 class.
Web3.version
web3.version

Contains the version of the web3 wrapper class.

Returns

String: The current version.

Example

web3.version;
> "1.0.0"