web3util 4.3.2

package/src/string_manipulation.ts

@@ -0,0 +1,166 @@
+/*
+This file is part of web3.js.
+
+web3.js is free software: you can redistribute it and/or modify
+it under the terms of the GNU Lesser General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+web3.js is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public License
+along with web3.js.  If not, see <http://www.gnu.org/licenses/>.
+*/
+
+/**
+ * @module Utils
+ */
+
+import { Numbers } from 'web3-types';
+import { NibbleWidthError } from 'web3-errors';
+import { isHexStrict, validator, utils as validatorUtils, bigintPower } from 'web3-validator';
+import { numberToHex, toHex, toNumber } from './converters.js';
+
+/**
+ * Adds a padding on the left of a string, if value is a integer or bigInt will be converted to a hex string.
+ * @param value - The value to be padded.
+ * @param characterAmount - The amount of characters the string should have.
+ * @param sign - The sign to be added (default is 0).
+ * @returns The padded string.
+ *
+ * @example
+ * ```ts
+ *
+ * console.log(web3.utils.padLeft('0x123', 10));
+ * >0x0000000123
+ * ```
+ */
+export const padLeft = (value: Numbers, characterAmount: number, sign = '0'): string => {
+	// To avoid duplicate code and circular dependency we will
+	// use `padLeft` implementation from `web3-validator`
+
+	if (typeof value === 'string') {
+		if (!isHexStrict(value)) {
+			return value.padStart(characterAmount, sign);
+		}
+		return validatorUtils.padLeft(value, characterAmount, sign);
+	}
+
+	validator.validate(['int'], [value]);
+
+	return validatorUtils.padLeft(value, characterAmount, sign);
+};
+
+/**
+ * Adds a padding on the right of a string, if value is a integer or bigInt will be converted to a hex string.
+ * @param value - The value to be padded.
+ * @param characterAmount - The amount of characters the string should have.
+ * @param sign - The sign to be added (default is 0).
+ * @returns The padded string.
+ *
+ * @example
+ * ```ts
+ * console.log(web3.utils.padRight('0x123', 10));
+ * > 0x1230000000
+ *
+ * console.log(web3.utils.padRight('0x123', 10, '1'));
+ * > 0x1231111111
+ * ```
+ */
+export const padRight = (value: Numbers, characterAmount: number, sign = '0'): string => {
+	if (typeof value === 'string' && !isHexStrict(value)) {
+		return value.padEnd(characterAmount, sign);
+	}
+
+	const hexString = typeof value === 'string' && isHexStrict(value) ? value : numberToHex(value);
+	const prefixLength = hexString.startsWith('-') ? 3 : 2;
+
+	validator.validate([hexString.startsWith('-') ? 'int' : 'uint'], [value]);
+
+	return hexString.padEnd(characterAmount + prefixLength, sign);
+};
+
+/**
+ * Adds a padding on the right of a string, if value is a integer or bigInt will be converted to a hex string. @alias `padRight`
+ */
+export const rightPad = padRight;
+
+/**
+ * Adds a padding on the left of a string, if value is a integer or bigInt will be converted to a hex string. @alias `padLeft`
+ */
+export const leftPad = padLeft;
+
+/**
+ * Converts a negative number into the two’s complement and return a hexstring of 64 nibbles.
+ * @param value - The value to be converted.
+ * @param nibbleWidth - The nibble width of the hex string (default is 64).
+ *
+ * @returns The hex string of the two’s complement.
+ *
+ * @example
+ * ```ts
+ * 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
+ * ```
+ */
+export const toTwosComplement = (value: Numbers, nibbleWidth = 64): string => {
+	validator.validate(['int'], [value]);
+
+	const val = toNumber(value);
+
+	if (val >= 0) return padLeft(toHex(val), nibbleWidth);
+
+	const largestBit = bigintPower(BigInt(2), BigInt(nibbleWidth * 4));
+	if (-val >= largestBit) {
+		throw new NibbleWidthError(`value: ${value}, nibbleWidth: ${nibbleWidth}`);
+	}
+	const updatedVal = BigInt(val);
+
+	const complement = updatedVal + largestBit;
+
+	return padLeft(numberToHex(complement), nibbleWidth);
+};
+
+/**
+ * Converts the twos complement into a decimal number or big int.
+ * @param value - The value to be converted.
+ * @param nibbleWidth - The nibble width of the hex string (default is 64).
+ * @returns The decimal number or big int.
+ *
+ * @example
+ * ```ts
+ * console.log(web3.utils.fromTwosComplement('0x0000000000000000000000000000000d', 32'));
+ * > 13
+ *
+ * console.log(web3.utils.fromTwosComplement('0x00000000000000000020000000000000', 32));
+ * > 9007199254740992n
+ * ```
+ */
+export const fromTwosComplement = (value: Numbers, nibbleWidth = 64): number | bigint => {
+	validator.validate(['int'], [value]);
+
+	const val = toNumber(value);
+
+	if (val < 0) return val;
+
+	const largestBit = Math.ceil(Math.log(Number(val)) / Math.log(2));
+
+	if (largestBit > nibbleWidth * 4)
+		throw new NibbleWidthError(`value: "${value}", nibbleWidth: "${nibbleWidth}"`);
+
+	// check the largest bit to see if negative
+	if (nibbleWidth * 4 !== largestBit) return val;
+
+	const complement = bigintPower(BigInt(2), BigInt(nibbleWidth) * BigInt(4));
+
+	return toNumber(BigInt(val) - complement);
+};

