web-eth-abi 4.3.0

package/src/api/parameters_api.ts

@@ -0,0 +1,287 @@
+/*
+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 ABI
+ */
+
+import { AbiError } from 'web3-errors';
+import { AbiInput, HexString } from 'web3-types';
+import { decodeParameters as decodeParametersInternal } from '../coders/decode.js';
+import { encodeParameters } from '../coders/encode.js';
+
+export { encodeParameters, inferTypesAndEncodeParameters } from '../coders/encode.js';
+
+/**
+ * Encodes a parameter based on its type to its ABI representation.
+ * @param abi -  The type of the parameter. See the [Solidity documentation](https://docs.soliditylang.org/en/develop/types.html) for a list of types.
+ * @param param - The actual parameter to encode.
+ * @returns -  The ABI encoded parameter
+ * @example
+ * ```ts
+ *  const res = web3.eth.abi.encodeParameter("uint256", "2345675643");
+ *  console.log(res);
+ *  0x000000000000000000000000000000000000000000000000000000008bd02b7b
+ *
+ *  const res = web3.eth.abi.encodeParameter("uint", "2345675643");
+ *
+ *  console.log(res);
+ *  >0x000000000000000000000000000000000000000000000000000000008bd02b7b
+ *
+ *    const res = web3.eth.abi.encodeParameter("bytes32", "0xdf3234");
+ *
+ *  console.log(res);
+ *  >0xdf32340000000000000000000000000000000000000000000000000000000000
+ *
+ *   const res = web3.eth.abi.encodeParameter("bytes", "0xdf3234");
+ *
+ *  console.log(res);
+ *  > 0x00000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000003df32340000000000000000000000000000000000000000000000000000000000
+ *
+ *   const res = web3.eth.abi.encodeParameter("bytes32[]", ["0xdf3234", "0xfdfd"]);
+ *
+ *  console.log(res);
+ *  > 0x00000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000002df32340000000000000000000000000000000000000000000000000000000000fdfd000000000000000000000000000000000000000000000000000000000000
+ *
+ *  const res = web3.eth.abi.encodeParameter(
+ *    {
+ *      ParentStruct: {
+ *        propertyOne: "uint256",
+ *        propertyTwo: "uint256",
+ *        childStruct: {
+ *          propertyOne: "uint256",
+ *          propertyTwo: "uint256",
+ *        },
+ *      },
+ *    },
+ *    {
+ *      propertyOne: 42,
+ *      propertyTwo: 56,
+ *      childStruct: {
+ *        propertyOne: 45,
+ *        propertyTwo: 78,
+ *      },
+ *    }
+ *  );
+ *
+ *  console.log(res);
+ *  > 0x000000000000000000000000000000000000000000000000000000000000002a0000000000000000000000000000000000000000000000000000000000000038000000000000000000000000000000000000000000000000000000000000002d000000000000000000000000000000000000000000000000000000000000004e
+ * ```
+ */
+export const encodeParameter = (abi: AbiInput, param: unknown): string =>
+	encodeParameters([abi], [param]);
+/**
+ * Should be used to decode list of params
+ */
+export const decodeParametersWith = (
+	abis: AbiInput[] | ReadonlyArray<AbiInput>,
+	bytes: HexString,
+	loose: boolean,
+): { [key: string]: unknown; __length__: number } => {
+	try {
+		if (abis.length > 0 && (!bytes || bytes === '0x' || bytes === '0X')) {
+			throw new AbiError(
+				"Returned values aren't valid, did it run Out of Gas? " +
+					'You might also see this error if you are not using the ' +
+					'correct ABI for the contract you are retrieving data from, ' +
+					'requesting data from a block number that does not exist, ' +
+					'or querying a node which is not fully synced.',
+			);
+		}
+		return decodeParametersInternal(abis, `0x${bytes.replace(/0x/i, '')}`, loose);
+	} catch (err) {
+		throw new AbiError(`Parameter decoding error: ${(err as Error).message}`, {
+			internalErr: err,
+		});
+	}
+};
+
+/**
+ * Should be used to decode list of params
+ */
+/**
+ * Decodes ABI encoded parameters to its JavaScript types.
+ * @param abi -  An array of {@link AbiInput}. See the [Solidity documentation](https://docs.soliditylang.org/en/develop/types.html) for a list of types.
+ * @param bytes - The ABI byte code to decode
+ * @returns - The result object containing the decoded parameters.
+ * @example
+ * ```ts
+ * let res = web3.eth.abi.decodeParameters(
+ *    ["string", "uint256"],
+ *    "0x000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000ea000000000000000000000000000000000000000000000000000000000000000848656c6c6f212521000000000000000000000000000000000000000000000000"
+ *  );
+ *  console.log(res);
+ *  > { '0': 'Hello!%!', '1': 234n, __length__: 2 }
+ *
+ * let res = web3.eth.abi.decodeParameters(
+ *    [
+ *      {
+ *        type: "string",
+ *        name: "myString",
+ *      },
+ *      {
+ *        type: "uint256",
+ *        name: "myNumber",
+ *      },
+ *    ],
+ *    "0x000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000ea000000000000000000000000000000000000000000000000000000000000000848656c6c6f212521000000000000000000000000000000000000000000000000"
+ *  );
+ * console.log(res);
+ *  > {
+ *  '0': 'Hello!%!',
+ *  '1': 234n,
+ *  __length__: 2,
+ *  myString: 'Hello!%!',
+ *  myNumber: 234n
+ * }
+ *
+ * const res = web3.eth.abi.decodeParameters(
+ *    [
+ *      "uint8[]",
+ *      {
+ *        ParentStruct: {
+ *          propertyOne: "uint256",
+ *          propertyTwo: "uint256",
+ *          childStruct: {
+ *            propertyOne: "uint256",
+ *            propertyTwo: "uint256",
+ *          },
+ *        },
+ *      },
+ *    ],
+ *    "0x00000000000000000000000000000000000000000000000000000000000000a0000000000000000000000000000000000000000000000000000000000000002a0000000000000000000000000000000000000000000000000000000000000038000000000000000000000000000000000000000000000000000000000000002d000000000000000000000000000000000000000000000000000000000000004e0000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000002a0000000000000000000000000000000000000000000000000000000000000018"
+ *  );
+ *  console.log(res);
+ *  >
+ *  '0': [ 42n, 24n ],
+ *  '1': {
+ *    '0': 42n,
+ *    '1': 56n,
+ *    '2': {
+ *      '0': 45n,
+ *      '1': 78n,
+ *      __length__: 2,
+ *      propertyOne: 45n,
+ *      propertyTwo: 78n
+ *    },
+ *    __length__: 3,
+ *    propertyOne: 42n,
+ *    propertyTwo: 56n,
+ *    childStruct: {
+ *      '0': 45n,
+ *      '1': 78n,
+ *      __length__: 2,
+ *      propertyOne: 45n,
+ *      propertyTwo: 78n
+ *    }
+ *  },
+ *  __length__: 2,
+ *  ParentStruct: {
+ *    '0': 42n,
+ *    '1': 56n,
+ *    '2': {
+ *      '0': 45n,
+ *      '1': 78n,
+ *      __length__: 2,
+ *      propertyOne: 45n,
+ *      propertyTwo: 78n
+ *    },
+ *    __length__: 3,
+ *    propertyOne: 42n,
+ *    propertyTwo: 56n,
+ *    childStruct: {
+ *      '0': 45n,
+ *      '1': 78n,
+ *      __length__: 2,
+ *      propertyOne: 45n,
+ *      propertyTwo: 78n
+ *    }
+ *  }
+ *}
+ * ```
+ */
+export const decodeParameters = (
+	abi: AbiInput[] | ReadonlyArray<AbiInput>,
+	bytes: HexString,
+): { [key: string]: unknown; __length__: number } => decodeParametersWith(abi, bytes, false);
+
+/**
+ * Should be used to decode bytes to plain param
+ */
+/**
+ * Decodes an ABI encoded parameter to its JavaScript type.
+ * @param abi -  The type of the parameter. See the [Solidity documentation](https://docs.soliditylang.org/en/develop/types.html) for a list of types.
+ * @param bytes - The ABI byte code to decode
+ * @returns - The decoded parameter
+ * @example
+ * ```ts
+ *   const res = web3.eth.abi.decodeParameter(
+ *    "uint256",
+ *    "0x0000000000000000000000000000000000000000000000000000000000000010"
+ *  );
+ *  console.log(res);
+ * > 16n
+ *
+ *  const res = web3.eth.abi.decodeParameter(
+ *    "string",
+ *    "0x0000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000000848656c6c6f212521000000000000000000000000000000000000000000000000"
+ *  );
+ *
+ *  console.log(res);
+ *  > Hello!%!
+ *
+ *  const res = web3.eth.abi.decodeParameter(
+ *    {
+ *      ParentStruct: {
+ *        propertyOne: "uint256",
+ *        propertyTwo: "uint256",
+ *        childStruct: {
+ *          propertyOne: "uint256",
+ *          propertyTwo: "uint256",
+ *        },
+ *      },
+ *    },
+ *    "0x000000000000000000000000000000000000000000000000000000000000002a0000000000000000000000000000000000000000000000000000000000000038000000000000000000000000000000000000000000000000000000000000002d000000000000000000000000000000000000000000000000000000000000004e"
+ *  );
+ *
+ *  console.log(res);
+ *   {
+ *  '0': 42n,
+ *  '1': 56n,
+ *  '2': {
+ *    '0': 45n,
+ *    '1': 78n,
+ *    __length__: 2,
+ *    propertyOne: 45n,
+ *    propertyTwo: 78n
+ *  },
+ *  __length__: 3,
+ *  propertyOne: 42n,
+ *  propertyTwo: 56n,
+ *  childStruct: {
+ *    '0': 45n,
+ *    '1': 78n,
+ *    __length__: 2,
+ *    propertyOne: 45n,
+ *    propertyTwo: 78n
+ *  }
+ *}
+ * ```
+ */
+export const decodeParameter = (abi: AbiInput, bytes: HexString): unknown =>
+	decodeParameters([abi], bytes)['0'];

