essential-eth 0.5.6 → 0.5.9

package/lib/cjs/utils/bytes.d.ts

@@ -2,10 +2,8 @@ export declare type Bytes = ArrayLike<number>;
 /**
  * @example
  * [1,2,3]
- *
  * @example
  * 0x123
- *
  * @example
  * '0x123'
  */
@@ -36,22 +34,22 @@ export interface Signature {
 }
 /**
  * Returns true if and only if value is a valid [Bytes](#bytes) or DataHexString
- * * Same as [`ethers.utils.isBytesLike`](https://docs.ethers.io/v5/api/utils/bytes/#utils-isBytesLike)
+ * Same as [`ethers.utils.isBytesLike`](https://docs.ethers.io/v5/api/utils/bytes/#utils-isBytesLike)
  *
+ * @param value the value to check whether or not it matches BytesLike
+ * @returns whether or not the value matches BytesLike
  * @example
- * ```js
+ * ```javascript
  * isBytesLike([1,2,3]);
  * // true
  * ```
- *
  * @example
- * ```js
+ * ```javascript
  * isBytesLike(false);
  * // false
  * ```
- *
  * @example
- * ```js
+ * ```javascript
  * isBytesLike(new Uint8Array(1));
  * // true
  * ```
@@ -59,22 +57,22 @@ export interface Signature {
 export declare function isBytesLike(value: any): value is BytesLike;
 /**
  * Returns true if and only if value is a valid [Bytes](#bytes)
- * * Same as [`ethers.utils.isBytes`](https://docs.ethers.io/v5/api/utils/bytes/#utils-isBytes)
+ * Same as [`ethers.utils.isBytes`](https://docs.ethers.io/v5/api/utils/bytes/#utils-isBytes)
  *
+ * @param value the value to check whether or not it matches Bytes
+ * @returns whether or not the value matches Bytes
  * @example
- * ```js
+ * ```javascript
  * isBytes([1,2,3]);
  * // true
  * ```
- *
  * @example
- * ```js
+ * ```javascript
  * isBytes(false);
  * // false
  * ```
- *
  * @example
- * ```js
+ * ```javascript
  * isBytes(new Uint8Array(1));
  * // true
  * ```
@@ -82,22 +80,23 @@ export declare function isBytesLike(value: any): value is BytesLike;
 export declare function isBytes(value: any): value is Bytes;
 /**
  * Converts DataHexStringOrArrayish to a Uint8Array
- * * Same as [`ethers.utils.arrayify`](https://docs.ethers.io/v5/api/utils/bytes/#utils-arrayify)
+ * Same as [`ethers.utils.arrayify`](https://docs.ethers.io/v5/api/utils/bytes/#utils-arrayify)
  *
+ * @param value the value to convert to a Uint8Array
+ * @param options options to use when converting the value to a Uint8Array
+ * @returns the value represented as a Uint8Array
  * @example
- * ```js
+ * ```javascript
  * arrayify(1);
  * // Uint8Array(1) [ 1 ]
  * ```
- *
  * @example
- * ```js
+ * ```javascript
  * arrayify(0x1234);
  * // Uint8Array(2) [ 18, 52 ]
  * ```
- *
  * @example
- * ```js
+ * ```javascript
  * arrayify('0x1', { hexPad: 'right' });
  * // Uint8Array(1) [ 16 ]
  * ```
@@ -105,38 +104,159 @@ export declare function isBytes(value: any): value is Bytes;
 export declare function arrayify(value: BytesLike | Hexable | number, options?: DataOptions): Uint8Array;
 /**
  * Concatenates all the BytesLike in arrayOfBytesLike into a single Uint8Array.
- * * Same as [`ethers.utils.concat`](https://docs.ethers.io/v5/api/utils/bytes/#utils-concat)
+ * Same as [`ethers.utils.concat`](https://docs.ethers.io/v5/api/utils/bytes/#utils-concat)
  *
+ * @param arrayOfBytesLike the array of {@link BytesLike} to concatenate together
+ * @returns a concatenated Uint8Array
  * @example
- * ```js
+ * ```javascript
  * concat([0, 1]);
  * // Uint8Array(2) [ 0, 1 ]
  * ```
  */
 export declare function concat(arrayOfBytesLike: ReadonlyArray<BytesLikeWithNumber>): Uint8Array;
