feat(abstract-utxo): add explainPsbtWasmBigInt for bigint amounts

Refactor explainPsbtWasm to use explainPsbtWasmBigInt that returns
bigint amounts instead of strings. The original function now delegates
to the new implementation and converts results to strings for backward
compatibility.

Add input details (address, value) to transaction explanations.

Export utility functions (decodePsbt, decodePsbtWith, isPsbt,
getVSize) from transaction module for external use.

BTC-2768

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

Author: OttoAllmendinger

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

@@ -1,7 +1,7 @@
 import { fixedScriptWallet } from '@bitgo/wasm-utxo';
 import { Triple } from '@bitgo/sdk-core';
 
-import type { FixedScriptWalletOutput, Output } from '../types';
+import type { FixedScriptWalletOutput, Output, BitGoPsbt } from '../types';
 
 import type { TransactionExplanationWasm } from './explainTransaction';
 
@@ -20,71 +20,122 @@ function isParsedExternalOutput(output: ParsedWalletOutput | ParsedExternalOutpu
   return output.scriptId === null;
 }
 
-function toChangeOutput(output: ParsedWalletOutput): FixedScriptWalletOutput {
+function toChangeOutputBigInt(output: ParsedWalletOutput): FixedScriptWalletOutput<bigint> {
   return {
     address: output.address ?? scriptToAddress(output.script),
-    amount: output.value.toString(),
+    amount: output.value,
     chain: output.scriptId.chain,
     index: output.scriptId.index,
     external: false,
   };
 }
 
-function toExternalOutput(output: ParsedExternalOutput): Output {
+function toExternalOutputBigInt(output: ParsedExternalOutput): Output<bigint> {
   return {
     address: output.address ?? scriptToAddress(output.script),
-    amount: output.value.toString(),
+    amount: output.value,
     external: true,
   };
 }
 
-export function explainPsbtWasm(
-  psbt: fixedScriptWallet.BitGoPsbt,
+interface ExplainPsbtWasmParams {
+  replayProtection: {
+    checkSignature?: boolean;
+    publicKeys: Buffer[];
+  };
+  customChangeWalletXpubs?: Triple<string> | fixedScriptWallet.RootWalletKeys;
+}
+
+export interface ExplainedInput<TAmount = bigint> {
+  address: string;
+  value: TAmount;
+}
+
+export interface TransactionExplanationBigInt {
+  id: string;
+  inputs: ExplainedInput[];
+  inputAmount: bigint;
+  outputs: Output<bigint>[];
+  changeOutputs: FixedScriptWalletOutput<bigint>[];
+  customChangeOutputs: FixedScriptWalletOutput<bigint>[];
+  outputAmount: bigint;
+  changeAmount: bigint;
+  customChangeAmount: bigint;
+  fee: bigint;
+}
+
+export function explainPsbtWasmBigInt(
+  psbt: BitGoPsbt,
   walletXpubs: Triple<string> | fixedScriptWallet.RootWalletKeys,
-  params: {
-    replayProtection: {
-      checkSignature?: boolean;
-      publicKeys: Buffer[];
-    };
-    customChangeWalletXpubs?: Triple<string> | fixedScriptWallet.RootWalletKeys;
-  }
-): TransactionExplanationWasm {
+  params: ExplainPsbtWasmParams
+): TransactionExplanationBigInt {
   const parsed = psbt.parseTransactionWithWalletKeys(walletXpubs, { replayProtection: params.replayProtection });
 
-  const changeOutputs: FixedScriptWalletOutput[] = [];
-  const outputs: Output[] = [];
+  const changeOutputs: FixedScriptWalletOutput<bigint>[] = [];
+  const outputs: Output<bigint>[] = [];
   const parsedCustomChangeOutputs = params.customChangeWalletXpubs
     ? psbt.parseOutputsWithWalletKeys(params.customChangeWalletXpubs)
     : undefined;
 
-  const customChangeOutputs: FixedScriptWalletOutput[] = [];
+  const customChangeOutputs: FixedScriptWalletOutput<bigint>[] = [];
 
   parsed.outputs.forEach((output, i) => {
     const parseCustomChangeOutput = parsedCustomChangeOutputs?.[i];
     if (isParsedWalletOutput(output)) {
-      // This is a change output
-      changeOutputs.push(toChangeOutput(output));
+      changeOutputs.push(toChangeOutputBigInt(output));
     } else if (parseCustomChangeOutput && isParsedWalletOutput(parseCustomChangeOutput)) {
-      customChangeOutputs.push(toChangeOutput(parseCustomChangeOutput));
+      customChangeOutputs.push(toChangeOutputBigInt(parseCustomChangeOutput));
     } else if (isParsedExternalOutput(output)) {
-      outputs.push(toExternalOutput(output));
+      outputs.push(toExternalOutputBigInt(output));
     } else {
       throw new Error('Invalid output');
     }
   });
 
-  const outputAmount = outputs.reduce((sum, output) => sum + BigInt(output.amount), BigInt(0));
-  const changeAmount = changeOutputs.reduce((sum, output) => sum + BigInt(output.amount), BigInt(0));
-  const customChangeAmount = customChangeOutputs.reduce((sum, output) => sum + BigInt(output.amount), BigInt(0));
+  const inputs = parsed.inputs.map((input) => ({ address: input.address, value: input.value }));
+  const inputAmount = inputs.reduce((sum, input) => sum + input.value, 0n);
+  const outputAmount = outputs.reduce((sum, output) => sum + output.amount, 0n);
+  const changeAmount = changeOutputs.reduce((sum, output) => sum + output.amount, 0n);
+  const customChangeAmount = customChangeOutputs.reduce((sum, output) => sum + output.amount, 0n);
 
   return {
     id: psbt.unsignedTxId(),
-    outputAmount: outputAmount.toString(),
-    changeAmount: changeAmount.toString(),
-    customChangeAmount: customChangeAmount.toString(),
+    inputs,
+    inputAmount,
     outputs,
     changeOutputs,
     customChangeOutputs,
-    fee: parsed.minerFee.toString(),
+    outputAmount,
+    changeAmount,
+    customChangeAmount,
+    fee: parsed.minerFee,
+  };
+}
+
+function stringifyOutput(output: Output<bigint>): Output {
+  return { ...output, amount: output.amount.toString() };
+}
+
+function stringifyChangeOutput(output: FixedScriptWalletOutput<bigint>): FixedScriptWalletOutput {
+  return { ...output, amount: output.amount.toString() };
+}
+
+export function explainPsbtWasm(
+  psbt: BitGoPsbt,
+  walletXpubs: Triple<string> | fixedScriptWallet.RootWalletKeys,
+  params: ExplainPsbtWasmParams
+): TransactionExplanationWasm {
+  const result = explainPsbtWasmBigInt(psbt, walletXpubs, params);
+  return {
+    id: result.id,
+    inputs: result.inputs.map((i) => ({ address: i.address, value: i.value.toString() })),
+    inputAmount: result.inputAmount.toString(),
+    outputAmount: result.outputAmount.toString(),
+    changeAmount: result.changeAmount.toString(),
+    customChangeAmount: result.customChangeAmount.toString(),
+    outputs: result.outputs.map(stringifyOutput),
+    changeOutputs: result.changeOutputs.map(stringifyChangeOutput),
+    customChangeOutputs: result.customChangeOutputs.map(stringifyChangeOutput),
+    fee: result.fee.toString(),
   };
 }

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

@@ -51,7 +51,10 @@ interface TransactionExplanationWithSignatures<TFee = string, TChangeOutput exte
 }
 
 /** For our wasm backend, we do not return the deprecated fields. We set TFee to string for backwards compatibility. */
-export type TransactionExplanationWasm = AbstractUtxoTransactionExplanation<string, FixedScriptWalletOutput>;
+export type TransactionExplanationWasm = AbstractUtxoTransactionExplanation<string, FixedScriptWalletOutput> & {
+  inputs: Array<{ address: string; value: string }>;
+  inputAmount: string;
+};
 
 /** When parsing the legacy transaction format, we cannot always infer the fee so we set it to string | undefined */
 export type TransactionExplanationUtxolibLegacy = TransactionExplanationWithSignatures<string | undefined>;

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

@@ -1,5 +1,10 @@
 export { explainPsbt, explainLegacyTx, ChangeAddressInfo } from './explainTransaction';
-export { explainPsbtWasm } from './explainPsbtWasm';
+export {
+  explainPsbtWasm,
+  explainPsbtWasmBigInt,
+  type ExplainedInput,
+  type TransactionExplanationBigInt,
+} from './explainPsbtWasm';
 export { parseTransaction } from './parseTransaction';
 export { CustomChangeOptions } from './parseOutput';
 export { verifyTransaction } from './verifyTransaction';

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

@@ -5,3 +5,4 @@ export { parseTransaction } from './parseTransaction';
 export { verifyTransaction } from './verifyTransaction';
 export * from './fetchInputs';
 export * as bip322 from './bip322';
+export { decodePsbt, decodePsbtWith } from './decode';

modules/abstract-utxo/test/unit/transaction/fixedScript/explainPsbt.ts

@@ -5,7 +5,7 @@ import { testutil } from '@bitgo/utxo-lib';
 import { fixedScriptWallet, Triple } from '@bitgo/wasm-utxo';
 
 import type { TransactionExplanation } from '../../../../src/transaction/fixedScript/explainTransaction';
-import { explainPsbt, explainPsbtWasm } from '../../../../src/transaction/fixedScript';
+import { explainPsbt, explainPsbtWasm, explainPsbtWasmBigInt } from '../../../../src/transaction/fixedScript';
 import { getCoinName } from '../../../../src/names';
 
 function describeTransactionWith(acidTest: testutil.AcidTest) {
@@ -79,12 +79,42 @@ function describeTransactionWith(acidTest: testutil.AcidTest) {
             break;
         }
       }
+
+      // verify new fields are present and stringified
+      assert.strictEqual(typeof wasmExplanation.inputAmount, 'string');
+      assert.ok(Array.isArray(wasmExplanation.inputs));
+      assert.ok(wasmExplanation.inputs.length > 0);
+      for (const input of wasmExplanation.inputs) {
+        assert.strictEqual(typeof input.address, 'string');
+        assert.strictEqual(typeof input.value, 'string');
+      }
     });
 
     if (acidTest.network !== utxolib.networks.bitcoin) {
       return;
     }
 
+    it('explainPsbtWasmBigInt returns bigint amounts and inputs array', function () {
+      const result = explainPsbtWasmBigInt(wasmPsbt, walletXpubs, {
+        replayProtection: { publicKeys: [acidTest.getReplayProtectionPublicKey()] },
+      });
+      assert.strictEqual(typeof result.fee, 'bigint');
+      assert.strictEqual(typeof result.outputAmount, 'bigint');
+      assert.strictEqual(typeof result.changeAmount, 'bigint');
+      assert.strictEqual(typeof result.inputAmount, 'bigint');
+      assert.ok(result.inputs.length > 0);
+      for (const input of result.inputs) {
+        assert.strictEqual(typeof input.address, 'string');
+        assert.strictEqual(typeof input.value, 'bigint');
+      }
+      const sumInputs = result.inputs.reduce((s, i) => s + i.value, 0n);
+      assert.strictEqual(result.inputAmount, sumInputs);
+      assert.strictEqual(
+        result.fee,
+        result.inputAmount - result.outputAmount - result.changeAmount - result.customChangeAmount
+      );
+    });
+
     // extended test suite for bitcoin
 
     it('returns custom change outputs when parameter is set', function () {