Getting Started

The web3.js library is a collection of modules that contain functionality for the ethereum ecosystem.

  • web3-eth is for the ethereum blockchain and smart contracts.
  • web3-shh is for the whisper protocol, to communicate p2p and broadcast.
  • web3-bzz is for the swarm protocol, the decentralized file storage.
  • web3-utils contains useful helper functions for Dapp developers.

Adding web3.js

First you need to get web3.js into your project. This can be done using the following methods:

  • npm: npm install web3
  • yarn: yarn add web3
  • pure js: link the dist/web3.min.js

After that you need to create a web3 instance and set a provider.

Most Ethereum-supported browsers like MetaMask have an EIP-1193 compliant provider available at window.ethereum.

For web3.js, check Web3.givenProvider.

If this property is null you should connect to a remote/local node.


                                            
        
// In Node.js use: const Web3 = require('web3');

        const web3 = new Web3(Web3.givenProvider || "ws://localhost:8545");
                                

That’s it! now you can use the web3 object.

Web3

This is the main (or ‘umbrella’) class of the web3.js library.

                                var Web3 = require('web3');                             
                                    > Web3.utils
                                    > Web3.version
                                    > Web3.givenProvider
                                    > Web3.providers
                                    > Web3.modules
                                
                            

Web3.modules

   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 module constructors:
  • Eth - Constructor: The Eth module for interacting with the Ethereum network (web3.eth).
  • Net - Constructor: The Net module for interacting with network properties (web3.eth.net).
  • Personal - Constructor: The Personal module for interacting with the Ethereum accounts (web3.eth.personal).
  • Shh - Constructor: The Shh module for interacting with the whisper protocol (web3.shh).
  • Bzz - Constructor: The Bzz module for interacting with the swarm network (web3.bzz).

Example

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

Web3 Instance

The Web3 class is an umbrella package to house all Ethereum related modules.

var Web3 = require('web3');

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

version

Static accessible property of the Web3 class and property of the instance as well.

          Web3.version
          web3.version
          

Contains the current package version of the web3.js library.

Returns

String: The current version.

Example

          
web3.version;
          > "1.2.3"
          

utils

Static accessible property of the Web3 class and property of the instance as well.

         
Web3.utils
         web3.utils
         

Utility functions are also exposes on the Web3 class object directly.

