feat(docs): Expand web3 config guide (#7131)

* add doc for `handleRevert` * add doc for defaultAccount * add doc for `defaultBlock` * add doc for transactionBlockTimeout * add doc for transactionConfirmationBlocks * add doc for transactionPollingInterval * add doc for transactionPollingTimeout * add doc for transactionReceiptPollingInterval and improve doc for transactionPollingInterval * add doc for transactionSendTimeout * add doc for transactionConfirmationPollingInterval * add doc for blockHeaderTimeout * add doc for maxListenersWarningThreshold * add doc for contractDataInputFill * add doc for defaultNetworkId * add doc for defaultHardfork, defaultChain and defaultCommon * add doc for defaultTransactionType * add doc for defaultMaxPriorityFeePerGas * refine * add doc for `handleRevert` * add doc for defaultAccount * add doc for `defaultBlock` * add doc for transactionBlockTimeout * add doc for transactionConfirmationBlocks * add doc for transactionPollingInterval * add doc for transactionPollingTimeout * add doc for transactionReceiptPollingInterval and improve doc for transactionPollingInterval * add doc for transactionSendTimeout * add doc for transactionConfirmationPollingInterval * add doc for blockHeaderTimeout * add doc for maxListenersWarningThreshold * add doc for contractDataInputFill * add doc for defaultNetworkId * add doc for defaultHardfork, defaultChain and defaultCommon * add doc for defaultTransactionType * add doc for defaultMaxPriorityFeePerGas * refine * fix semi colons * emphasize the default value and use the original default value in the code snippet * run deploy * revert * add link, fix pr comments * remove redundant global config example * Apply suggestions from code review Co-authored-by: Junaid <86780488+jdevcs@users.noreply.github.com> * resolve review comments * Apply suggestions from code review Co-authored-by: Dan Forbes <dan@danforbes.dev> * remove all example except for transactionPollingInterval, defaultReturnFormat and defaultCommon * Apply suggestions from code review Co-authored-by: Dan Forbes <dan@danforbes.dev> * Update docs/docs/guides/web3_config/index.md --------- Co-authored-by: blackmoshui <qiufan_glamour@outlook.com> Co-authored-by: Alex <luu.alex98@gmail.com> Co-authored-by: luu-alex <98a.lexluu@gmail.com> Co-authored-by: Junaid <86780488+jdevcs@users.noreply.github.com> Co-authored-by: Dan Forbes <dan@danforbes.dev>
web3 · Aug 6, 2024 · 8b435c1 · 8b435c1 · github-actions · Aug 6, 2024
1 parent 5080e80
commit 8b435c1
Show file tree

Hide file tree

Showing 2 changed files with 231 additions and 34 deletions.
diff --git a/docs/docs/guides/web3_config/index.md b/docs/docs/guides/web3_config/index.md
@@ -9,25 +9,26 @@ sidebar_label: 'Web3 Config Guide'
 
 There is list of configuration params that can be set for modifying behavior of different functions in web3.js packages. Following is list of configuration options with details:
 
-- [handleRevert]( /api/web3-core/class/Web3Config#handleRevert) 
-- [defaultAccount](/api/web3-core/class/Web3Config#defaultAccount)
-- [defaultBlock](/api/web3-core/class/Web3Config#defaultBlock) 
-- [transactionBlockTimeout](/api/web3-core/class/Web3Config#transactionBlockTimeout)  
-- [transactionConfirmationBlocks](/api/web3-core/class/Web3Config#transactionConfirmationBlocks)  
-- [transactionPollingInterval](/api/web3-core/class/Web3Config#transactionPollingInterval)  
-- [transactionPollingTimeout](/api/web3-core/class/Web3Config#transactionPollingTimeout)  
-- [transactionReceiptPollingInterval](/api/web3-core/class/Web3Config#transactionReceiptPollingInterval)  
-- [transactionSendTimeout](/api/web3-core/class/Web3Config#transactionSendTimeout)  
-- [transactionConfirmationPollingInterval](/api/web3-core/class/Web3Config#transactionConfirmationPollingInterval)  
-- [blockHeaderTimeout](/api/web3-core/class/Web3Config#blockHeaderTimeout)
-- [maxListenersWarningThreshold](/api/web3-core/class/Web3Config#maxListenersWarningThreshold)  
-- [contractDataInputFill](/api/web3-core/class/Web3Config#contractDataInputFill)
-- [defaultNetworkId](/api/web3-core/class/Web3Config#defaultNetworkId)  
-- [defaultChain](/api/web3-core/class/Web3Config#defaultChain)  
-- [defaultHardfork](/api/web3-core/class/Web3Config#defaultHardfork)  
-- [defaultCommon](/api/web3-core/class/Web3Config#defaultCommon)  
-- [defaultTransactionType](/api/web3-core/class/Web3Config#defaultTransactionType)  
-- [defaultReturnFormat](/api/web3-core/class/Web3Config#defaultReturnFormat)  
+- [handleRevert](/guides/web3_config/#handlerevert)
+- [defaultAccount](/guides/web3_config/#defaultaccount)
+- [defaultBlock](/guides/web3_config/#defaultblock)
+- [transactionBlockTimeout](/guides/web3_config/#transactionblocktimeout)  
+- [transactionConfirmationBlocks](/guides/web3_config/#transactionconfirmationblocks)  
+- [transactionPollingInterval](/guides/web3_config/#transactionpollinginterval)  
+- [transactionPollingTimeout](/guides/web3_config/#transactionpollingtimeout)  
+- [transactionReceiptPollingInterval](/guides/web3_config/#transactionreceiptpollinginterval)  
+- [transactionSendTimeout](/guides/web3_config/#transactionsendtimeout)  
+- [[Deprecated] transactionConfirmationPollingInterval](/guides/web3_config/#transactionconfirmationpollinginterval)
+- [blockHeaderTimeout](/guides/web3_config/#blockheadertimeout)
+- [maxListenersWarningThreshold](/guides/web3_config/#maxlistenerswarningthreshold)  
+- [contractDataInputFill](/guides/web3_config/#contractdatainputfill)
+- [defaultNetworkId](/guides/web3_config/#defaultnetworkid)  
+- [defaultChain](/guides/web3_config/#defaultchain)  
+- [defaultHardfork](/guides/web3_config/#defaulthardfork)  
+- [defaultCommon](/guides/web3_config/#defaultcommon)  
+- [defaultTransactionType](/guides/web3_config/#defaulttransactiontype)
+- [defaultMaxPriorityFeePerGas](/guides/web3_config/#defaultmaxpriorityfeepergas)
+- [defaultReturnFormat](/guides/web3_config/#defaultreturnformat)  
 
 ## Global level Config
 
@@ -201,44 +202,240 @@ console.log(web3.getContextObject().config)
 */
 ```
 
+## Explanation of Configuration Parameters
 
-### defaultReturnFormat
-The `defaultReturnFormat` allows users to specify the format in which certain types of data should be returned by default. It is a configuration parameter that can be set at the global level and affects how data is returned across the entire library.
+### [handleRevert](/api/web3-core/class/Web3Config#handleRevert)
+The following methods will retrieve specific error types and error messages when `handleRevert` is set to `true`:
+- [`web3.eth.sendTransaction()`](/api/web3-eth/function/sendTransaction);
+- [`myContract.methods.myMethod().send()`](/libdocs/Contract#send);
+
+The error type will be one of the following:
+- [InvalidResponseError](/api/web3-errors/class/InvalidResponseError)
+- [ContractExecutionError](/api/web3-errors/class/ContractExecutionError)
+- [TransactionRevertWithCustomError](/api/web3-errors/class/TransactionRevertWithCustomError)
+- [TransactionRevertedWithoutReasonError](/api/web3-errors/class/TransactionRevertedWithoutReasonError)
+- [TransactionRevertInstructionError](/api/web3-errors/class/TransactionRevertInstructionError)
+- [TransactionPollingTimeoutError](/api/web3-errors/class/TransactionPollingTimeoutError)
+
+For example, the error message could be `TransactionRevertInstructionError('Returned error: invalid argument 0: json: cannot unmarshal invalid hex string into Go struct field TransactionArgs.data of type hexutil.Bytes')`. The `handleRevert` option is only supported for [`sendTransaction`](/api/web3-eth/function/sendTransaction) and not for [`sendSignedTransaction`](/api/web3-eth/function/sendSignedTransaction) for now.
+
+The default value of `handleRevert` is `false`.
+
+### [defaultAccount](/api/web3-core/class/Web3Config#defaultAccount)
+The `defaultAccount` option is used as the default `from` property, if no `from` property is specified for the following methods:
+- [`web3.eth.sendTransaction()`](/api/web3-eth/function/sendTransaction);
+- [`web3.eth.call()`](/api/web3-eth/function/call);
+- [`myContract.methods.myMethod().call()`](/libdocs/Contract#call);
+- [`myContract.methods.myMethod().send()`](/libdocs/Contract#send);
+
+The default value of `defaultAccount` is `undefined`.
+
+### [defaultBlock](/api/web3-core/class/Web3Config#defaultBlock)
+The following methods accept an optional `blockNumber` parameter, the `defaultBlock` option is used for these methods if no `blockNumber` parameter is provided. 
+- [`web3.eth.getBalance()`](/api/web3-eth/function/getBalance);
+- [`web3.eth.getCode()`](/api/web3-eth/function/getCode);
+- [`web3.eth.getTransactionCount()`](/api/web3-eth/function/getTransactionCount);
+- [`web3.eth.getStorageAt()`](/api/web3-eth/function/getStorageAt);
+- [`web3.eth.call()`](/api/web3-eth/function/call);
+- [`myContract.methods.myMethod().call()`](/libdocs/Contract#call);
+
+If a `blockNumber` parameter is provided to one of the above function calls, it will override this option.
+
+The default value of `defaultBlock` is "latest".
+
+#### All available choices for defaultBlock:
 ```ts
-import { Web3, FMT_NUMBER, FMT_BYTES } from 'web3';
+web3.defaultBlock = 20167235; // A block number
+web3.defaultBlock = "earliest"; // The genesis block
+web3.defaultBlock = "latest"; // The latest block (current head of the blockchain)
+web3.defaultBlock = "pending"; // The block pending to be mined (including pending transactions)
+web3.defaultBlock = "finalized"; // (For POS networks) The finalized block is one which has been accepted as canonical by greater than 2/3 of validators
+web3.defaultBlock = "safe"; // (For POS networks) The safe head block is one which under normal network conditions, is expected to be included in the canonical chain. Under normal network conditions the safe head and the actual tip of the chain will be equivalent (with safe head trailing only by a few seconds). Safe heads will be less likely to be reorged than the proof of work network`s latest blocks.
+```
 
-web3.defaultReturnFormat = {
-    number: FMT_NUMBER.BIGINT,
-    bytes: FMT_BYTES.HEX,
+### [transactionBlockTimeout](/api/web3-core/class/Web3Config#transactionBlockTimeout)
+ This option defines the number of new blocks to wait for the **first confirmation**, otherwise the [`PromiEvent`](/api/web3/class/Web3PromiEvent) rejects with a timeout error.
+
+The default value of `transactionBlockTimeout` is 50. 
+
+### [transactionConfirmationBlocks](/api/web3-core/class/Web3Config#transactionConfirmationBlocks)
+This defines the number of blocks required for a transaction to be considered confirmed. Different chains have varying security considerations and requirements for confirmation block numbers.
+
+The default value of `transactionConfirmationBlocks` is 24.
+
+### [transactionPollingInterval](/api/web3-core/class/Web3Config#transactionPollingInterval)
+This option defines the number of seconds between Web3 calls for a receipt which confirms that a transaction was mined by the network. Modifying this value can reduce the wait time for confirmations or decrease the number of network requests. Setting the `transactionPollingInterval` would also set [`transactionReceiptPollingInterval`](/guides/web3_config/#transactionreceiptpollinginterval) and [`transactionConfirmationPollingInterval`](/guides/web3_config/#transactionconfirmationpollinginterval) to the same value.
+
+The default value of `transactionPollingInterval` is 1000 ms.
+
+```ts
+import { Web3 } from 'web3';
+
+const web3 = new Web3('http://127.0.0.1:7545');
+
+web3.transactionPollingInterval = 1000; // 1000 ms = 1 s
+
+console.log(web3.getContextObject().config);
+/* ↳
+  ...
+  transactionPollingInterval: 1000,
+  transactionPollingTimeout: 750000,
+  transactionReceiptPollingInterval: 1000,
+  transactionSendTimeout: 750000,
+  transactionConfirmationPollingInterval: 1000,
+  ...
+*/
+```
+
+### [transactionPollingTimeout](/api/web3-core/class/Web3Config#transactionPollingTimeout)
+This option defines the number of seconds Web3 will wait for a receipt which confirms that a transaction was mined by the network. It can be set based on the average transaction confirmation time on the network. Note: If the `transactionPollingTimeout` is exceeded, the transaction may still be pending.
+
+The default value of `transactionPollingTimeout` is 750 seconds (12.5 minutes).
+
+### [transactionReceiptPollingInterval](/api/web3-core/class/Web3Config#transactionReceiptPollingInterval)
+This option defines the number of seconds between Web3 calls for a receipt which confirms that a transaction was mined by the network. Compared to [`transactionPollingInterval`](/guides/web3_config/#transactionpollinginterval), it takes higher precedence. When this value is set, it will be read first.
+
+The default value of `transactionReceiptPollingInterval` is `undefined`.
+
+### [transactionSendTimeout](/api/web3-core/class/Web3Config#transactionSendTimeout)
+The `transactionSendTimeout` option is used to specify how long to wait for the network to return the sent transaction result. Note: If the RPC call times out, the transaction may still be pending or even mined by the network. It is recommended that the pending transactions be checked in such a case.
+
+The default value of `transactionSendTimeout` is 750 seconds (12.5 minutes).
+
+### [transactionConfirmationPollingInterval](/api/web3-core/class/Web3Config#transactionConfirmationPollingInterval)
+The `transactionConfirmationPollingInterval` option is deprecated. Please use [`transactionReceiptPollingInterval`](/guides/web3_config/#transactionreceiptpollinginterval) or [`transactionPollingInterval`](/guides/web3_config/#transactionpollinginterval) instead.
+
+### [blockHeaderTimeout](/api/web3-core/class/Web3Config#blockHeaderTimeout)
+After sending a transaction, Web3 will listen for the appearance of new blocks and proceed with subsequent operations based on the transaction results within them. This option defines the number of seconds Web3 should wait for the appearance of new blocks before reverting to polling to fetch the transaction receipt.
+
+The default value of `blockHeaderTimeout` is 10 seconds.
+
+### [maxListenersWarningThreshold](/api/web3-core/class/Web3Config#maxListenersWarningThreshold)
+The `maxListenersWarningThreshold` is used to set the `maxListeners` property in [`EventEmitter`](/api/web3-utils/class/EventEmitter).
+
+The default value of `maxListenersWarningThreshold` is 100.
+
+### [contractDataInputFill](/api/web3-core/class/Web3Config#contractDataInputFill)
+The `contractDataInputFill` option allows users to specify whether the [`data`](/api/web3/namespace/types#data) or [`input`](/api/web3/namespace/types#input) property (or both properties) should be set to the hash of the method signature and encoded parameters. This will affect the contracts [`send`](/libdocs/Contract#send), [`call`](/libdocs/Contract#call) and [`estimateGas`](/libdocs/Contract#estimategas) methods.
+
+The default value of `contractDataInputFill` is `data`.
+
+#### All available choices for contractDataInputFill:
+```ts
+'data'
+'input'
+'both'
+```
+
+### [defaultNetworkId](/api/web3-core/class/Web3Config#defaultNetworkId)
+Each network has its own [network ID](https://docs.goquorum.consensys.io/concepts/network-and-chain-id). The `defaultNetworkId` option allows users to set the default network ID. If this option is not set, Web3 will fetch the network ID with an RPC request.
+
+The default value of `defaultNetworkId` is `undefined`.
+
+### [defaultChain](/api/web3-core/class/Web3Config#defaultChain)
+The `defaultChain` option is used to set the [`Common`](/api/web3-eth-contract/class/Contract#defaultCommon) `baseChain` property. The value of this option should be consistent with [`defaultCommon.baseChain`](/guides/web3_config/#defaultcommon) if both options are set.
+
+The default value of `defaultChain` is `mainnet`.
+
+#### All available choices for defaultChain:
+```ts
+'goerli'
+'kovan'
+'mainnet'
+'rinkeby'
+'ropsten'
+'sepolia'
+```
+
+### [defaultHardfork](/api/web3-core/class/Web3Config#defaultHardfork)
+The `defaultHardfork` option is used to set the [`Common`](/api/web3-eth-contract/class/Contract#defaultCommon) `hardfork` property. The value of this option should be consistent with [`defaultCommon.hardfork`](/guides/web3_config/#defaultcommon) if both options are set.
+
+The default value of `defaultHardfork` is `london`.
+
+#### All available choices for defaultHardFork:
+```ts
+'chainstart'
+'frontier'
+'homestead'
+'dao'
+'tangerineWhistle'
+'spuriousDragon'
+'byzantium'
+'constantinople'
+'petersburg'
+'istanbul'
+'muirGlacier'
+'berlin'
+'london'
+'altair'
+'arrowGlacier'
+'grayGlacier'
+'bellatrix'
+'merge'
+'capella'
+'sharding'
+```
+
+### [defaultCommon](/api/web3-core/class/Web3Config#defaultCommon)
+The `defaultCommon` option is used to set the [`defaultCommon`](/libdocs/Contract#defaultcommon) value for smart contract transactions. It should be consistent with the [`defaultHardfork`](/guides/web3_config/#defaulthardfork) and [`defaultChain`](/guides/web3_config/#defaultchain) options if they are set.
+
+The default value of `defaultCommon` is `undefined`.
+
+```ts
+import { Web3, Hardfork } from 'web3';
+
+const web3 = new Web3('http://127.0.0.1:7545');
+
+web3.defaultHardfork = 'berlin'
+web3.defaultChain = 'goerli'
+
+web3.defaultCommon = {
+    baseChain: 'goerli',
+    hardfork: 'berlin' as Hardfork,
+    customChain: {
+        networkId: 1,
+        chainId: 1,
+    },
 };
 
+console.log(web3.getContextObject().config);
 ```
-:::info
-The `defaultReturnFormat` can be configured both globally and at the package level:
+
+### [defaultTransactionType](/api/web3-core/class/Web3Config#defaultTransactionType)
+The `defaultTransactionType` option is used to set the transaction type. Transactions with type 0x0 are legacy transactions that use the transaction format that existed before [typed transactions](https://ethereum.org/en/developers/docs/transactions/#typed-transaction-envelope) were introduced in [EIP-2718](https://eips.ethereum.org/EIPS/eip-2718). Transactions with type 0x1 are transactions introduced in [EIP-2930](https://eips.ethereum.org/EIPS/eip-2930). Transactions with type 0x2 are transactions introduced in [EIP-1559](https://eips.ethereum.org/EIPS/eip-1559), included in Ethereum's London fork.
+
+The default value of `defaultTransactionType` is `0x02`.
+
+### [defaultMaxPriorityFeePerGas](/api/web3-core/class/Web3Config#defaultMaxPriorityFeePerGas)
+The `defaultMaxPriorityFeePerGas` option is used to set the [`defaultMaxPriorityFeePerGas`](/api/web3-eth-contract/class/Contract#defaultMaxPriorityFeePerGas) value for [EIP-1559](https://eips.ethereum.org/EIPS/eip-1559) smart contract transactions ([transaction type](#defaulttransactiontype) 0x2).
+
+The default value of `defaultMaxPriorityFeePerGas` is 2500000000 (2.5gwei) in hexstring format.
+
+### [defaultReturnFormat](/api/web3-core/class/Web3Config#defaultReturnFormat)
+The `defaultReturnFormat` option allows users to specify the format in which certain types of data should be returned by default. It is a configuration parameter that can be set at the global level and affects how data is returned across the entire library.
 ```ts
-import { Web3Eth, FMT_NUMBER, FMT_BYTES } from 'web3-eth';
+import { Web3, FMT_NUMBER, FMT_BYTES } from 'web3';
 
-const eth = new Web3Eth()
-eth.defaultReturnFormat = {
+web3.defaultReturnFormat = {
     number: FMT_NUMBER.BIGINT,
     bytes: FMT_BYTES.HEX,
 };
 
 ```
-:::
+
 #### All available choices for numeric data:
 ```ts 
 export enum FMT_NUMBER {
     NUMBER = 'NUMBER_NUMBER',
     HEX = 'NUMBER_HEX',
     STR = 'NUMBER_STR',
     BIGINT = 'NUMBER_BIGINT',
-}
+};
 ```
 #### All available choices for bytes data:     
 ```ts
 export enum FMT_BYTES {
     HEX = 'BYTES_HEX',
     UINT8ARRAY = 'BYTES_UINT8ARRAY',
-}
+};
 ```
diff --git a/packages/web3-core/src/web3_config.ts b/packages/web3-core/src/web3_config.ts
@@ -152,7 +152,7 @@ export abstract class Web3Config
 	 * The `contractDataInputFill` options property will allow you to set the hash of the method signature and encoded parameters to the property
 	 * either `data`, `input` or both within your contract.
 	 * This will affect the contracts send, call and estimateGas methods
-	 * Default is `input`.
+	 * Default is `data`.
 	 */
 	public get contractDataInputFill() {
 		return this.config.contractDataInputFill;
Benchmark suite	Current: `8b435c1`	Previous: `5080e80`	Ratio
`processingTx`	`9078` ops/sec (`±4.67%`)	`8980` ops/sec (`±4.32%`)	`0.99`
`processingContractDeploy`	`39858` ops/sec (`±6.95%`)	`38011` ops/sec (`±6.45%`)	`0.95`
`processingContractMethodSend`	`16111` ops/sec (`±6.62%`)	`15444` ops/sec (`±9.38%`)	`0.96`
`processingContractMethodCall`	`27631` ops/sec (`±7.57%`)	`28258` ops/sec (`±6.66%`)	`1.02`
`abiEncode`	`44291` ops/sec (`±7.06%`)	`43457` ops/sec (`±6.82%`)	`0.98`
`abiDecode`	`31565` ops/sec (`±7.32%`)	`31180` ops/sec (`±8.37%`)	`0.99`
`sign`	`1575` ops/sec (`±1.11%`)	`1518` ops/sec (`±3.09%`)	`0.96`
`verify`	`365` ops/sec (`±2.63%`)	`368` ops/sec (`±0.97%`)	`1.01`