Merge pull request #2216 from ethereum/documentation/web3-module-options

Web3 module options to include_package-core added
web3 · Jan 27, 2019 · 599c52e · 599c52e
2 parents d816865 + fcba5a9
commit 599c52e
Show file tree

Hide file tree

Showing 2 changed files with 211 additions and 2 deletions.
diff --git a/docs/include_package-core.rst b/docs/include_package-core.rst
@@ -1,4 +1,49 @@
 
+Web3 Module 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:
+
+--------------
+Module Options
+--------------
+
+:ref:`defaultAccount <web3-module-defaultaccount>`
+
+:ref:`defaultBlock <web3-module-defaultblock>`
+
+:ref:`defaultGas <web3-module-defaultgas>`
+
+:ref:`defaultGasPrice <web3-module-defaultaccount>`
+
+:ref:`transactionBlockTimeout <web3-module-transactionblocktimeout>`
+
+:ref:`transactionConfirmationBlocks <web3-module-transactionconfirmationblocks>`
+
+:ref:`transactionPollingTimeout <web3-module-transactionpollingtimeout>`
+
+-------
+Example
+-------
+
+.. code-block:: javascript
+
+    import Web3 from 'web3';
+
+    const options = {
+        defaultAccount: '0x0',
+        defaultBlock: 'latest',
+        defaultGas: 1,
+        defaultGasPrice: 0,
+        transactionBlockTimeout: 50,
+        transactionConfirmationBlocks: 24,
+        transactionPollingTimeout: 480
+    }
+
+    const web3 = new Web3('http://localhost:8545', options);
+
+------------------------------------------------------------------------------
 
 setProvider
 =====================
@@ -175,7 +220,7 @@ BatchRequest
     new web3.BatchRequest()
     new web3.eth.BatchRequest()
     new web3.shh.BatchRequest()
-    new web3.bzz.BatchRequest()
+    ...
 
 Class to create and execute batch requests.
 
@@ -206,3 +251,167 @@ Example
     batch.add(web3.eth.getBalance.request('0x0000000000000000000000000000000000000000', 'latest', callback));
     batch.add(contract.methods.balance(address).call.request({from: '0x0000000000000000000000000000000000000000'}, callback2));
     batch.execute();
+
+------------------------------------------------------------------------------
+
+.. _web3-module-defaultblock:
+
+defaultBlock
+=====================
+
+.. code-block:: javascript
+
+    web3.defaultBlock
+    web3.eth.defaultBlock
+    web3.shh.defaultBlock
+    ...
+
+The default block which will be used for a requests.
+
+-------
+Returns
+-------
+
+``string|number``: The current value of the defaultBlock property.
+
+------------------------------------------------------------------------------
+
+.. _web3-module-defaultaccount:
+
+defaultBlock
+=====================
+
+.. code-block:: javascript
+
+    web3.defaultAccount
+    web3.eth.defaultAccount
+    web3.shh.defaultAccount
+    ...
+
+The default account which will be used for a requests.
+
+-------
+Returns
+-------
+
+``null|string``: The current value of the defaultAccount property.
+
+------------------------------------------------------------------------------
+
+.. _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
+    ...
+
+This can be used with a socket provider and defines the number of blocks until the PromiEvent
+rejects with a timeout error.
+
+
+-------
+Returns
+-------
+
+``number``: The current value of transactionBlockTimeout
+
+------------------------------------------------------------------------------
+
+.. _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.
+The PromiEvent will resolve with the desired receipt when enough confirmations happened.
+
+
+-------
+Returns
+-------
+
+``number``: The current value of transactionConfirmationBlocks
+
+------------------------------------------------------------------------------
+
+
+.. _web3-module-transactionpollingtimeout:
+
+transactionPollingTimeout
+=====================
+
+.. code-block:: javascript
+
+    web3.transactionPollingTimeout
+    web3.eth.transactionPollingTimeout
+    web3.shh.transactionPollingTimeout
+    ...
+
+This defines the polling cycles amount when you send a transaction with the HttpProvider.
+The PromiEvent rejects with a timeout error when the timeout got exceeded. (1 cycle == 1sec.).
+
+
+-------
+Returns
+-------
+
+``number``: The current value of transactionPollingTimeout
+
+------------------------------------------------------------------------------
diff --git a/packages/web3-core/src/AbstractWeb3Module.js b/packages/web3-core/src/AbstractWeb3Module.js
@@ -70,7 +70,7 @@ export default class AbstractWeb3Module {
      *
      * @property defaultBlock
      *
-     * @returns {null|String}
+     * @returns {String|Number}
      */
     get defaultBlock() {
         return this._defaultBlock;