See web3.utils for more.

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

  • Object - myProvider: a valid provider.
  • Returns

    Boolean

    Example: Local Geth Node

    
                                    
    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"
             

    Example: Remote Node Provider

    
                                    
    // Using a remote node provider, like Alchemy (https://www.alchemyapi.io/supernode), is simple.
             var Web3 = require('web3');
             var web3 = new Web3("https://eth-mainnet.alchemyapi.io/v2/your-api-key");
             

    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: HTTP provider, does not support 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"
             

    Configuration

    
                                    
    // ====
             // Http
             // ====
                                                                
             var Web3HttpProvider = require('web3-providers-http');
                                                               
             var options = {
                keepAlive: true,
                withCredentials: false,
                timeout: 20000, // ms
                headers: [
                    {
                       name: 'Access-Control-Allow-Origin',
                        value: '*'
                    },
                    {
                          ...
                        }
                    ],
                    agent: {
                         http: http.Agent(...),
                         baseUrl: ''
                    }
                };
                                                                 
                var provider = new Web3HttpProvider('http://localhost:8545', options);
                                                                
                // ==========
                // Websockets
                // ==========
                                                                
                var Web3WsProvider = require('web3-providers-ws');
                                                                
                var options = {
                    timeout: 30000, // ms
                                                                
                    // Useful for credentialed urls, e.g: ws://username:password@localhost:8546
                    headers: {
                        authorization: 'Basic username:password'
                    },
                                                                
                    clientConfig: {
                        // Useful if requests are large
                        maxReceivedFrameSize: 100000000,   // bytes - default: 1MiB
                        maxReceivedMessageSize: 100000000, // bytes - default: 8MiB
                                                                
                        // Useful to keep a connection alive
                        keepalive: true,
                        keepaliveInterval: 60000 // ms
                },
                                                                
                // Enable auto reconnection
                reconnect: {
                        auto: true,
                        delay: 5000, // ms
                        maxAttempts: 5,
                        onTimeout: false
                    }
                };
                                                                
                var ws = new Web3WsProvider('ws://localhost:8546', options);
                 

    More information for the Http and Websocket provider modules can be found here:

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

    Section-2


    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

  • Object - myProvider: a valid provider.
  • Returns

    Boolean

    Example: Local Geth Node

    
                                    
    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"
                

    Example: Remote Node Provider

    
                                    
    // Using a remote node provider, like Alchemy (https://www.alchemyapi.io/supernode), is simple.
                var Web3 = require('web3');
                var web3 = new Web3("https://eth-mainnet.alchemyapi.io/v2/your-api-key");
                

    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: HTTP provider, does not support 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"
                

    Configuration

    
                                    
    // ====
                // Http
                // ====
                                                                                        
                var Web3HttpProvider = require('web3-providers-http');
                                                                                        
                var options = {
                     keepAlive: true,
                     withCredentials: false,
                     timeout: 20000, // ms
                     headers: [
                         {
                             name: 'Access-Control-Allow-Origin',
                             value: '*'
                         },
                         {
                             ...
                         }
                     ],
                     agent: {
                         http: http.Agent(...),
                         baseUrl: ''
                     }
                };
                                                                                        
                var provider = new Web3HttpProvider('http://localhost:8545', options);
                                                                                        
                // ==========
                // Websockets
                // ==========
                                                                                        
                var Web3WsProvider = require('web3-providers-ws');
                                                                                        
                var options = {
                     timeout: 30000, // ms
                                                                                        
                     // Useful for credentialed urls, e.g: ws://username:password@localhost:8546
                     headers: {
                         authorization: 'Basic username:password'
                     },
                                                                                        
                     clientConfig: {
                         // Useful if requests are large
                         maxReceivedFrameSize: 100000000,   // bytes - default: 1MiB
                         maxReceivedMessageSize: 100000000, // bytes - default: 8MiB
                                                                                        
                         // Useful to keep a connection alive
                         keepalive: true,
                         keepaliveInterval: 60000 // ms
                     },
                                                                                        
                     // Enable auto reconnection
                     reconnect: {
                         auto: true,
                         delay: 5000, // ms
                         maxAttempts: 5,
                         onTimeout: false
                     }
                };
                                                                                        
                var ws = new Web3WsProvider('ws://localhost:8546', options);
                

    More information for the Http and Websocket provider modules can be found here:


    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 input 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|BN|BigNumber: A block number
    • "earliest" - 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 can be one of the following:

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

    Default is "london"

    Example

    
                                        
    web3.eth.defaultHardfork;
                > "london"
                                                                                                                            
                // 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, istanbul, berlin, or london

    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 is used over socket-based connections. This option defines the amount of new blocks it should wait until the first confirmation happens, otherwise the PromiEvent rejects with a timeout error.

    Returns

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

    Example

    
                                        
    web3.eth.transactionBlockTimeout;
                > 50
                                                                                                                    
                // set the transaction block timeout
                web3.eth.transactionBlockTimeout = 100;
                

    transactionConfirmationBlocks

    
                                        
    web3.eth.transactionConfirmationBlocks
                

    This defines the number of blocks it requires until a transaction is considered confirmed.

    Returns

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

    Example

    
                                        
    web3.eth.transactionConfirmationBlocks;
                > 24
                                                                                                                   
                // set the transaction confirmations blocks
                web3.eth.transactionConfirmationBlocks = 50;
                

    transactionPollingTimeout

    
                                        
    web3.eth.transactionPollingTimeout
                

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

    Returns

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

    Example

    
                                        
    web3.eth.transactionPollingTimeout;
                > 750
                                                                                                                   
                // set the transaction polling timeout
                web3.eth.transactionPollingTimeout = 1000;
                

    handleRevert

    
                                        
    web3.eth.handleRevert
                

    The handleRevert options property defaults to false and returns the revert reason string if enabled for the following methods:

    Note

    The revert reason string and signature exist as a property on the returned error.

    Returns

    boolean: The current value of handleRevert (default: false)

    Example

    
                                        
    web3.eth.handlRevert;
                > false
                                                                                                      
                // turn revert handling on
                web3.eth.handleRevert = true;
                

    maxListenersWarningThreshold

    
                                        
    web3.eth.maxListenersWarningThreshold
                

    This defines the threshold above which a warning about the number of event listeners attached to a provider which supports sockets subscriptions will be written to the console. You may see this warning if you call setProvider on large numbers of Web3 contract objects.

    Returns

    number: The current value of maxListenersWarningThreshold (default: 100)

    Example

    
                                        
    web3.eth.maxListenersWarningThreshold;
                > 100
                                                                                                                    
                // set the max listeners warning threshold
                web3.eth.maxListenersWarningThreshold = 200;
                

    getProtocolVersion

    
                                        
    web3.eth.getProtocolVersion([callback])
                

    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 the node is currently synced to.
    • highestBlock - Number: The estimated block number to sync to.
    • knownStates - Number: The number of estimated states to download.
    • pulledStates - Number: The number of 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"
                                                                                                                            

    getFeeHistory

    
                                        
    web3.eth.getFeeHistory(blockCount, newestBlock, rewardPercentiles, [callback])
                                                                                                            

    Transaction fee history Returns base fee per gas and transaction effective priority fee per gas history for the requested block range if available. The range between headBlock-4 and headBlock is guaranteed to be available while retrieving data from the pending block and older history are optional to support. For pre-EIP-1559 blocks the gas prices are returned as rewards and zeroes are returned for the base fee per gas.

    Parameters

    1. String|Number|BN|BigNumber - Number of blocks in the requested range. Between 1 and 1024 blocks can be requested in a single query. Less than requested may be returned if not all blocks are available.
    2. String|Number|BN|BigNumber - Highest number block of the requested range.
    3. Array of numbers - A monotonically increasing list of percentile values to sample from each block’s effective priority fees per gas in ascending order, weighted by gas used. Example: [“0”, “25”, “50”, “75”, “100”] or [“0”, “0.5”, “1”, “1.5”, “3”, “80”]
    4. Function - (optional) Optional callback, returns an error object as first parameter and the result as second.

    Returns

    Promise returns Object - Fee history for the returned block range. The object:

    • Number oldestBlock - Lowest number block of the returned range.
    • Array of strings baseFeePerGas - An array of block base fees per gas. This includes the next block after the newest of the returned range, because this value can be derived from the newest block. Zeroes are returned for pre-EIP-1559 blocks.
    • Array of numbers gasUsedRatio - An array of block gas used ratios. These are calculated as the ratio of gasUsed and gasLimit.
    • Array of string arrays reward - An array of effective priority fee per gas data points from a single block. All zeroes are returned if the block is empty.

    getAccounts

    
                                        
    web3.eth.getAccounts([callback])
                                                                                                            

    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.

    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 "earliest", "latest" and "pending" 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 "earliest", "latest" and "pending" 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 "earliest", "latest" 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. 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 if a pending block.
    • hash 32 Bytes - String: Hash of the block. null if a pending block.
    • parentHash 32 Bytes - String: Hash of the parent block.
    • nonce 8 Bytes - String: Hash of the generated proof-of-work. null if a 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 if a 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 "earliest", "latest" 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 "earliest", "latest" 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 "earliest", "latest" 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 if pending.
    • blockNumber - Number: Block number where this transaction was in. null if pending.
    • transactionIndex - Number: Integer of the transactions index position in the block. null if pending.
    • from - String: Address of the sender.
    • to - String: Address of the receiver. null if it’s 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"
                }
                

    getPendingTransactions

    
                
    web3.eth.getPendingTransactions([, callback])
                

    Returns a list of pending transactions.

    Parameters

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

    Returns

    Promise<object[]> - Array of pending transactions:

    • 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 if pending.
    • blockNumber - Number: Block number where this transaction was in. null if pending.
    • transactionIndex - Number: Integer of the transactions index position in the block. null if pending.
    • from - String: Address of the sender.
    • to - String: Address of the receiver. null when it’s a contract creation transaction.
    • value - String: Value transferred in wei.
    • gasPrice - String: The wei per unit of gas 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.getPendingTransactions().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'
                             v: '0x3d',
                             r: '0xaabc9ddafffb2ae0bac4107697547d22d9383667d9e97f5409dd6881ce08f13f',
                             s: '0x69e43116be8f842dcd4a0b2f760043737a59534430b762317db21d9ac8c5034'
                     },....,{
                             hash: '0x9fc76417374aa880d4449a1f7f31ec597f00b1f6f3dd2d66f4c9c6c445836d8b',
                             nonce: 3,
                             blockHash: '0xef95f2f1ed3ca60b048b4bf67cde2195961e0bba6f70bcbea9a2c4e133e34b46',
                             blockNumber: 4,
                             transactionIndex: 0,
                             from: '0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b',
                             to: '0x6295ee1b4f6dd65047762f924ecd367c17eabf8f',
                             value: '123450000000000000',
                             gas: 314159,
                             gasPrice: '2000000000000',
                             input: '0x57cb2fc4'
                             v: '0x3d',
                             r: '0xaabc9ddafffb2ae0bac4107697547d22d9383667d9e97f5409dd6881ce08f13f',
                             s: '0x69e43116be8f842dcd4a0b2f760043737a59534430b762317db21d9ac8c5034'
                     }
                ]
                

    getTransactionFromBlock

    
                
    getTransactionFromBlock(hashStringOrNumber, indexNumber [, callback])
                

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

    Parameters

    1. String|Number|BN|BigNumber - A block number or hash. Or the string "earliest", "latest" or "pending" as in the default block parameter.
    2. Number - The transaction’s 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 if 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 it’s 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 number 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 "earliest", "latest" and "pending" 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.
      • type - Number|String|BN|BigNumber: (optional) A positive unsigned 8-bit number between 0 and 0x7f that represents the type of the transaction.
      • maxFeePerGas - Number|String|BN: (optional, defaulted to (2 * block.baseFeePerGas) + maxPriorityFeePerGas) The maximum fee per gas that the transaction is willing to pay in total
      • maxPriorityFeePerGas - Number|String|BN (optional, defaulted to 1 Gwei) The maximum fee per gas to give miners to incentivize them to include the transaction (Priority fee)
      • accessList - List of hexstrings (optional) a list of addresses and storage keys that the transaction plans to access
      • 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 the 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 london.
      • 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, istanbul, berlin, or london
    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. Resolves when the transaction receipt is available. The following events are also available:

    • sending returns payload: Object: Fired immediately before transmitting the transaction request.
    • sent returns payload: Object: Fired immediately after the request body has been written to the client, but before the transaction hash is received.
    • "transactionHash" returns transactionHash: String: Fired when the transaction hash is available.
    • "receipt" returns receipt: Object: Fired when the transaction receipt is available.
    • "confirmation" returns confirmationNumber: Number, receipt: Object, latestBlockHash: String: 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 it’s mined.

    "error" returns error: Error: Fired if an error occurs during sending. If the transaction was rejected by the network with a receipt, the receipt will be available as a property on the error object.

    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 contract
                }, 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. Resolves 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 using ethereumjs-tx@2.0.0 if you don’t specify the parameter chain it will use mainnet by default.


    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 it is a string it will be converted using web3.utils.utf8ToHex.
    2. String|Number - Address to sign data with. Can be an address or the 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.

    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. See 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. For calls the from property is optional however it is highly recommended to explicitly set it or it may default to address(0) depending on your node or provider.
    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 "earliest", "latest" and "pending" 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. Note: You must specify a from address otherwise you may experience odd behavior.

    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 if still pending.
    • blockNumber - Number: The block number where this log was created in. null if 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
                 

    requestAccounts

    
                 
    web3.eth.requestAccounts([callback])
                 

    This method will request/enable the accounts from the current environment. This method will only work if you’re using the injected provider from a application like Metamask, Status or TrustWallet. It doesn’t work if you’re connected to a node with a default Web3.js provider (WebsocketProvider, HttpProvidder and IpcProvider).

    For more information about the behavior of this method please read EIP-1102: Opt-in account exposure.

    Parameters

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

    Returns

    Promise<Array> - Returns an array of enabled accounts.

    Example

    
                 
    web3.eth.requestAccounts().then(console.log);
                 > ['0aae0B295369a9FD31d5F28D9Ec85E40f4cb692BAf', '0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe']
                 

    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"
                                                                                                                        

    getProof

    
                                        
    web3.eth.getProof(address, storageKey, blockNumber, [callback])
                                                                                                            

    Returns the account and storage-values of the specified account including the Merkle-proof as described in EIP-1186.

    Parameters

    1. String 20 Bytes: The Address of the account or contract.
    2. Number[] | BigNumber[] | BN[] | String[] 32 Bytes: Array of storage-keys which should be proofed and included. See web3.eth.getStorageAt.
    3. Number | String | BN | BigNumber: Integer block number. Pre-defined block numbers as "earliest", "latest" and "pending" can also be used.
    4. Function - (optional) Optional callback, returns an error object as first parameter and the result as second.

    Returns

    Promise<Object> - A account object.

    • address - String: The address of the account.
    • balance - String: The balance of the account. See web3.eth.getBalance.
    • codeHash - String: hash of the code of the account. For a simple account without code it will return "0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470".
    • nonce - String: Nonce of the account.
    • storageHash - String: SHA3 of the StorageRoot. All storage will deliver a MerkleProof starting with this rootHash.
    • accountProof - String[]:Array of rlp-serialized MerkleTree-Nodes, starting with the stateRoot-Node, following the path of the SHA3 (address) as key.
    • storageProof - Object[] Array of storage-entries as requested.
      • key - String The requested storage key.
      • value - String The storage value.

    Example

    
                                        
    web3.eth.getProof(
                     "0x1234567890123456789012345678901234567890",
                     ["0x0000000000000000000000000000000000000000000000000000000000000000","0x0000000000000000000000000000000000000000000000000000000000000001"],
                     "latest"
                 ).then(console.log);
                 > {
                     "address": "0x1234567890123456789012345678901234567890",
                     "accountProof": [
                         "0xf90211a090dcaf88c40c7bbc95a912cbdde67c175767b31173df9ee4b0d733bfdd511c43a0babe369f6b12092f49181ae04ca173fb68d1a5456f18d20fa32cba73954052bda0473ecf8a7e36a829e75039a3b055e51b8332cbf03324ab4af2066bbd6fbf0021a0bbda34753d7aa6c38e603f360244e8f59611921d9e1f128372fec0d586d4f9e0a04e44caecff45c9891f74f6a2156735886eedf6f1a733628ebc802ec79d844648a0a5f3f2f7542148c973977c8a1e154c4300fec92f755f7846f1b734d3ab1d90e7a0e823850f50bf72baae9d1733a36a444ab65d0a6faaba404f0583ce0ca4dad92da0f7a00cbe7d4b30b11faea3ae61b7f1f2b315b61d9f6bd68bfe587ad0eeceb721a07117ef9fc932f1a88e908eaead8565c19b5645dc9e5b1b6e841c5edbdfd71681a069eb2de283f32c11f859d7bcf93da23990d3e662935ed4d6b39ce3673ec84472a0203d26456312bbc4da5cd293b75b840fc5045e493d6f904d180823ec22bfed8ea09287b5c21f2254af4e64fca76acc5cd87399c7f1ede818db4326c98ce2dc2208a06fc2d754e304c48ce6a517753c62b1a9c1d5925b89707486d7fc08919e0a94eca07b1c54f15e299bd58bdfef9741538c7828b5d7d11a489f9c20d052b3471df475a051f9dd3739a927c89e357580a4c97b40234aa01ed3d5e0390dc982a7975880a0a089d613f26159af43616fd9455bb461f4869bfede26f2130835ed067a8b967bfb80",
                         "0xf90211a0395d87a95873cd98c21cf1df9421af03f7247880a2554e20738eec2c7507a494a0bcf6546339a1e7e14eb8fb572a968d217d2a0d1f3bc4257b22ef5333e9e4433ca012ae12498af8b2752c99efce07f3feef8ec910493be749acd63822c3558e6671a0dbf51303afdc36fc0c2d68a9bb05dab4f4917e7531e4a37ab0a153472d1b86e2a0ae90b50f067d9a2244e3d975233c0a0558c39ee152969f6678790abf773a9621a01d65cd682cc1be7c5e38d8da5c942e0a73eeaef10f387340a40a106699d494c3a06163b53d956c55544390c13634ea9aa75309f4fd866f312586942daf0f60fb37a058a52c1e858b1382a8893eb9c1f111f266eb9e21e6137aff0dddea243a567000a037b4b100761e02de63ea5f1fcfcf43e81a372dafb4419d126342136d329b7a7ba032472415864b08f808ba4374092003c8d7c40a9f7f9fe9cc8291f62538e1cc14a074e238ff5ec96b810364515551344100138916594d6af966170ff326a092fab0a0d31ac4eef14a79845200a496662e92186ca8b55e29ed0f9f59dbc6b521b116fea090607784fe738458b63c1942bba7c0321ae77e18df4961b2bc66727ea996464ea078f757653c1b63f72aff3dcc3f2a2e4c8cb4a9d36d1117c742833c84e20de994a0f78407de07f4b4cb4f899dfb95eedeb4049aeb5fc1635d65cf2f2f4dfd25d1d7a0862037513ba9d45354dd3e36264aceb2b862ac79d2050f14c95657e43a51b85c80",
                         "0xf90171a04ad705ea7bf04339fa36b124fa221379bd5a38ffe9a6112cb2d94be3a437b879a08e45b5f72e8149c01efcb71429841d6a8879d4bbe27335604a5bff8dfdf85dcea00313d9b2f7c03733d6549ea3b810e5262ed844ea12f70993d87d3e0f04e3979ea0b59e3cdd6750fa8b15164612a5cb6567cdfb386d4e0137fccee5f35ab55d0efda0fe6db56e42f2057a071c980a778d9a0b61038f269dd74a0e90155b3f40f14364a08538587f2378a0849f9608942cf481da4120c360f8391bbcc225d811823c6432a026eac94e755534e16f9552e73025d6d9c30d1d7682a4cb5bd7741ddabfd48c50a041557da9a74ca68da793e743e81e2029b2835e1cc16e9e25bd0c1e89d4ccad6980a041dda0a40a21ade3a20fcd1a4abb2a42b74e9a32b02424ff8db4ea708a5e0fb9a09aaf8326a51f613607a8685f57458329b41e938bb761131a5747e066b81a0a16808080a022e6cef138e16d2272ef58434ddf49260dc1de1f8ad6dfca3da5d2a92aaaadc58080",
                         "0xf851808080a009833150c367df138f1538689984b8a84fc55692d3d41fe4d1e5720ff5483a6980808080808080808080a0a319c1c415b271afc0adcb664e67738d103ac168e0bc0b7bd2da7966165cb9518080"
                     ],
                     "balance": 0,
                     "codeHash": "0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470",
                     "nonce": 0,
                     "storageHash": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421",
                     "storageProof": [
                         {
                             "key": "0x0000000000000000000000000000000000000000000000000000000000000000",
                             "value": '0',
                             "proof": []
                         },
                         {
                             "key": "0x0000000000000000000000000000000000000000000000000000000000000001",
                             "value": '0',
                             "proof": []
                         }
                     ]
                 }
                                                                                                                       

    Section-3


    web3.eth.subscribe

    The web3.eth.subscribe function lets you subscribe to specific events in the blockchain.

    subscribe

    
                                        
    web3.eth.subscribe(type [, options] [, callback]);
                                                                                                            

    Parameters

    1. String - The subscription you want to subscribe to.
    2. Mixed - (optional) Optional additional parameters, depending on the subscription type.
    3. Function - (optional) Optional callback, returns an error object as first parameter and the result as second. Will be called for each incoming subscription, and the subscription itself as the 3rd parameter.

    Returns

    EventEmitter - A Subscription instance

    • subscription.id: The subscription id, used to identify and unsubscribing the subscription.
    • subscription.subscribe([callback]): Can be used to re-subscribe with the same parameters.
    • subscription.unsubscribe([callback]): Unsubscribes the subscription and returns TRUE in the callback if successful.
    • subscription.arguments: The subscription arguments, used when re-subscribing.
    • on("data") returns Object: Fires on each incoming log with the log object as argument.
    • on("changed") returns Object: Fires on each log which was removed from the blockchain. The log will have the additional property "removed: true".
    • on("error") returns Object: Fires when an error in the subscription occurs.
    • on("connected") returns String: Fires once after the subscription successfully connected. Returns the subscription id.

    Notification returns

    • Mixed - depends on the subscription, see the different subscriptions for more.

    Example

    
                                        
    var subscription = web3.eth.subscribe('logs', {
                     address: '0x123456..',
                     topics: ['0x12345...']
                 }, function(error, result){
                     if (!error)
                         console.log(result);
                 });
                                                                                                                           
                 // unsubscribes the subscription
                 subscription.unsubscribe(function(error, success){
                     if(success)
                         console.log('Successfully unsubscribed!');
                 });
                                                                                                                            

    clearSubscriptions

    
                                            
    web3.eth.clearSubscriptions()
                                                                                                                                    

    Resets subscriptions.

    Note

    This will not reset subscriptions from other packages like web3-shh, as they use their own requestManager.

    Parameters

    1. Boolean: If true it keeps the "syncing" subscription.

    Returns

    Boolean

    Example

    
                                            
    web3.eth.subscribe('logs', {} ,function(){ ... });
    
                 ...
                                                                                                           
                 web3.eth.clearSubscriptions();
                                                                                                                                            

    subscribe(“pendingTransactions”)

    
                                            
    web3.eth.subscribe('pendingTransactions' [, callback]);
                                                                                                                                        

    Subscribes to incoming pending transactions.

    Parameters

    1. String - "pendingTransactions", the type of the subscription.
    2. Function - (optional) Optional callback, returns an error object as first parameter and the result as second. Will be called for each incoming subscription.

    Returns

    EventEmitter: An subscription instance as an event emitter with the following events:

    • "data" returns String: Fires on each incoming pending transaction and returns the transaction hash.
    • "error" returns Object: Fires when an error in the subscription occurs.

    Notification returns

    1. Object|Null - First parameter is an error object if the subscription failed.
    2. String - Second parameter is the transaction hash.

    Example

    
                                            
    var subscription = web3.eth.subscribe('pendingTransactions', function(error, result){
                     if (!error)
                         console.log(result);
                 })
                 .on("data", function(transaction){
                     console.log(transaction);
                 });
                                                                                                                                                   
                 // unsubscribes the subscription
                 subscription.unsubscribe(function(error, success){
                     if(success)
                         console.log('Successfully unsubscribed!');
                 });
                                                                                                 

    subscribe(“newBlockHeaders”)

    
                                            
    web3.eth.subscribe('newBlockHeaders' [, callback]);
                                                                                                                                    

    Subscribes to incoming block headers. This can be used as timer to check for changes on the blockchain.

    Parameters

    1. String - "newBlockHeaders", the type of the subscription.
    2. Function - (optional) Optional callback, returns an error object as first parameter and the result as second. Will be called for each incoming subscription.

    Returns

    EventEmitter: An subscription instance as an event emitter with the following events:

    • "data" returns Object: Fires on each incoming block header.
    • "error" returns Object: Fires when an error in the subscription occurs.
    • "connected" returns Number: Fires once after the subscription successfully connected. Returns the subscription id.

    The structure of a returned block header is as follows:

    • 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.
    • receiptsRoot 32 Bytes - String: The root of the receipts.
    • miner - String: The address of the beneficiary to whom the mining rewards were given.
    • extraData - String: The “extra data” field of this block.
    • 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.

    Notification returns

    1. Object|Null - First parameter is an error object if the subscription failed.
    2. Object - The block header object like above.

    Example

    
                                            
    var subscription = web3.eth.subscribe('newBlockHeaders', function(error, result){
                     if (!error) {
                         console.log(result);
                                                                                                                                                    
                         return;
                    }
                                                                                                                                          
                     console.error(error);
                 })
                 .on("connected", function(subscriptionId){
                     console.log(subscriptionId);
                 })
                 .on("data", function(blockHeader){
                     console.log(blockHeader);
                 })
                 .on("error", console.error);
                                                                                                                                      
                 // unsubscribes the subscription
                 subscription.unsubscribe(function(error, success){
                     if (success) {
                         console.log('Successfully unsubscribed!');
                     }
                 });
                                                                                                              

    subscribe(“syncing”)

    
                                            
    web3.eth.subscribe('syncing' [, callback]);
                                                                                                                                    

    Subscribe to syncing events. This will return an object when the node is syncing and when it’s finished syncing will return FALSE.

    Parameters

    1. String - "syncing", the type of the subscription.
    2. Function - (optional) Optional callback, returns an error object as first parameter and the result as second. Will be called for each incoming subscription.

    Returns

    EventEmitter: An subscription instance as an event emitter with the following events:

    • "data" returns Object: Fires on each incoming sync object as argument.
    • "changed" returns Object: Fires when the synchronisation is started with true and when finished with false.
    • "error" returns Object: Fires when an error in the subscription occurs.

    For the structure of a returned event Object see web3.eth.isSyncing return values.

    Notification returns

    1. Object|Null - First parameter is an error object if the subscription failed.
    2. Object|Boolean - The syncing object, when started it will return true once or when finished it will return false once.

    Example

    
                                            
    var subscription = web3.eth.subscribe('syncing', function(error, sync){
                     if (!error)
                         console.log(sync);
                 })
                 .on("data", function(sync){
                     // show some syncing stats
                 })
                 .on("changed", function(isSyncing){
                     if(isSyncing) {
                         // stop app operation
                     } else {
                         // regain app operation
                     }
                 });
                                                                                                                                                        
                 // unsubscribes the subscription
                 subscription.unsubscribe(function(error, success){
                     if(success)
                         console.log('Successfully unsubscribed!');
                 });
                     

    subscribe(“logs”)

    
                                            
    web3.eth.subscribe('logs', options [, callback]);
                     

    Subscribes to incoming logs, filtered by the given options. If a valid numerical fromBlock options property is set, Web3 will retrieve logs beginning from this point, backfilling the response as necessary.

    Parameters

    1. "logs" - String, the type of the subscription.
    2. Object - The subscription options
    • fromBlock - Number: The fromBlock dictates at which block the subscription will start from, if it is left empty, the default is latest (a.k.a the chain head)
    • 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, '0x00...']. You can also pass another array for each topic with options for that topic e.g. [null, ['option1', 'option2']]
    1. callback - Function: (optional) Optional callback, returns an error object as first parameter and the result as second. Will be called for each incoming subscription.

    Returns

    EventEmitter: A subscription instance as an event emitter with the following events:

    • "data" returns Object: Fires on each incoming log with the log object as argument.
    • "changed" returns Object: Fires on each log which was removed from the blockchain. The log will have the additional property "removed: true".
    • "error" returns Object: Fires when an error in the subscription occurs.
    • "connected" returns Number: Fires once after the subscription successfully connected. Returns the subscription id.

    For the structure of a returned event Object see web3.eth.getPastEvents return values.

    Notification returns

    1. Object|Null - First parameter is an error object if the subscription failed.
    2. Object - The log object like in web3.eth.getPastEvents return values.
    
                                            
    var subscription = web3.eth.subscribe('logs', {
                     address: '0x123456..',
                     topics: ['0x12345...']
                 }, function(error, result){
                     if (!error)
                         console.log(result);
                 })
                 .on("connected", function(subscriptionId){
                     console.log(subscriptionId);
                 })
                 .on("data", function(log){
                     console.log(log);
                 })
                 .on("changed", function(log){
                 });
                                                                                                                                                      
                 // unsubscribes the subscription
                 subscription.unsubscribe(function(error, success){
                     if(success)
                         console.log('Successfully unsubscribed!');
                 });
                     

    Section-4


    web3.eth.Contract

    The web3.eth.Contract object makes it easy to interact with smart contracts on the ethereum blockchain. When you create a new contract object you give it the json interface of the respective smart contract and web3 will auto convert all calls into low level ABI calls over RPC for you.

    This allows you to interact with smart contracts as if they were JavaScript objects.

    To use it standalone:

    
                                            
    var Contract = require('web3-eth-contract');
    
                 // set provider for all later instances to use
                 Contract.setProvider('ws://localhost:8546');
                                                                                
                 var contract = new Contract(jsonInterface, address);
                                                                                
                 contract.methods.somFunc().send({from: ....})
                 .on('receipt', function(){
                     ...
                 });
                     

    new contract

    
                                                
    new web3.eth.Contract(jsonInterface[, address][, options])
                     

    Creates a new contract instance with all its methods and events defined in its json interface object.

    Parameters

    1. jsonInterface - Object: The json interface for the contract to instantiate
    2. address - String (optional): The address of the smart contract to call.
    3. options - Object (optional): The options of the contract. Some are used as fallbacks for calls and transactions:
      • from - String: The address transactions should be made from.
      • gasPrice - String: The gas price in wei to use for transactions.
      • gas - Number: The maximum gas provided for a transaction (gas limit).
      • data - String: The byte code of the contract. Used when the contract gets deployed.

    Returns

    Object: The contract instance with all its methods and events.

    Example

    
                                                
    var myContract = new web3.eth.Contract([...], '0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe', {
                     from: '0x1234567890123456789012345678901234567891', // default from address
                     gasPrice: '20000000000' // default gas price in wei, 20 gwei in this case
                 });
                     

    = Properties =


    defaultAccount

    
                                                
    web3.eth.Contract.defaultAccount
                 contract.defaultAccount // on contract instance
                     

    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.Contract.defaultBlock
                 contract.defaultBlock // on contract instance
                     

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

    Property

    The default block parameters can be one of the following:

    • Number|BN|BigNumber: A block number
    • "earliest" - 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

    
                                                
    contract.defaultBlock;
                 > "latest"
                                                                                            
                 // set the default block
                 contract.defaultBlock = 231;
                     

    defaultHardfork

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

    
                                                
    contract.defaultHardfork;
                 > "petersburg"
                                                                                            
                 // set the default block
                 contract.defaultHardfork = 'istanbul';
                     

    defaultChain

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

    
                                                
    contract.defaultChain;
                 > "mainnet"
                                                                                       
                 // set the default chain
                 contract.defaultChain = 'goerli';
                     

    defaultCommon

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

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

    transactionBlockTimeout

    
                                                
    web3.eth.Contract.transcationBlockTimeout
                 contract.transactionBlockTimeout // on contract instance
                     

    The transactionBlockTimeout is used over socket-based connections. This option defines the amount of new blocks it should wait until the first confirmation happens, otherwise the PromiEvent rejects with a timeout error.

    Returns

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



    transactionConfirmationBlocks

    
                                                
    web3.eth.Contract.transactionConfirmationBlocks
                 contract.transactionConfirmationBlocks // on contract instance
                     

    This defines the number of blocks it requires until a transaction is considered confirmed.

    Returns

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



    transactionPollingTimeout

    
                                                
    web3.eth.Contract.transactionPollingTimeout
                 contract.transactionPollingTimeout // on contract instance
                  

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

    Returns

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


    handleRevert

    
                                                
    web3.eth.Contract.handleRevert
                 contract.handleRevert // on contract instance
                     

    The handleRevert options property defaults to false and returns the revert reason string if enabled on send or call of a contract method.

    Note

    The revert reason string and signature are properties on the returned error.

    Returns

    boolean: The current value of handleRevert (default: false)


    options

    
                                                
    myContract.options
                     

    The options object for the contract instance. from, gas and gasPrice are used as fallback values when sending transactions.

    Properties

    Object - options:

    • address - String: The address where the contract is deployed. See options.address.
    • jsonInterface - Array: The json interface of the contract. See options.jsonInterface.
    • data - String: The byte code of the contract. Used when the contract gets deployed.
    • from - String: The address transactions should be made from.
    • gasPrice - String: The gas price in wei to use for transactions.
    • gas - Number: The maximum gas provided for a transaction (gas limit).
    • handleRevert - Boolean: It will otherwise use the default value provided from the Eth module. See handleRevert.
    • transactionBlockTimeout - Number: It will otherwise use the default value provided from the Eth module. See transactionBlockTimeout.
    • transactionConfirmationBlocks - Number: It will otherwise use the default value provided from the Eth module. See transactionConfirmationBlocks.
    • transactionPollingTimeout - Number: It will otherwise use the default value provided from the Eth module. See transactionPollingTimeout.
    • chain - Number: It will otherwise use the default value provided from the Eth module. See defaultChain.
    • hardfork - Number: It will otherwise use the default value provided from the Eth module. See defaultHardfork.
    • common - Number: It will otherwise use the default value provided from the Eth module. See defaultCommon.

    Example

    
                                                
    myContract.options;
                 > {
                     address: '0x1234567890123456789012345678901234567891',
                     jsonInterface: [...],
                     from: '0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe',
                     gasPrice: '10000000000000',
                     gas: 1000000
                 }
                                                                                                
                 myContract.options.from = '0x1234567890123456789012345678901234567891'; // default from address
                 myContract.options.gasPrice = '20000000000000'; // default gas price in wei
                 myContract.options.gas = 5000000; // provide as fallback always 5M gas
                     

    options.address

    
                                                
    myContract.options.address
                     

    The address used for this contract instance. All transactions generated by web3.js from this contract will contain this address as the "to".

    The address will be stored in lowercase.

    Property

    address - String|null: The address for this contract, or null if not yet set.

    Example

    
                                                
    myContract.options.address;
                 > '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae'
                                                                                                        
                 // set a new address
                 myContract.options.address = '0x1234FFDD...';
                     

    options.jsonInterface

    
                                                
    myContract.options.jsonInterface
                     

    The json interface object derived from the ABI of this contract.

    Property

    jsonInterface - Array: The json interface for this contract. Re-setting this will regenerate the methods and events of the contract instance.

    Example

    
                                                
    myContract.options.jsonInterface;
                 > [{
                     "type":"function",
                     "name":"foo",
                     "inputs": [{"name":"a","type":"uint256"}],
                     "outputs": [{"name":"b","type":"address"}]
                 },{
                     "type":"event",
                     "name":"Event",
                     "inputs": [{"name":"a","type":"uint256","indexed":true},{"name":"b","type":"bytes32","indexed":false}],
                 }]
                                                                                               
                 // set a new interface
                 myContract.options.jsonInterface = [...];
                     

    = Methods =


    clone

    
                                                
    myContract.clone()
                     

    Clones the current contract instance.

    Parameters

    none

    Returns

    Object: The new contract instance.

    Example

    
                                                
    var contract1 = new eth.Contract(abi, address, {gasPrice: '12345678', from: fromAddress});
    
                 var contract2 = contract1.clone();
                 contract2.options.address = address2;
                                                                                                  
                 (contract1.options.address !== contract2.options.address);
                 > true
                     

    deploy

    
                                                
    myContract.deploy(options)
                     

    Call this function to deploy the contract to the blockchain. After successful deployment the promise will resolve with a new contract instance.

    Parameters

    1. options - Object: The options used for deployment.
      • data - String: The byte code of the contract.
      • arguments - Array (optional): The arguments which get passed to the constructor on deployment.

    Returns

    Object: The transaction object:

    • Array - arguments: The arguments passed to the method before. They can be changed.
    • Function - send: Will deploy the contract. The promise will resolve with the new contract instance, instead of the receipt!
    • Function - estimateGas: Will estimate the gas used for deploying. Note: You must specify a from address otherwise you may experience odd behavior.
    • Function - encodeABI: Encodes the ABI of the deployment, which is contract data + constructor parameters

    Example

    
                                                
    myContract.deploy({
                     data: '0x12345...',
                     arguments: [123, 'My String']
                 })
                 .send({
                     from: '0x1234567890123456789012345678901234567891',
                     gas: 1500000,
                     gasPrice: '30000000000000'
                 }, function(error, transactionHash){ ... })
                 .on('error', function(error){ ... })
                 .on('transactionHash', function(transactionHash){ ... })
                 .on('receipt', function(receipt){
                     console.log(receipt.contractAddress) // contains the new contract address
                 })
                 .on('confirmation', function(confirmationNumber, receipt){ ... })
                 .then(function(newContractInstance){
                     console.log(newContractInstance.options.address) // instance with the new contract address
                 });
                                                                                                    
                                                                                                    
                 // When the data is already set as an option to the contract itself
                 myContract.options.data = '0x12345...';
                                                                                                    
                 myContract.deploy({
                     arguments: [123, 'My String']
                 })
                 .send({
                     from: '0x1234567890123456789012345678901234567891',
                     gas: 1500000,
                     gasPrice: '30000000000000'
                 })
                 .then(function(newContractInstance){
                     console.log(newContractInstance.options.address) // instance with the new contract address
                 });
                                                                                                    
                                                                                                   
                 // Simply encoding
                 myContract.deploy({
                     data: '0x12345...',
                     arguments: [123, 'My String']
                 })
                 .encodeABI();
                 > '0x12345...0000012345678765432'
                                                                                                    
                                                                                                   
                 // Gas estimation
                 myContract.deploy({
                     data: '0x12345...',
                     arguments: [123, 'My String']
                 })
                 .estimateGas(function(err, gas){
                     console.log(gas);
                 });
                     

    methods

    
                                                
    myContract.methods.myMethod([param1[, param2[, ...]]])
                     

    Creates a transaction object for that method, which then can be called, send, estimated, or ABI encoded.

    The methods of this smart contract are available through:

    • The name: myContract.methods.myMethod(123)
    • The name with parameters: myContract.methods['myMethod(uint256)'](123)
    • The signature: myContract.methods['0x58cf5f10'](123)

    This allows calling functions with same name but different parameters from the JavaScript contract object.

    Parameters

    Parameters of any method depend on the smart contracts methods, defined in the JSON interface.

    Returns

    Object: The transaction object:

    • Array - arguments: The arguments passed to the method before. They can be changed.
    • Function - call: Will call the “constant” method and execute its smart contract method in the EVM without sending a transaction (Can’t alter the smart contract state).
    • Function - send: Will send a transaction to the smart contract and execute its method (Can alter the smart contract state).
    • Function - estimateGas: Will estimate the gas used when the method would be executed on chain. Note: You must specify a from address otherwise you may experience odd behavior.
    • Function - encodeABI: Encodes the ABI for this method. This can be send using a transaction, call the method or passing into another smart contracts method as argument.

    Example

    
                                                
    // calling a method
    
                 myContract.methods.myMethod(123).call({from: '0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe'}, function(error, result){
                     ...
                 });
                                                                                                        
                 // or sending and using a promise
                 myContract.methods.myMethod(123).send({from: '0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe'})
                 .then(function(receipt){
                     // receipt can also be a new contract instance, when coming from a "contract.deploy({...}).send()"
                 });
                                                                                                       
                 // or sending and using the events
                                                                                                        
                 myContract.methods.myMethod(123).send({from: '0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe'})
                 .on('transactionHash', function(hash){
                     ...
                 })
                 .on('receipt', function(receipt){
                     ...
                 })
                 .on('confirmation', function(confirmationNumber, receipt){
                     ...
                 })
                 .on('error', function(error, receipt) {
                     ...
                 });
                     

    methods.myMethod.call

    
                                                
    myContract.methods.myMethod([param1[, param2[, ...]]]).call(options [, defaultBlock] [, callback])
                     

    Will call a “constant” method and execute its smart contract method in the EVM without sending any transaction. Note calling cannot alter the smart contract state.

    Parameters

    1. options - Object (optional): The options used for calling.
      • from - String (optional): The address the call “transaction” should be made from. For calls the from property is optional however it is highly recommended to explicitly set it or it may default to address(0) depending on your node or provider.
      • gasPrice - String (optional): The gas price in wei to use for this call “transaction”.
      • gas - Number (optional): The maximum gas provided for this call “transaction” (gas limit).
    2. defaultBlock - Number|String|BN|BigNumber (optional): If you pass this parameter it will not use the default block set with contract.defaultBlock. Pre-defined block numbers as "earliest", "latest", and "pending" can also be used. Useful for requesting data from or replaying transactions in past blocks.
    3. callback - Function (optional): This callback will be fired with the result of the smart contract method execution as the second argument, or with an error object as the first argument.

    Returns

    Promise returns Mixed: The return value(s) of the smart contract method. If it returns a single value, it’s returned as is. If it has multiple return values they are returned as an object with properties and indices:

    Example

    
                                                
    // using the callback
                 myContract.methods.myMethod(123).call({from: '0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe'}, function(error, result){
                     ...
                 });
                                                                                                   
                 // using the promise
                 myContract.methods.myMethod(123).call({from: '0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe'})
                 .then(function(result){
                     ...
                 });
                                                                                                    
                                                                                                   
                 // MULTI-ARGUMENT RETURN:
                                                                                                   
                 // Solidity
                 contract MyContract {
                     function myFunction() returns(uint256 myNumber, string myString) {
                         return (23456, "Hello!%");
                     }
                 }
                                                                                                   
                 // web3.js
                 var MyContract = new web3.eth.Contract(abi, address);
                 MyContract.methods.myFunction().call()
                 .then(console.log);
                 > Result {
                     myNumber: '23456',
                     myString: 'Hello!%',
                     0: '23456', // these are here as fallbacks if the name is not know or given
                     1: 'Hello!%'
                 }
                                                                                                    
                                                                                                   
                 // SINGLE-ARGUMENT RETURN:
                                                                                              
                 // Solidity
                 contract MyContract {
                     function myFunction() returns(string myString) {
                         return "Hello!%";
                     }
                 }
                                                                                                    
                 // web3.js
                 var MyContract = new web3.eth.Contract(abi, address);
                 MyContract.methods.myFunction().call()
                 .then(console.log);
                 > "Hello!%"
                     

    methods.myMethod.send

    
                                                
    myContract.methods.myMethod([param1[, param2[, ...]]]).send(options[, callback])
                     

    Will send a transaction to the smart contract and execute its method. Note this can alter the smart contract state.

    Parameters

    1. options - Object: The options used for sending.
      • from - String: The address the transaction should be sent from.
      • gasPrice - String (optional): The gas price in wei to use for this transaction.
      • gas - Number (optional): The maximum gas provided for this transaction (gas limit).
      • value - ``Number|String|BN|BigNumber``(optional): The value transferred for the transaction in wei.
      • nonce - Number (optional): the nonce number of transaction
    2. callback - Function (optional): This callback will be fired first with the “transactionHash”, or with an error object as the first argument.

    Returns

    The callback will return the 32 bytes transaction hash.

    PromiEvent: A promise combined event emitter. Resolves when the transaction receipt is available, OR if this send() is called from a someContract.deploy(), then the promise will resolve with the new contract instance. Additionally the following events are available:

    • sending returns payload: Object: Fired immediately before transmitting the transaction request.
    • sent returns payload: Object: Fired immediately after the request body has been written to the client, but before the transaction hash is received.
    • "transactionHash" returns transactionHash: String: Fired when the transaction hash is available.
    • "receipt" returns receipt: Object: Fired when the transaction receipt is available. Receipts from contracts will have no logs property, but instead an events property with event names as keys and events as properties. See getPastEvents return values for details about the returned event object.
    • "confirmation" returns confirmation: Number, receipt: Object, latestBlockHash: String: Fired for every confirmation up to the 24th confirmation.
    • "error" returns error: Error: Fired if an error occurs during sending. If the transaction was rejected by the network with a receipt, the receipt will be available as a property on the error object.

    Example

    
                                                
    // using the callback
                 myContract.methods.myMethod(123).send({from: '0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe'}, function(error, transactionHash){
                     ...
                 });
                                                                                           
                 // using the promise
                 myContract.methods.myMethod(123).send({from: '0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe'})
                 .then(function(receipt){
                     // receipt can also be a new contract instance, when coming from a "contract.deploy({...}).send()"
                 });
                                                                                           
                                                                                           
                 // using the event emitter
                 myContract.methods.myMethod(123).send({from: '0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe'})
                 .on('transactionHash', function(hash){
                     ...
                 })
                 .on('confirmation', function(confirmationNumber, receipt){
                     ...
                 })
                 .on('receipt', function(receipt){
                     // receipt example
                     console.log(receipt);
                     > {
                         "transactionHash": "0x9fc76417374aa880d4449a1f7f31ec597f00b1f6f3dd2d66f4c9c6c445836d8b",
                         "transactionIndex": 0,
                         "blockHash": "0xef95f2f1ed3ca60b048b4bf67cde2195961e0bba6f70bcbea9a2c4e133e34b46",
                         "blockNumber": 3,
                         "contractAddress": "0x11f4d0A3c12e86B4b5F39B213F7E19D048276DAe",
                         "cumulativeGasUsed": 314159,
                         "gasUsed": 30234,
                         "events": {
                         "MyEvent": {
                             returnValues: {
                                 myIndexedParam: 20,
                                 myOtherIndexedParam: '0x123456789...',
                                 myNonIndexParam: 'My String'
                             },
                             raw: {
                                 data: '0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385',
                                 topics: ['0xfd43ade1c09fade1c0d57a7af66ab4ead7c2c2eb7b11a91ffdd57a7af66ab4ead7', '0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385']
                             },
                             event: 'MyEvent',
                             signature: '0xfd43ade1c09fade1c0d57a7af66ab4ead7c2c2eb7b11a91ffdd57a7af66ab4ead7',
                             logIndex: 0,
                             transactionIndex: 0,
                             transactionHash: '0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385',
                             blockHash: '0xfd43ade1c09fade1c0d57a7af66ab4ead7c2c2eb7b11a91ffdd57a7af66ab4ead7',
                             blockNumber: 1234,
                             address: '0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe'
                         },
                         "MyOtherEvent": {
                             ...
                         },
                         "MyMultipleEvent":[{...}, {...}] // If there are multiple of the same event, they will be in an array
                     }
                 }
             })
             .on('error', function(error, receipt) { // If the transaction was rejected by the network with a receipt, the second parameter will be the receipt.
                 ...
             });
                     

    methods.myMethod.estimateGas

    
                                                
    myContract.methods.myMethod([param1[, param2[, ...]]]).estimateGas(options[, callback])
                     

    Will call to estimate the gas a method execution will take when executed in the EVM. The estimation can differ from the actual gas used when later sending a transaction, as the state of the smart contract can be different at that time. Note: You must specify a from address otherwise you may experience odd behavior.

    Parameters

    1. options - Object (optional): The options used for calling.
      • from - String (optional): The address the call “transaction” should be made from.
      • gas - Number (optional): The maximum gas provided for this call “transaction” (gas limit). Setting a specific value helps to detect out of gas errors. If all gas is used it will return the same number.
      • value - Number|String|BN|BigNumber (optional): The value transferred for the call “transaction” in wei.
    2. callback - Function (optional): This callback will be fired with the result of the gas estimation as the second argument, or with an error object as the first argument.

    Returns

    Promise returns Number: The gas amount estimated.

    Example

    
                                                
    // using the callback
             myContract.methods.myMethod(123).estimateGas({gas: 5000000}, function(error, gasAmount){
                 if(gasAmount == 5000000)
                     console.log('Method ran out of gas');
             });
                                                                                           
             // using the promise
             myContract.methods.myMethod(123).estimateGas({from: '0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe'})
             .then(function(gasAmount){
                 ...
             })
             .catch(function(error){
                 ...
             });
                     

    methods.myMethod.encodeABI

    
                                                
    myContract.methods.myMethod([param1[, param2[, ...]]]).encodeABI()
                     

    Encodes the ABI for this method. The resulting hex string is 32-bit function signature hash plus the passed parameters in Solidity tightly packed format. This can be used to send a transaction, call a method, or pass it into another smart contract’s method as arguments. Set the data field on web3.eth.sendTransaction options as the encodeABI() result and it is the same as calling the contract method with contract.myMethod.send().

    Some use cases for encodeABI() include: preparing a smart contract transaction for a multisignature wallet, working with offline wallets and cold storage and creating transaction payload for complex smart contract proxy calls.

    Parameters

    none

    Returns

    String: The encoded ABI byte code to send via a transaction or call.

    Example

    
                                                
    myContract.methods.myMethod(123).encodeABI();
             > '0x58cf5f1000000000000000000000000000000000000000000000000000000000000007B'
                     

    = Events =


    once

    
                                                
    myContract.once(event[, options], callback)
                     

    Subscribes to an event and unsubscribes immediately after the first event or error. Will only fire for a single event.

    Parameters

    1. event - String: The name of the event in the contract, or "allEvents" to get all events.
    2. options - Object (optional): The options used for deployment.
      • filter - Object (optional): Lets you filter events by indexed parameters, e.g. {filter: {myNumber: [12,13]}} means all events where “myNumber” is 12 or 13.
      • topics - Array (optional): This allows you to manually set the topics for the event filter. If given the filter property and event signature, (topic[0]) will not be set automatically. Each topic can also be a nested array of topics that behaves as “or” operation between the given nested topics.
    3. callback - Function: This callback will be fired for the first event as the second argument, or an error as the first argument. See getPastEvents return values for details about the event structure.

    Returns

    undefined

    Example

    
                
    myContract.once('MyEvent', {
                     filter: {myIndexedParam: [20,23], myOtherIndexedParam: '0x123456789...'}, // Using an array means OR: e.g. 20 or 23
                     fromBlock: 0
                }, function(error, event){ console.log(event); });
                                                                                       
                // event output example
                > {
                     returnValues: {
                         myIndexedParam: 20,
                         myOtherIndexedParam: '0x123456789...',
                         myNonIndexParam: 'My String'
                     },
                     raw: {
                         data: '0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385',
                         topics: ['0xfd43ade1c09fade1c0d57a7af66ab4ead7c2c2eb7b11a91ffdd57a7af66ab4ead7', '0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385']
                     },
                     event: 'MyEvent',
                     signature: '0xfd43ade1c09fade1c0d57a7af66ab4ead7c2c2eb7b11a91ffdd57a7af66ab4ead7',
                     logIndex: 0,
                     transactionIndex: 0,
                     transactionHash: '0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385',
                     blockHash: '0xfd43ade1c09fade1c0d57a7af66ab4ead7c2c2eb7b11a91ffdd57a7af66ab4ead7',
                     blockNumber: 1234,
                     address: '0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe'
                }
                

    events

    
                
    myContract.events.MyEvent([options][, callback])
                

    Subscribe to an event.

    Parameters

    1. options - Object (optional): The options used for deployment.
      • filter - Object (optional): Let you filter events by indexed parameters, e.g. {filter: {myNumber: [12,13]}} means all events where “myNumber” is 12 or 13.
      • fromBlock - Number|String|BN|BigNumber (optional): The block number (greater than or equal to) from which to get events on. Pre-defined block numbers as "earliest", "latest" and "pending" can also be used. For specific range use getPastEvents.
      • topics - Array (optional): This allows to manually set the topics for the event filter. If given the filter property and event signature, (topic[0]) will not be set automatically. Each topic can also be a nested array of topics that behaves as “or” operation between the given nested topics.
    2. callback - Function (optional): This callback will be fired for each event as the second argument, or an error as the first argument.

    Returns

    EventEmitter: The event emitter has the following events:

    • "data" returns Object: Fires on each incoming event with the event object as argument.
    • "changed" returns Object: Fires on each event which was removed from the blockchain. The event will have the additional property "removed: true".
    • "error" returns Object: Fires when an error in the subscription occours.
    • "connected" returns String: Fires once after the subscription successfully connected. Returns the subscription id.

    The structure of the returned event Object looks as follows:

    • event - String: The event name.
    • signature - String|Null: The event signature, null if it’s an anonymous event.
    • address - String: Address this event originated from.
    • returnValues - Object: The return values coming from the event, e.g. {myVar: 1, myVar2: '0x234...'}.
    • 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 this event was created in. null when it’s still pending.
    • blockNumber - Number: The block number this log was created in. null when still pending.
    • raw.data - String: The data containing non-indexed log parameter.
    • raw.topics - Array: An array with max 4 32 Byte topics, topic 1-3 contains indexed parameters of the event.

    Example

    
                
    myContract.events.MyEvent({
                     filter: {myIndexedParam: [20,23], myOtherIndexedParam: '0x123456789...'}, // Using an array means OR: e.g. 20 or 23
                     fromBlock: 0
                }, function(error, event){ console.log(event); })
                .on("connected", function(subscriptionId){
                     console.log(subscriptionId);
                })
                .on('data', function(event){
                     console.log(event); // same results as the optional callback above
                })
                .on('changed', function(event){
                     // remove event from local database
                })
                .on('error', function(error, receipt) { // If the transaction was rejected by the network with a receipt, the second parameter will be the receipt.
                     ...
                });
                                                                                       
                // event output example
                > {
                     returnValues: {
                         myIndexedParam: 20,
                         myOtherIndexedParam: '0x123456789...',
                         myNonIndexParam: 'My String'
                     },
                     raw: {
                         data: '0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385',
                         topics: ['0xfd43ade1c09fade1c0d57a7af66ab4ead7c2c2eb7b11a91ffdd57a7af66ab4ead7', '0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385']
                     },
                     event: 'MyEvent',
                     signature: '0xfd43ade1c09fade1c0d57a7af66ab4ead7c2c2eb7b11a91ffdd57a7af66ab4ead7',
                     logIndex: 0,
                     transactionIndex: 0,
                     transactionHash: '0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385',
                     blockHash: '0xfd43ade1c09fade1c0d57a7af66ab4ead7c2c2eb7b11a91ffdd57a7af66ab4ead7',
                     blockNumber: 1234,
                     address: '0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe'
                }
                

    events.allEvents

    
                
    myContract.events.allEvents([options][, callback])
                

    Same as events but receives all events from this smart contract. Optionally the filter property can filter those events.


    getPastEvents

    
                
    myContract.getPastEvents(event[, options][, callback])
                

    Gets past events for this contract.

    Parameters

    1. event - String: The name of the event in the contract, or "allEvents" to get all events.
    2. options - Object (optional): The options used for deployment.
      • filter - Object (optional): Lets you filter events by indexed parameters, e.g. {filter: {myNumber: [12,13]}} means all events where “myNumber” is 12 or 13.
      • fromBlock - Number|String|BN|BigNumber (optional): The block number (greater than or equal to) from which to get events on. Pre-defined block numbers as "earliest", "latest" and "pending" can also be used.
      • toBlock - Number|String|BN|BigNumber (optional): The block number (less than or equal to) to get events up to (Defaults to "latest"). Pre-defined block numbers as "earliest", "latest" and "pending" can also be used.
      • topics - Array (optional): This allows manually setting the topics for the event filter. If given the filter property and event signature, (topic[0]) will not be set automatically. Each topic can also be a nested array of topics that behaves as “or” operation between the given nested topics.
    3. callback - Function (optional): This callback will be fired with an array of event logs as the second argument, or an error as the first argument.

    Returns

    Promise returns Array: An array with the past event Objects, matching the given event name and filter.

    For the structure of a returned event Object see getPastEvents return values.

    Example

    
                    
    myContract.getPastEvents('MyEvent', {
                         filter: {myIndexedParam: [20,23], myOtherIndexedParam: '0x123456789...'}, // Using an array means OR: e.g. 20 or 23
                         fromBlock: 0,
                         toBlock: 'latest'
                    }, function(error, events){ console.log(events); })
                    .then(function(events){
                         console.log(events) // same results as the optional callback above
                    });
                                                                               
                    > [{
                         returnValues: {
                             myIndexedParam: 20,
                             myOtherIndexedParam: '0x123456789...',
                             myNonIndexParam: 'My String'
                         },
                         raw: {
                             data: '0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385',
                             topics: ['0xfd43ade1c09fade1c0d57a7af66ab4ead7c2c2eb7b11a91ffdd57a7af66ab4ead7', '0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385']
                         },
                         event: 'MyEvent',
                         signature: '0xfd43ade1c09fade1c0d57a7af66ab4ead7c2c2eb7b11a91ffdd57a7af66ab4ead7',
                         logIndex: 0,
                         transactionIndex: 0,
                         transactionHash: '0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385',
                         blockHash: '0xfd43ade1c09fade1c0d57a7af66ab4ead7c2c2eb7b11a91ffdd57a7af66ab4ead7',
                         blockNumber: 1234,
                         address: '0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe'
                    },{
                         ...
                    }]