Add default return format to the context (#6947)

* add default return format * fix ens tests * add format tests * lint fix * add types and docs * fix * fix * add changelog * add changelog * fix tests * fix * fix * fix * fix * fix changelog * fix default * add estimate gas test * add guide to upgrade from 1.x * fix change log * remove changelogs * fix
web3 · Apr 18, 2024 · 93296c2 · 93296c2 · github-actions · Apr 18, 2024
1 parent 1ab7a6b
commit 93296c2
Show file tree

Hide file tree

Showing 34 changed files with 845 additions and 323 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2120,7 +2120,7 @@ If there are any bugs, improvements, optimizations or any new feature proposal f
 #### web3-eth
 
 -   Ensure provider.supportsSubscriptions exists before watching by subscription (#6440)
--   Fixed param sent to `checkRevertBeforeSending` in `sendSignedTransaction` 
+-   Fixed param sent to `checkRevertBeforeSending` in `sendSignedTransaction`
 -   Fixed `defaultTransactionBuilder` for value issue (#6509)
 
 #### web3-eth-abi
@@ -2129,7 +2129,7 @@ If there are any bugs, improvements, optimizations or any new feature proposal f
 
 #### web3-eth-accounts
 
--   Fixed `recover` function, `v` will be normalized to value 0,1 (#6344) 
+-   Fixed `recover` function, `v` will be normalized to value 0,1 (#6344)
 
 #### web3-providers-http
 
@@ -2252,27 +2252,26 @@ If there are any bugs, improvements, optimizations or any new feature proposal f
 
 #### web3-eth-contract
 
--	Will populate `data` for transactions in contract for metamask provider instead of `input` (#6534)
+-   Will populate `data` for transactions in contract for metamask provider instead of `input` (#6534)
 
 ## [4.3.0]
 
 ### Changed
 
 #### web3-core
 
--	Web3config `contractDataInputFill` has been defaulted to `data`, instead of `input`. (#6622)
+-   Web3config `contractDataInputFill` has been defaulted to `data`, instead of `input`. (#6622)
 
 #### web3-eth-contracts
 
--	By default, contracts will fill `data` instead of `input` within method calls (#6622)
+-   By default, contracts will fill `data` instead of `input` within method calls (#6622)
 
 ### Added
 
-
 #### web3-utils
 
 -   `SocketProvider` now contains public function `getPendingRequestQueueSize`, `getSentRequestsQueueSize` and `clearQueues` (#6479)
--   Added `safeDisconnect` as a `SocketProvider` method to disconnect only when request queue size and send request queue size is 0 (#6479) 
+-   Added `safeDisconnect` as a `SocketProvider` method to disconnect only when request queue size and send request queue size is 0 (#6479)
 -   Add `isContractInitOptions` method (#6555)
 
 #### web3
@@ -2305,7 +2304,7 @@ If there are any bugs, improvements, optimizations or any new feature proposal f
 
 #### web3-eth-contract
 
--	Allow the `deploy` function to accept parameters, even when no ABI was provided to the `Contract`(#6635)
+-   Allow the `deploy` function to accept parameters, even when no ABI was provided to the `Contract`(#6635)
 
 #### web3
 
@@ -2324,8 +2323,8 @@ If there are any bugs, improvements, optimizations or any new feature proposal f
 
 #### web3-eth-contract
 
--	Fix and error that happen when trying to get past events by calling `contract.getPastEvents` or `contract.events.allEvents()`, if there is no matching events. (#6647)
--	Fixed: The Contract is not using the context wallet passed if context was passed at constructor. (#6661)
+-   Fix and error that happen when trying to get past events by calling `contract.getPastEvents` or `contract.events.allEvents()`, if there is no matching events. (#6647)
+-   Fixed: The Contract is not using the context wallet passed if context was passed at constructor. (#6661)
 
 #### web3-utils
 
@@ -2347,7 +2346,7 @@ If there are any bugs, improvements, optimizations or any new feature proposal f
 
 -   Adds missing exported type `AbiItem` from 1.x to v4 for compatabiltiy (#6678)
 
-### Changed 
+### Changed
 
 #### web3
 
@@ -2359,7 +2358,7 @@ If there are any bugs, improvements, optimizations or any new feature proposal f
 
 #### web3
 
--   Added EIP-6963 utility function `requestEIP6963Providers` for multi provider discovery 
+-   Added EIP-6963 utility function `requestEIP6963Providers` for multi provider discovery
 
 #### web3-eth
 
@@ -2393,17 +2392,17 @@ If there are any bugs, improvements, optimizations or any new feature proposal f
 
 #### web3-eth-ens
 
-- Added function getText and getName in ENS and resolver classes (#6914)
+-   Added function getText and getName in ENS and resolver classes (#6914)
 
 ### fixed
 
 #### web3-validator
 
-- Multi-dimensional arrays(with a fix length) are now handled properly when parsing ABIs (#6798)
+-   Multi-dimensional arrays(with a fix length) are now handled properly when parsing ABIs (#6798)
 
 #### web3-utils
 
-- fixed erroneous parsing of big numbers in the `toNumber(...)` function (#6880)
+-   fixed erroneous parsing of big numbers in the `toNumber(...)` function (#6880)
 
 ## [4.8.0]
 
@@ -2421,30 +2420,60 @@ If there are any bugs, improvements, optimizations or any new feature proposal f
 
 #### web3-eth-contract
 
--	Fix an issue with smart contract function overloading (#6922)
+-   Fix an issue with smart contract function overloading (#6922)
 
 #### web3-utils
 
-- fixed toHex incorrectly hexing Uint8Arrays and Buffer (#6957)
-- fixed isUint8Array not returning true for Buffer (#6957)
-
+-   fixed toHex incorrectly hexing Uint8Arrays and Buffer (#6957)
+-   fixed isUint8Array not returning true for Buffer (#6957)
 
 ### Added
 
 #### web3-eth-contract
 
--	Added a console warning in case of an ambiguous call to a solidity method with parameter overloading (#6942)
--	Added contract.deploy(...).decodeData(...) and contract.decodeMethodData(...) that decode data based on the ABI (#6950)
+-   Added a console warning in case of an ambiguous call to a solidity method with parameter overloading (#6942)
+-   Added contract.deploy(...).decodeData(...) and contract.decodeMethodData(...) that decode data based on the ABI (#6950)
 
 #### web3-eth
 
--   method `getBlock` now includes properties of eip 4844, 4895, 4788 when returning block (#6933) 
+-   method `getBlock` now includes properties of eip 4844, 4895, 4788 when returning block (#6933)
 -   update type `withdrawalsSchema`, `blockSchema` and `blockHeaderSchema` schemas to include properties of eip 4844, 4895, 4788 (#6933)
 
-
 #### web3-types
 
 -   Added `signature` to type `AbiFunctionFragment` (#6922)
 -   update type `Withdrawals`, `block` and `BlockHeaderOutput` to include properties of eip 4844, 4895, 4788 (#6933)
 
 ## [Unreleased]
+
+### Added
+
+#### web3-core
+
+-   `defaultReturnFormat` was added to the configuration options. (#6947)
+
+#### web3-eth
+
+-   `defaultReturnFormat` was added to all methods that have `ReturnType` param. (#6947)
+
+#### web3-eth-contract
+
+-   `defaultReturnFormat` was added to all methods that have `ReturnType` param. (#6947)
+
+#### web3-eth-ens
+
+-   `defaultReturnFormat` was added to all methods that have `ReturnType` param. (#6947)
+
+#### web3-net
+
+-   `defaultReturnFormat` was added to all methods that have `ReturnType` param. (#6947)
+
+#### web3-types
+
+-   Added `signature` to type `AbiFunctionFragment` (#6922)
+-   update type `Withdrawals`, `block` and `BlockHeaderOutput` to include properties of eip 4844, 4895, 4788 (#6933)
+
+### Fixed
+
+#### web3-validator
+
diff --git a/docs/docs/guides/web3_config/index.md b/docs/docs/guides/web3_config/index.md
@@ -27,6 +27,7 @@ There is list of configuration params that can be set for modifying behavior of
 - [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)  
 
 ## Global level Config
 
@@ -198,4 +199,46 @@ console.log(web3.getContextObject().config)
   transactionPollingTimeout: 750000,
   ...
 */
-```
+```
+
+
+### 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.
+```ts
+import { Web3, FMT_NUMBER, FMT_BYTES } from 'web3';
+
+web3.defaultReturnFormat = {
+    number: FMT_NUMBER.BIGINT,
+    bytes: FMT_BYTES.HEX,
+};
+
+```
+:::info
+The `defaultReturnFormat` can be configured both globally and at the package level:
+```ts
+import { Web3Eth, FMT_NUMBER, FMT_BYTES } from 'web3-eth';
+
+const eth = new Web3Eth()
+eth.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/docs/docs/guides/web3_upgrade_guide/1.x/index.md b/docs/docs/guides/web3_upgrade_guide/1.x/index.md
@@ -79,6 +79,9 @@ It will not have:
 -   `givenProvider` default value is `undefined` instead of `null`
 -   `currentProvider` default value is `undefined` instead of `null` (if web3 is instantiated without a provider)
 
+:::warning
+In version 4.x, all numbers return as BigInt instead of string or number, which constitutes a breaking change for users accustomed to handling numbers as string or number in their code. For instance, web3.eth.getBalance will now return BigInt instead of string or number. If you wish to retain numbers as number or string, you can refer to [this guide](/guides/web3_config/#defaultreturnformat) on how to set returning types in web3js 4.x.
+:::
 ### Web3 BatchRequest
 
 ```ts

diff --git a/packages/web3-core/CHANGELOG.md b/packages/web3-core/CHANGELOG.md
@@ -207,4 +207,7 @@ Documentation:
 
 -	Web3config `contractDataInputFill` has been defaulted to `data`, istead of `input`. (#6622)
 
-## [Unreleased]
+## [Unreleased]
+
+### Added
+-   `defaultReturnFormat` was added to the configuration options. (#6947)
diff --git a/packages/web3-core/src/web3_config.ts b/packages/web3-core/src/web3_config.ts
@@ -15,7 +15,14 @@ You should have received a copy of the GNU Lesser General Public License
 along with web3.js.  If not, see <http://www.gnu.org/licenses/>.
 */
 
-import { Numbers, HexString, BlockNumberOrTag, Common } from 'web3-types';
+import {
+	Numbers,
+	HexString,
+	BlockNumberOrTag,
+	Common,
+	DEFAULT_RETURN_FORMAT,
+	DataFormat,
+} from 'web3-types';
 import { ConfigHardforkMismatchError, ConfigChainMismatchError } from 'web3-errors';
 import { isNullish, toHex } from 'web3-utils';
 import { TransactionTypeParser } from './types.js';
@@ -52,6 +59,7 @@ export interface Web3ConfigOptions {
 	};
 	transactionBuilder?: TransactionBuilder;
 	transactionTypeParser?: TransactionTypeParser;
+	defaultReturnFormat: DataFormat;
 }
 
 type ConfigEvent<T, P extends keyof T = keyof T> = P extends unknown
@@ -93,6 +101,7 @@ export abstract class Web3Config
 		},
 		transactionBuilder: undefined,
 		transactionTypeParser: undefined,
+		defaultReturnFormat: DEFAULT_RETURN_FORMAT,
 	};
 
 	public constructor(options?: Partial<Web3ConfigOptions>) {
@@ -348,6 +357,15 @@ export abstract class Web3Config
 		this.config.maxListenersWarningThreshold = val;
 	}
 
+	public get defaultReturnFormat() {
+		return this.config.defaultReturnFormat;
+	}
+	public set defaultReturnFormat(val) {
+		this._triggerConfigChange('defaultReturnFormat', val);
+
+		this.config.defaultReturnFormat = val;
+	}
+
 	public get defaultNetworkId() {
 		return this.config.defaultNetworkId;
 	}

diff --git a/packages/web3-core/test/unit/__snapshots__/web3_context.test.ts.snap b/packages/web3-core/test/unit/__snapshots__/web3_context.test.ts.snap
@@ -13,6 +13,10 @@ exports[`Web3Context getContextObject should return correct context object 1`] =
     "defaultHardfork": "london",
     "defaultMaxPriorityFeePerGas": "0x9502f900",
     "defaultNetworkId": undefined,
+    "defaultReturnFormat": {
+      "bytes": "BYTES_HEX",
+      "number": "NUMBER_BIGINT",
+    },
     "defaultTransactionType": "0x2",
     "enableExperimentalFeatures": {
       "useRpcCallSpecification": false,

diff --git a/packages/web3-core/test/unit/web3_config.test.ts b/packages/web3-core/test/unit/web3_config.test.ts
@@ -16,6 +16,7 @@ along with web3.js.  If not, see <http://www.gnu.org/licenses/>.
 */
 
 import { toHex } from 'web3-utils';
+import { DEFAULT_RETURN_FORMAT } from 'web3-types';
 import { Web3Config, Web3ConfigEvent } from '../../src/web3_config';
 
 class MyConfigObject extends Web3Config {}
@@ -44,6 +45,7 @@ const defaultConfig = {
 	transactionConfirmationPollingInterval: undefined,
 	defaultTransactionType: '0x2',
 	defaultMaxPriorityFeePerGas: toHex(2500000000),
+	defaultReturnFormat: DEFAULT_RETURN_FORMAT,
 };
 const setValue = {
 	string: 'newValue',

diff --git a/packages/web3-eth-accounts/test/config/setup.js b/packages/web3-eth-accounts/test/config/setup.js
@@ -23,6 +23,6 @@ require('jest-extended');
 
 process.env.NODE_ENV = 'test';
 
-const jestTimeout = 10000;
+const jestTimeout = 15000;
 
 jest.setTimeout(jestTimeout);
diff --git a/packages/web3-eth-contract/CHANGELOG.md b/packages/web3-eth-contract/CHANGELOG.md
@@ -328,7 +328,6 @@ Documentation:
 -   Added `dataInputFill` as a ContractInitOption, allowing users to have the choice using property `data`, `input` or `both` for contract methods to be sent to the RPC provider. (#6355)
 -   Added to `Web3Config` property `contractDataInputFill` allowing users to have the choice using property `data`, `input` or `both` for contract methods to be sent to the RPC provider when creating contracts. (#6377)
 
-
 ## [4.1.1]
 
 ### Changed
@@ -345,24 +344,24 @@ Documentation:
 
 ### Fixed
 
--	Will populate `data` for transactions in contract for metamask provider instead of `input` (#6534)
+-   Will populate `data` for transactions in contract for metamask provider instead of `input` (#6534)
 
 ## [4.1.4]
 
 ### Changed
 
--	By default, contracts will fill `data` instead of `input` within method calls (#6622)
+-   By default, contracts will fill `data` instead of `input` within method calls (#6622)
 
 ## [4.2.0]
 
 ### Changed
 
--	Allow the `deploy` function to accept parameters, even when no ABI was provided to the `Contract`(#6635)
+-   Allow the `deploy` function to accept parameters, even when no ABI was provided to the `Contract`(#6635)
 
 ### Fixed
 
--	Fix and error that happen when trying to get past events by calling `contract.getPastEvents` or `contract.events.allEvents()`, if there is no matching events. (#6647)
--	Fixed: The Contract is not using the context wallet passed if context was passed at constructor. (#6661)
+-   Fix and error that happen when trying to get past events by calling `contract.getPastEvents` or `contract.events.allEvents()`, if there is no matching events. (#6647)
+-   Fixed: The Contract is not using the context wallet passed if context was passed at constructor. (#6661)
 
 ## [4.3.0]
 
@@ -374,11 +373,15 @@ Documentation:
 
 ### Fixed
 
--	Fix an issue with smart contract function overloading (#6922)
+-   Fix an issue with smart contract function overloading (#6922)
 
 ### Added
 
--	Added a console warning in case of an ambiguous call to a solidity method with parameter overloading (#6942)
--	Added contract.deploy(...).decodeData(...) and contract.decodeMethodData(...) that decode data based on the ABI (#6950)
+-   Added a console warning in case of an ambiguous call to a solidity method with parameter overloading (#6942)
+-   Added contract.deploy(...).decodeData(...) and contract.decodeMethodData(...) that decode data based on the ABI (#6950)
 
 ## [Unreleased]
+
+### Added
+
+-   `defaultReturnFormat` was added to all methods that have `ReturnType` param. (#6947)
Benchmark suite	Current: `93296c2`	Previous: `6c075db`	Ratio
`processingTx`	`8971` ops/sec (`±4.04%`)	`9301` ops/sec (`±4.81%`)	`1.04`
`processingContractDeploy`	`38494` ops/sec (`±8.81%`)	`39129` ops/sec (`±7.62%`)	`1.02`
`processingContractMethodSend`	`18292` ops/sec (`±8.93%`)	`19443` ops/sec (`±5.19%`)	`1.06`
`processingContractMethodCall`	`37274` ops/sec (`±6.63%`)	`38971` ops/sec (`±6.34%`)	`1.05`
`abiEncode`	`41910` ops/sec (`±7.74%`)	`44252` ops/sec (`±6.92%`)	`1.06`
`abiDecode`	`28672` ops/sec (`±8.35%`)	`30419` ops/sec (`±8.89%`)	`1.06`
`sign`	`1529` ops/sec (`±1.11%`)	`1656` ops/sec (`±4.08%`)	`1.08`
`verify`	`365` ops/sec (`±0.52%`)	`373` ops/sec (`±0.78%`)	`1.02`