Web3.js Utility Functions

Common errors

• TypeError: (0 , web3_utils_1.toWei) is not a function

  cause Attempting to import named exports using a CommonJS `require()` statement or incorrect bundling in an ESM-only context.
  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.

• Error: Invalid number value. Value must be a string or BigInt.

  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.
  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.

• TypeError: Cannot read properties of undefined (reading 'toBN')

  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`.
  fix Replace all occurrences of `toBN` with `toBigInt`. Update numerical operations to use native `BigInt` arithmetic rather than `BigNumber.js` methods.

Warnings

• breaking 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.
  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.
• gotcha 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.
  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`.
• gotcha 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.
  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')`.

Install

• npm install web3-utils npm
• yarn add web3-utils yarn
• pnpm add web3-utils pnpm

Imports

• toWei
  wrong:

  const { toWei } = require('web3-utils')

  correct:

  import { toWei } from 'web3-utils'

  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.
• isAddress
  wrong:

  import isAddress from 'web3-utils'

  correct:

  import { isAddress } from 'web3-utils'

  All utility functions are named exports. There is no default export from 'web3-utils'.
• sha3

  import { sha3 } from 'web3-utils'

  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.
• toBigInt
  wrong:

  import { toBN } from 'web3-utils'

  correct:

  import { toBigInt } from 'web3-utils'

  `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+.

Quickstart

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.

import { toWei, fromWei, isAddress, sha3, toBigInt } from 'web3-utils';

// 1. Unit Conversion
const ethValue = '1.5';
const weiValue = toWei(ethValue, 'ether');
console.log(`1.5 Ether in Wei: ${weiValue}`); // Outputs a BigInt

const backToEth = fromWei(weiValue, 'ether');
console.log(`Wei back to Ether: ${backToEth}`); // Outputs a string representation

// 2. Address Validation
const validAddress = '0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B';
const invalidAddress = '0x123invalidAddress';

console.log(`Is '${validAddress}' a valid address? ${isAddress(validAddress)}`);
console.log(`Is '${invalidAddress}' a valid address? ${isAddress(invalidAddress)}`);

// 3. Hashing
const dataToHash = 'Hello Web3!';
const hashedData = sha3(dataToHash);
console.log(`SHA3 hash of '${dataToHash}': ${hashedData}`);

// 4. BigInt Handling (v4+)
const bigNumberString = '1000000000000000000'; // 1 Ether in Wei
const bigIntValue = toBigInt(bigNumberString);
console.log(`Converted to BigInt: ${bigIntValue}, type: ${typeof bigIntValue}`);