package/src/coders/base/address.ts

@@ -0,0 +1,75 @@
+/*
+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 { toChecksumAddress } from 'web3-utils';
+import { isAddress, utils } from 'web3-validator';
+import { DecoderResult, EncoderResult } from '../types.js';
+import { alloc, WORD_SIZE } from '../utils.js';
+
+const ADDRESS_BYTES_COUNT = 20;
+const ADDRESS_OFFSET = WORD_SIZE - ADDRESS_BYTES_COUNT;
+
+export function encodeAddress(param: AbiParameter, input: unknown): EncoderResult {
+	if (typeof input !== 'string') {
+		throw new AbiError('address type expects string as input type', {
+			value: input,
+			name: param.name,
+			type: param.type,
+		});
+	}
+	let address = input.toLowerCase();
+	if (!address.startsWith('0x')) {
+		address = `0x${address}`;
+	}
+	if (!isAddress(address)) {
+		throw new AbiError('provided input is not valid address', {
+			value: input,
+			name: param.name,
+			type: param.type,
+		});
+	}
+	// for better performance, we could convert hex to destination bytes directly (encoded var)
+	const addressBytes = utils.hexToUint8Array(address);
+	// expand address to WORD_SIZE
+	const encoded = alloc(WORD_SIZE);
+	encoded.set(addressBytes, ADDRESS_OFFSET);
+	return {
+		dynamic: false,
+		encoded,
+	};
+}
+
+export function decodeAddress(_param: AbiParameter, bytes: Uint8Array): DecoderResult<string> {
+	const addressBytes = bytes.subarray(ADDRESS_OFFSET, WORD_SIZE);
+	if (addressBytes.length !== ADDRESS_BYTES_COUNT) {
+		throw new AbiError('Invalid decoding input, not enough bytes to decode address', { bytes });
+	}
+	const result = utils.uint8ArrayToHexString(addressBytes);
+
+	// should we check is decoded value is valid address?
+	// if(!isAddress(result)) {
+	//     throw new AbiError("encoded data is not valid address", {
+	//         address: result,
+	//     });
+	// }
+	return {
+		result: toChecksumAddress(result),
+		encoded: bytes.subarray(WORD_SIZE),
+		consumed: WORD_SIZE,
+	};
+}

package/src/coders/base/array.ts

@@ -0,0 +1,120 @@
+/*
+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';
+// eslint-disable-next-line import/no-cycle
+import { decodeParamFromAbiParameter, encodeNumber, encodeParamFromAbiParameter } from './index.js';
+import { DecoderResult, EncoderResult } from '../types.js';
+import { extractArrayType, isDynamic, WORD_SIZE } from '../utils.js';
+import { decodeNumber } from './number.js';
+import { encodeDynamicParams } from './utils.js';
+
+export function encodeArray(param: AbiParameter, values: unknown): EncoderResult {
+	if (!Array.isArray(values)) {
+		throw new AbiError('Expected value to be array', { abi: param, values });
+	}
+	const { size, param: arrayItemParam } = extractArrayType(param);
+	const encodedParams = values.map(v => encodeParamFromAbiParameter(arrayItemParam, v));
+	const dynamic = size === -1;
+	const dynamicItems = encodedParams.length > 0 && encodedParams[0].dynamic;
+	if (!dynamic && values.length !== size) {
+		throw new AbiError("Given arguments count doesn't match array length", {
+			arrayLength: size,
+			argumentsLength: values.length,
+		});
+	}
+	if (dynamic || dynamicItems) {
+		const encodingResult = encodeDynamicParams(encodedParams);
+		if (dynamic) {
+			const encodedLength = encodeNumber(
+				{ type: 'uint256', name: '' },
+				encodedParams.length,
+			).encoded;
+			return {
+				dynamic: true,
+				encoded:
+					encodedParams.length > 0
+						? uint8ArrayConcat(encodedLength, encodingResult)
+						: encodedLength,
+			};
+		}
+		return {
+			dynamic: true,
+			encoded: encodingResult,
+		};
+	}
+
+	return {
+		dynamic: false,
+		encoded: uint8ArrayConcat(...encodedParams.map(p => p.encoded)),
+	};
+}
+
+export function decodeArray(param: AbiParameter, bytes: Uint8Array): DecoderResult<unknown[]> {
+	// eslint-disable-next-line prefer-const
+	let { size, param: arrayItemParam } = extractArrayType(param);
+	const dynamic = size === -1;
+
+	let consumed = 0;
+	const result: unknown[] = [];
+	let remaining = bytes;
+	// dynamic array, we need to decode length
+	if (dynamic) {
+		const lengthResult = decodeNumber({ type: 'uint32', name: '' }, bytes);
+		size = Number(lengthResult.result);
+		consumed = lengthResult.consumed;
+		remaining = lengthResult.encoded;
+	}
+	const hasDynamicChild = isDynamic(arrayItemParam);
+	if (hasDynamicChild) {
+		// known length but dynamic child, each child is actually head element with encoded offset
+		for (let i = 0; i < size; i += 1) {
+			const offsetResult = decodeNumber(
+				{ type: 'uint32', name: '' },
+				remaining.subarray(i * WORD_SIZE),
+			);
+			consumed += offsetResult.consumed;
+			const decodedChildResult = decodeParamFromAbiParameter(
+				arrayItemParam,
+				remaining.subarray(Number(offsetResult.result)),
+			);
+			consumed += decodedChildResult.consumed;
+			result.push(decodedChildResult.result);
+		}
+		return {
+			result,
+			encoded: remaining.subarray(consumed),
+			consumed,
+		};
+	}
+
+	for (let i = 0; i < size; i += 1) {
+		// decode static params
+		const decodedChildResult = decodeParamFromAbiParameter(
+			arrayItemParam,
+			bytes.subarray(consumed),
+		);
+		consumed += decodedChildResult.consumed;
+		result.push(decodedChildResult.result);
+	}
+	return {
+		result,
+		encoded: bytes.subarray(consumed),
+		consumed,
+	};
+}

package/src/coders/base/bool.ts

@@ -0,0 +1,54 @@
+/*
+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, InvalidBooleanError } from 'web3-errors';
+import { AbiParameter } from 'web3-types';
+import { toBool } from 'web3-utils';
+import { DecoderResult, EncoderResult } from '../types.js';
+import { WORD_SIZE } from '../utils.js';
+import { decodeNumber, encodeNumber } from './number.js';
+
+export function encodeBoolean(param: AbiParameter, input: unknown): EncoderResult {
+	let value;
+	try {
+		value = toBool(input);
+	} catch (e) {
+		if (e instanceof InvalidBooleanError) {
+			throw new AbiError('provided input is not valid boolean value', {
+				type: param.type,
+				value: input,
+				name: param.name,
+			});
+		}
+	}
+
+	return encodeNumber({ type: 'uint8', name: '' }, Number(value));
+}
+
+export function decodeBool(_param: AbiParameter, bytes: Uint8Array): DecoderResult<boolean> {
+	const numberResult = decodeNumber({ type: 'uint8', name: '' }, bytes);
+	if (numberResult.result > 1 || numberResult.result < 0) {
+		throw new AbiError('Invalid boolean value encoded', {
+			boolBytes: bytes.subarray(0, WORD_SIZE),
+			numberResult,
+		});
+	}
+	return {
+		result: numberResult.result === BigInt(1),
+		encoded: numberResult.encoded,
+		consumed: WORD_SIZE,
+	};
+}

package/src/coders/base/bytes.ts

@@ -0,0 +1,106 @@
+/*
+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, Bytes } from 'web3-types';
+import { bytesToHex, bytesToUint8Array } from 'web3-utils';
+import { isBytes, ValidInputTypes } from 'web3-validator';
+import { DecoderResult, EncoderResult } from '../types.js';
+import { alloc, WORD_SIZE } from '../utils.js';
+import { decodeNumber, encodeNumber } from './number.js';
+
+const MAX_STATIC_BYTES_COUNT = 32;
+
+export function encodeBytes(param: AbiParameter, input: unknown): EncoderResult {
+	// hack for odd length hex strings
+	if (typeof input === 'string' && input.length % 2 !== 0) {
+		// eslint-disable-next-line no-param-reassign
+		input += '0';
+	}
+	if (!isBytes(input as ValidInputTypes)) {
+		throw new AbiError('provided input is not valid bytes value', {
+			type: param.type,
+			value: input,
+			name: param.name,
+		});
+	}
+	const bytes = bytesToUint8Array(input as Bytes);
+	const [, size] = param.type.split('bytes');
+	// fixed size
+	if (size) {
+		if (Number(size) > MAX_STATIC_BYTES_COUNT || Number(size) < 1) {
+			throw new AbiError(
+				'invalid bytes type. Static byte type can have between 1 and 32 bytes',
+				{
+					type: param.type,
+				},
+			);
+		}
+		if (Number(size) < bytes.length) {
+			throw new AbiError('provided input size is different than type size', {
+				type: param.type,
+				value: input,
+				name: param.name,
+			});
+		}
+		const encoded = alloc(WORD_SIZE);
+		encoded.set(bytes);
+		return {
+			dynamic: false,
+			encoded,
+		};
+	}
+
+	const partsLength = Math.ceil(bytes.length / WORD_SIZE);
+	// one word for length of data + WORD for each part of actual data
+	const encoded = alloc(WORD_SIZE + partsLength * WORD_SIZE);
+
+	encoded.set(encodeNumber({ type: 'uint32', name: '' }, bytes.length).encoded);
+	encoded.set(bytes, WORD_SIZE);
+	return {
+		dynamic: true,
+		encoded,
+	};
+}
+
+export function decodeBytes(param: AbiParameter, bytes: Uint8Array): DecoderResult<string> {
+	const [, sizeString] = param.type.split('bytes');
+	let size = Number(sizeString);
+	let remainingBytes = bytes;
+	let partsCount = 1;
+	let consumed = 0;
+	if (!size) {
+		// dynamic bytes
+		const result = decodeNumber({ type: 'uint32', name: '' }, remainingBytes);
+		size = Number(result.result);
+		consumed += result.consumed;
+		remainingBytes = result.encoded;
+		partsCount = Math.ceil(size / WORD_SIZE);
+	}
+	if (size > bytes.length) {
+		throw new AbiError('there is not enough data to decode', {
+			type: param.type,
+			encoded: bytes,
+			size,
+		});
+	}
+
+	return {
+		result: bytesToHex(remainingBytes.subarray(0, size)),
+		encoded: remainingBytes.subarray(partsCount * WORD_SIZE),
+		consumed: consumed + partsCount * WORD_SIZE,
+	};
+}