Byte Manipulation

While there are many high-level APIs for interacting with Ethereum, such as Contracts and Providers, a lot of the low level access requires byte manipulation operations.

Many of these operations are used internally, but can also be used to help normalize binary data representations from the output of various functions and methods.

Types

Bytes

A Bytes is any object which is an Array or TypedArray with each value in the valid byte range (i.e. between 0 and 255 inclusive), or is an Object with a length property where each indexed property is in the valid byte range.

BytesLike

A BytesLike can be either a Bytes or a DataHexString.

DataHexString

A DataHexstring is identical to a HexString except that it has an even number of nibbles, and therefore is a valid representation of binary data as a string.

HexString

A Hexstring is a string which has a 0x prefix followed by any number of nibbles (i.e. case-insensitive hexadecimal characters, 0-9 and a-f).

Signature

Raw Signature inherits string<DataHexString<65>>

A Raw Signature is a common Signature format where the r, s and v are concatenated into a 65 byte (130 nibble) DataHexString.

SignatureLike

A SignatureLike is similar to a Signature, except redundant properties may be omitted or it may be a Raw Signature.

For example, if _vs is specified, s and v may be omitted. Likewise, if recoveryParam is provided, v may be omitted (as in these cases the missing values can be computed).

Inspection

ethers.utils.isBytes( object ) boolean

Returns true if and only if object is a valid Bytes.

ethers.utils.isBytesLike( object ) boolean

Returns true if and only if object is a Bytes or DataHexString.

ethers.utils.isHexString( object , [ length ] ) boolean

Returns true if and only if object is a valid hex string. If length is specified and object is not a valid DataHexString of length bytes, an InvalidArgument error is thrown.

Converting between Arrays and Hexstrings

ethers.utils.arrayify( DataHexStringOrArrayish [ , options ] ) Uint8Array

Converts DataHexStringOrArrayish to a Uint8Array.

ethers.utils.hexlify( hexstringOrArrayish ) string< DataHexString >

Converts hexstringOrArrayish to a DataHexString.

ethers.utils.hexValue( aBigNumberish ) string< HexString >

Converts aBigNumberish to a HexString, with no unnecessary leading zeros.

Examples
// Convert a hexstring to a Uint8Array arrayify("0x1234") // Uint8Array [ 18, 52 ] // Convert an Array to a hexstring hexlify([1, 2, 3, 4]) // '0x01020304' // Convert an Object to a hexstring hexlify({ length: 2, "0": 1, "1": 2 }) // '0x0102' // Convert an Array to a hexstring hexlify([ 1 ]) // '0x01' // Convert a number to a stripped hex value hexValue(1) // '0x1' // Convert an Array to a stripped hex value hexValue([ 1, 2 ]) // '0x102'

Array Manipulation

ethers.utils.concat( arrayOfBytesLike ) Uint8Array

Concatenates all the BytesLike in arrayOfBytesLike into a single Uint8Array.

ethers.utils.stripZeros( aBytesLike ) Uint8Array

Returns a Uint8Array with all leading 0 bytes of aBtyesLike removed.

ethers.utils.zeroPad( aBytesLike , length ) Uint8Array

Returns a Uint8Array of the data in aBytesLike with 0 bytes prepended to length bytes long.

If aBytesLike is already longer than length bytes long, an InvalidArgument error will be thrown.

Hexstring Manipulation

ethers.utils.hexConcat( arrayOfBytesLike ) string< DataHexString >

Concatenates all the BytesLike in arrayOfBytesLike into a single DataHexString

ethers.utils.hexDataLength( aBytesLike ) string< DataHexString >

Returns the length (in bytes) of aBytesLike.

ethers.utils.hexDataSlice( aBytesLike , offset [ , endOffset ] ) string< DataHexString >

Returns a DataHexString representation of a slice of aBytesLike, from offset (in bytes) to endOffset (in bytes). If endOffset is omitted, the length of aBytesLike is used.

ethers.utils.hexStripZeros( aBytesLike ) string< HexString >

Returns a HexString representation of aBytesLike with all leading zeros removed.

ethers.utils.hexZeroPad( aBytesLike , length ) string< DataHexString >

Returns a DataHexString representation of aBytesLike padded to length bytes.

If aBytesLike is already longer than length bytes long, an InvalidArgument error will be thrown.

Signature Conversion

ethers.utils.joinSignature( aSignatureLike ) string< RawSignature >

Return the raw-format of aSignaturelike, which is 65 bytes (130 nibbles) long, concatenating the r, s and (normalized) v of a Signature.

ethers.utils.splitSignature( aSignatureLikeOrBytesLike ) Signature

Return the full expanded-format of aSignaturelike or a raw-format DataHexString. Any missing properties will be computed.

Random Bytes

ethers.utils.randomBytes( length ) Uint8Array

Return a new Uint8Array of length random bytes.

ethers.utils.shuffled( array ) Array< any >

Return a copy of array shuffled using Fisher-Yates Shuffle.

Examples
utils.randomBytes(8) // Uint8Array [ 74, 222, 172, 224, 158, 239, 170, 50 ] const data = [ 1, 2, 3, 4, 5, 6, 7 ]; // Returns a new Array utils.shuffled(data); // [ // 6, // 5, // 1, // 3, // 7, // 4, // 2 // ] // The Original is unscathed... data // [ // 1, // 2, // 3, // 4, // 5, // 6, // 7 // ]