{"id":12656,"library":"web3-utils","title":"Web3.js Utility Functions","description":"web3-utils is a core package within the web3.js ecosystem, providing a collection of essential utility functions for Ethereum dApp development. These utilities cover common tasks such as converting between different Ether units (e.g., Ether to Wei), validating Ethereum addresses, cryptographic hashing (like SHA3), and handling large numbers. As of the provided information, the package version is 4.3.3, though recent releases indicate active development up to v4.16.0 within the broader web3.js monorepo. It maintains a frequent release cadence, often aligning with fixes and features across the web3.js suite. A key differentiator is its tight integration and API consistency with the rest of the web3.js library, making it the de-facto choice for projects built on web3.js. It ships with full TypeScript support, ensuring type safety for modern JavaScript projects.","status":"active","version":"4.3.3","language":"javascript","source_language":"en","source_url":"https://github.com/ChainSafe/web3.js","tags":["javascript","typescript"],"install":[{"cmd":"npm install web3-utils","lang":"bash","label":"npm"},{"cmd":"yarn add web3-utils","lang":"bash","label":"yarn"},{"cmd":"pnpm add web3-utils","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"web3-utils is primarily designed for ESM usage since web3.js v4. While CommonJS might work in some environments, ESM is the recommended and type-safe approach. `toWei` is used for converting values to Wei, accepting a string or BigInt value.","wrong":"const { toWei } = require('web3-utils')","symbol":"toWei","correct":"import { toWei } from 'web3-utils'"},{"note":"All utility functions are named exports. There is no default export from 'web3-utils'.","wrong":"import isAddress from 'web3-utils'","symbol":"isAddress","correct":"import { isAddress } from 'web3-utils'"},{"note":"Used for computing the Keccak-256 hash of a string. Ensure input is a string or Buffer. Since v4, BigInts are widely used for numerical operations.","symbol":"sha3","correct":"import { sha3 } from 'web3-utils'"},{"note":"`toBigInt` is the v4 equivalent of `toBN` from web3.js v1.x. All numerical operations in v4, including those in web3-utils, now primarily use native JavaScript `BigInt` type instead of `BigNumber.js` instances. Using `toBN` will result in errors or unexpected behavior in v4+.","wrong":"import { toBN } from 'web3-utils'","symbol":"toBigInt","correct":"import { toBigInt } from 'web3-utils'"}],"quickstart":{"code":"import { toWei, fromWei, isAddress, sha3, toBigInt } from 'web3-utils';\n\n// 1. Unit Conversion\nconst ethValue = '1.5';\nconst weiValue = toWei(ethValue, 'ether');\nconsole.log(`1.5 Ether in Wei: ${weiValue}`); // Outputs a BigInt\n\nconst backToEth = fromWei(weiValue, 'ether');\nconsole.log(`Wei back to Ether: ${backToEth}`); // Outputs a string representation\n\n// 2. Address Validation\nconst validAddress = '0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B';\nconst invalidAddress = '0x123invalidAddress';\n\nconsole.log(`Is '${validAddress}' a valid address? ${isAddress(validAddress)}`);\nconsole.log(`Is '${invalidAddress}' a valid address? ${isAddress(invalidAddress)}`);\n\n// 3. Hashing\nconst dataToHash = 'Hello Web3!';\nconst hashedData = sha3(dataToHash);\nconsole.log(`SHA3 hash of '${dataToHash}': ${hashedData}`);\n\n// 4. BigInt Handling (v4+)\nconst bigNumberString = '1000000000000000000'; // 1 Ether in Wei\nconst bigIntValue = toBigInt(bigNumberString);\nconsole.log(`Converted to BigInt: ${bigIntValue}, type: ${typeof bigIntValue}`);\n","lang":"typescript","description":"This quickstart demonstrates common web3-utils functions: converting between Ether and Wei, validating an Ethereum address, calculating a SHA3 hash, and using `toBigInt` for large number handling."},"warnings":[{"fix":"Migrate all code that manipulates large numbers to use native `BigInt` types. Replace `toBN()` with `toBigInt()`, and adapt arithmetic operations (e.g., `+`, `-`, `*`, `/`) to work with `BigInt` (e.g., `10n + 5n`). Ensure all number-like inputs are explicitly converted to `BigInt` where expected or passed as strings.","message":"web3.js v4 (and consequently web3-utils) has fundamentally shifted from using `BigNumber.js` library instances to native JavaScript `BigInt` for all large number operations. This is a major breaking change from web3.js v1.x. Functions like `toBN` are replaced by `toBigInt` and methods like `_sendPendingRequests` now catch errors differently.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Always install all `web3.js` related packages from the same major version to ensure compatibility. For example, if you are using `web3@4.x.x`, ensure all sub-packages like `web3-utils`, `web3-eth`, `web3-eth-contract` are also `4.x.x`.","message":"web3-utils is part of the web3.js monorepo. Using a version of `web3-utils` that is significantly different from other `web3-*` packages (e.g., `web3-eth`, `web3-eth-accounts`) can lead to runtime errors or unexpected behavior due to API inconsistencies or internal type mismatches, as hinted by `TransactionFactory.registerTransactionType` fixes in v4.12.0/v4.12.1.","severity":"gotcha","affected_versions":">=4.0.0"},{"fix":"Always pass numerical values as strings or native `BigInt`s to functions that operate on large numbers. Example: `toWei('1.0', 'ether')` or `toWei(1000000000000000000n, 'wei')`.","message":"Many web3-utils functions that deal with numerical inputs (e.g., `toWei`, `fromWei`, `padLeft`, `padRight`) expect numeric values to be passed as strings or BigInts for precision. Passing a standard JavaScript `number` can lead to precision loss for very large or very small values, or even throw 'Invalid number value' errors.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure you are using `import { toWei } from 'web3-utils'` for named ESM imports. If in a CommonJS environment that doesn't transpile ESM, consider using a bundler or ensuring your Node.js version supports ESM, or downgrade to web3.js v1.x if CJS is strictly required and cannot be transpiled.","cause":"Attempting to import named exports using a CommonJS `require()` statement or incorrect bundling in an ESM-only context.","error":"TypeError: (0 , web3_utils_1.toWei) is not a function"},{"fix":"Convert the number to a string (e.g., `value.toString()`) or explicitly cast to a `BigInt` (e.g., `BigInt(value)`) before passing it to the utility function.","cause":"Passing a standard JavaScript `number` type directly to a web3-utils function (e.g., `toWei`, `toBigInt`) that expects a string or `BigInt` for precise numerical handling.","error":"Error: Invalid number value. Value must be a string or BigInt."},{"fix":"Replace all occurrences of `toBN` with `toBigInt`. Update numerical operations to use native `BigInt` arithmetic rather than `BigNumber.js` methods.","cause":"Attempting to use the `toBN` function in web3-utils v4+. This function was removed in favor of `toBigInt` when web3.js migrated to native `BigInt`.","error":"TypeError: Cannot read properties of undefined (reading 'toBN')"}],"ecosystem":"npm"}