web-eth-abi 4.3.0

package/src/coders/base/index.ts

@@ -0,0 +1,95 @@
+/*
+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 { AbiParameter } from 'web3-types';
+import { AbiError } from 'web3-errors';
+import { EncoderResult, DecoderResult } from '../types.js';
+import { decodeAddress, encodeAddress } from './address.js';
+import { decodeBool, encodeBoolean } from './bool.js';
+import { decodeBytes, encodeBytes } from './bytes.js';
+import { decodeNumber, encodeNumber } from './number.js';
+import { decodeString, encodeString } from './string.js';
+// eslint-disable-next-line import/no-cycle
+import { decodeTuple, encodeTuple } from './tuple.js';
+// eslint-disable-next-line import/no-cycle
+import { decodeArray, encodeArray } from './array.js';
+
+export { encodeAddress, decodeAddress } from './address.js';
+export { encodeBoolean, decodeBool } from './bool.js';
+export { encodeBytes, decodeBytes } from './bytes.js';
+export { encodeNumber, decodeNumber } from './number.js';
+export { encodeString, decodeString } from './string.js';
+// eslint-disable-next-line import/no-cycle
+export { encodeTuple, decodeTuple } from './tuple.js';
+// eslint-disable-next-line import/no-cycle
+export { encodeArray, decodeArray } from './array.js';
+
+export function encodeParamFromAbiParameter(param: AbiParameter, value: unknown): EncoderResult {
+	if (param.type === 'string') {
+		return encodeString(param, value);
+	}
+	if (param.type === 'bool') {
+		return encodeBoolean(param, value);
+	}
+	if (param.type === 'address') {
+		return encodeAddress(param, value);
+	}
+	if (param.type === 'tuple') {
+		return encodeTuple(param, value);
+	}
+	if (param.type.endsWith(']')) {
+		return encodeArray(param, value);
+	}
+	if (param.type.startsWith('bytes')) {
+		return encodeBytes(param, value);
+	}
+	if (param.type.startsWith('uint') || param.type.startsWith('int')) {
+		return encodeNumber(param, value);
+	}
+	throw new AbiError('Unsupported', {
+		param,
+		value,
+	});
+}
+
+export function decodeParamFromAbiParameter(param: AbiParameter, bytes: Uint8Array): DecoderResult {
+	if (param.type === 'string') {
+		return decodeString(param, bytes);
+	}
+	if (param.type === 'bool') {
+		return decodeBool(param, bytes);
+	}
+	if (param.type === 'address') {
+		return decodeAddress(param, bytes);
+	}
+	if (param.type === 'tuple') {
+		return decodeTuple(param, bytes);
+	}
+	if (param.type.endsWith(']')) {
+		return decodeArray(param, bytes);
+	}
+	if (param.type.startsWith('bytes')) {
+		return decodeBytes(param, bytes);
+	}
+	if (param.type.startsWith('uint') || param.type.startsWith('int')) {
+		return decodeNumber(param, bytes);
+	}
+	throw new AbiError('Unsupported', {
+		param,
+		bytes,
+	});
+}

package/src/coders/base/number.ts

@@ -0,0 +1,116 @@
+/*
+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 { AbiError } from 'web3-errors';
+import type { AbiParameter } from 'web3-types';
+import { padLeft, toBigInt } from 'web3-utils';
+import { utils } from 'web3-validator';
+import { DecoderResult, EncoderResult } from '../types.js';
+import { WORD_SIZE } from '../utils.js';
+import { numberLimits } from './numbersLimits.js';
+
+// eslint-disable-next-line no-bitwise
+const mask = BigInt(1) << BigInt(256);
+
+function bigIntToUint8Array(value: bigint, byteLength = WORD_SIZE): Uint8Array {
+	let hexValue;
+	if (value < 0) {
+		hexValue = (mask + value).toString(16);
+	} else {
+		hexValue = value.toString(16);
+	}
+	hexValue = padLeft(hexValue, byteLength * 2);
+	return utils.hexToUint8Array(hexValue);
+}
+
+function uint8ArrayToBigInt(value: Uint8Array, max: bigint): bigint {
+	const hexValue = utils.uint8ArrayToHexString(value);
+	const result = BigInt(hexValue);
+	if (result <= max) return result;
+	return result - mask;
+}
+
+export function encodeNumber(param: AbiParameter, input: unknown): EncoderResult {
+	let value;
+	try {
+		value = toBigInt(input);
+	} catch (e) {
+		throw new AbiError('provided input is not number value', {
+			type: param.type,
+			value: input,
+			name: param.name,
+		});
+	}
+	const limit = numberLimits.get(param.type);
+	if (!limit) {
+		throw new AbiError('provided abi contains invalid number datatype', { type: param.type });
+	}
+	if (value < limit.min) {
+		throw new AbiError('provided input is less then minimum for given type', {
+			type: param.type,
+			value: input,
+			name: param.name,
+			minimum: limit.min.toString(),
+		});
+	}
+	if (value > limit.max) {
+		throw new AbiError('provided input is greater then maximum for given type', {
+			type: param.type,
+			value: input,
+			name: param.name,
+			maximum: limit.max.toString(),
+		});
+	}
+	return {
+		dynamic: false,
+		encoded: bigIntToUint8Array(value),
+	};
+}
+
+export function decodeNumber(param: AbiParameter, bytes: Uint8Array): DecoderResult<bigint> {
+	if (bytes.length < WORD_SIZE) {
+		throw new AbiError('Not enough bytes left to decode', { param, bytesLeft: bytes.length });
+	}
+	const boolBytes = bytes.subarray(0, WORD_SIZE);
+	const limit = numberLimits.get(param.type);
+	if (!limit) {
+		throw new AbiError('provided abi contains invalid number datatype', { type: param.type });
+	}
+	const numberResult = uint8ArrayToBigInt(boolBytes, limit.max);
+
+	if (numberResult < limit.min) {
+		throw new AbiError('decoded value is less then minimum for given type', {
+			type: param.type,
+			value: numberResult,
+			name: param.name,
+			minimum: limit.min.toString(),
+		});
+	}
+	if (numberResult > limit.max) {
+		throw new AbiError('decoded value is greater then maximum for given type', {
+			type: param.type,
+			value: numberResult,
+			name: param.name,
+			maximum: limit.max.toString(),
+		});
+	}
+	return {
+		result: numberResult,
+		encoded: bytes.subarray(WORD_SIZE),
+		consumed: WORD_SIZE,
+	};
+}

package/src/coders/base/numbersLimits.ts

@@ -0,0 +1,39 @@
+/*
+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/>.
+*/
+
+/*
+ * this variable contains the precalculated limits for all the numbers for uint and int types
+ */
+export const numberLimits = new Map<string, { min: bigint; max: bigint }>();
+
+let base = BigInt(256); // 2 ^ 8 = 256
+for (let i = 8; i <= 256; i += 8) {
+	numberLimits.set(`uint${i}`, {
+		min: BigInt(0),
+		max: base - BigInt(1),
+	});
+	numberLimits.set(`int${i}`, {
+		min: -base / BigInt(2),
+		max: base / BigInt(2) - BigInt(1),
+	});
+	base *= BigInt(256);
+}
+
+// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+numberLimits.set(`int`, numberLimits.get('int256')!);
+// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+numberLimits.set(`uint`, numberLimits.get('uint256')!);

