Decoding EIP-838 error codes

CHANGELOG.md

@@ -736,17 +736,31 @@ should use 4.0.1-alpha.0 for testing.
 
 ### Added
 
+#### web3-core
+
+-   If the response error was `execution reverted`, raise `ContractExecutionError` and pass the response error to it in order to be set as `innerError` (this innerError will be decoded at web3-eth-contract if its ABI was provided according to EIP-838). (#5434)
+
 #### web3-error
 
--   Add optional `innerError` property to the abstract class `Web3Error`.
+-   Add optional `innerError` property to the abstract class `Web3Error`. This `innerError` could be `Error`, `Error[]` or `undefined`. (#5435) (#5434)
+-   The class `Web3ContractError` is moved to this package from `web3-eth-contract`. (#5434)
+
+#### web3-eth-abi
+
+-   If an error happens when decoding a value, preserve that exception at `innerError` inside the error class `AbiError`. (#5435)
+-   Add basic functionality that is used, by `web3-eth-contract`, when decoding error data according to EIP-838. (#5434)
+
+#### web3-eth-contract
+
+-   Decoding error data, using Error ABI if available, according to EIP-838. (#5434)
+-   The class `Web3ContractError` is moved from this package to `web3-error`. (#5434)
 
 ### Fixed
 
 #### web3-eth-contract
 
--   According to the latest change in `web3-eth-abi`, the decoded values of the large numbers, returned from function calls or events, are now available as `BigInt`.
+-   According to the latest change in `web3-eth-abi`, the decoded values of the large numbers, returned from function calls or events, are now available as `BigInt`. (#5435)
 
 #### web3-eth-abi
 
--   Return `BigInt` instead of `string` when decoding function parameters for large numbers, such as `uint256`.
--   If an error happens when decoding a value, preserve that exception at `innerError` inside the `AbiError`.
+-   Return `BigInt` instead of `string` when decoding function parameters for large numbers, such as `uint256`. (#5435)

packages/web3-core/CHANGELOG.md

@@ -34,3 +34,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - I've improved the security in XY (#1000)
 
 -->
+
+## [Unreleased]
+
+### Added
+
+-   If the response error was `execution reverted`, raise `ContractExecutionError` and pass the response error to it in order to be set as `innerError` (this innerError will be decoded at web3-eth-contract if its ABI was provided according to EIP-838). (#5434)

packages/web3-core/src/web3_request_manager.ts

@@ -16,7 +16,12 @@ along with web3.js.  If not, see <http://www.gnu.org/licenses/>.
 */
 
 import { Socket } from 'net';
-import { InvalidResponseError, ProviderError, ResponseError } from 'web3-errors';
+import {
+	ContractExecutionError,
+	InvalidResponseError,
+	ProviderError,
+	ResponseError,
+} from 'web3-errors';
 import HttpProvider from 'web3-providers-http';
 import IpcProvider from 'web3-providers-ipc';
 import WSProvider from 'web3-providers-ws';
@@ -26,6 +31,7 @@ import {
 	JsonRpcBatchResponse,
 	JsonRpcPayload,
 	JsonRpcResponse,
+	JsonRpcResponseWithError,
 	SupportedProviders,
 	Web3APIMethod,
 	Web3APIPayload,
@@ -287,7 +293,16 @@ export class Web3RequestManager<
 		// This is the majority of the cases so check these first
 		// A valid JSON-RPC response with error object
 		if (jsonRpc.isResponseWithError<ErrorType>(response)) {
-			throw new InvalidResponseError<ErrorType>(response);
+			if (
+				(response.error as unknown as { message: string })?.message === 'execution reverted'
+			) {
+				// This message means that there was an error while executing the code of the smart contract
+				// However, more processing will happen at a higher level to decode the error data,
+				//	according to the Error ABI, if it was available as of EIP-838.
+				throw new ContractExecutionError((response as JsonRpcResponseWithError).error);
+			} else {
+				throw new InvalidResponseError<ErrorType>(response);
+			}
 		}
 
 		// This is the majority of the cases so check these first

packages/web3-errors/CHANGELOG.md

@@ -39,4 +39,5 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
--   Add optional `innerError` property to the abstract class `Web3Error`.
+-   Add optional `innerError` property to the abstract class `Web3Error`. This `innerError` could be `Error`, `Error[]` or `undefined`. (#5435) (#5434)
+-   The class `Web3ContractError` is moved to this package from `web3-eth-contract`. (#5434)

packages/web3-errors/src/error_codes.ts

@@ -38,6 +38,7 @@ export const ERR_CONTRACT_MISSING_DEPLOY_DATA = 306;
 export const ERR_CONTRACT_MISSING_ADDRESS = 307;
 export const ERR_CONTRACT_MISSING_FROM_ADDRESS = 308;
 export const ERR_CONTRACT_INSTANTIATION = 309;
+export const ERR_CONTRACT_EXECUTION_REVERTED = 310;
 
 // Transaction error codes
 export const ERR_TX = 400;
@@ -75,6 +76,7 @@ export const ERR_TX_LOCAL_WALLET_NOT_AVAILABLE = 429;
 
 export const ERR_TX_NOT_FOUND = 430;
 export const ERR_TX_SEND_TIMEOUT = 431;
+
 // Connection error codes
 export const ERR_CONN = 500;
 export const ERR_CONN_INVALID = 501;

packages/web3-errors/src/errors/contract_errors.ts

@@ -17,8 +17,11 @@ along with web3.js.  If not, see <http://www.gnu.org/licenses/>.
 
 /* eslint-disable max-classes-per-file */
 
+import { JsonRpcError, TransactionReceipt, HexString } from 'web3-types';
 import {
+	ERR_CONTRACT,
 	ERR_CONTRACT_ABI_MISSING,
+	ERR_CONTRACT_EXECUTION_REVERTED,
 	ERR_CONTRACT_EVENT_NOT_EXISTS,
 	ERR_CONTRACT_INSTANTIATION,
 	ERR_CONTRACT_MISSING_ADDRESS,
@@ -30,6 +33,16 @@ import {
 } from '../error_codes';
 import { Web3Error } from '../web3_error_base';
 
+export class Web3ContractError extends Web3Error {
+	public code = ERR_CONTRACT;
+	public receipt?: TransactionReceipt;
+
+	public constructor(message: string, receipt?: TransactionReceipt) {
+		super(message);
+
+		this.receipt = receipt;
+	}
+}
 export class ResolverMethodMissingError extends Web3Error {
 	public code = ERR_CONTRACT_RESOLVER_MISSING;
 
@@ -111,3 +124,51 @@ export class ContractNoFromAddressDefinedError extends Web3Error {
 export class ContractInstantiationError extends Web3Error {
 	public code = ERR_CONTRACT_INSTANTIATION;
 }
+
+/**
+ * This class is expected to be set as an `innerError` inside ContractExecutionError
+ * The properties would be typically decoded from the `data` if it was encoded according to EIP-838
+ */
+export class Eip838ExecutionError extends Web3ContractError {
+	public readonly name: string;
+	public code: number;
+	public data?: HexString;
+	public errorName?: string;
+	public errorSignature?: string;
+	public errorArgs?: { [K in string]: unknown };
+
+	public constructor(code: number, message: string, data?: HexString) {
+		super(message);
+		this.name = this.constructor.name;
+		this.code = code;
+		this.data = data;
+	}
+
+	public setDecodedProperties(
+		errorName: string,
+		errorSignature?: string,
+		errorArgs?: { [K in string]: unknown },
+	) {
+		this.errorName = errorName;
+		this.errorSignature = errorSignature;
+		this.errorArgs = errorArgs;
+	}
+}
+
+/**
+ * Used when an error is raised while executing a function inside a smart contract.
+ * The data is expected to be encoded according to EIP-848.
+ */
+export class ContractExecutionError extends Web3ContractError {
+	public innerError: Eip838ExecutionError;
+
+	public constructor(rpcError: JsonRpcError) {
+		super('Error happened while trying to execute a function inside a smart contract');
+		this.code = ERR_CONTRACT_EXECUTION_REVERTED;
+		this.innerError = new Eip838ExecutionError(
+			rpcError.code,
+			rpcError.message,
+			rpcError.data as string,
+		);
+	}
+}

packages/web3-errors/src/errors/response_errors.ts

@@ -16,7 +16,7 @@ along with web3.js.  If not, see <http://www.gnu.org/licenses/>.
 */
 
 // eslint-disable-next-line max-classes-per-file
-import { JsonRpcResponse, JsonRpcResponseWithError } from 'web3-types';
+import { JsonRpcError, JsonRpcResponse, JsonRpcResponseWithError } from 'web3-types';
 import { Web3Error } from '../web3_error_base';
 import { ERR_INVALID_RESPONSE, ERR_RESPONSE } from '../error_codes';
 
@@ -65,9 +65,15 @@ export class ResponseError<ErrorType = unknown> extends Web3Error {
 export class InvalidResponseError<ErrorType = unknown> extends ResponseError<ErrorType> {
 	public constructor(result: JsonRpcResponse<unknown, ErrorType>) {
 		super(result);
-		if (!this.message || this.message === '') {
-			this.message = `Invalid JSON RPC response: ${JSON.stringify(result)}`;
-		}
 		this.code = ERR_INVALID_RESPONSE;
+
+		let errorOrErrors: JsonRpcError | JsonRpcError[] | undefined;
+		if (`error` in result) {
+			errorOrErrors = result.error as JsonRpcError;
+		} else if (result instanceof Array) {
+			errorOrErrors = result.map(r => r.error) as JsonRpcError[];
+		}
+
+		this.innerError = errorOrErrors as Error | Error[] | undefined;
 	}
 }

packages/web3-errors/src/web3_error_base.ts

@@ -23,9 +23,9 @@ export abstract class Web3Error extends Error implements ErrorInterface {
 	public readonly name: string;
 	public abstract readonly code: number;
 	public stack: string | undefined;
-	public innerError: Error | undefined;
+	public innerError: Error | Error[] | undefined;
 
-	public constructor(msg?: string, innerError?: Error) {
+	public constructor(msg?: string, innerError?: Error | Error[]) {
 		super(msg);
 		this.innerError = innerError;
 		this.name = this.constructor.name;

packages/web3-errors/test/unit/__snapshots__/errors.test.ts.snap

@@ -162,7 +162,14 @@ Object {
     "a": "10",
     "b": "20",
   },
-  "innerError": undefined,
+  "innerError": Object {
+    "code": 123,
+    "data": Object {
+      "a": "10",
+      "b": "20",
+    },
+    "message": "error message",
+  },
   "message": "Returned error: error message",
   "name": "InvalidResponseError",
 }

packages/web3-eth-abi/CHANGELOG.md

@@ -39,7 +39,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
-#### web3-eth-abi
+### Added
+
+-   If an error happens when decoding a value, preserve that exception at `innerError` inside the error class `AbiError`. (#5435)
+-   Add basic functionality that is used, by `web3-eth-contract`, when decoding error data according to EIP-838. (#5434)
+
+### Fixed
 
--   Return `BigInt` instead of `string` when decoding function parameters for large numbers, such as `uint256`.
--   If an error happens when decoding a value, preserve that exception at `innerError` inside the `AbiError`.
+-   Return `BigInt` instead of `string` when decoding function parameters for large numbers, such as `uint256`. (#5435)

packages/web3-eth-abi/src/api/errors_api.ts

@@ -0,0 +1,40 @@
+/*
+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 { sha3Raw } from 'web3-utils';
+import { AbiError } from 'web3-errors';
+import { AbiErrorFragment } from '../types';
+import { jsonInterfaceMethodToString, isAbiErrorFragment } from '../utils';
+
+/**
+ * Encodes the error name to its ABI signature, which are the sha3 hash of the error name including input types.
+ */
+export const encodeErrorSignature = (functionName: string | AbiErrorFragment): string => {
+	if (typeof functionName !== 'string' && !isAbiErrorFragment(functionName)) {
+		throw new AbiError('Invalid parameter value in encodeErrorSignature');
+	}
+
+	let name: string;
+
+	if (functionName && (typeof functionName === 'function' || typeof functionName === 'object')) {
+		name = jsonInterfaceMethodToString(functionName);
+	} else {
+		name = functionName;
+	}
+
+	return sha3Raw(name);
+};

packages/web3-eth-abi/src/index.ts

@@ -16,6 +16,7 @@ along with web3.js.  If not, see <http://www.gnu.org/licenses/>.
 */
 
 export * from './types';
+export * from './api/errors_api';
 export * from './api/events_api';
 export * from './api/functions_api';
 export * from './api/logs_api';

packages/web3-eth-abi/src/types.ts

@@ -88,11 +88,19 @@ export type AbiEventFragment = AbiBaseFragment & {
 	readonly anonymous?: boolean;
 };
 
+// https://docs.soliditylang.org/en/latest/abi-spec.html#errors
+export type AbiErrorFragment = AbiBaseFragment & {
+	readonly name: string;
+	readonly type: string | 'error';
+	readonly inputs?: ReadonlyArray<AbiParameter>;
+};
+
 // https://docs.soliditylang.org/en/latest/abi-spec.html#json
 export type AbiFragment =
 	| AbiConstructorFragment
 	| AbiFunctionFragment
 	| AbiEventFragment
+	| AbiErrorFragment
 	| AbiFallbackFragment;
 
 export type ContractAbi = ReadonlyArray<AbiFragment>;

packages/web3-eth-abi/src/utils.ts

@@ -34,7 +34,13 @@ export const isAbiFragment = (item: unknown): item is AbiFragment =>
 	!isNullish(item) &&
 	typeof item === 'object' &&
 	!isNullish((item as { type: string }).type) &&
-	['function', 'event', 'constructor'].includes((item as { type: string }).type);
+	['function', 'event', 'constructor', 'error'].includes((item as { type: string }).type);
+
+export const isAbiErrorFragment = (item: unknown): item is AbiEventFragment =>
+	!isNullish(item) &&
+	typeof item === 'object' &&
+	!isNullish((item as { type: string }).type) &&
+	(item as { type: string }).type === 'error';
 
 export const isAbiEventFragment = (item: unknown): item is AbiEventFragment =>
 	!isNullish(item) &&
@@ -278,7 +284,7 @@ export const flattenTypes = (
  * returns a string
  */
 export const jsonInterfaceMethodToString = (json: AbiFragment): string => {
-	if (isAbiEventFragment(json) || isAbiFunctionFragment(json)) {
+	if (isAbiErrorFragment(json) || isAbiEventFragment(json) || isAbiFunctionFragment(json)) {
 		if (json.name?.includes('(')) {
 			return json.name;
 		}

packages/web3-eth-contract/CHANGELOG.md

@@ -173,6 +173,11 @@ const transactionHash = receipt.transactionHash;
 
 ## [Unreleased]
 
+### Added
+
+-   Decoding error data, using Error ABI if available, according to EIP-838. (#5434)
+-   The class `Web3ContractError` is moved from this package to `web3-error`. (#5434)
+
 ### Fixed
 
--   According to the latest change in `web3-eth-abi`, the decoded values of the large numbers, returned from function calls or events, are now available as `BigInt`.
+-   According to the latest change in `web3-eth-abi`, the decoded values of the large numbers, returned from function calls or events, are now available as `BigInt`. (#5435)