Utils
This package provides utility functions for Ethereum dapps and other web3.js packages.
For using Utils functions, first install Web3 package using npm i web3 or yarn add web3.
After that, Web3 Utils functions will be available as mentioned below.
import { Web3 } from 'web3';
const web3 = new Web3();
const value = web3.utils.fromWei("1", "ether")
For using individual package install web3-utils package using npm i web3-utils or yarn add web3-utils and only import required functions.
This is more efficient approach for building lightweight applications.
import { fromWei, soliditySha3Raw } from 'web3-utils';
console.log(fromWei("1", "ether"));
console.log(soliditySha3Raw({ type: "string", value: "helloworld" }))
Functions
asciiToHex
▸ asciiToHex(str): string
Should be called to get hex representation (prefixed by 0x) of ascii string
Parameters
| Name | Type | Description |
|---|---|---|
str | string | String to be converted to hex |
Returns
string
- Hex string
Example
console.log(web3.utils.asciiToHex('Hello World'));
> 0x48656c6c6f20576f726c64
bytesToHex
▸ bytesToHex(bytes): string
Convert a byte array to a hex string
Parameters
| Name | Type | Description |
|---|---|---|
bytes | Bytes | Byte array to be converted |
Returns
string
- The hex string representation of the input byte array
Example
console.log(web3.utils.bytesToHex(new Uint8Array([72, 12])));
> "0x480c"
___
### bytesToUint8Array
▸ **bytesToUint8Array**(`data`): `Uint8Array`
Convert a value from bytes to Uint8Array
#### Parameters
| Name | Type | Description |
| :------ | :------ | :------ |
| `data` | `Bytes` | Data to be converted |
#### Returns
`Uint8Array`
- The Uint8Array representation of the input data
**`Example`**
```ts
console.log(web3.utils.bytesToUint8Array("0xab")));
> Uint8Array(1) [ 171 ]
checkAddressCheckSum
▸ checkAddressCheckSum(data): boolean
Checks the checksum of a given address. Will also return false on non-checksum addresses.
Parameters
| Name | Type |
|---|---|
data | string |
Returns
boolean
Deprecated
Will be removed in next release. Please use web3-validator package instead.
compareBlockNumbers
▸ compareBlockNumbers(blockA, blockB): 0 | 1 | -1
Compares between block A and block B
Parameters
| Name | Type | Description |
|---|---|---|
blockA | BlockNumberOrTag | Block number or string |
blockB | BlockNumberOrTag | Block number or string |
Returns
0 | 1 | -1
- Returns -1 if a < b, returns 1 if a > b and returns 0 if a == b
Example
console.log(web3.utils.compareBlockNumbers('latest', 'pending'));
> -1
console.log(web3.utils.compareBlockNumbers(12, 11));
> 1
encodePacked
▸ encodePacked(...values): string
Encode packed arguments to a hexstring
Parameters
| Name | Type |
|---|---|
...values | Sha3Input[] |
Returns
string
fromAscii
▸ fromAscii(str): string
Parameters
| Name | Type |
|---|---|
str | string |
Returns
string
Alias
asciiToHex
fromDecimal
▸ fromDecimal(value, hexstrict?): string
Converts value to it's hex representation
Parameters
| Name | Type |
|---|---|
value | Numbers |
hexstrict? | boolean |
Returns
string
Alias
numberToHex
fromTwosComplement
▸ fromTwosComplement(value, nibbleWidth?): number | bigint
Converts the twos complement into a decimal number or big int.
Parameters
| Name | Type | Default value | Description |
|---|---|---|---|
value | Numbers | undefined | The value to be converted. |
nibbleWidth | number | 64 | The nibble width of the hex string (default is 64). |
Returns
number | bigint
The decimal number or big int.
Example
console.log(web3.utils.fromTwosComplement('0x0000000000000000000000000000000d', 32'));
> 13
console.log(web3.utils.fromTwosComplement('0x00000000000000000020000000000000', 32));
> 9007199254740992n
fromUtf8
▸ fromUtf8(str): string
Parameters
| Name | Type |
|---|---|
str | string |
Returns
string
Alias
utf8ToHex
fromWei
▸ fromWei(number, unit): string
Takes a number of wei and converts it to any other ether unit.
Parameters
| Name | Type | Description |
|---|---|---|
number | Numbers | The value in wei |
unit | number | "noether" | "wei" | "kwei" | "Kwei" | "babbage" | "femtoether" | "mwei" | "Mwei" | "lovelace" | "picoether" | "gwei" | "Gwei" | "shannon" | "nanoether" | "nano" | "szabo" | "microether" | "micro" | "finney" | "milliether" | "milli" | "ether" | "kether" | "grand" | "mether" | "gether" | "tether" | The unit to convert to |
Returns
string
- Returns the converted value in the given unit
Example
console.log(web3.utils.fromWei("1", "ether"));
> 0.000000000000000001
console.log(web3.utils.fromWei("1", "shannon"));
> 0.000000001
getStorageSlotNumForLongString
▸ getStorageSlotNumForLongString(mainSlotNumber): undefined | string
Get slot number for storage long string in contract. Basically for getStorage method returns slotNumber where will data placed
Parameters
| Name | Type | Description |
|---|---|---|
mainSlotNumber | string | number | the slot number where will be stored hash of long string |
Returns
undefined | string
- the slot number where will be stored long string
hexToAscii
▸ hexToAscii(str): string
Should be called to get ascii from it's hex representation
Parameters
| Name | Type | Description |
|---|---|---|
str | string | Hex string to be converted to ascii |
Returns
string
- Ascii string
Example
console.log(web3.utils.hexToAscii('0x48656c6c6f20576f726c64'));
> Hello World
hexToBytes
▸ hexToBytes(bytes): Uint8Array
Convert a hex string to a byte array
Parameters
| Name | Type |
|---|---|
bytes | string |
Returns
Uint8Array
- The byte array representation of the input hex string
Example
console.log(web3.utils.hexToBytes('0x74657374'));
> Uint8Array(4) [ 116, 101, 115, 116 ]
hexToNumber
▸ hexToNumber(value): number | bigint
Converts value to it's number representation
Parameters
| Name | Type | Description |
|---|---|---|
value | string | Hex string to be converted |
Returns
number | bigint
- The number representation of the input value
Example
conoslle.log(web3.utils.hexToNumber('0xa'));
> 10
hexToNumberString
▸ hexToNumberString(data): string
Converts value to it's decimal representation in string
Parameters
| Name | Type |
|---|---|
data | string |
Returns
string
- The decimal representation of the input value
Example
console.log(web3.utils.hexToNumberString('0xa'));
> "10"
hexToString
▸ hexToString(str): string
Parameters
| Name | Type |
|---|---|
str | string |
Returns
string
Alias
hexToUtf8
hexToUtf8
▸ hexToUtf8(str): string
Should be called to get utf8 from it's hex representation
Parameters
| Name | Type | Description |
|---|---|---|
str | string | Hex string to be converted |
Returns
string
- Utf8 string
Example
console.log(web3.utils.hexToUtf8('0x48656c6c6f20576f726c64'));
> Hello World
isAddress
▸ isAddress(value, checkChecksum?): boolean
Checks if a given string is a valid Ethereum address. It will also check the checksum, if the address has upper and lowercase letters.
Parameters
| Name | Type |
|---|---|
value | ValidInputTypes |
checkChecksum? | boolean |
Returns
boolean
Deprecated
Will be removed in next release. Please use web3-validator package instead.
isBloom
▸ isBloom(bloom): boolean
Returns true if the bloom is a valid bloom https://github.com/joshstevens19/ethereum-bloom-filters/blob/fbeb47b70b46243c3963fe1c2988d7461ef17236/src/index.ts#L7
Parameters
| Name | Type |
|---|---|
bloom | ValidInputTypes |
Returns
boolean
Deprecated
Will be removed in next release. Please use web3-validator package instead.
isContractAddressInBloom
▸ isContractAddressInBloom(bloom, contractAddress): boolean
Returns true if the contract address is part of the given bloom. note: false positives are possible.
Parameters
| Name | Type |
|---|---|
bloom | string |
contractAddress | string |
Returns
boolean
Deprecated
Will be removed in next release. Please use web3-validator package instead.
isHex
▸ isHex(hex): boolean
returns true if input is a hexstring, number or bigint
Parameters
| Name | Type |
|---|---|
hex | ValidInputTypes |
Returns
boolean
Deprecated
Will be removed in next release. Please use web3-validator package instead.
isHexStrict
▸ isHexStrict(hex): boolean
Parameters
| Name | Type |
|---|---|
hex | ValidInputTypes |
Returns
boolean
Deprecated
Will be removed in next release. Please use web3-validator package instead.
isInBloom
▸ isInBloom(bloom, value): boolean
Returns true if the value is part of the given bloom note: false positives are possible.
Parameters
| Name | Type |
|---|---|
bloom | string |
value | string | Uint8Array |
Returns
boolean
Deprecated
Will be removed in next release. Please use web3-validator package instead.
isTopic
▸ isTopic(topic): boolean
Checks if its a valid topic
Parameters
| Name | Type |
|---|---|
topic | string |
Returns
boolean
Deprecated
Will be removed in next release. Please use web3-validator package instead.
isTopicInBloom
▸ isTopicInBloom(bloom, topic): boolean
Returns true if the topic is part of the given bloom. note: false positives are possible.
Parameters
| Name | Type |
|---|---|
bloom | string |
topic | string |
Returns
boolean
Deprecated
Will be removed in next release. Please use web3-validator package instead.
isUserEthereumAddressInBloom
▸ isUserEthereumAddressInBloom(bloom, ethereumAddress): boolean
Returns true if the ethereum users address is part of the given bloom note: false positives are possible.
Parameters
| Name | Type |
|---|---|
bloom | string |
ethereumAddress | string |
Returns
boolean
Deprecated
Will be removed in next release. Please use web3-validator package instead.
keccak256Wrapper
▸ keccak256Wrapper(data): string
A wrapper for ethereum-cryptography/keccak256 to allow hashing a string and a bigint in addition to UInt8Array
Parameters
| Name | Type | Description |
|---|---|---|
data | string | number | bigint | Uint8Array | readonly number[] | the input to hash |
Returns
string
- the Keccak-256 hash of the input
Example
console.log(web3.utils.keccak256Wrapper('web3.js'));
> 0x63667efb1961039c9bb0d6ea7a5abdd223a3aca7daa5044ad894226e1f83919a
console.log(web3.utils.keccak256Wrapper(1));
> 0xc89efdaa54c0f20c7adf612882df0950f5a951637e0307cdcb4c672f298b8bc6
console.log(web3.utils.keccak256Wrapper(0xaf12fd));
> 0x358640fd4719fa923525d74ab5ae80a594301aba5543e3492b052bf4598b794c
leftPad
▸ leftPad(value, characterAmount, sign?): string
Adds a padding on the left of a string, if value is a integer or bigInt will be converted to a hex string.
Parameters
| Name | Type | Default value |
|---|---|---|
value | Numbers | undefined |
characterAmount | number | undefined |
sign | string | '0' |
Returns
string
Alias
padLeft
numberToHex
▸ numberToHex(value, hexstrict?): string
Converts value to it's hex representation
Parameters
| Name | Type | Description |
|---|---|---|
value | Numbers | Value to be converted |
hexstrict? | boolean | Add padding to converted value if odd, to make it hexstrict |
Returns
string
- The hex representation of the input value
Example
console.log(web3.utils.numberToHex(10));
> "0xa"
padLeft
▸ padLeft(value, characterAmount, sign?): string
Adds a padding on the left of a string, if value is a integer or bigInt will be converted to a hex string.
Parameters
| Name | Type | Default value | Description |
|---|---|---|---|
value | Numbers | undefined | The value to be padded. |
characterAmount | number | undefined | The amount of characters the string should have. |
sign | string | '0' | The sign to be added (default is 0). |
Returns
string
The padded string.
Example
console.log(web3.utils.padLeft('0x123', 10));
>0x0000000123
padRight
▸ padRight(value, characterAmount, sign?): string
Adds a padding on the right of a string, if value is a integer or bigInt will be converted to a hex string.
Parameters
| Name | Type | Default value | Description |
|---|---|---|---|
value | Numbers | undefined | The value to be padded. |
characterAmount | number | undefined | The amount of characters the string should have. |
sign | string | '0' | The sign to be added (default is 0). |
Returns
string
The padded string.
Example
console.log(web3.utils.padRight('0x123', 10));
> 0x1230000000
console.log(web3.utils.padRight('0x123', 10, '1'));
> 0x1231111111
processSolidityEncodePackedArgs
▸ processSolidityEncodePackedArgs(arg): string
returns a string of the tightly packed value given based on the type
Parameters
| Name | Type | Description |
|---|---|---|
arg | Sha3Input | the input to return the tightly packed value |
Returns
string
- the tightly packed value
randomBytes
▸ randomBytes(size): Uint8Array
Returns a random byte array by the given bytes size
Parameters
| Name | Type | Description |
|---|---|---|
size | number | The size of the random byte array returned |
Returns
Uint8Array
- random byte array
Example
console.log(web3.utils.randomBytes(32));
> Uint8Array(32) [
93, 172, 226, 32, 33, 176, 156, 156,
182, 30, 240, 2, 69, 96, 174, 197,
33, 136, 194, 241, 197, 156, 110, 111,
66, 87, 17, 88, 67, 48, 245, 183
]
randomHex
▸ randomHex(byteSize): string
Returns a random hex string by the given bytes size
Parameters
| Name | Type | Description |
|---|---|---|
byteSize | number | The size of the random hex string returned |
Returns
string
- random hex string
console.log(web3.utils.randomHex(32));
> 0x139f5b88b72a25eab053d3b57fe1f8a9dbc62a526b1cb1774d0d7db1c3e7ce9e
rightPad
▸ rightPad(value, characterAmount, sign?): string
Adds a padding on the right of a string, if value is a integer or bigInt will be converted to a hex string.
Parameters
| Name | Type | Default value |
|---|---|---|
value | Numbers | undefined |
characterAmount | number | undefined |
sign | string | '0' |
Returns
string
Alias
padRight
sha3
▸ sha3(data): undefined | string
computes the Keccak-256 hash of the input and returns a hexstring
Parameters
| Name | Type | Description |
|---|---|---|
data | Bytes | the input to hash |
Returns
undefined | string
- the Keccak-256 hash of the input
Example
console.log(web3.utils.sha3('web3.js'));
> 0x63667efb1961039c9bb0d6ea7a5abdd223a3aca7daa5044ad894226e1f83919a
console.log(web3.utils.sha3(''));
> undefined
sha3Raw
▸ sha3Raw(data): string
Will calculate the sha3 of the input but does return the hash value instead of null if for example a empty string is passed.
Parameters
| Name | Type | Description |
|---|---|---|
data | Bytes | the input to hash |
Returns
string
- the Keccak-256 hash of the input
Example
conosle.log(web3.utils.sha3Raw('web3.js'));
> 0x63667efb1961039c9bb0d6ea7a5abdd223a3aca7daa5044ad894226e1f83919a
console.log(web3.utils.sha3Raw(''));
> 0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470
soliditySha3
▸ soliditySha3(...values): undefined | string
Will tightly pack values given in the same way solidity would then hash. returns a hash string, or null if input is empty
Parameters
| Name | Type | Description |
|---|---|---|
...values | Sha3Input[] | the input to return the tightly packed values |
Returns
undefined | string
- the keccack246 of the tightly packed values
Example
console.log(web3.utils.soliditySha3({ type: "string", value: "31323334" }));
> 0xf15f8da2ad27e486d632dc37d24912f634398918d6f9913a0a0ff84e388be62b
soliditySha3Raw
▸ soliditySha3Raw(...values): string
Will tightly pack values given in the same way solidity would then hash.
returns a hash string, if input is empty will return 0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470
Parameters
| Name | Type | Description |
|---|---|---|
...values | TypedObject[] | TypedObjectAbbreviated[] | the input to return the tightly packed values |
Returns
string
- the keccack246 of the tightly packed values
Example
console.log(web3.utils.soliditySha3Raw({ type: "string", value: "helloworld" }))
> 0xfa26db7ca85ead399216e7c6316bc50ed24393c3122b582735e7f3b0f91b93f0
stringToHex
▸ stringToHex(str): string
Parameters
| Name | Type |
|---|---|
str | string |
Returns
string
Alias
utf8ToHex
toAscii
▸ toAscii(str): string
Parameters
| Name | Type |
|---|---|
str | string |
Returns
string
Alias
hexToAscii
toBigInt
▸ toBigInt(value): bigint
Auto converts any given value into it's bigint representation
Parameters
| Name | Type | Description |
|---|---|---|
value | unknown | The value to convert |
Returns
bigint
- Returns the value in bigint representation
Example
console.log(web3.utils.toBigInt(1));
> 1n
toChecksumAddress
▸ toChecksumAddress(address): string
Will convert an upper or lowercase Ethereum address to a checksum address.
Parameters
| Name | Type | Description |
|---|---|---|
address | string | An address string |
Returns
string
The checksum address
Example
web3.utils.toChecksumAddress('0xc1912fee45d61c87cc5ea59dae31190fffff232d');
> "0xc1912fEE45d61C87Cc5EA59DaE31190FFFFf232d"
toDecimal
▸ toDecimal(value): number | bigint
Converts value to it's number representation
Parameters
| Name | Type |
|---|---|
value | string |
Returns
number | bigint
Alias
hexToNumber
toHex
▸ toHex(value, returnType?): string
Auto converts any given value into it's hex representation.
Parameters
| Name | Type | Description |
|---|---|---|
value | string | number | bigint | boolean | object | Uint8Array | Value to be converted to hex |
returnType? | boolean | If true, it will return the type of the value |
Returns
string
Example
console.log(web3.utils.toHex(10));
> 0xa
console.log(web3.utils.toHex('0x123', true));
> bytes
toNumber
▸ toNumber(value): number | bigint
Converts any given value into it's number representation, if possible, else into it's bigint representation.
Parameters
| Name | Type | Description |
|---|---|---|
value | Numbers | The value to convert |
Returns
number | bigint
- Returns the value in number or bigint representation
Example
console.log(web3.utils.toNumber(1));
> 1
console.log(web3.utils.toNumber(Number.MAX_SAFE_INTEGER));
> 9007199254740991
console.log(web3.utils.toNumber(BigInt(Number.MAX_SAFE_INTEGER)));
> 9007199254740991
console.log(web3.utils.toNumber(BigInt(Number.MAX_SAFE_INTEGER) + BigInt(1)));
> 9007199254740992n
toTwosComplement
▸ toTwosComplement(value, nibbleWidth?): string
Converts a negative number into the two’s complement and return a hexstring of 64 nibbles.
Parameters
| Name | Type | Default value | Description |
|---|---|---|---|
value | Numbers | undefined | The value to be converted. |
nibbleWidth | number | 64 | The nibble width of the hex string (default is 64). |
Returns
string
The hex string of the two’s complement.
Example
console.log(web3.utils.toTwosComplement(13, 32));
> 0x0000000000000000000000000000000d
console.log(web3.utils.toTwosComplement('-0x1', 32));
> 0xffffffffffffffffffffffffffffffff
console.log(web3.utils.toTwosComplement(BigInt('9007199254740992'), 32));
> 0x00000000000000000020000000000000
toUtf8
▸ toUtf8(input): string
Parameters
| Name | Type |
|---|---|
input | string | Uint8Array |
Returns
string
Alias
hexToUtf8
toWei
▸ toWei(number, unit): string
Takes a number of a unit and converts it to wei.
Parameters
| Name | Type | Description |
|---|---|---|
number | Numbers | The number to convert. |
unit | number | "noether" | "wei" | "kwei" | "Kwei" | "babbage" | "femtoether" | "mwei" | "Mwei" | "lovelace" | "picoether" | "gwei" | "Gwei" | "shannon" | "nanoether" | "nano" | "szabo" | "microether" | "micro" | "finney" | "milliether" | "milli" | "ether" | "kether" | "grand" | "mether" | "gether" | "tether" | EtherUnits The unit of the number passed. |
Returns
string
The number converted to wei.
Example
console.log(web3.utils.toWei("0.001", "ether"));
> 1000000000000000 //(wei)
utf8ToHex
▸ utf8ToHex(str): string
Should be called to get hex representation (prefixed by 0x) of utf8 string
Parameters
| Name | Type | Description |
|---|---|---|
str | string | Utf8 string to be converted |
Returns
string
- The hex representation of the input string
Example
console.log(utf8ToHex('web3.js'));
> "0x776562332e6a73"
uuidV4
▸ uuidV4(): string
Generate a version 4 (random) uuid https://github.com/uuidjs/uuid/blob/main/src/v4.js#L5
Returns
string
- A version 4 uuid of the form xxxxxxxx-xxxx-4xxx-xxxx-xxxxxxxxxxxx
Example
console.log(web3.utils.uuidV4());
> "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed"