feat: add tx explanation for TxIntentMismatch errors #7580

danielpeng1 · 2025-11-20T12:43:57Z

Adding tx explanation for TxIntentMismatch errors for UTXO and ETH-like coins.

Implemented getTxExplanation method in both AbstractEthLikeNewCoins and AbstractUtxoCoin to generate detailed transaction explanations for error reporting.
- Created txExplanation.ts to use in abstractUtxoCoin.ts and both verifyTransactions
Updated error handling in tx verification methods to include tx explanations in TxIntentMismatchError and its subclasses.
Added unit tests to validate the inclusion of tx explanations in error instances.

OttoAllmendinger · 2025-11-20T13:14:11Z

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

+      txHex: txPrebuild.txHex,
+      txInfo: txPrebuild.txInfo,
+    });
+    return JSON.stringify(explanation, null, 2);


this will not work with bigint values

will do a bigint-safe JSON serialization. Can I create a test file modules/abstract-utxo/test/unit/txExplanation.ts to test this

why do we need to a return a string here anyway? we already have src/transaction/explainTransaction.ts already as well, so why are we adding another file here?

why can't the caller of this func (whoever that is) deal with the string conversion?

Is the alternative to return the object (explanation)? Then the parent error class TxIntentMismatchError's constructor would handle the JSON.stringify for example?

regardless I can move this function to src/transaction/explainTransaction.ts

Is the alternative to return the object (explanation)? Then the parent error class TxIntentMismatchError's constructor would handle the JSON.stringify for example?

yes

regardless I can move this function to src/transaction/explainTransaction.ts

I don't think we need a new function

but then we would need to duplicate/in-line this try catch logic in each call site? In descriptor/verifyTransaction.ts, fixedScript/verifyTransaction.ts, abstractUtxoCoin.ts

how about https://github.com/BitGo/BitGoJS/pull/7580/files/418878dd16a114c8dae0b233019abc5ad4bdf41f#r2546538479

Isn't this is returning a string again though? (instead of the explanation object)

yes but at least it is relegated to the error class, so I'm not as concerned about the interface

you can implement it returning unknown or string | undefined, your call

OttoAllmendinger · 2025-11-20T13:15:13Z

modules/abstract-utxo/src/abstractUtxoCoin.ts

  async verifyTransaction<TNumber extends number | bigint = number>(
    params: VerifyTransactionOptions<TNumber>
  ): Promise<boolean> {
+    const txExplanation = await getTxExplanation(this, params.txPrebuild);


this is pretty wasteful if we only use it in the catch block - move it there

OttoAllmendinger · 2025-11-20T13:15:18Z

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

  params: VerifyTransactionOptions<TNumber>,
  descriptorMap: DescriptorMap
 ): Promise<boolean> {
+  const txExplanation = await getTxExplanation(coin, params.txPrebuild);


OttoAllmendinger

better deal with the string explanation -> conversion in the sdk-core errors

OttoAllmendinger · 2025-11-20T14:34:59Z

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

+      txHex: txPrebuild.txHex,
+      txInfo: txPrebuild.txInfo,
+    });
+    return JSON.stringify(explanation, null, 2);


why do we need to a return a string here anyway? we already have src/transaction/explainTransaction.ts already as well, so why are we adding another file here?

why can't the caller of this func (whoever that is) deal with the string conversion?

OttoAllmendinger · 2025-11-20T14:35:40Z

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

 * @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


better make this unknown

OttoAllmendinger · 2025-11-20T14:36:10Z

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

    txParams: TransactionParams[],
-    txHex: string | undefined
+    txHex: string | undefined,
+    txExplanation?: string


unknown here

OttoAllmendinger · 2025-11-20T14:36:39Z

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

    this.id = id;
    this.txParams = txParams;
    this.txHex = txHex;
+    this.txExplanation = txExplanation;


do some sort of safe stringification here (JSON.stringify with bigint substitution)

OttoAllmendinger · 2025-11-20T15:29:33Z

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

 * @property {string | undefined} txHex - The raw transaction in hexadecimal format
+ * @property {string | undefined} txExplanation - Stringified transaction explanation
 */
 export class TxIntentMismatchError extends BitGoJsError {


add a static function here

static tryGetTxExplanation(coin: AbstractCoin, tx): Promise<string | undefined> { try { return bigintSafeStringify(coin.getExplanation(tx)); } catch (e) { return String(e); // with tx etc } }

OttoAllmendinger · 2025-11-20T15:29:46Z

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

+      txHex: txPrebuild.txHex,
+      txInfo: txPrebuild.txInfo,
+    });
+    return JSON.stringify(explanation, null, 2);


how about https://github.com/BitGo/BitGoJS/pull/7580/files/418878dd16a114c8dae0b233019abc5ad4bdf41f#r2546538479

mullapudipruthvik · 2025-11-20T20:19:41Z

modules/abstract-eth/src/abstractEthLikeNewCoins.ts

  async verifyTssTransaction(params: VerifyEthTransactionOptions): Promise<boolean> {
    const { txParams, txPrebuild, wallet } = params;

+    const txExplanation = await this.getTxExplanation(txPrebuild);


can we have this inside throwRecipientMismatch function ?
so that its only called when required

and probably have the string conversion inside, instead of a new function

feat: add tx explanation for TxIntentMismatch errors

418878d

Ticket: WP-6608

danielpeng1 self-assigned this Nov 20, 2025

danielpeng1 marked this pull request as ready for review November 20, 2025 13:09

danielpeng1 requested review from a team as code owners November 20, 2025 13:09

danielpeng1 requested review from mohammadalfaiyazbitgo, pengyuc-bitgo and rahulhegde-bitgo November 20, 2025 13:09

OttoAllmendinger requested changes Nov 20, 2025

View reviewed changes

OttoAllmendinger reviewed Nov 20, 2025

View reviewed changes

mullapudipruthvik reviewed Nov 20, 2025

View reviewed changes

feat: add tx explanation for TxIntentMismatch errors #7580

Are you sure you want to change the base?

feat: add tx explanation for TxIntentMismatch errors #7580

Uh oh!

Conversation

danielpeng1 commented Nov 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

danielpeng1 Nov 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

danielpeng1 Nov 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

OttoAllmendinger left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

danielpeng1 commented Nov 20, 2025 •

edited

Loading

danielpeng1 Nov 20, 2025 •

edited

Loading

danielpeng1 Nov 20, 2025 •

edited

Loading