feat: add tx explanation for TxIntentMismatch errors

Ticket: WP-6608

Author: danielpeng1

modules/abstract-eth/src/abstractEthLikeNewCoins.ts

@@ -2798,6 +2798,34 @@ export abstract class AbstractEthLikeNewCoins extends AbstractEthLikeCoin {
     return txPrebuild.coin === nativeCoin;
   }
 
+  /**
+   * Generate transaction explanation for error reporting
+   * @param txPrebuild - Transaction prebuild containing txHex and fee info
+   * @returns Stringified JSON explanation
+   */
+  private async getTxExplanation(txPrebuild?: TransactionPrebuild): Promise<string | undefined> {
+    if (!txPrebuild?.txHex || !txPrebuild?.gasPrice) {
+      return undefined;
+    }
+
+    try {
+      const explanation = await this.explainTransaction({
+        txHex: txPrebuild.txHex,
+        feeInfo: {
+          fee: txPrebuild.gasPrice.toString(),
+        },
+      });
+      return JSON.stringify(explanation, null, 2);
+    } catch (e) {
+      const errorDetails = {
+        error: 'Failed to parse transaction explanation',
+        txHex: txPrebuild.txHex,
+        details: e instanceof Error ? e.message : String(e),
+      };
+      return JSON.stringify(errorDetails, null, 2);
+    }
+  }
+
   /**
    * Verify if a tss transaction is valid
    *
@@ -2811,9 +2839,18 @@ export abstract class AbstractEthLikeNewCoins extends AbstractEthLikeCoin {
   async verifyTssTransaction(params: VerifyEthTransactionOptions): Promise<boolean> {
     const { txParams, txPrebuild, wallet } = params;
 
+    const txExplanation = await this.getTxExplanation(txPrebuild);
+
     // Helper to throw TxIntentMismatchRecipientError with recipient details
     const throwRecipientMismatch = (message: string, mismatchedRecipients: Recipient[]): never => {
-      throw new TxIntentMismatchRecipientError(message, undefined, [txParams], txPrebuild?.txHex, mismatchedRecipients);
+      throw new TxIntentMismatchRecipientError(
+        message,
+        undefined,
+        [txParams],
+        txPrebuild?.txHex,
+        mismatchedRecipients,
+        txExplanation
+      );
     };
 
     if (
@@ -2915,9 +2952,18 @@ export abstract class AbstractEthLikeNewCoins extends AbstractEthLikeCoin {
       return this.verifyTssTransaction(params);
     }
 
+    const txExplanation = await this.getTxExplanation(txPrebuild);
+
     // Helper to throw TxIntentMismatchRecipientError with recipient details
     const throwRecipientMismatch = (message: string, mismatchedRecipients: Recipient[]): never => {
-      throw new TxIntentMismatchRecipientError(message, undefined, [txParams], txPrebuild?.txHex, mismatchedRecipients);
+      throw new TxIntentMismatchRecipientError(
+        message,
+        undefined,
+        [txParams],
+        txPrebuild?.txHex,
+        mismatchedRecipients,
+        txExplanation
+      );
     };
 
     if (!txParams?.recipients || !txPrebuild?.recipients || !wallet) {
@@ -3019,7 +3065,8 @@ export abstract class AbstractEthLikeNewCoins extends AbstractEthLikeCoin {
         'coin in txPrebuild did not match that in txParams supplied by client',
         undefined,
         [txParams],
-        txPrebuild?.txHex
+        txPrebuild?.txHex,
+        txExplanation
       );
     }
     return true;

modules/abstract-utxo/src/abstractUtxoCoin.ts

@@ -61,6 +61,7 @@ import {
   assertValidTransactionRecipient,
   explainTx,
   fromExtendedAddressFormat,
+  getTxExplanation,
   isScriptRecipient,
   parseTransaction,
   verifyTransaction,
@@ -143,7 +144,8 @@ function convertValidationErrorToTxIntentMismatch(
   error: AggregateValidationError,
   reqId: string | IRequestTracer | undefined,
   txParams: BaseTransactionParams,
-  txHex: string | undefined
+  txHex: string | undefined,
+  txExplanation?: string
 ): TxIntentMismatchRecipientError {
   const mismatchedRecipients: MismatchedRecipient[] = [];
 
@@ -170,7 +172,8 @@ function convertValidationErrorToTxIntentMismatch(
     reqId,
     [txParams],
     txHex,
-    mismatchedRecipients
+    mismatchedRecipients,
+    txExplanation
   );
   // 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
@@ -615,11 +618,19 @@ export abstract class AbstractUtxoCoin extends BaseCoin {
   async verifyTransaction<TNumber extends number | bigint = number>(
     params: VerifyTransactionOptions<TNumber>
   ): Promise<boolean> {
+    const txExplanation = await getTxExplanation(this, params.txPrebuild);
+
     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 convertValidationErrorToTxIntentMismatch(
+          error,
+          params.reqId,
+          params.txParams,
+          params.txPrebuild.txHex,
+          txExplanation
+        );
       }
       throw error;
     }

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

@@ -4,6 +4,7 @@ import { DescriptorMap } from '@bitgo/utxo-core/descriptor';
 
 import { AbstractUtxoCoin, VerifyTransactionOptions } from '../../abstractUtxoCoin';
 import { BaseOutput, BaseParsedTransactionOutputs } from '../types';
+import { getTxExplanation } from '../txExplanation';
 
 import { toBaseParsedTransactionOutputsFromPsbt } from './parse';
 
@@ -75,13 +76,16 @@ export async function verifyTransaction<TNumber extends number | bigint>(
   params: VerifyTransactionOptions<TNumber>,
   descriptorMap: DescriptorMap
 ): Promise<boolean> {
+  const txExplanation = await getTxExplanation(coin, params.txPrebuild);
+
   const tx = coin.decodeTransactionFromPrebuild(params.txPrebuild);
   if (!(tx instanceof utxolib.bitgo.UtxoPsbt)) {
     throw new TxIntentMismatchError(
       'unexpected transaction type',
       params.reqId,
       [params.txParams],
-      params.txPrebuild.txHex
+      params.txPrebuild.txHex,
+      txExplanation
     );
   }
 

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

@@ -8,6 +8,7 @@ import { AbstractUtxoCoin, VerifyTransactionOptions } from '../../abstractUtxoCo
 import { Output, ParsedTransaction } from '../types';
 import { verifyCustomChangeKeySignatures, verifyKeySignature, verifyUserPublicKey } from '../../verifyKey';
 import { getPsbtTxInputs, getTxInputs } from '../fetchInputs';
+import { getTxExplanation } from '../txExplanation';
 
 const debug = buildDebug('bitgo:abstract-utxo:verifyTransaction');
 
@@ -50,9 +51,11 @@ export async function verifyTransaction<TNumber extends bigint | number>(
 ): Promise<boolean> {
   const { txParams, txPrebuild, wallet, verification = {}, reqId } = params;
 
+  const txExplanation = await getTxExplanation(coin, txPrebuild);
+
   // Helper to throw TxIntentMismatchError with consistent context
   const throwTxMismatch = (message: string): never => {
-    throw new TxIntentMismatchError(message, reqId, [txParams], txPrebuild.txHex);
+    throw new TxIntentMismatchError(message, reqId, [txParams], txPrebuild.txHex, txExplanation);
   };
 
   if (!_.isUndefined(verification.disableNetworking) && !_.isBoolean(verification.disableNetworking)) {

modules/abstract-utxo/src/transaction/index.ts

@@ -3,5 +3,6 @@ export * from './recipient';
 export { explainTx } from './explainTransaction';
 export { parseTransaction } from './parseTransaction';
 export { verifyTransaction } from './verifyTransaction';
+export { getTxExplanation } from './txExplanation';
 export * from './fetchInputs';
 export * as bip322 from './bip322';

modules/abstract-utxo/src/transaction/txExplanation.ts

@@ -0,0 +1,31 @@
+import { AbstractUtxoCoin, TransactionPrebuild } from '../abstractUtxoCoin';
+
+/**
+ * Generate a stringified transaction explanation for error reporting
+ * @param coin - The UTXO coin instance
+ * @param txPrebuild - Transaction prebuild containing txHex and txInfo
+ * @returns Stringified JSON explanation
+ */
+export async function getTxExplanation<TNumber extends number | bigint>(
+  coin: AbstractUtxoCoin,
+  txPrebuild: TransactionPrebuild<TNumber>
+): Promise<string | undefined> {
+  if (!txPrebuild.txHex) {
+    return undefined;
+  }
+
+  try {
+    const explanation = await coin.explainTransaction({
+      txHex: txPrebuild.txHex,
+      txInfo: txPrebuild.txInfo,
+    });
+    return JSON.stringify(explanation, null, 2);
+  } catch (e) {
+    const errorDetails = {
+      error: 'Failed to parse transaction explanation',
+      txHex: txPrebuild.txHex,
+      details: e instanceof Error ? e.message : String(e),
+    };
+    return JSON.stringify(errorDetails, null, 2);
+  }
+}

