Byte Manipulation

While there are many high-level APIs for interacting with Hedera, 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.

The Bytes package is directly imported from the The Ethers Project. The complete documentation can be found in the official ethers docs.

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

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

hethers.utils.isBytes( object ) ⇒ boolean

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

hethers.utils.isBytesLike( object ) ⇒ boolean

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

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

hethers.utils.arrayify( DataHexStringOrArrayish [ , options ] ) ⇒ Uint8Array

Converts DataHexStringOrArrayish to a Uint8Array.

hethers.utils.hexlify( hexstringOrArrayish ) ⇒ string<DataHexString>

Converts hexstringOrArrayish to a DataHexString.

hethers.utils.hexValue( aBigNumberish ) ⇒ string<HexString>

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

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

hethers.utils.concat( arrayOfBytesLike ) ⇒ Uint8Array

Concatenates all the BytesLike in arrayOfBytesLike into a single Uint8Array.

hethers.utils.stripZeros( aBytesLike ) ⇒ Uint8Array

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

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

hethers.utils.hexConcat( arrayOfBytesLike ) ⇒ string<DataHexString>

Concatenates all the BytesLike in arrayOfBytesLike into a single DataHexString

hethers.utils.hexDataLength( aBytesLike ) ⇒ string<DataHexString>

Returns the length (in bytes) of aBytesLike.

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

hethers.utils.hexStripZeros( aBytesLike ) ⇒ string<HexString>

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

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

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

hethers.utils.splitSignature( aSignatureLikeOrBytesLike ) ⇒ Signature

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

Random Bytes

hethers.utils.randomBytes( length ) ⇒ Uint8Array

Return a new Uint8Array of length random bytes.

hethers.utils.shuffled( array ) ⇒ Array<any>

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

utils.randomBytes(8)
// Uint8Array [ 238, 239, 73, 38, 25, 219, 132, 179 ]

const data = [ 1, 2, 3, 4, 5, 6, 7 ];

// Returns a new Array
utils.shuffled(data);
// [
//   4,
//   6,
//   5,
//   2,
//   1,
//   7,
//   3
// ]

// The Original is unscathed...
data
// [
//   1,
//   2,
//   3,
//   4,
//   5,
//   6,
//   7
// ]