+/**
+ * Strips leading zeros from a BytesLike object
+ *
+ * @param value the value to strip leading zeros from
+ * @returns value without leading zeroes, expressed as a Uint8Array
+ * @example
+ * ```javascript
+ * stripZeros('0x00002834');
+ * // Uint8Array { [Iterator]  0: 40, 1: 52 }
+ * // Equivalent to '0x2834'
+ * ```
+ */
 export declare function stripZeros(value: BytesLike): Uint8Array;
+/**
+ * Pads the beginning of a {@link BytesLike} with zeros so it's the specified length as a Uint8Array
+ *
+ * @param value the value to pad
+ * @param length the desired length of the value
+ * @returns the value padded with zeros to the specified length
+ * @example
+ * ```javascript
+ * zeroPad('0x039284');
+ * // Uint8Array { [Iterator]  0: 0, 1: 0, 2: 0, 3: 3, 4: 146, 5: 132 }
+ * // Equivalent to 0x000000039284
+ * ```
+ * @example
+ * ```javascript
+ * zeroPad([39, 25, 103, 45], 5);
+ * // Uint8Array { [Iterator]  0: 0, 1: 39, 2: 25, 3: 103, 4: 45 }
+ * ```
+ */
 export declare function zeroPad(value: BytesLike, length: number): Uint8Array;
 /**
  * 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.
- * * Same as [`ethers.utils.isHexString`](https://docs.ethers.io/v5/api/utils/bytes/#utils-isHexString)
+ * Same as [`ethers.utils.isHexString`](https://docs.ethers.io/v5/api/utils/bytes/#utils-isHexString)
+ *
+ * @param value the value to check whether or not it's a hex string
+ * @param length a length of bytes that the value should be equal to
+ * @returns whether the value is a valid hex string (and optionally, whether it matches the length specified)
+ * @example
+ * ```javascript
+ * isHexString('0x4924');
+ * // true
+ * ```
+ * @example
+ * ```javascript
+ * isHexString('0x4924', 4);
+ * // false
+ * // length of 4 in bytes would mean a hex string with 8 characters
+ * ```
  */
 export declare function isHexString(value: any, length?: number): boolean;
 /**
+ * Converts a value into a hex string
+ *
+ * @param value the value to convert
+ * @param options options to use when converting the value to a hex string
+ * @returns the value represented as a hex string
  * @example
- * ```js
+ * ```javascript
  * hexlify(4);
  * // '0x04'
- *
+ * ```
+ * @example
+ * ```javascript
  * hexlify(14);
  * // '0x0e'
  * ```
  */
 export declare function hexlify(value: BytesLike | Hexable | number | bigint, options?: DataOptions): string;
+/**
+ * Gets the length of data represented as a hex string
+ *
+ * @param data the data to check the length of
+ * @returns the length of the data
+ * @example
+ * ```javascript
+ * hexDataLength([2, 4, 0, 1]);
+ * // 4
+ * ```
+ * @example
+ * ```javascript
+ * hexDataLength('0x3925');
+ * // 2
+ * ```
+ */
 export declare function hexDataLength(data: BytesLike): number | null;
+/**
+ * Slices a {@link BytesLike} to extract a certain part of the input
+ *
+ * @param data the data to slice from
+ * @param offset the index to start extraction at
+ * @param endOffset the index to end extraction at
+ * @returns the extracted data as a hex string
+ * @example
+ * ```javascript
+ * hexDataSlice([20, 6, 48], 0, 2);
+ * // '0x1406'
+ * ```
+ */
 export declare function hexDataSlice(data: BytesLikeWithNumber, offset: number, endOffset?: number): string;
+/**
+ * Concatenates values together into one hex string
+ *
+ * @param items the items to concatenate together
+ * @returns a single hex string including all of the items to be concatenated
+ * @example
+ * ```javascript
+ * hexConcat([[2, 4, 0, 1], 9, '0x2934', '0x3947']);
+ * // '0x020400010929343947'
+ * ```
+ */
 export declare function hexConcat(items: ReadonlyArray<BytesLike>): string;
