chore: add UNKNOWN error code (#2562)

Co-authored-by: Anderson Arboleya <anderson@arboleya.me>
Co-authored-by: Peter Smith <peter@blueoceancomputing.co.uk>
Co-authored-by: Sérgio Torres <30977845+Torres-ssf@users.noreply.github.com>

.changeset/stale-starfishes-hope.md

@@ -0,0 +1,6 @@
+---
+"@fuel-ts/account": patch
+"@fuel-ts/errors": patch
+---
+
+chore: add `UNKNOWN` error code

apps/docs/src/guide/errors/error-codes.md

@@ -258,3 +258,9 @@ It could be that the passphrase is incorrect and/or the wallet does _not_ exist
 
 The hashing algorithm is currently locked, any subsequent attempts to register a new implementation will throw this error.
 The purpose of the lock function is to provide a way to ensure that the implementation of the specific hashing algorithm cannot be changed once it is locked. This can be useful in scenarios where you want to guarantee the integrity and consistency of the hashing function throughout your application.
+
+## `UNKNOWN`
+
+In cases where the error hasn't been mapped yet, this code will be used.
+
+If you believe you found a bug, please report the [issue](https://github.com/FuelLabs/fuels-ts/issues/new/choose) to the team.

packages/account/src/providers/utils/extract-tx-error.ts

@@ -19,14 +19,20 @@ import type { TransactionResultReceipt } from '../transaction-response';
  * @param status - The transaction failure status.
  * @returns The error message.
  */
-export const assemblePanicError = (statusReason: string) => {
+export const assemblePanicError = (
+  statusReason: string,
+  metadata: Record<string, unknown>
+): FuelError => {
   let errorMessage = `The transaction reverted with reason: "${statusReason}".`;
 
   if (PANIC_REASONS.includes(statusReason)) {
     errorMessage = `${errorMessage}\n\nYou can read more about this error at:\n\n${PANIC_DOC_URL}#variant.${statusReason}`;
   }
 
-  return { errorMessage, reason: statusReason };
+  return new FuelError(ErrorCode.SCRIPT_REVERTED, errorMessage, {
+    ...metadata,
+    reason: statusReason,
+  });
 };
 
 /** @hidden */
@@ -40,8 +46,9 @@ const stringify = (obj: unknown) => JSON.stringify(obj, null, 2);
  */
 export const assembleRevertError = (
   receipts: Array<TransactionResultReceipt>,
-  logs: Array<unknown>
-) => {
+  logs: Array<unknown>,
+  metadata: Record<string, unknown>
+): FuelError => {
   let errorMessage = 'The transaction reverted with an unknown reason.';
 
   const revertReceipt = receipts.find(({ type }) => type === ReceiptType.Revert) as ReceiptRevert;
@@ -88,12 +95,21 @@ export const assembleRevertError = (
         break;
 
       default:
-        reason = 'unknown';
-        errorMessage = `The transaction reverted with an unknown reason: ${revertReceipt.val}`;
+        throw new FuelError(
+          ErrorCode.UNKNOWN,
+          `The transaction reverted with an unknown reason: ${revertReceipt.val}`,
+          {
+            ...metadata,
+            reason: 'unknown',
+          }
+        );
     }
   }
 
-  return { errorMessage, reason };
+  return new FuelError(ErrorCode.SCRIPT_REVERTED, errorMessage, {
+    ...metadata,
+    reason,
+  });
 };
 
 interface IExtractTxError {
@@ -112,18 +128,16 @@ export const extractTxError = (params: IExtractTxError): FuelError => {
 
   const isPanic = receipts.some(({ type }) => type === ReceiptType.Panic);
   const isRevert = receipts.some(({ type }) => type === ReceiptType.Revert);
-
-  const { errorMessage, reason } = isPanic
-    ? assemblePanicError(statusReason)
-    : assembleRevertError(receipts, logs);
-
   const metadata = {
     logs,
     receipts,
     panic: isPanic,
     revert: isRevert,
-    reason,
+    reason: '',
   };
 
-  return new FuelError(ErrorCode.SCRIPT_REVERTED, errorMessage, metadata);
+  if (isPanic) {
+    return assemblePanicError(statusReason, metadata);
+  }
+  return assembleRevertError(receipts, logs, metadata);
 };

packages/errors/src/error-codes.ts

@@ -103,4 +103,7 @@ export enum ErrorCode {
 
   // graphql
   STREAM_PARSING_ERROR = 'stream-parsing-error',
+
+  // Unknown
+  UNKNOWN = 'unknown',
 }

packages/errors/src/fuel-error.test.ts

@@ -51,5 +51,12 @@ it('converts error to plain object', () => {
   const message = 'It happens';
   const metadata = { name: 'FuelLabs' };
   const err = new FuelError(code, message, metadata);
-  expect(err.toObject()).toEqual({ code, name, message, VERSIONS: err.VERSIONS, metadata });
+  expect(err.toObject()).toEqual({
+    code,
+    name,
+    message,
+    VERSIONS: err.VERSIONS,
+    metadata,
+    rawError: {},
+  });
 });

packages/errors/src/fuel-error.ts

@@ -6,6 +6,7 @@ export class FuelError extends Error {
   static readonly CODES = ErrorCode;
   readonly VERSIONS = versions;
   readonly metadata: Record<string, unknown>;
+  readonly rawError: unknown;
 
   static parse(e: unknown) {
     const error = e as FuelError;
@@ -32,15 +33,21 @@ export class FuelError extends Error {
 
   code: ErrorCode;
 
-  constructor(code: ErrorCode, message: string, metadata: Record<string, unknown> = {}) {
+  constructor(
+    code: ErrorCode,
+    message: string,
+    metadata: Record<string, unknown> = {},
+    rawError: unknown = {}
+  ) {
     super(message);
     this.code = code;
     this.name = 'FuelError';
     this.metadata = metadata;
+    this.rawError = rawError;
   }
 
   toObject() {
-    const { code, name, message, metadata, VERSIONS } = this;
-    return { code, name, message, metadata, VERSIONS };
+    const { code, name, message, metadata, VERSIONS, rawError } = this;
+    return { code, name, message, metadata, VERSIONS, rawError };
   }
 }

packages/errors/src/test-utils/expect-to-throw-fuel-error.ts

@@ -47,6 +47,14 @@ export const expectToThrowFuelError = async (
     expect(thrownError.metadata).toEqual(expect.objectContaining(expectedError.metadata));
   }
 
+  if (expectedError.message) {
+    expect(thrownError.message).toEqual(expectedError.message);
+  }
+
+  if (expectedError.rawError) {
+    expect(thrownError.rawError).toEqual(expectedError.rawError);
+  }
+
   expect(thrownError.name).toEqual('FuelError');
   expect(thrownError).toMatchObject(expectedError);
 };

packages/fuel-gauge/src/revert-error.test.ts

@@ -223,20 +223,16 @@ describe('Revert Error Testing', () => {
     );
   });
 
-  it('should throw for explicit "revert" call', async () => {
+  it('should throw UNKNOWN Error for revert', async () => {
     await expectToThrowFuelError(
       () => contractInstance.functions.revert_with_0().call(),
-      new FuelError(
-        ErrorCode.SCRIPT_REVERTED,
-        `The transaction reverted with an unknown reason: 0`,
-        {
-          logs: [],
-          receipts: expect.any(Array<TransactionResultReceipt>),
-          panic: false,
-          revert: true,
-          reason: 'unknown',
-        }
-      )
+      new FuelError(ErrorCode.UNKNOWN, `The transaction reverted with an unknown reason: 0`, {
+        logs: [],
+        receipts: expect.any(Array<TransactionResultReceipt>),
+        panic: false,
+        revert: true,
+        reason: 'unknown',
+      })
     );
   });