feat: improve transaction verification error handling

Replace custom validation errors with SDK's TxIntentMismatchRecipientError to
provide more detailed information about mismatched transaction outputs. This
enhances error reporting by including specific details about missing or
unexpected outputs, helping users understand what differs between their intent
and the actual transaction.

Co-authored-by: llm-git <llm-git@ttll.de>

Ticket: BTC-2579

TICKET: WP-6189

Author: lcovar

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

@@ -1,5 +1,12 @@
 import * as utxolib from '@bitgo/utxo-lib';
-import { ITransactionRecipient, TxIntentMismatchError, VerifyTransactionOptions } from '@bitgo/sdk-core';
+import {
+  IRequestTracer,
+  ITransactionRecipient,
+  MismatchedRecipient,
+  TxIntentMismatchError,
+  TxIntentMismatchRecipientError,
+  VerifyTransactionOptions,
+} from '@bitgo/sdk-core';
 import { DescriptorMap } from '@bitgo/utxo-core/descriptor';
 
 import { AbstractUtxoCoin, BaseOutput, BaseParsedTransactionOutputs } from '../../abstractUtxoCoin';
@@ -57,6 +64,52 @@ 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.
  *
@@ -68,6 +121,7 @@ export function assertValidTransaction(
  * @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(
   coin: AbstractUtxoCoin,
@@ -83,6 +137,15 @@ export async function verifyTransaction(
       params.txPrebuild.txHex
     );
   }
-  assertValidTransaction(tx, descriptorMap, params.txParams.recipients ?? [], tx.network);
+
+  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;
+  }
+
   return true;
 }

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

@@ -55,11 +55,11 @@ export async function verifyTransaction<TNumber extends bigint | number>(
   };
 
   if (!_.isUndefined(verification.disableNetworking) && !_.isBoolean(verification.disableNetworking)) {
-    throwTxMismatch('verification.disableNetworking must be a boolean');
+    throw new TypeError('verification.disableNetworking must be a boolean');
   }
   const isPsbt = txPrebuild.txHex && utxolib.bitgo.isPsbt(txPrebuild.txHex);
   if (isPsbt && txPrebuild.txInfo?.unspents) {
-    throwTxMismatch('should not have unspents in txInfo for psbt');
+    throw new Error('should not have unspents in txInfo for psbt');
   }
   const disableNetworking = !!verification.disableNetworking;
   const parsedTransaction: ParsedTransaction<TNumber> = await coin.parseTransaction<TNumber>({
@@ -97,7 +97,7 @@ export async function verifyTransaction<TNumber extends bigint | number>(
     const isBackupKeySignatureValid = verify(keychains.backup, keySignatures.backupPub);
     const isBitgoKeySignatureValid = verify(keychains.bitgo, keySignatures.bitgoPub);
     if (!isBackupKeySignatureValid || !isBitgoKeySignatureValid) {
-      throwTxMismatch('secondary public key signatures invalid');
+      throw new Error('secondary public key signatures invalid');
     }
     debug('successfully verified backup and bitgo key signatures');
   } else if (!disableNetworking) {
@@ -108,11 +108,11 @@ export async function verifyTransaction<TNumber extends bigint | number>(
 
   if (parsedTransaction.needsCustomChangeKeySignatureVerification) {
     if (!keychains.user || !userPublicKeyVerified) {
-      throwTxMismatch('transaction requires verification of user public key, but it was unable to be verified');
+      throw new Error('transaction requires verification of user public key, but it was unable to be verified');
     }
     const customChangeKeySignaturesVerified = verifyCustomChangeKeySignatures(parsedTransaction, keychains.user);
     if (!customChangeKeySignaturesVerified) {
-      throwTxMismatch(
+      throw new Error(
         'transaction requires verification of custom change key signatures, but they were unable to be verified'
       );
     }
@@ -168,7 +168,7 @@ export async function verifyTransaction<TNumber extends bigint | number>(
 
   const allOutputs = parsedTransaction.outputs;
   if (!txPrebuild.txHex) {
-    throw new TxIntentMismatchError(`txPrebuild.txHex not set`, reqId, [txParams], undefined);
+    throw new Error(`txPrebuild.txHex not set`);
   }
   const inputs = isPsbt
     ? getPsbtTxInputs(txPrebuild.txHex, coin.network).map((v) => ({
@@ -185,7 +185,7 @@ export async function verifyTransaction<TNumber extends bigint | number>(
   const fee = inputAmount - outputAmount;
 
   if (fee < 0) {
-    throwTxMismatch(
+    throw new Error(
       `attempting to spend ${outputAmount} satoshis, which exceeds the input amount (${inputAmount} satoshis) by ${-fee}`
     );
   }