package/src/uint8array.ts

@@ -0,0 +1,59 @@
+/*
+This file is part of web3.js.
+
+web3.js is free software: you can redistribute it and/or modify
+it under the terms of the GNU Lesser General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+web3.js is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public License
+along with web3.js.  If not, see <http://www.gnu.org/licenses/>.
+*/
+
+export function isUint8Array(data: unknown | Uint8Array): data is Uint8Array {
+	return (
+		data instanceof Uint8Array ||
+		(data as { constructor: { name: string } })?.constructor?.name === 'Uint8Array' ||
+		(data as { constructor: { name: string } })?.constructor?.name === 'Buffer'
+	);
+}
+
+export function uint8ArrayConcat(...parts: Uint8Array[]): Uint8Array {
+	const length = parts.reduce((prev, part) => {
+		const agg = prev + part.length;
+		return agg;
+	}, 0);
+	const result = new Uint8Array(length);
+	let offset = 0;
+	for (const part of parts) {
+		result.set(part, offset);
+		offset += part.length;
+	}
+	return result;
+}
+
+/**
+ * Returns true if the two passed Uint8Arrays have the same content
+ */
+export function uint8ArrayEquals(a: Uint8Array, b: Uint8Array): boolean {
+	if (a === b) {
+		return true;
+	}
+
+	if (a.byteLength !== b.byteLength) {
+		return false;
+	}
+
+	for (let i = 0; i < a.byteLength; i += 1) {
+		if (a[i] !== b[i]) {
+			return false;
+		}
+	}
+
+	return true;
+}

package/src/uuid.ts

@@ -0,0 +1,59 @@
+/*
+This file is part of web3.js.
+
+web3.js is free software: you can redistribute it and/or modify
+it under the terms of the GNU Lesser General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+web3.js is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public License
+along with web3.js.  If not, see <http://www.gnu.org/licenses/>.
+*/
+
+/**
+ * @module Utils
+ */
+
+import { bytesToHex } from './converters.js';
+import { randomBytes } from './random.js';
+
+/**
+ * Generate a version 4 (random) uuid
+ * https://github.com/uuidjs/uuid/blob/main/src/v4.js#L5
+ * @returns - A version 4 uuid of the form xxxxxxxx-xxxx-4xxx-xxxx-xxxxxxxxxxxx
+ * @example
+ * ```ts
+ * console.log(web3.utils.uuidV4());
+ * > "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed"
+ * ```
+ */
+export const uuidV4 = (): string => {
+	const bytes = randomBytes(16);
+
+	// https://github.com/ethers-io/ethers.js/blob/ce8f1e4015c0f27bf178238770b1325136e3351a/packages/json-wallets/src.ts/utils.ts#L54
+	// Section: 4.1.3:
+	// - time_hi_and_version[12:16] = 0b0100
+	/* eslint-disable-next-line */
+	bytes[6] = (bytes[6] & 0x0f) | 0x40;
+
+	// Section 4.4
+	// - clock_seq_hi_and_reserved[6] = 0b0
+	// - clock_seq_hi_and_reserved[7] = 0b1
+	/* eslint-disable-next-line */
+	bytes[8] = (bytes[8] & 0x3f) | 0x80;
+
+	const hexString = bytesToHex(bytes);
+
+	return [
+		hexString.substring(2, 10),
+		hexString.substring(10, 14),
+		hexString.substring(14, 18),
+		hexString.substring(18, 22),
+		hexString.substring(22, 34),
+	].join('-');
+};

