feat: refactoring error handling for transaction verification

Ticket: WP-6189

Author: danielpeng1

modules/abstract-utxo/src/abstractUtxoCoin.ts

@@ -22,6 +22,7 @@ import {
   IWallet,
   KeychainsTriplet,
   KeyIndices,
+  MismatchedRecipient,
   MultisigType,
   multisigTypes,
   P2shP2wshUnsupportedError,
@@ -39,6 +40,7 @@ import {
   TransactionParams as BaseTransactionParams,
   TransactionPrebuild as BaseTransactionPrebuild,
   Triple,
+  TxIntentMismatchRecipientError,
   UnexpectedAddressError,
   UnsupportedAddressTypeError,
   VerificationOptions,
@@ -72,6 +74,11 @@ import {
   parseTransaction,
   verifyTransaction,
 } from './transaction';
+import {
+  AggregateValidationError,
+  ErrorMissingOutputs,
+  ErrorImplicitExternalOutputs,
+} from './transaction/descriptor/verifyTransaction';
 import { assertDescriptorWalletAddress, getDescriptorMapFromWallet, isDescriptorWallet } from './descriptor';
 import { getChainFromNetwork, getFamilyFromNetwork, getFullNameFromNetwork } from './names';
 import { CustomChangeOptions } from './transaction/fixedScript';
@@ -113,6 +120,52 @@ const { getExternalChainCode, isChainCode, scriptTypeForChain, outputScripts } =
 
 type Unspent<TNumber extends number | bigint = number> = bitgo.Unspent<TNumber>;
 
+/**
+ * Convert ValidationError to TxIntentMismatchRecipientError with structured data
+ *
+ * This preserves the structured error information from the original ValidationError
+ * by extracting the mismatched outputs and converting them to the standardized format.
+ * The original error is preserved as the `cause` for debugging purposes.
+ */
+function convertValidationErrorToTxIntentMismatch(
+  error: AggregateValidationError,
+  reqId: string | IRequestTracer | undefined,
+  txParams: BaseTransactionParams,
+  txHex: string | undefined
+): TxIntentMismatchRecipientError {
+  const mismatchedRecipients: MismatchedRecipient[] = [];
+
+  for (const err of error.errors) {
+    if (err instanceof ErrorMissingOutputs) {
+      mismatchedRecipients.push(
+        ...err.missingOutputs.map((output) => ({
+          address: output.address,
+          amount: output.amount.toString(),
+        }))
+      );
+    } else if (err instanceof ErrorImplicitExternalOutputs) {
+      mismatchedRecipients.push(
+        ...err.implicitExternalOutputs.map((output) => ({
+          address: output.address,
+          amount: output.amount.toString(),
+        }))
+      );
+    }
+  }
+
+  const txIntentError = new TxIntentMismatchRecipientError(
+    error.message,
+    reqId,
+    [txParams],
+    txHex,
+    mismatchedRecipients
+  );
+  // Preserve the original structured error as the cause for debugging
+  // See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause
+  (txIntentError as Error & { cause?: Error }).cause = error;
+  return txIntentError;
+}
+
 export type DecodedTransaction<TNumber extends number | bigint> =
   | utxolib.bitgo.UtxoTransaction<TNumber>
   | utxolib.bitgo.UtxoPsbt;
@@ -631,13 +684,21 @@ export abstract class AbstractUtxoCoin extends BaseCoin {
    * @param params.verification.disableNetworking Disallow fetching any data from the internet for verification purposes
    * @param params.verification.keychains Pass keychains manually rather than fetching them by id
    * @param params.verification.addresses Address details to pass in for out-of-band verification
-   * @returns {boolean}
+   * @returns {boolean} True if verification passes
    * @throws {TxIntentMismatchError} if transaction validation fails
+   * @throws {TxIntentMismatchRecipientError} if transaction recipients don't match user intent
    */
   async verifyTransaction<TNumber extends number | bigint = number>(
     params: VerifyTransactionOptions<TNumber>
   ): Promise<boolean> {
-    return verifyTransaction(this, this.bitgo, params);
+    try {
+      return await verifyTransaction(this, this.bitgo, params);
+    } catch (error) {
+      if (error instanceof AggregateValidationError) {
+        throw convertValidationErrorToTxIntentMismatch(error, params.reqId, params.txParams, params.txPrebuild.txHex);
+      }
+      throw error;
+    }
   }
 
   /**

modules/abstract-utxo/src/transaction/descriptor/verifyTransaction.ts

@@ -1,15 +1,13 @@
 import * as utxolib from '@bitgo/utxo-lib';
-import {
-  IRequestTracer,
-  ITransactionRecipient,
-  MismatchedRecipient,
-  TxIntentMismatchError,
-  TxIntentMismatchRecipientError,
-  VerifyTransactionOptions,
-} from '@bitgo/sdk-core';
+import { ITransactionRecipient, TxIntentMismatchError } from '@bitgo/sdk-core';
 import { DescriptorMap } from '@bitgo/utxo-core/descriptor';
 
-import { AbstractUtxoCoin, BaseOutput, BaseParsedTransactionOutputs } from '../../abstractUtxoCoin';
+import {
+  AbstractUtxoCoin,
+  BaseOutput,
+  BaseParsedTransactionOutputs,
+  VerifyTransactionOptions,
+} from '../../abstractUtxoCoin';
 
 import { toBaseParsedTransactionOutputsFromPsbt } from './parse';
 
@@ -64,52 +62,6 @@ export function assertValidTransaction(
   assertExpectedOutputDifference(toBaseParsedTransactionOutputsFromPsbt(psbt, descriptors, recipients, network));
 }
 
-/**
- * Convert ValidationError to TxIntentMismatchRecipientError with structured data
- *
- * This preserves the structured error information from the original ValidationError
- * by extracting the mismatched outputs and converting them to the standardized format.
- * The original error is preserved as the `cause` for debugging purposes.
- */
-function convertValidationErrorToTxIntentMismatch(
-  error: AggregateValidationError,
-  reqId: string | IRequestTracer | undefined,
-  txParams: VerifyTransactionOptions['txParams'],
-  txHex: string | undefined
-): TxIntentMismatchRecipientError {
-  const mismatchedRecipients: MismatchedRecipient[] = [];
-
-  for (const err of error.errors) {
-    if (err instanceof ErrorMissingOutputs) {
-      mismatchedRecipients.push(
-        ...err.missingOutputs.map((output) => ({
-          address: output.address,
-          amount: output.amount.toString(),
-        }))
-      );
-    } else if (err instanceof ErrorImplicitExternalOutputs) {
-      mismatchedRecipients.push(
-        ...err.implicitExternalOutputs.map((output) => ({
-          address: output.address,
-          amount: output.amount.toString(),
-        }))
-      );
-    }
-  }
-
-  const txIntentError = new TxIntentMismatchRecipientError(
-    error.message,
-    reqId,
-    [txParams],
-    txHex,
-    mismatchedRecipients
-  );
-  // Preserve the original structured error as the cause for debugging
-  // See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause
-  (txIntentError as Error & { cause?: Error }).cause = error;
-  return txIntentError;
-}
-
 /**
  * Wrapper around assertValidTransaction that returns a boolean instead of throwing.
  *
@@ -121,11 +73,10 @@ function convertValidationErrorToTxIntentMismatch(
  * @param descriptorMap
  * @returns {boolean} True if verification passes
  * @throws {TxIntentMismatchError} if transaction validation fails
- * @throws {TxIntentMismatchRecipientError} if transaction recipients don't match user intent
  */
-export async function verifyTransaction(
+export async function verifyTransaction<TNumber extends number | bigint>(
   coin: AbstractUtxoCoin,
-  params: VerifyTransactionOptions,
+  params: VerifyTransactionOptions<TNumber>,
   descriptorMap: DescriptorMap
 ): Promise<boolean> {
   const tx = coin.decodeTransactionFromPrebuild(params.txPrebuild);
@@ -138,14 +89,7 @@ export async function verifyTransaction(
     );
   }
 
-  try {
-    assertValidTransaction(tx, descriptorMap, params.txParams.recipients ?? [], tx.network);
-  } catch (error) {
-    if (error instanceof AggregateValidationError) {
-      throw convertValidationErrorToTxIntentMismatch(error, params.reqId, params.txParams, params.txPrebuild.txHex);
-    }
-    throw error;
-  }
+  assertValidTransaction(tx, descriptorMap, params.txParams.recipients ?? [], tx.network);
 
   return true;
 }