package/src/coders/base/string.ts

@@ -0,0 +1,38 @@
+/*
+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 { AbiError } from 'web3-errors';
+import { AbiParameter } from 'web3-types';
+import { hexToUtf8, utf8ToBytes } from 'web3-utils';
+import { DecoderResult, EncoderResult } from '../types.js';
+import { decodeBytes, encodeBytes } from './bytes.js';
+
+export function encodeString(_param: AbiParameter, input: unknown): EncoderResult {
+	if (typeof input !== 'string') {
+		throw new AbiError('invalid input, should be string', { input });
+	}
+	const bytes = utf8ToBytes(input);
+	return encodeBytes({ type: 'bytes', name: '' }, bytes);
+}
+
+export function decodeString(_param: AbiParameter, bytes: Uint8Array): DecoderResult<string> {
+	const r = decodeBytes({ type: 'bytes', name: '' }, bytes);
+	return {
+		result: hexToUtf8(r.result),
+		encoded: r.encoded,
+		consumed: r.consumed,
+	};
+}

package/src/coders/base/tuple.ts

@@ -0,0 +1,130 @@
+/*
+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 { AbiError } from 'web3-errors';
+import { AbiParameter } from 'web3-types';
+import { uint8ArrayConcat } from 'web3-utils';
+import { DecoderResult, EncoderResult } from '../types.js';
+// eslint-disable-next-line import/no-cycle
+import { decodeParamFromAbiParameter, encodeParamFromAbiParameter } from './index.js';
+import { encodeDynamicParams } from './utils.js';
+import { isDynamic } from '../utils.js';
+import { decodeNumber } from './number.js';
+
+export function encodeTuple(param: AbiParameter, input: unknown): EncoderResult {
+	let dynamic = false;
+	if (!Array.isArray(input) && typeof input !== 'object') {
+		throw new AbiError('param must be either Array or Object', {
+			param,
+			input,
+		});
+	}
+	const narrowedInput = input as Array<unknown> | Record<string, unknown>;
+	const encoded: Array<EncoderResult> = [];
+	for (let i = 0; i < (param.components?.length ?? 0); i += 1) {
+		// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+		const paramComponent = param.components![i];
+		let result: EncoderResult;
+		if (Array.isArray(narrowedInput)) {
+			if (i >= narrowedInput.length) {
+				throw new AbiError('input param length missmatch', {
+					param,
+					input,
+				});
+			}
+			result = encodeParamFromAbiParameter(paramComponent, narrowedInput[i]);
+		} else {
+			const paramInput = narrowedInput[paramComponent.name ?? ''];
+			// eslint-disable-next-line no-null/no-null
+			if (paramInput === undefined || paramInput === null) {
+				throw new AbiError('missing input defined in abi', {
+					param,
+					input,
+					paramName: paramComponent.name,
+				});
+			}
+			result = encodeParamFromAbiParameter(paramComponent, paramInput);
+		}
+		if (result.dynamic) {
+			dynamic = true;
+		}
+		encoded.push(result);
+	}
+
+	if (dynamic) {
+		return {
+			dynamic: true,
+			encoded: encodeDynamicParams(encoded),
+		};
+	}
+	return {
+		dynamic: false,
+		encoded: uint8ArrayConcat(...encoded.map(e => e.encoded)),
+	};
+}
+
+export function decodeTuple(
+	param: AbiParameter,
+	bytes: Uint8Array,
+): DecoderResult<{ [key: string]: unknown; __length__: number }> {
+	const result: { [key: string]: unknown; __length__: number } = {
+		__length__: 0,
+	};
+
+	// tracks how much static params consumed bytes
+	let consumed = 0;
+
+	if (!param.components) {
+		return {
+			result,
+			encoded: bytes,
+			consumed,
+		};
+	}
+	// track how much dynamic params consumed bytes
+	let dynamicConsumed = 0;
+	for (const [index, childParam] of param.components.entries()) {
+		let decodedResult: DecoderResult;
+		if (isDynamic(childParam)) {
+			// if dynamic, we will have offset encoded
+			const offsetResult = decodeNumber(
+				{ type: 'uint32', name: '' },
+				bytes.subarray(consumed),
+			);
+			// offset counts from start of original byte sequence
+			decodedResult = decodeParamFromAbiParameter(
+				childParam,
+				bytes.subarray(Number(offsetResult.result)),
+			);
+			consumed += offsetResult.consumed;
+			dynamicConsumed += decodedResult.consumed;
+		} else {
+			// static param, just decode
+			decodedResult = decodeParamFromAbiParameter(childParam, bytes.subarray(consumed));
+			consumed += decodedResult.consumed;
+		}
+		result.__length__ += 1;
+		result[index] = decodedResult.result;
+		if (childParam.name && childParam.name !== '') {
+			result[childParam.name] = decodedResult.result;
+		}
+	}
+	return {
+		encoded: bytes.subarray(consumed + dynamicConsumed),
+		result,
+		consumed: consumed + dynamicConsumed,
+	};
+}

package/src/coders/base/utils.ts

@@ -0,0 +1,51 @@
+/*
+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 { uint8ArrayConcat } from 'web3-utils';
+import { EncoderResult } from '../types.js';
+import { WORD_SIZE } from '../utils.js';
+import { encodeNumber } from './number.js';
+
+export function encodeDynamicParams(encodedParams: ReadonlyArray<EncoderResult>): Uint8Array {
+	let staticSize = 0;
+	let dynamicSize = 0;
+	const staticParams: EncoderResult[] = [];
+	const dynamicParams: EncoderResult[] = [];
+	// figure out static size
+	for (const encodedParam of encodedParams) {
+		if (encodedParam.dynamic) {
+			staticSize += WORD_SIZE;
+		} else {
+			staticSize += encodedParam.encoded.length;
+		}
+	}
+
+	for (const encodedParam of encodedParams) {
+		if (encodedParam.dynamic) {
+			staticParams.push(
+				encodeNumber({ type: 'uint256', name: '' }, staticSize + dynamicSize),
+			);
+			dynamicParams.push(encodedParam);
+			dynamicSize += encodedParam.encoded.length;
+		} else {
+			staticParams.push(encodedParam);
+		}
+	}
+	return uint8ArrayConcat(
+		...staticParams.map(p => p.encoded),
+		...dynamicParams.map(p => p.encoded),
+	);
+}

package/src/coders/decode.ts

@@ -0,0 +1,32 @@
+/*
+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 { AbiInput, HexString } from 'web3-types';
+import { utils } from 'web3-validator';
+import { decodeTuple } from './base/tuple.js';
+import { toAbiParams } from './utils.js';
+
+export function decodeParameters(
+	abis: AbiInput[] | ReadonlyArray<AbiInput>,
+	bytes: HexString,
+	_loose: boolean,
+): { [key: string]: unknown; __length__: number } {
+	const abiParams = toAbiParams(abis);
+	const bytesArray = utils.hexToUint8Array(bytes);
+
+	return decodeTuple({ type: 'tuple', name: '', components: abiParams }, bytesArray).result;
+}

package/src/coders/encode.ts

@@ -0,0 +1,114 @@
+/*
+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 { AbiError } from 'web3-errors';
+import { AbiInput, AbiParameter } from 'web3-types';
+import { toHex } from 'web3-utils';
+import { utils } from 'web3-validator';
+import { encodeTuple } from './base/index.js';
+import { toAbiParams } from './utils.js';
+
+/**
+ * @param params - The params to infer the ABI from
+ * @returns The inferred ABI
+ * @example
+ * ```
+ * inferParamsAbi([1, -1, 'hello', '0x1234', ])
+ * ```
+ * > [{ type: 'int256' }, { type: 'uint256' }, { type: 'string' }, { type: 'bytes' }]
+ * ```
+ */
+function inferParamsAbi(params: unknown[]): ReadonlyArray<AbiParameter> {
+	const abi: AbiParameter[] = [];
+	params.forEach(param => {
+		if (Array.isArray(param)) {
+			const inferredParams = inferParamsAbi(param);
+			abi.push({
+				type: 'tuple',
+				components: inferredParams,
+				name: '',
+				// eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+			} as AbiParameter);
+		} else {
+			// eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+			abi.push({ type: toHex(param as any, true) } as AbiParameter);
+		}
+	});
+	return abi;
+}
+
+/**
+ * Encodes a parameter based on its type to its ABI representation.
+ * @param abi - An array of {@link AbiInput}. See [Solidity's documentation](https://solidity.readthedocs.io/en/v0.5.3/abi-spec.html#json) for more details.
+ * @param params - The actual parameters to encode.
+ * @returns - The ABI encoded parameters
+ * @example
+ * ```ts
+ * const res = web3.eth.abi.encodeParameters(
+ *    ["uint256", "string"],
+ *    ["2345675643", "Hello!%"]
+ *  );
+ *
+ *  console.log(res);
+ *  > 0x000000000000000000000000000000000000000000000000000000008bd02b7b0000000000000000000000000000000000000000000000000000000000000040000000000000000000000000000000000000000000000000000000000000000748656c6c6f212500000000000000000000000000000000000000000000000000
+ * ```
+ */
+export function encodeParameters(abi: ReadonlyArray<AbiInput>, params: unknown[]): string {
+	if (abi?.length !== params.length) {
+		throw new AbiError('Invalid number of values received for given ABI', {
+			expected: abi?.length,
+			received: params.length,
+		});
+	}
+
+	const abiParams = toAbiParams(abi);
+	return utils.uint8ArrayToHexString(
+		encodeTuple({ type: 'tuple', name: '', components: abiParams }, params).encoded,
+	);
+}
+
+/**
+ * Infer a smart contract method parameter type and then encode this parameter.
+ * @param params - The parameters to encode.
+ * @returns - The ABI encoded parameters
+ *
+ * @remarks
+ * This method is useful when you don't know the type of the parameters you want to encode. It will infer the type of the parameters and then encode them.
+ * However, it is not recommended to use this method when you know the type of the parameters you want to encode. In this case, use the {@link encodeParameters} method instead.
+ * The type inference is not perfect and can lead to unexpected results. Especially when you want to encode an array, uint that is not uint256 or bytes....
+ * @example
+ * ```ts
+ * const res = web3.eth.abi.encodeParameters(
+ *    ["2345675643", "Hello!%"]
+ *  );
+ *
+ *  console.log(res);
+ *  > 0x000000000000000000000000000000000000000000000000000000008bd02b7b0000000000000000000000000000000000000000000000000000000000000040000000000000000000000000000000000000000000000000000000000000000748656c6c6f212500000000000000000000000000000000000000000000000000
+ * ```
+ */
+export function inferTypesAndEncodeParameters(params: unknown[]): string {
+	try {
+		const abiParams = inferParamsAbi(params);
+		return utils.uint8ArrayToHexString(
+			encodeTuple({ type: 'tuple', name: '', components: abiParams }, params).encoded,
+		);
+	} catch (e) {
+		// throws If the inferred params type caused an error
+		throw new AbiError('Could not infer types from given params', {
+			params,
+		});
+	}
+}

package/src/coders/types.ts

@@ -0,0 +1,39 @@
+/*
+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 type EncoderResult = {
+	dynamic: boolean;
+
+	encoded: Uint8Array;
+};
+export type DecoderResult<T = unknown> = {
+	result: T;
+
+	// remaining bytes not yet decoded
+	encoded: Uint8Array;
+
+	// number of bytes consumed
+	consumed: number;
+};
+
+export type NumberType = {
+	signed: boolean;
+	byteLength: number;
+};
+export type BytesType = {
+	size?: number;
+};