refactor: update txExplanation for TxIntentMismatchError

Ticket: WP-6608

Author: danielpeng1

modules/abstract-eth/src/abstractEthLikeNewCoins.ts

@@ -3072,10 +3072,9 @@ 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 => {
+    const throwRecipientMismatch = async (message: string, mismatchedRecipients: Recipient[]): Promise<never> => {
+      const txExplanation = await this.getTxExplanation(txPrebuild);
       throw new TxIntentMismatchRecipientError(
         message,
         undefined,
@@ -3114,12 +3113,13 @@ export abstract class AbstractEthLikeNewCoins extends AbstractEthLikeCoin {
         const txJson = tx.toJson();
         if (txJson.data === '0x') {
           if (expectedAmount !== txJson.value) {
-            throwRecipientMismatch('the transaction amount in txPrebuild does not match the value given by client', [
-              { address: txJson.to, amount: txJson.value },
-            ]);
+            await throwRecipientMismatch(
+              'the transaction amount in txPrebuild does not match the value given by client',
+              [{ address: txJson.to, amount: txJson.value }]
+            );
           }
           if (expectedDestination.toLowerCase() !== txJson.to.toLowerCase()) {
-            throwRecipientMismatch('destination address does not match with the recipient address', [
+            await throwRecipientMismatch('destination address does not match with the recipient address', [
               { address: txJson.to, amount: txJson.value },
             ]);
           }
@@ -3149,13 +3149,14 @@ export abstract class AbstractEthLikeNewCoins extends AbstractEthLikeCoin {
           }
 
           if (expectedTokenAmount !== amount.toString()) {
-            throwRecipientMismatch('the transaction amount in txPrebuild does not match the value given by client', [
-              { address: addHexPrefix(recipientAddress.toString()), amount: amount.toString() },
-            ]);
+            await throwRecipientMismatch(
+              'the transaction amount in txPrebuild does not match the value given by client',
+              [{ address: addHexPrefix(recipientAddress.toString()), amount: amount.toString() }]
+            );
           }
 
           if (expectedRecipientAddress !== addHexPrefix(recipientAddress.toString()).toLowerCase()) {
-            throwRecipientMismatch('destination address does not match with the recipient address', [
+            await throwRecipientMismatch('destination address does not match with the recipient address', [
               { address: addHexPrefix(recipientAddress.toString()), amount: amount.toString() },
             ]);
           }
@@ -3185,10 +3186,9 @@ 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 => {
+    const throwRecipientMismatch = async (message: string, mismatchedRecipients: Recipient[]): Promise<never> => {
+      const txExplanation = await this.getTxExplanation(txPrebuild);
       throw new TxIntentMismatchRecipientError(
         message,
         undefined,
@@ -3226,7 +3226,7 @@ export abstract class AbstractEthLikeNewCoins extends AbstractEthLikeCoin {
       const expectedHopAddress = optionalDeps.ethUtil.stripHexPrefix(decodedHopTx.getSenderAddress().toString());
       const actualHopAddress = optionalDeps.ethUtil.stripHexPrefix(txPrebuild.recipients[0].address);
       if (expectedHopAddress.toLowerCase() !== actualHopAddress.toLowerCase()) {
-        throwRecipientMismatch('recipient address of txPrebuild does not match hop address', [
+        await throwRecipientMismatch('recipient address of txPrebuild does not match hop address', [
           { address: txPrebuild.recipients[0].address, amount: txPrebuild.recipients[0].amount.toString() },
         ]);
       }
@@ -3246,17 +3246,18 @@ export abstract class AbstractEthLikeNewCoins extends AbstractEthLikeCoin {
       if (txParams.tokenName) {
         const expectedTotalAmount = new BigNumber(0);
         if (!expectedTotalAmount.isEqualTo(txPrebuild.recipients[0].amount)) {
-          throwRecipientMismatch('batch token transaction amount in txPrebuild should be zero for token transfers', [
-            { address: txPrebuild.recipients[0].address, amount: txPrebuild.recipients[0].amount.toString() },
-          ]);
+          await throwRecipientMismatch(
+            'batch token transaction amount in txPrebuild should be zero for token transfers',
+            [{ address: txPrebuild.recipients[0].address, amount: txPrebuild.recipients[0].amount.toString() }]
+          );
         }
       } else {
         let expectedTotalAmount = new BigNumber(0);
         for (let i = 0; i < recipients.length; i++) {
           expectedTotalAmount = expectedTotalAmount.plus(recipients[i].amount);
         }
         if (!expectedTotalAmount.isEqualTo(txPrebuild.recipients[0].amount)) {
-          throwRecipientMismatch(
+          await throwRecipientMismatch(
             'batch transaction amount in txPrebuild received from BitGo servers does not match txParams supplied by client',
             [{ address: txPrebuild.recipients[0].address, amount: txPrebuild.recipients[0].amount.toString() }]
           );
@@ -3269,7 +3270,7 @@ export abstract class AbstractEthLikeNewCoins extends AbstractEthLikeCoin {
         !batcherContractAddress ||
         batcherContractAddress.toLowerCase() !== txPrebuild.recipients[0].address.toLowerCase()
       ) {
-        throwRecipientMismatch('recipient address of txPrebuild does not match batcher address', [
+        await throwRecipientMismatch('recipient address of txPrebuild does not match batcher address', [
           { address: txPrebuild.recipients[0].address, amount: txPrebuild.recipients[0].amount.toString() },
         ]);
       }
@@ -3280,20 +3281,21 @@ export abstract class AbstractEthLikeNewCoins extends AbstractEthLikeCoin {
       }
       const expectedAmount = new BigNumber(recipients[0].amount);
       if (!expectedAmount.isEqualTo(txPrebuild.recipients[0].amount)) {
-        throwRecipientMismatch(
+        await throwRecipientMismatch(
           'normal transaction amount in txPrebuild received from BitGo servers does not match txParams supplied by client',
           [{ address: txPrebuild.recipients[0].address, amount: txPrebuild.recipients[0].amount.toString() }]
         );
       }
       if (this.isETHAddress(recipients[0].address) && recipients[0].address !== txPrebuild.recipients[0].address) {
-        throwRecipientMismatch(
+        await throwRecipientMismatch(
           'destination address in normal txPrebuild does not match that in txParams supplied by client',
           [{ address: txPrebuild.recipients[0].address, amount: txPrebuild.recipients[0].amount.toString() }]
         );
       }
     }
     // Check coin is correct for all transaction types
     if (!this.verifyCoin(txPrebuild)) {
+      const txExplanation = await this.getTxExplanation(txPrebuild);
       throw new TxIntentMismatchError(
         'coin in txPrebuild did not match that in txParams supplied by client',
         undefined,

modules/abstract-utxo/src/abstractUtxoCoin.ts

@@ -28,6 +28,7 @@ import {
   PresignTransactionOptions,
   RequestTracer,
   SignedTransaction,
+  TxIntentMismatchError,
   SignTransactionOptions as BaseSignTransactionOptions,
   SupplementGenerateWalletOptions,
   TransactionParams as BaseTransactionParams,
@@ -61,7 +62,6 @@ import {
   assertValidTransactionRecipient,
   explainTx,
   fromExtendedAddressFormat,
-  getTxExplanation,
   isScriptRecipient,
   parseTransaction,
   verifyTransaction,
@@ -145,7 +145,7 @@ function convertValidationErrorToTxIntentMismatch(
   reqId: string | IRequestTracer | undefined,
   txParams: BaseTransactionParams,
   txHex: string | undefined,
-  txExplanation?: string
+  txExplanation?: unknown
 ): TxIntentMismatchRecipientError {
   const mismatchedRecipients: MismatchedRecipient[] = [];
 
@@ -619,12 +619,14 @@ 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) {
+        const txExplanation = await TxIntentMismatchError.tryGetTxExplanation(
+          this as unknown as IBaseCoin,
+          params.txPrebuild
+        );
         throw convertValidationErrorToTxIntentMismatch(
           error,
           params.reqId,

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

@@ -1,10 +1,9 @@
 import * as utxolib from '@bitgo/utxo-lib';
-import { ITransactionRecipient, TxIntentMismatchError } from '@bitgo/sdk-core';
+import { ITransactionRecipient, TxIntentMismatchError, IBaseCoin } from '@bitgo/sdk-core';
 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';
 
@@ -76,10 +75,12 @@ 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)) {
+    const txExplanation = await TxIntentMismatchError.tryGetTxExplanation(
+      coin as unknown as IBaseCoin,
+      params.txPrebuild
+    );
     throw new TxIntentMismatchError(
       'unexpected transaction type',
       params.reqId,

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

@@ -1,14 +1,13 @@
 import buildDebug from 'debug';
 import _ from 'lodash';
 import BigNumber from 'bignumber.js';
-import { BitGoBase, TxIntentMismatchError } from '@bitgo/sdk-core';
+import { BitGoBase, TxIntentMismatchError, IBaseCoin } from '@bitgo/sdk-core';
 import * as utxolib from '@bitgo/utxo-lib';
 
 import { AbstractUtxoCoin, VerifyTransactionOptions } from '../../abstractUtxoCoin';
 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');
 
@@ -51,7 +50,7 @@ export async function verifyTransaction<TNumber extends bigint | number>(
 ): Promise<boolean> {
   const { txParams, txPrebuild, wallet, verification = {}, reqId } = params;
 
-  const txExplanation = await getTxExplanation(coin, txPrebuild);
+  const txExplanation = await TxIntentMismatchError.tryGetTxExplanation(coin as unknown as IBaseCoin, txPrebuild);
 
   // Helper to throw TxIntentMismatchError with consistent context
   const throwTxMismatch = (message: string): never => {

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

@@ -3,6 +3,5 @@ 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

@@ -3,6 +3,7 @@
 import { BitGoJsError } from '../bitgojsError';
 import { IRequestTracer } from '../api/types';
 import { TransactionParams } from './baseCoin';
+import { IBaseCoin } from './baseCoin/iBaseCoin';
 import { SendManyOptions } from './wallet';
 
 // re-export for backwards compat
@@ -271,20 +272,58 @@ 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
+   * @param {unknown} txExplanation - Transaction explanation
    */
   public constructor(
     message: string,
     id: string | IRequestTracer | undefined,
     txParams: TransactionParams[],
     txHex: string | undefined,
-    txExplanation?: string
+    txExplanation?: unknown
   ) {
     super(message);
     this.id = id;
     this.txParams = txParams;
     this.txHex = txHex;
-    this.txExplanation = txExplanation;
+    this.txExplanation = txExplanation ? this.safeStringify(txExplanation) : undefined;
+  }
+
+  /**
+   * Safely stringify a value with BigInt support
+   * @param value - Value to stringify
+   * @returns JSON string with BigInts converted to strings
+   */
+  private safeStringify(value: unknown): string {
+    return JSON.stringify(value, (_, v) => (typeof v === 'bigint' ? v.toString() : v), 2);
+  }
+
+  /**
+   * Try to get transaction explanation from a coin's explainTransaction method.
+   *
+   * @param coin - Coin instance implementing IBaseCoin
+   * @param txPrebuild - Transaction prebuild containing txHex and txInfo
+   * @returns Transaction explanation object or undefined
+   */
+  static async tryGetTxExplanation(
+    coin: IBaseCoin,
+    txPrebuild: { txHex?: string; txInfo?: unknown }
+  ): Promise<unknown> {
+    if (!txPrebuild.txHex) {
+      return undefined;
+    }
+
+    try {
+      return await coin.explainTransaction({
+        txHex: txPrebuild.txHex,
+        txInfo: txPrebuild.txInfo,
+      });
+    } catch (e) {
+      return {
+        error: 'Failed to parse transaction explanation',
+        txHex: txPrebuild.txHex,
+        details: e instanceof Error ? e.message : String(e),
+      };
+    }
   }
 }
 
@@ -309,15 +348,15 @@ 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
+   * @param {unknown} txExplanation - Transaction explanation
    */
   public constructor(
     message: string,
     id: string | IRequestTracer | undefined,
     txParams: TransactionParams[],
     txHex: string | undefined,
     mismatchedRecipients: MismatchedRecipient[],
-    txExplanation?: string
+    txExplanation?: unknown
   ) {
     super(message, id, txParams, txHex, txExplanation);
     this.mismatchedRecipients = mismatchedRecipients;
@@ -345,15 +384,15 @@ 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
+   * @param {unknown} txExplanation - Transaction explanation
    */
   public constructor(
     message: string,
     id: string | IRequestTracer | undefined,
     txParams: TransactionParams[],
     txHex: string | undefined,
     mismatchedDataPayload: ContractDataPayload,
-    txExplanation?: string
+    txExplanation?: unknown
   ) {
     super(message, id, txParams, txHex, txExplanation);
     this.mismatchedDataPayload = mismatchedDataPayload;
@@ -381,15 +420,15 @@ 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
+   * @param {unknown} txExplanation - Transaction explanation
    */
   public constructor(
     message: string,
     id: string | IRequestTracer | undefined,
     txParams: TransactionParams[],
     txHex: string | undefined,
     tokenApproval: TokenApproval,
-    txExplanation?: string
+    txExplanation?: unknown
   ) {
     super(message, id, txParams, txHex, txExplanation);
     this.tokenApproval = tokenApproval;