feat(abstract-utxo): add custom change wallet parsing to PSBT explainer

Add support for parsing custom change outputs using provided wallet xpubs.
This enhances the transaction explanation function to identify outputs that
might belong to a different wallet than the main one.

Issue: BTC-2732

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

Author: OttoAllmendinger

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

@@ -46,34 +46,45 @@ export function explainPsbtWasm(
       checkSignature?: boolean;
       outputScripts: Buffer[];
     };
+    customChangeWalletXpubs?: Triple<string>;
   }
 ): TransactionExplanationWasm {
   const parsed = psbt.parseTransactionWithWalletKeys(walletXpubs, params.replayProtection);
 
   const changeOutputs: FixedScriptWalletOutput[] = [];
   const outputs: Output[] = [];
+  const parsedCustomChangeOutputs = params.customChangeWalletXpubs
+    ? psbt.parseOutputsWithWalletKeys(params.customChangeWalletXpubs)
+    : undefined;
 
-  parsed.outputs.forEach((output) => {
+  const customChangeOutputs: FixedScriptWalletOutput[] = [];
+
+  parsed.outputs.forEach((output, i) => {
+    const parseCustomChangeOutput = parsedCustomChangeOutputs?.[i];
     if (isParsedWalletOutput(output)) {
       // This is a change output
       changeOutputs.push(toChangeOutput(output));
+    } else if (parseCustomChangeOutput && isParsedWalletOutput(parseCustomChangeOutput)) {
+      customChangeOutputs.push(toChangeOutput(parseCustomChangeOutput));
     } else if (isParsedExternalOutput(output)) {
-      // This is an external output
       outputs.push(toExternalOutput(output));
     } else {
       throw new Error('Invalid output');
     }
   });
 
-  const changeAmount = changeOutputs.reduce((sum, output) => sum + BigInt(output.amount), BigInt(0));
   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));
 
   return {
     id: psbt.unsignedTxid(),
     outputAmount: outputAmount.toString(),
     changeAmount: changeAmount.toString(),
+    customChangeAmount: customChangeAmount.toString(),
     outputs,
     changeOutputs,
+    customChangeOutputs,
     fee: parsed.minerFee.toString(),
   };
 }

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

@@ -20,13 +20,23 @@ function describeTransactionWith(acidTest: testutil.AcidTest) {
   describe(`${acidTest.name}`, function () {
     let psbt: utxolib.bitgo.UtxoPsbt;
     let psbtBytes: Buffer;
+    let walletXpubs: Triple<string>;
+    let customChangeWalletXpubs: Triple<string> | undefined;
+    let wasmPsbt: fixedScriptWallet.BitGoPsbt;
     let refExplanation: TransactionExplanation;
     before('prepare', function () {
       psbt = acidTest.createPsbt();
       refExplanation = explainPsbt(psbt, { pubs: acidTest.rootWalletKeys }, acidTest.network, {
         strict: true,
       });
       psbtBytes = psbt.toBuffer();
+      const networkName = utxolib.getNetworkName(acidTest.network);
+      assert(networkName);
+      walletXpubs = acidTest.rootWalletKeys.triple.map((k) => k.neutered().toBase58()) as Triple<string>;
+      customChangeWalletXpubs = acidTest.otherWalletKeys.triple.map((k) => k.neutered().toBase58()) as Triple<string>;
+      if (hasWasmUtxoSupport(acidTest.network)) {
+        wasmPsbt = fixedScriptWallet.BitGoPsbt.fromBytes(psbtBytes, networkName);
+      }
     });
 
     it('should match the expected values for explainPsbt', function () {
@@ -60,10 +70,6 @@ function describeTransactionWith(acidTest: testutil.AcidTest) {
         return this.skip();
       }
 
-      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>;
       const wasmExplanation = explainPsbtWasm(wasmPsbt, walletXpubs, {
         replayProtection: {
           outputScripts: [acidTest.getReplayProtectionOutputScript()],
@@ -86,6 +92,25 @@ function describeTransactionWith(acidTest: testutil.AcidTest) {
         }
       }
     });
+
+    if (acidTest.network !== utxolib.networks.bitcoin) {
+      return;
+    }
+
+    // extended test suite for bitcoin
+
+    it('returns custom change outputs when parameter is set', function () {
+      const wasmExplanation = explainPsbtWasm(wasmPsbt, walletXpubs, {
+        replayProtection: {
+          outputScripts: [acidTest.getReplayProtectionOutputScript()],
+        },
+        customChangeWalletXpubs,
+      });
+      assert.ok(wasmExplanation.customChangeOutputs);
+      assert.deepStrictEqual(wasmExplanation.outputs.length, 2);
+      assert.deepStrictEqual(wasmExplanation.customChangeOutputs.length, 1);
+      assert.deepStrictEqual(wasmExplanation.customChangeOutputs[0].amount, '900');
+    });
   });
 }