Skip to main content

web3 Utils Migration Guide

Import​

To make use you only import the utility functions which are needed by your app. We encourage the named import for web3-utils package. This change has no impact on the using the namespace Web3.utils or web3.utils. If you still want to import the full utils it can be done as following:

// 1.x
import web3Utils from 'web3-utils';

// 4.x
import * as web3Utils from 'web3-utils';

No BN property​

The web3-utils package no longer includes a BN property for using the the bn.js package for working with (big) numbers. In 4.x, the native JavaScript BigInt type is used.

// 1.x
new Web3.utils.BN(1);

// 4.x
BigInt(4);

Unit conversion functions​

The toWei does not have an optional second parameter. You have to pass the source unit explicitly.

// 1.x
web3.utils.toWei('0.1');

// 4.x
web3.utils.toWei('0.1', 'ether');

Conversion to Hex​

The toHex behave exactly the same in both v1.x and 4.x, except for a string that contains only numbers. In 1.x if a number was provided inside a string like 123 it used to be treated as a number. While in 4.x it will be treated as a string, except if it was prefixed with 0x. For more clarity, check below:

// 1.x
new Web3().utils.toHex(0x1); // returns  0x1
new Web3().utils.toHex('0x1'); // returns  0x1
new Web3().utils.toHex(1); // returns  0x1
new Web3().utils.toHex('1'); // returns  0x1

// 4.x
new Web3().utils.toHex(0x1); // returns  0x1
new Web3().utils.toHex('0x1'); // returns  0x1
new Web3().utils.toHex(1); // returns  0x1
new Web3().utils.toHex('1'); // returns  0x31

Validation functions​

Validation functions has been moved to the new package web3-validator. Actually, you can still import them from web3-util. But they are marked as "deprecated" and you are encouraged to import them from web3-validator.

However, there are changes for the following:

isHex and isHexStrict validation functions​

There is a fix, and some edge-cases-changes for those 2 functions but the overall functionality stayed the same. And here is exactly whet changed:

isHex now returns true for all negative numbers​

isHex('-123'); // in 1.x used to return `false`. But changed in 4.x to return `true`
// `true`

isHex now returns false for an empty string​

isHex(''); // in 1.x used to return `true`. But changed in 4.x to return `false`
// `false`

isHex and isHexStrict now returns false for '-0x'​

isHex('-0x'); // in 1.x used to return `true`. But changed in 4.x to return `false`
// `false`

isHexStrict('-0x'); // in 1.x used to return `true`. But changed in 4.x to return `false`
// `false`

stripHexPrefix method​

In 1.x stripHexPrefix method is located in the web3-utils package, in 4.x this has been moved to web3-eth-accounts

import { stripHexPrefix } from 'web3-eth-accounts';

console.log(stripHexPrefix('0x123')); // "123"

Other functions​

compareBlockNumbers now accepts either both block tags or both block numbers for comparison as parameters. The only exception is comparison of block tag earliest with numbers.

compareBlockNumbers('earliest', 'safe'); // its valid comparison, and it will return `-1`

compareBlockNumbers(8692, 2); // its valid comparison, and it will return `1`

compareBlockNumbers('latest', 500); // in 1.x it used to return `1`, but now it will throw error InvalidBlockError