+/**
+ * Converts a number of different types into a hex string
+ *
+ * @param value the value to convert into a hex string
+ * @returns the value represented as a hex string
+ * @example
+ * ```javascript
+ * hexValue(39);
+ * // '0x27'
+ * ```
+ * @example
+ * ```javascript
+ * hexValue([9, 4, 19, 4]);
+ * // '0x9041304'
+ * ```
+ */
 export declare function hexValue(value: BytesLike | Hexable | number | bigint): string;
+/**
+ * Strips the leading zeros from a value and returns it as a hex string
+ *
+ * @param value the value to strip zeros from
+ * @returns a hex string representation of the value, without leading zeros
+ * @example
+ * ```javascript
+ * hexStripZeros([0,0,0,48]);
+ * // '0x30'
+ * ```
+ */
 export declare function hexStripZeros(value: BytesLike): string;
 /**
  * Returns a hex string padded to a specified length of bytes.
@@ -145,24 +265,21 @@ export declare function hexStripZeros(value: BytesLike): string;
  *
  * Differs from ["padLeft" in web3.js](https://web3js.readthedocs.io/en/v1.7.1/web3-utils.html#padleft) because web3 counts by characters, not bytes.
  *
- * @param hexValue - A hex-string, hex-number, or decimal number (auto-converts to base-16) to be padded
- * @param length - The final length in bytes
- *
- * @throws - If the value is not a hex string or number
- * @throws - If the value is longer than the length
- *
+ * @param value A hex-string, hex-number, or decimal number (auto-converts to base-16) to be padded
+ * @param length The final length in bytes
+ * @returns A hex string padded to the specified length
+ * @throws If the value is not a hex string or number
+ * @throws If the value is longer than the length
  * @example
  * ```javascript
  * hexZeroPad('0x60', 2);
  * // '0x0060'
  * ```
- *
  * @example
  * ```javascript
  * hexZeroPad(0x60, 3);
  * // '0x000060'
  * ```
- *
  * @example
  * ```javascript
  * hexZeroPad('12345', 1);

package/lib/cjs/utils/bytes.js

@@ -1,29 +1,41 @@
 "use strict";
-// primary duplicate code from https://github.com/ethers-io/ethers.js/blob/f599d6f23dad0d0acaa3828d6b7acaab2d5e455b/packages/bytes/src.ts/index.ts
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.hexZeroPad = exports.hexStripZeros = exports.hexValue = exports.hexConcat = exports.hexDataSlice = exports.hexDataLength = exports.hexlify = exports.isHexString = exports.zeroPad = exports.stripZeros = exports.concat = exports.arrayify = exports.isBytes = exports.isBytesLike = void 0;
+// primarily duplicate code from https://github.com/ethers-io/ethers.js/blob/f599d6f23dad0d0acaa3828d6b7acaab2d5e455b/packages/bytes/src.ts/index.ts
 const logger_1 = require("../logger/logger");
+/**
+ * Check if a value can be converted to a hex string
+ *
+ * @param value the value to check whether or not it's Hexable
+ * @returns whether or not the value is Hexable
+ * @example
+ * ```javascript
+ * const val = tinyBig(203);
+ * isHexable(val);
+ * // true
+ * ```
+ */
 function isHexable(value) {
     return !!value.toHexString;
 }
 /**
  * Returns true if and only if value is a valid [Bytes](#bytes) or DataHexString
- * * Same as [`ethers.utils.isBytesLike`](https://docs.ethers.io/v5/api/utils/bytes/#utils-isBytesLike)
+ * Same as [`ethers.utils.isBytesLike`](https://docs.ethers.io/v5/api/utils/bytes/#utils-isBytesLike)
  *
+ * @param value the value to check whether or not it matches BytesLike
+ * @returns whether or not the value matches BytesLike
  * @example
- * ```js
+ * ```javascript
  * isBytesLike([1,2,3]);
  * // true
  * ```
- *
  * @example
- * ```js
+ * ```javascript
  * isBytesLike(false);
  * // false
  * ```
- *
  * @example
- * ```js
+ * ```javascript
  * isBytesLike(new Uint8Array(1));
  * // true
  * ```
@@ -32,27 +44,43 @@ function isBytesLike(value) {
     return (isHexString(value) && !(value.length % 2)) || isBytes(value);
 }
 exports.isBytesLike = isBytesLike;
+/**
+ * Checks if a value is an integer
+ *
+ * @param value the value to check whether or not it's an integer
+ * @returns whether or not value is an integer
+ * @example
+ * ```javascript
+ * isInteger(4)
+ * // true
+ * ```
+ * @example
+ * ```javascript
+ * isInteger(6.2)
+ * // false
+ * ```
+ */
 function isInteger(value) {
     return typeof value === 'number' && value == value && value % 1 === 0;
 }
 /**
  * Returns true if and only if value is a valid [Bytes](#bytes)
- * * Same as [`ethers.utils.isBytes`](https://docs.ethers.io/v5/api/utils/bytes/#utils-isBytes)
+ * Same as [`ethers.utils.isBytes`](https://docs.ethers.io/v5/api/utils/bytes/#utils-isBytes)
  *
+ * @param value the value to check whether or not it matches Bytes
+ * @returns whether or not the value matches Bytes
  * @example
- * ```js
+ * ```javascript
  * isBytes([1,2,3]);
  * // true
  * ```
- *
  * @example
- * ```js
+ * ```javascript
  * isBytes(false);
  * // false
  * ```
- *
  * @example
- * ```js
+ * ```javascript
  * isBytes(new Uint8Array(1));
  * // true
  * ```
@@ -81,22 +109,23 @@ function isBytes(value) {
 exports.isBytes = isBytes;
 /**
  * Converts DataHexStringOrArrayish to a Uint8Array
- * * Same as [`ethers.utils.arrayify`](https://docs.ethers.io/v5/api/utils/bytes/#utils-arrayify)
+ * Same as [`ethers.utils.arrayify`](https://docs.ethers.io/v5/api/utils/bytes/#utils-arrayify)
  *
+ * @param value the value to convert to a Uint8Array
+ * @param options options to use when converting the value to a Uint8Array
+ * @returns the value represented as a Uint8Array
  * @example
- * ```js
+ * ```javascript
  * arrayify(1);
  * // Uint8Array(1) [ 1 ]
  * ```
- *
  * @example
- * ```js
+ * ```javascript
  * arrayify(0x1234);
  * // Uint8Array(2) [ 18, 52 ]
  * ```
- *
  * @example
- * ```js
+ * ```javascript
  * arrayify('0x1', { hexPad: 'right' });
  * // Uint8Array(1) [ 16 ]
  * ```
@@ -152,10 +181,12 @@ function arrayify(value, options) {
 exports.arrayify = arrayify;
 /**
  * Concatenates all the BytesLike in arrayOfBytesLike into a single Uint8Array.
- * * Same as [`ethers.utils.concat`](https://docs.ethers.io/v5/api/utils/bytes/#utils-concat)
+ * Same as [`ethers.utils.concat`](https://docs.ethers.io/v5/api/utils/bytes/#utils-concat)
  *
+ * @param arrayOfBytesLike the array of {@link BytesLike} to concatenate together
+ * @returns a concatenated Uint8Array
  * @example
- * ```js
+ * ```javascript
  * concat([0, 1]);
  * // Uint8Array(2) [ 0, 1 ]
  * ```
@@ -171,6 +202,18 @@ function concat(arrayOfBytesLike) {
     return result;
 }
 exports.concat = concat;
+/**
+ * Strips leading zeros from a BytesLike object
+ *
+ * @param value the value to strip leading zeros from
+ * @returns value without leading zeroes, expressed as a Uint8Array
+ * @example
+ * ```javascript
+ * stripZeros('0x00002834');
+ * // Uint8Array { [Iterator]  0: 40, 1: 52 }
+ * // Equivalent to '0x2834'
+ * ```
+ */
 function stripZeros(value) {
     let result = arrayify(value);
     if (result.length === 0) {
@@ -188,6 +231,24 @@ function stripZeros(value) {
     return result;
 }
 exports.stripZeros = stripZeros;
+/**
+ * Pads the beginning of a {@link BytesLike} with zeros so it's the specified length as a Uint8Array
+ *
+ * @param value the value to pad
+ * @param length the desired length of the value
+ * @returns the value padded with zeros to the specified length
+ * @example
+ * ```javascript
+ * zeroPad('0x039284');
+ * // Uint8Array { [Iterator]  0: 0, 1: 0, 2: 0, 3: 3, 4: 146, 5: 132 }
+ * // Equivalent to 0x000000039284
+ * ```
+ * @example
+ * ```javascript
+ * zeroPad([39, 25, 103, 45], 5);
+ * // Uint8Array { [Iterator]  0: 0, 1: 39, 2: 25, 3: 103, 4: 45 }
+ * ```
+ */
 function zeroPad(value, length) {
     value = arrayify(value);
     if (value.length > length) {
@@ -201,7 +262,22 @@ exports.zeroPad = zeroPad;
 /**
  * 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.
- * * Same as [`ethers.utils.isHexString`](https://docs.ethers.io/v5/api/utils/bytes/#utils-isHexString)
+ * Same as [`ethers.utils.isHexString`](https://docs.ethers.io/v5/api/utils/bytes/#utils-isHexString)
+ *
+ * @param value the value to check whether or not it's a hex string
+ * @param length a length of bytes that the value should be equal to
+ * @returns whether the value is a valid hex string (and optionally, whether it matches the length specified)
+ * @example
+ * ```javascript
+ * isHexString('0x4924');
+ * // true
+ * ```
+ * @example
+ * ```javascript
+ * isHexString('0x4924', 4);
+ * // false
+ * // length of 4 in bytes would mean a hex string with 8 characters
+ * ```
  */
 function isHexString(value, length) {
     if (typeof value !== 'string' || !value.match(/^0x[0-9A-Fa-f]*$/)) {
@@ -215,11 +291,18 @@ function isHexString(value, length) {
 exports.isHexString = isHexString;
 const HexCharacters = '0123456789abcdef';
 /**
+ * Converts a value into a hex string
+ *
+ * @param value the value to convert
+ * @param options options to use when converting the value to a hex string
+ * @returns the value represented as a hex string
  * @example
- * ```js
+ * ```javascript
  * hexlify(4);
  * // '0x04'
- *
+ * ```
+ * @example
+ * ```javascript
  * hexlify(14);
  * // '0x0e'
  * ```
@@ -283,6 +366,22 @@ function hexlify(value, options) {
     return logger_1.logger.throwArgumentError('invalid hexlify value', 'value', value);
 }
 exports.hexlify = hexlify;
+/**
+ * Gets the length of data represented as a hex string
+ *
+ * @param data the data to check the length of
+ * @returns the length of the data
+ * @example
+ * ```javascript
+ * hexDataLength([2, 4, 0, 1]);
+ * // 4
+ * ```
+ * @example
+ * ```javascript
+ * hexDataLength('0x3925');
+ * // 2
+ * ```
+ */
 function hexDataLength(data) {
     if (typeof data !== 'string') {
         data = hexlify(data);
@@ -293,6 +392,19 @@ function hexDataLength(data) {
     return (data.length - 2) / 2;
 }
 exports.hexDataLength = hexDataLength;
+/**
+ * Slices a {@link BytesLike} to extract a certain part of the input
+ *
+ * @param data the data to slice from
+ * @param offset the index to start extraction at
+ * @param endOffset the index to end extraction at
+ * @returns the extracted data as a hex string
+ * @example
+ * ```javascript
+ * hexDataSlice([20, 6, 48], 0, 2);
+ * // '0x1406'
+ * ```
+ */
 function hexDataSlice(data, offset, endOffset) {
     if (typeof data !== 'string') {
         data = hexlify(data);
@@ -307,6 +419,17 @@ function hexDataSlice(data, offset, endOffset) {
     return '0x' + data.substring(offset);
 }
 exports.hexDataSlice = hexDataSlice;
+/**
+ * Concatenates values together into one hex string
+ *
+ * @param items the items to concatenate together
+ * @returns a single hex string including all of the items to be concatenated
+ * @example
+ * ```javascript
+ * hexConcat([[2, 4, 0, 1], 9, '0x2934', '0x3947']);
+ * // '0x020400010929343947'
+ * ```
+ */
 function hexConcat(items) {
     let result = '0x';
     items.forEach((item) => {
@@ -315,6 +438,22 @@ function hexConcat(items) {
     return result;
 }
 exports.hexConcat = hexConcat;
+/**
+ * Converts a number of different types into a hex string
+ *
+ * @param value the value to convert into a hex string
+ * @returns the value represented as a hex string
+ * @example
+ * ```javascript
+ * hexValue(39);
+ * // '0x27'
+ * ```
+ * @example
+ * ```javascript
+ * hexValue([9, 4, 19, 4]);
+ * // '0x9041304'
+ * ```
+ */
 function hexValue(value) {
     const trimmed = hexStripZeros(hexlify(value, { hexPad: 'left' }));
     if (trimmed === '0x') {
@@ -323,6 +462,17 @@ function hexValue(value) {
     return trimmed;
 }
 exports.hexValue = hexValue;
+/**
+ * Strips the leading zeros from a value and returns it as a hex string
+ *
+ * @param value the value to strip zeros from
+ * @returns a hex string representation of the value, without leading zeros
+ * @example
+ * ```javascript
+ * hexStripZeros([0,0,0,48]);
+ * // '0x30'
+ * ```
+ */
 function hexStripZeros(value) {
     if (typeof value !== 'string') {
         value = hexlify(value);
@@ -345,24 +495,21 @@ exports.hexStripZeros = hexStripZeros;
  *
  * Differs from ["padLeft" in web3.js](https://web3js.readthedocs.io/en/v1.7.1/web3-utils.html#padleft) because web3 counts by characters, not bytes.
  *
- * @param hexValue - A hex-string, hex-number, or decimal number (auto-converts to base-16) to be padded
- * @param length - The final length in bytes
- *
- * @throws - If the value is not a hex string or number
- * @throws - If the value is longer than the length
- *
+ * @param value A hex-string, hex-number, or decimal number (auto-converts to base-16) to be padded
+ * @param length The final length in bytes
+ * @returns A hex string padded to the specified length
+ * @throws If the value is not a hex string or number
+ * @throws If the value is longer than the length
  * @example
  * ```javascript
  * hexZeroPad('0x60', 2);
  * // '0x0060'
  * ```
- *
  * @example
  * ```javascript
  * hexZeroPad(0x60, 3);
  * // '0x000060'
  * ```
- *
  * @example
  * ```javascript
  * hexZeroPad('12345', 1);

package/lib/cjs/utils/compute-address.d.ts

@@ -2,7 +2,16 @@
  * Computes the address that corresponds to a specified public or private key
  *
  * @param key the public or private key to find the address related to
- *
  * @returns the address that corresponds to the key specified
+ * @example
+ * ```javascript
+ * computeAddress('0x0458eb591f407aef12936bd2989ca699cf5061de9c4964dd6eb6005fd8f580c407434447e813969a1be6e9954b002cad84dfc67a69e032b273e4695e7d0db2d952'); // public key
+ * // '0xA2902059a7BF992f1450BACD7357CCAa5cC8336a'
+ * ```
+ * @example
+ * ```javascript
+ * computeAddress('0x2f2c419acf4a1da8c1ebea75bb3fcfbd3ec2aa3bf0162901ccdc2f38b8f92427'); // private key
+ * // '0xA2902059a7BF992f1450BACD7357CCAa5cC8336a'
+ * ```
  */
 export declare function computeAddress(key: string): string;

package/lib/cjs/utils/compute-address.js

@@ -8,8 +8,17 @@ const keccak256_1 = require("./keccak256");
  * Computes the address that corresponds to a specified public or private key
  *
  * @param key the public or private key to find the address related to
- *
  * @returns the address that corresponds to the key specified
+ * @example
+ * ```javascript
+ * computeAddress('0x0458eb591f407aef12936bd2989ca699cf5061de9c4964dd6eb6005fd8f580c407434447e813969a1be6e9954b002cad84dfc67a69e032b273e4695e7d0db2d952'); // public key
+ * // '0xA2902059a7BF992f1450BACD7357CCAa5cC8336a'
+ * ```
+ * @example
+ * ```javascript
+ * computeAddress('0x2f2c419acf4a1da8c1ebea75bb3fcfbd3ec2aa3bf0162901ccdc2f38b8f92427'); // private key
+ * // '0xA2902059a7BF992f1450BACD7357CCAa5cC8336a'
+ * ```
  */
 function computeAddress(key) {
     // compressed public keys start with 0x04