web3-utils

library4.3.3jsnpmunverified

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.

serialization auth-security

npm install web3-utils

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · WEB3-UTILS

web3-utils

serializationjavascriptv4.3.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

toWei

✓ import { toWei } from 'web3-utils'

✗ const { toWei } = require('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

✓ import { isAddress } from 'web3-utils'

✗ 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

✓ import { toBigInt } from 'web3-utils'

✗ import { toBN } 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+.

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}`);

Debug

Known issues

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

affects: >=4.0.0

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

affects: >=4.0.0

gotchaMany 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')`.

affects: >=1.0.0

Errors

Common errors & fixes

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

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.

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')

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.

Upgrade

Version history

4.3.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

31 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/ChainSafe/web3.js ↗

packagehttps://www.npmjs.com/package/web3-utils ↗

homepagehttps://web3js.org ↗