package/src/validation.ts

@@ -0,0 +1,193 @@
+/*
+This file is part of web3.js.
+
+web3.js is free software: you can redistribute it and/or modify
+it under the terms of the GNU Lesser General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+web3.js is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public License
+along with web3.js.  If not, see <http://www.gnu.org/licenses/>.
+*/
+
+/**
+ * @module Utils
+ */
+
+import { InvalidBlockError } from 'web3-errors';
+import {
+	checkAddressCheckSum as checkAddressCheckSumValidator,
+	isAddress as isAddressValidator,
+	isBlockTag,
+	isBloom as isBloomValidator,
+	isContractAddressInBloom as isContractAddressInBloomValidator,
+	isHex as isHexValidator,
+	isHexStrict as isHexStrictValidator,
+	isInBloom as isInBloomValidator,
+	isNullish as isNullishValidator,
+	isTopic as isTopicValidator,
+	isTopicInBloom as isTopicInBloomValidator,
+	isUserEthereumAddressInBloom as isUserEthereumAddressInBloomValidator,
+} from 'web3-validator';
+import { BlockNumberOrTag, BlockTags, ContractInitOptions } from 'web3-types';
+
+/**
+ * @deprecated Will be removed in next release. Please use `web3-validator` package instead.
+ */
+export const isHexStrict = isHexStrictValidator;
+
+/**
+ * returns true if input is a hexstring, number or bigint
+ *
+ * @deprecated Will be removed in next release. Please use `web3-validator` package instead.
+ */
+export const isHex = isHexValidator;
+
+/**
+ * Checks the checksum of a given address. Will also return false on non-checksum addresses.
+ *
+ * @deprecated Will be removed in next release. Please use `web3-validator` package instead.
+ */
+export const checkAddressCheckSum = checkAddressCheckSumValidator;
+
+/**
+ * Checks if a given string is a valid Ethereum address. It will also check the checksum, if the address has upper and lowercase letters.
+ *
+ * @deprecated Will be removed in next release. Please use `web3-validator` package instead.
+ */
+export const isAddress = isAddressValidator;
+
+/**
+ * Returns true if the bloom is a valid bloom
+ * https://github.com/joshstevens19/ethereum-bloom-filters/blob/fbeb47b70b46243c3963fe1c2988d7461ef17236/src/index.ts#L7
+ *
+ * @deprecated Will be removed in next release. Please use `web3-validator` package instead.
+ */
+export const isBloom = isBloomValidator;
+
+/**
+ * Returns true if the value is part of the given bloom
+ * note: false positives are possible.
+ *
+ * @deprecated Will be removed in next release. Please use `web3-validator` package instead.
+ */
+export const isInBloom = isInBloomValidator;
+
+/**
+ * Returns true if the ethereum users address is part of the given bloom note: false positives are possible.
+ *
+ * @deprecated Will be removed in next release. Please use `web3-validator` package instead.
+ */
+export const isUserEthereumAddressInBloom = isUserEthereumAddressInBloomValidator;
+
+/**
+ * Returns true if the contract address is part of the given bloom.
+ * note: false positives are possible.
+ *
+ * @deprecated Will be removed in next release. Please use `web3-validator` package instead.
+ */
+export const isContractAddressInBloom = isContractAddressInBloomValidator;
+
+/**
+ * Checks if its a valid topic
+ *
+ * @deprecated Will be removed in next release. Please use `web3-validator` package instead.
+ */
+export const isTopic = isTopicValidator;
+
+/**
+ * Returns true if the topic is part of the given bloom.
+ * note: false positives are possible.
+ *
+ * @deprecated Will be removed in next release. Please use `web3-validator` package instead.
+ */
+export const isTopicInBloom = isTopicInBloomValidator;
+
+/**
+ * Compares between block A and block B
+ * @param blockA - Block number or string
+ * @param blockB - Block number or string
+ *
+ * @returns - Returns -1 if a \< b, returns 1 if a \> b and returns 0 if a == b
+ *
+ * @example
+ * ```ts
+ * console.log(web3.utils.compareBlockNumbers('latest', 'pending'));
+ * > -1
+ *
+ * console.log(web3.utils.compareBlockNumbers(12, 11));
+ * > 1
+ * ```
+ */
+export const compareBlockNumbers = (blockA: BlockNumberOrTag, blockB: BlockNumberOrTag) => {
+	const isABlockTag = typeof blockA === 'string' && isBlockTag(blockA);
+	const isBBlockTag = typeof blockB === 'string' && isBlockTag(blockB);
+
+	if (
+		blockA === blockB ||
+		((blockA === 'earliest' || blockA === 0) && (blockB === 'earliest' || blockB === 0)) // only exception compare blocktag with number
+	) {
+		return 0;
+	}
+	if (blockA === 'earliest' && blockB > 0) {
+		return -1;
+	}
+	if (blockB === 'earliest' && blockA > 0) {
+		return 1;
+	}
+
+	if (isABlockTag && isBBlockTag) {
+		// Increasing order:  earliest, finalized , safe, latest, pending
+		const tagsOrder = {
+			[BlockTags.EARLIEST as string]: 1,
+			[BlockTags.FINALIZED as string]: 2,
+			[BlockTags.SAFE as string]: 3,
+			[BlockTags.LATEST as string]: 4,
+			[BlockTags.PENDING as string]: 5,
+		};
+
+		if (tagsOrder[blockA] < tagsOrder[blockB]) {
+			return -1;
+		}
+
+		return 1;
+	}
+	if ((isABlockTag && !isBBlockTag) || (!isABlockTag && isBBlockTag)) {
+		throw new InvalidBlockError('Cannot compare blocktag with provided non-blocktag input.');
+	}
+
+	const bigIntA = BigInt(blockA);
+	const bigIntB = BigInt(blockB);
+
+	if (bigIntA < bigIntB) {
+		return -1;
+	}
+	if (bigIntA === bigIntB) {
+		return 0;
+	}
+	return 1;
+};
+
+export const isContractInitOptions = (options: unknown): options is ContractInitOptions =>
+	typeof options === 'object' &&
+	!isNullishValidator(options) &&
+	Object.keys(options).length !== 0 &&
+	[
+		'input',
+		'data',
+		'from',
+		'gas',
+		'gasPrice',
+		'gasLimit',
+		'address',
+		'jsonInterface',
+		'syncWithContext',
+		'dataInputFill',
+	].some(key => key in options);
+
+export const isNullish = isNullishValidator;