modules/sdk-core/src/bitgo/errors.ts

@@ -256,11 +256,13 @@ export interface ContractDataPayload {
  * @property {string | IRequestTracer | undefined} id - Transaction ID or request tracer for tracking
  * @property {TransactionParams[]} txParams - Array of transaction parameters that were analyzed
  * @property {string | undefined} txHex - The raw transaction in hexadecimal format
+ * @property {string | undefined} txExplanation - Stringified transaction explanation
  */
 export class TxIntentMismatchError extends BitGoJsError {
   public readonly id: string | IRequestTracer | undefined;
   public readonly txParams: TransactionParams[];
   public readonly txHex: string | undefined;
+  public readonly txExplanation: string | undefined;
 
   /**
    * Creates an instance of TxIntentMismatchError
@@ -269,17 +271,20 @@ export class TxIntentMismatchError extends BitGoJsError {
    * @param {string | IRequestTracer | undefined} id - Transaction ID or request tracer
    * @param {TransactionParams[]} txParams - Transaction parameters that were analyzed
    * @param {string | undefined} txHex - Raw transaction hex string
+   * @param {string | undefined} txExplanation - Stringified transaction explanation
    */
   public constructor(
     message: string,
     id: string | IRequestTracer | undefined,
     txParams: TransactionParams[],
-    txHex: string | undefined
+    txHex: string | undefined,
+    txExplanation?: string
   ) {
     super(message);
     this.id = id;
     this.txParams = txParams;
     this.txHex = txHex;
+    this.txExplanation = txExplanation;
   }
 }
 
@@ -304,15 +309,17 @@ export class TxIntentMismatchRecipientError extends TxIntentMismatchError {
    * @param {TransactionParams[]} txParams - Transaction parameters that were analyzed
    * @param {string | undefined} txHex - Raw transaction hex string
    * @param {MismatchedRecipient[]} mismatchedRecipients - Array of recipients that don't match user intent
+   * @param {string | undefined} txExplanation - Stringified transaction explanation
    */
   public constructor(
     message: string,
     id: string | IRequestTracer | undefined,
     txParams: TransactionParams[],
     txHex: string | undefined,
-    mismatchedRecipients: MismatchedRecipient[]
+    mismatchedRecipients: MismatchedRecipient[],
+    txExplanation?: string
   ) {
-    super(message, id, txParams, txHex);
+    super(message, id, txParams, txHex, txExplanation);
     this.mismatchedRecipients = mismatchedRecipients;
   }
 }
@@ -338,15 +345,17 @@ export class TxIntentMismatchContractError extends TxIntentMismatchError {
    * @param {TransactionParams[]} txParams - Transaction parameters that were analyzed
    * @param {string | undefined} txHex - Raw transaction hex string
    * @param {ContractDataPayload} mismatchedDataPayload - The contract interaction data that doesn't match user intent
+   * @param {string | undefined} txExplanation - Stringified transaction explanation
    */
   public constructor(
     message: string,
     id: string | IRequestTracer | undefined,
     txParams: TransactionParams[],
     txHex: string | undefined,
-    mismatchedDataPayload: ContractDataPayload
+    mismatchedDataPayload: ContractDataPayload,
+    txExplanation?: string
   ) {
-    super(message, id, txParams, txHex);
+    super(message, id, txParams, txHex, txExplanation);
     this.mismatchedDataPayload = mismatchedDataPayload;
   }
 }
@@ -372,15 +381,17 @@ export class TxIntentMismatchApprovalError extends TxIntentMismatchError {
    * @param {TransactionParams[]} txParams - Transaction parameters that were analyzed
    * @param {string | undefined} txHex - Raw transaction hex string
    * @param {TokenApproval} tokenApproval - Details of the token approval that doesn't match user intent
+   * @param {string | undefined} txExplanation - Stringified transaction explanation
    */
   public constructor(
     message: string,
     id: string | IRequestTracer | undefined,
     txParams: TransactionParams[],
     txHex: string | undefined,
-    tokenApproval: TokenApproval
+    tokenApproval: TokenApproval,
+    txExplanation?: string
   ) {
-    super(message, id, txParams, txHex);
+    super(message, id, txParams, txHex, txExplanation);
     this.tokenApproval = tokenApproval;
   }
 }