options ===================== An Web3 module does provide several options for configuring the transaction confirmation worklfow or for defining default values. These are the currently available option properties on a Web3 module: .. _web3-module-options: -------------- Module Options -------------- :ref:`defaultAccount ` :ref:`defaultBlock ` :ref:`defaultGas ` :ref:`defaultGasPrice ` :ref:`transactionBlockTimeout ` :ref:`transactionConfirmationBlocks ` :ref:`transactionPollingTimeout ` :ref:`transactionSigner ` ------- Example ------- .. code-block:: javascript import Web3 from 'web3'; const options = { defaultAccount: '0x0', defaultBlock: 'latest', defaultGas: 1, defaultGasPrice: 0, transactionBlockTimeout: 50, transactionConfirmationBlocks: 24, transactionPollingTimeout: 480, transactionSigner: new CustomTransactionSigner() } const web3 = new Web3('http://localhost:8545', null, options); ------------------------------------------------------------------------------ .. _web3-module-defaultblock: defaultBlock ===================== .. code-block:: javascript web3.defaultBlock web3.eth.defaultBlock web3.shh.defaultBlock ... The default block is used for all methods which have a block parameter. You can override it by passing the block parameter if a block is required. Example: - :ref:`web3.eth.getBalance() ` - :ref:`web3.eth.getCode() ` - :ref:`web3.eth.getTransactionCount() ` - :ref:`web3.eth.getStorageAt() ` - :ref:`web3.eth.call() ` - :ref:`new web3.eth.Contract() -> myContract.methods.myMethod().call() ` ------- Returns ------- The ``defaultBlock`` property can return the following values: - ``Number``: A block number - ``"genesis"`` - ``String``: The genesis block - ``"latest"`` - ``String``: The latest block (current head of the blockchain) - ``"pending"`` - ``String``: The currently mined block (including pending transactions) Default is ``"latest"`` ------------------------------------------------------------------------------ .. _web3-module-defaultaccount: defaultAccount ===================== .. code-block:: javascript web3.defaultAccount web3.eth.defaultAccount web3.shh.defaultAccount ... This default address is used as the default ``"from"`` property, if no ``"from"`` property is specified. ------- Returns ------- ``String`` - 20 Bytes: Any Ethereum address. You need to have the private key for that address in your node or keystore. (Default is ``undefined``) ------------------------------------------------------------------------------ .. _web3-module-defaultgasprice: defaultGasPrice ===================== .. code-block:: javascript web3.defaultGasPrice web3.eth.defaultGasPrice web3.shh.defaultGasPrice ... The default gas price which will be used for a request. ------- Returns ------- ``string|number``: The current value of the defaultGasPrice property. ------------------------------------------------------------------------------ .. _web3-module-defaultgas: defaultGas ===================== .. code-block:: javascript web3.defaultGas web3.eth.defaultGas web3.shh.defaultGas ... The default gas which will be used for a request. ------- Returns ------- ``string|number``: The current value of the defaultGas property. ------------------------------------------------------------------------------ .. _web3-module-transactionblocktimeout: transactionBlockTimeout ===================== .. code-block:: javascript web3.transactionBlockTimeout web3.eth.transactionBlockTimeout web3.shh.transactionBlockTimeout ... The ``transactionBlockTimeout`` will be used over a socket based connection. This option does define the amount of new blocks it should wait until the first confirmation happens. This means the PromiEvent rejects with a timeout error when the timeout got exceeded. ------- Returns ------- ``number``: The current value of transactionBlockTimeout ------------------------------------------------------------------------------ .. _web3-module-transactionconfirmationblocks: transactionConfirmationBlocks ===================== .. code-block:: javascript web3.transactionConfirmationBlocks web3.eth.transactionConfirmationBlocks web3.shh.transactionConfirmationBlocks ... This defines the number of blocks it requires until a transaction will be handled as confirmed. ------- Returns ------- ``number``: The current value of transactionConfirmationBlocks ------------------------------------------------------------------------------ .. _web3-module-transactionpollingtimeout: transactionPollingTimeout ===================== .. code-block:: javascript web3.transactionPollingTimeout web3.eth.transactionPollingTimeout web3.shh.transactionPollingTimeout ... The ``transactionPollingTimeout`` will be used over a HTTP connection. This option does define the amount of polls (each second) it should wait until the first confirmation happens. ------- Returns ------- ``number``: The current value of transactionPollingTimeout ------------------------------------------------------------------------------ .. _web3-module-transactionSigner: transactionSigner ================= .. code-block:: javascript web3.eth.transactionSigner ... The ``transactionSigner`` property does provide us the possibility to customize the signing process of the ``Eth`` module and the related sub-modules. The interface of a ``TransactionSigner``: .. code-block:: javascript interface TransactionSigner { sign(txObject: Transaction): Promise } interface SignedTransaction { messageHash: string, v: string, r: string, s: string, rawTransaction: string } ------- Returns ------- ``TransactionSigner``: A JavaScript class of type TransactionSigner. ------------------------------------------------------------------------------ setProvider ===================== .. code-block:: javascript web3.setProvider(myProvider) web3.eth.setProvider(myProvider) web3.shh.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. ---------- Parameters ---------- 1. ``Object|String`` - ``provider``: a valid provider 2. ``Net`` - ``net``: (optional) the node.js Net package. This is only required for the IPC provider. ------- Returns ------- ``Boolean`` ------- Example ------- .. code-block:: javascript import Web3 from 'web3'; const web3 = new Web3('http://localhost:8545'); // or const web3 = new Web3(new Web3.providers.HttpProvider('http://localhost:8545')); // change provider web3.setProvider('ws://localhost:8546'); // or web3.setProvider(new Web3.providers.WebsocketProvider('ws://localhost:8546')); // Using the IPC provider in node.js const net = require('net'); const web3 = new Web3('/Users/myuser/Library/Ethereum/geth.ipc', net); // mac os path // or const web3 = new Web3(new Web3.providers.IpcProvider('/Users/myuser/Library/Ethereum/geth.ipc', net)); // mac os path // on windows the path is: '\\\\.\\pipe\\geth.ipc' // on linux the path is: '/users/myuser/.ethereum/geth.ipc' ------------------------------------------------------------------------------ providers ===================== .. code-block:: javascript Web3.providers Eth.providers ... Contains the current available providers. ---------- Value ---------- ``Object`` with the following providers: - ``Object`` - ``HttpProvider``: The HTTP provider is **deprecated**, as it won't work for subscriptions. - ``Object`` - ``WebsocketProvider``: The Websocket provider is the standard for usage in legacy browsers. - ``Object`` - ``IpcProvider``: The IPC provider is used node.js dapps when running a local node. Gives the most secure connection. ------- Example ------- .. code-block:: javascript const Web3 = require('web3'); // use the given Provider, e.g in Mist, or instantiate a new websocket provider const web3 = new Web3(Web3.givenProvider || 'ws://localhost:8546'); // or const web3 = new Web3(Web3.givenProvider || new Web3.providers.WebsocketProvider('ws://localhost:8546')); // Using the IPC provider in node.js const net = require('net'); const web3 = new Web3('/Users/myuser/Library/Ethereum/geth.ipc', net); // mac os path // or const web3 = new Web3(new Web3.providers.IpcProvider('/Users/myuser/Library/Ethereum/geth.ipc', net)); // mac os path // on windows the path is: '\\\\.\\pipe\\geth.ipc' // on linux the path is: '/users/myuser/.ethereum/geth.ipc' ------------------------------------------------------------------------------ givenProvider ===================== .. code-block:: javascript Web3.givenProvider web3.eth.givenProvider web3.shh.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 ``false``. ------- Example ------- .. code-block:: javascript web3.setProvider(Web3.givenProvider || 'ws://localhost:8546'); ------------------------------------------------------------------------------ currentProvider ===================== .. code-block:: javascript web3.currentProvider web3.eth.currentProvider web3.shh.currentProvider ... Will return the current provider. ------- Returns ------- ``Object``: The current provider set. ------- Example ------- .. code-block:: javascript if (!web3.currentProvider) { web3.setProvider('http://localhost:8545'); } ------------------------------------------------------------------------------ BatchRequest ===================== .. code-block:: javascript new web3.BatchRequest() new web3.eth.BatchRequest() new web3.shh.BatchRequest() ... Class to create and execute batch requests. ---------- Parameters ---------- none ------- Returns ------- ``Object``: With the following methods: - ``add(request)``: To add a request object to the batch call. - ``execute()``: Will execute the batch request. ------- Example ------- .. code-block:: javascript const contract = new web3.eth.Contract(abi, address); const batch = new web3.BatchRequest(); batch.add(web3.eth.getBalance.request('0x0000000000000000000000000000000000000000', 'latest')); batch.add(contract.methods.balance(address).call.request({from: '0x0000000000000000000000000000000000000000'})); batch.execute().then(...);