package/src/web3_deferred_promise.ts

@@ -0,0 +1,149 @@
+/*
+This file is part of web3.js.
+
+web3.js is free software: you can redistribute it and/or modify
+it under the terms of the GNU Lesser General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+web3.js is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public License
+along with web3.js.  If not, see <http://www.gnu.org/licenses/>.
+*/
+
+import { OperationTimeoutError } from 'web3-errors';
+import { Web3DeferredPromiseInterface } from 'web3-types';
+import { Timeout } from './promise_helpers.js';
+
+/**
+ * The class is a simple implementation of a deferred promise with optional timeout functionality,
+ * which can be useful when dealing with asynchronous tasks.
+ *
+ */
+export class Web3DeferredPromise<T> implements Promise<T>, Web3DeferredPromiseInterface<T> {
+	// public tag to treat object as promise by different libs
+	// eslint-disable-next-line @typescript-eslint/prefer-as-const
+	public [Symbol.toStringTag]: 'Promise' = 'Promise';
+
+	private readonly _promise: Promise<T>;
+	private _resolve!: (value: T | PromiseLike<T>) => void;
+	private _reject!: (reason?: unknown) => void;
+	private _state: 'pending' | 'fulfilled' | 'rejected' = 'pending';
+	private _timeoutId?: Timeout;
+	private readonly _timeoutInterval?: number;
+	private readonly _timeoutMessage: string;
+
+	/**
+	 *
+	 * @param timeout - (optional) The timeout in milliseconds.
+	 * @param eagerStart - (optional) If true, the timer starts as soon as the promise is created.
+	 * @param timeoutMessage - (optional) The message to include in the timeout erro that is thrown when the promise times out.
+	 */
+	public constructor(
+		{
+			timeout,
+			eagerStart,
+			timeoutMessage,
+		}: { timeout: number; eagerStart: boolean; timeoutMessage: string } = {
+			timeout: 0,
+			eagerStart: false,
+			timeoutMessage: 'DeferredPromise timed out',
+		},
+	) {
+		this._promise = new Promise<T>((resolve, reject) => {
+			this._resolve = resolve;
+			this._reject = reject;
+		});
+
+		this._timeoutMessage = timeoutMessage;
+		this._timeoutInterval = timeout;
+
+		if (eagerStart) {
+			this.startTimer();
+		}
+	}
+	/**
+	 * Returns the current state of the promise.
+	 * @returns 'pending' | 'fulfilled' | 'rejected'
+	 */
+	public get state(): 'pending' | 'fulfilled' | 'rejected' {
+		return this._state;
+	}
+	/**
+	 *
+	 * @param onfulfilled - (optional) The callback to execute when the promise is fulfilled.
+	 * @param onrejected  - (optional) The callback to execute when the promise is rejected.
+	 * @returns
+	 */
+	public async then<TResult1, TResult2>(
+		onfulfilled?: (value: T) => TResult1 | PromiseLike<TResult1>,
+		onrejected?: (reason: unknown) => TResult2 | PromiseLike<TResult2>,
+	): Promise<TResult1 | TResult2> {
+		return this._promise.then(onfulfilled, onrejected);
+	}
+	/**
+	 *
+	 * @param onrejected - (optional) The callback to execute when the promise is rejected.
+	 * @returns
+	 */
+	public async catch<TResult>(
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		onrejected?: (reason: any) => TResult | PromiseLike<TResult>,
+	): Promise<T | TResult> {
+		return this._promise.catch(onrejected);
+	}
+
+	/**
+	 *
+	 * @param onfinally - (optional) The callback to execute when the promise is settled (fulfilled or rejected).
+	 * @returns
+	 */
+	public async finally(onfinally?: (() => void) | undefined): Promise<T> {
+		return this._promise.finally(onfinally);
+	}
+
+	/**
+	 * Resolves the current promise.
+	 * @param value - The value to resolve the promise with.
+	 */
+	public resolve(value: T | PromiseLike<T>): void {
+		this._resolve(value);
+		this._state = 'fulfilled';
+		this._clearTimeout();
+	}
+
+	/**
+	 * Rejects the current promise.
+	 * @param reason - The reason to reject the promise with.
+	 */
+	public reject(reason?: unknown): void {
+		this._reject(reason);
+		this._state = 'rejected';
+		this._clearTimeout();
+	}
+
+	/**
+	 * Starts the timeout timer for the promise.
+	 */
+	public startTimer() {
+		if (this._timeoutInterval && this._timeoutInterval > 0) {
+			this._timeoutId = setTimeout(this._checkTimeout.bind(this), this._timeoutInterval);
+		}
+	}
+
+	private _checkTimeout() {
+		if (this._state === 'pending' && this._timeoutId) {
+			this.reject(new OperationTimeoutError(this._timeoutMessage));
+		}
+	}
+
+	private _clearTimeout() {
+		if (this._timeoutId) {
+			clearTimeout(this._timeoutId);
+		}
+	}
+}