feat(abstract-utxo): add aggregateTransactionExplanations with tests

Add comprehensive test coverage for the new aggregation function,
verifying identity property for single explanations and additive
property for multiple explanations.

Issue: BTC-2768

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

Author: OttoAllmendinger

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

@@ -139,3 +139,45 @@ export function explainPsbtWasm(
     fee: result.fee.toString(),
   };
 }
+
+export interface AggregatedTransactionExplanation {
+  inputCount: number;
+  outputCount: number;
+  changeOutputCount: number;
+  inputAmount: bigint;
+  outputAmount: bigint;
+  changeAmount: bigint;
+  fee: bigint;
+}
+
+export function aggregateTransactionExplanations(
+  explanations: TransactionExplanationBigInt[]
+): AggregatedTransactionExplanation {
+  let inputCount = 0;
+  let outputCount = 0;
+  let changeOutputCount = 0;
+  let fee = 0n;
+  let inputAmount = 0n;
+  let outputAmount = 0n;
+  let changeAmount = 0n;
+
+  for (const e of explanations) {
+    inputCount += e.inputs.length;
+    outputCount += e.outputs.length;
+    changeOutputCount += e.changeOutputs.length;
+    fee += e.fee;
+    inputAmount += e.inputAmount;
+    outputAmount += e.outputAmount;
+    changeAmount += e.changeAmount;
+  }
+
+  return {
+    inputCount,
+    outputCount,
+    changeOutputCount,
+    inputAmount,
+    outputAmount,
+    changeAmount,
+    fee,
+  };
+}

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

@@ -2,8 +2,10 @@ export { explainPsbt, explainLegacyTx, ChangeAddressInfo } from './explainTransa
 export {
   explainPsbtWasm,
   explainPsbtWasmBigInt,
+  aggregateTransactionExplanations,
   type ExplainedInput,
   type TransactionExplanationBigInt,
+  type AggregatedTransactionExplanation,
 } from './explainPsbtWasm';
 export { parseTransaction } from './parseTransaction';
 export { CustomChangeOptions } from './parseOutput';

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

@@ -5,7 +5,13 @@ import { testutil } from '@bitgo/utxo-lib';
 import { fixedScriptWallet, Triple } from '@bitgo/wasm-utxo';
 
 import type { TransactionExplanation } from '../../../../src/transaction/fixedScript/explainTransaction';
-import { explainPsbt, explainPsbtWasm, explainPsbtWasmBigInt } from '../../../../src/transaction/fixedScript';
+import {
+  explainPsbt,
+  explainPsbtWasm,
+  explainPsbtWasmBigInt,
+  aggregateTransactionExplanations,
+  type TransactionExplanationBigInt,
+} from '../../../../src/transaction/fixedScript';
 import { getCoinName } from '../../../../src/names';
 
 function describeTransactionWith(acidTest: testutil.AcidTest) {
@@ -135,3 +141,46 @@ function describeTransactionWith(acidTest: testutil.AcidTest) {
 describe('explainPsbt(Wasm)', function () {
   testutil.AcidTest.suite().forEach((test) => describeTransactionWith(test));
 });
+
+describe('aggregateTransactionExplanations', function () {
+  testutil.AcidTest.suite()
+    .filter((t) => t.network === utxolib.networks.bitcoin)
+    .forEach((acidTest) => {
+      describe(acidTest.name, function () {
+        let exp: TransactionExplanationBigInt;
+
+        before('prepare', function () {
+          const psbtBytes = acidTest.createPsbt().toBuffer();
+          const networkName = utxolib.getNetworkName(acidTest.network);
+          assert(networkName);
+          const wasmPsbt = fixedScriptWallet.BitGoPsbt.fromBytes(psbtBytes, networkName);
+          const walletXpubs = acidTest.rootWalletKeys.triple.map((k) => k.neutered().toBase58()) as Triple<string>;
+          exp = explainPsbtWasmBigInt(wasmPsbt, walletXpubs, {
+            replayProtection: { publicKeys: [acidTest.getReplayProtectionPublicKey()] },
+          });
+        });
+
+        it('aggregating a single explanation is identity', function () {
+          const agg = aggregateTransactionExplanations([exp]);
+          assert.strictEqual(agg.inputCount, exp.inputs.length);
+          assert.strictEqual(agg.outputCount, exp.outputs.length);
+          assert.strictEqual(agg.changeOutputCount, exp.changeOutputs.length);
+          assert.strictEqual(agg.inputAmount, exp.inputAmount);
+          assert.strictEqual(agg.outputAmount, exp.outputAmount);
+          assert.strictEqual(agg.changeAmount, exp.changeAmount);
+          assert.strictEqual(agg.fee, exp.fee);
+        });
+
+        it('aggregating two identical explanations doubles all counts and amounts', function () {
+          const agg = aggregateTransactionExplanations([exp, exp]);
+          assert.strictEqual(agg.inputCount, exp.inputs.length * 2);
+          assert.strictEqual(agg.outputCount, exp.outputs.length * 2);
+          assert.strictEqual(agg.changeOutputCount, exp.changeOutputs.length * 2);
+          assert.strictEqual(agg.inputAmount, exp.inputAmount * 2n);
+          assert.strictEqual(agg.outputAmount, exp.outputAmount * 2n);
+          assert.strictEqual(agg.changeAmount, exp.changeAmount * 2n);
+          assert.strictEqual(agg.fee, exp.fee * 2n);
+        });
+      });
+    });
+});