#
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

- r and s --- The x co-ordinate of r and the s value of the signature
- v --- The parity of the y co-ordinate of r
- _vs --- The compact representation of the s and v
- recoveryParam --- The normalized (i.e. 0 or 1) value of v

###
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
source

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

ethers.utils.isBytesLike( object ) ⇒ boolean
source

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

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

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
source

Converts DataHexStringOrArrayish to a Uint8Array.

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

Converts hexstringOrArrayish to a DataHexString.

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

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
source

Concatenates all the BytesLike in arrayOfBytesLike into a single Uint8Array.

ethers.utils.stripZeros( aBytesLike ) ⇒ Uint8Array
source

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

ethers.utils.zeroPad( aBytesLike , length ) ⇒ Uint8Array
source

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

Concatenates all the BytesLike in arrayOfBytesLike into a single DataHexString

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

Returns the length (in bytes) of aBytesLike.

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

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

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

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

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

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
source

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
source

Return a new Uint8Array of length random bytes.

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

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

Examples
utils.randomBytes(8) // Uint8Array [ 97, 223, 223, 186, 224, 0, 90, 28 ] const data = [ 1, 2, 3, 4, 5, 6, 7 ]; // Returns a new Array utils.shuffled(data); // [ // 5, // 3, // 1, // 4, // 6, // 7, // 2 // ] // The Original is unscathed... data // [ // 1, // 2, // 3, // 4, // 5, // 6, // 7 // ]
The content of this site is licensed under the Creative Commons License. Generated on February 8, 2021, 3:25pm.