feat(wasm-utxo): add method to parse outputs with wallet keys

Adds a new method to BitGoPsbt that allows parsing transaction outputs
with wallet keys without requiring valid wallet inputs. This enables
identification of which outputs belong to a given wallet, even if the
inputs don't belong to the same wallet.

The implementation reuses existing parsing logic and adds proper tests
that verify outputs can be correctly identified when using different
wallet keys.

Issue: BTC-2652

Co-authored-by: llm-git <[email protected]>

Author: OttoAllmendinger

packages/wasm-utxo/js/fixedScriptWallet.ts

@@ -106,4 +106,19 @@ export class BitGoPsbt {
   ): ParsedTransaction {
     return this.wasm.parseTransactionWithWalletKeys(walletKeys, replayProtection);
   }
+
+  /**
+   * Parse outputs with wallet keys to identify which outputs belong to a wallet
+   * with the given wallet keys.
+   *
+   * This is useful in cases where we want to identify outputs that belong to a different
+   * wallet than the inputs.
+   *
+   * @param walletKeys - The wallet keys to use for identification
+   * @returns Array of parsed outputs
+   * @note This method does NOT validate wallet inputs. It only parses outputs.
+   */
+  parseOutputsWithWalletKeys(walletKeys: WalletKeys): ParsedOutput[] {
+    return this.wasm.parseOutputsWithWalletKeys(walletKeys);
+  }
 }

packages/wasm-utxo/src/fixed_script_wallet/bitgo_psbt/mod.rs

@@ -463,6 +463,67 @@ impl BitGoPsbt {
         }
     }
 
+    /// Parse outputs with wallet keys to identify which outputs belong to the wallet
+    ///
+    /// # Arguments
+    /// - `wallet_keys`: The wallet's root keys for deriving scripts
+    ///
+    /// # Returns
+    /// - `Ok(Vec<ParsedOutput>)` with parsed outputs
+    /// - `Err(ParseTransactionError)` if output parsing fails
+    ///
+    /// # Note
+    /// This method does NOT validate wallet inputs. It only parses outputs to identify
+    /// which ones belong to the provided wallet keys.
+    fn parse_outputs(
+        &self,
+        wallet_keys: &crate::fixed_script_wallet::RootWalletKeys,
+    ) -> Result<Vec<ParsedOutput>, ParseTransactionError> {
+        let psbt = self.psbt();
+        let network = self.network();
+
+        let mut parsed_outputs = Vec::new();
+
+        for (output_index, tx_output) in psbt.unsigned_tx.output.iter().enumerate() {
+            let psbt_output = &psbt.outputs[output_index];
+
+            // Parse the output
+            let parsed_output = ParsedOutput::parse(psbt_output, tx_output, wallet_keys, network)
+                .map_err(|error| ParseTransactionError::Output {
+                index: output_index,
+                error,
+            })?;
+
+            parsed_outputs.push(parsed_output);
+        }
+
+        Ok(parsed_outputs)
+    }
+
+    /// Parse outputs with wallet keys to identify which outputs belong to a particular wallet.
+    ///
+    /// This is useful in cases where we want to identify outputs that belong to a different
+    /// wallet than the inputs.
+    ///
+    /// If you only want to identify change outputs, use `parse_transaction_with_wallet_keys` instead.
+    ///
+    /// # Arguments
+    /// - `wallet_keys`: A wallet's root keys for deriving scripts (can be different wallet than the inputs)
+    ///
+    /// # Returns
+    /// - `Ok(Vec<ParsedOutput>)` with parsed outputs
+    /// - `Err(ParseTransactionError)` if output parsing fails
+    ///
+    /// # Note
+    /// This method does NOT validate wallet inputs. It only parses outputs to identify
+    /// which ones belong to the provided wallet keys.
+    pub fn parse_outputs_with_wallet_keys(
+        &self,
+        wallet_keys: &crate::fixed_script_wallet::RootWalletKeys,
+    ) -> Result<Vec<ParsedOutput>, ParseTransactionError> {
+        self.parse_outputs(wallet_keys)
+    }
+
     /// Parse transaction with wallet keys to identify wallet inputs/outputs and calculate metrics
     ///
     /// # Arguments
@@ -512,27 +573,26 @@ impl BitGoPsbt {
             parsed_inputs.push(parsed_input);
         }
 
-        // Parse outputs
-        let mut parsed_outputs = Vec::new();
+        // Parse outputs using the reusable method
+        let parsed_outputs = self.parse_outputs(wallet_keys)?;
+
+        // Calculate totals and spend amount
         let mut total_output_value = 0u64;
         let mut spend_amount = 0u64;
 
-        for (output_index, tx_output) in psbt.unsigned_tx.output.iter().enumerate() {
-            let psbt_output = &psbt.outputs[output_index];
-
+        for (output_index, (tx_output, parsed_output)) in psbt
+            .unsigned_tx
+            .output
+            .iter()
+            .zip(parsed_outputs.iter())
+            .enumerate()
+        {
             total_output_value = total_output_value
                 .checked_add(tx_output.value.to_sat())
                 .ok_or(ParseTransactionError::OutputValueOverflow {
                     index: output_index,
                 })?;
 
-            // Parse the output
-            let parsed_output = ParsedOutput::parse(psbt_output, tx_output, wallet_keys, network)
-                .map_err(|error| ParseTransactionError::Output {
-                index: output_index,
-                error,
-            })?;
-
             // If this is an external output, add to spend amount
             if parsed_output.is_external() {
                 spend_amount = spend_amount.checked_add(tx_output.value.to_sat()).ok_or(
@@ -541,8 +601,6 @@ impl BitGoPsbt {
                     },
                 )?;
             }
-
-            parsed_outputs.push(parsed_output);
         }
 
         // Calculate miner fee

packages/wasm-utxo/src/wasm/fixed_script_wallet.rs

@@ -171,4 +171,25 @@ impl BitGoPsbt {
         // Convert to JsValue directly using TryIntoJsValue
         parsed_tx.try_to_js_value()
     }
+
+    /// Parse outputs with wallet keys to identify which outputs belong to a wallet
+    ///
+    /// Note: This method does NOT validate wallet inputs. It only parses outputs.
+    #[wasm_bindgen(js_name = parseOutputsWithWalletKeys)]
+    pub fn parse_outputs_with_wallet_keys(
+        &self,
+        wallet_keys: JsValue,
+    ) -> Result<JsValue, WasmUtxoError> {
+        // Convert wallet keys from JsValue
+        let wallet_keys = root_wallet_keys_from_jsvalue(&wallet_keys)?;
+
+        // Call the Rust implementation
+        let parsed_outputs = self
+            .psbt
+            .parse_outputs_with_wallet_keys(&wallet_keys)
+            .map_err(|e| WasmUtxoError::new(&format!("Failed to parse outputs: {}", e)))?;
+
+        // Convert Vec<ParsedOutput> to JsValue
+        parsed_outputs.try_to_js_value()
+    }
 }

packages/wasm-utxo/test/fixedScript/parseTransactionWithWalletKeys.ts

@@ -3,9 +3,15 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import * as utxolib from "@bitgo/utxo-lib";
 import { fixedScriptWallet } from "../../js";
+import { BitGoPsbt } from "../../js/fixedScriptWallet";
 
 type Triple<T> = [T, T, T];
 
+function getOtherWalletKeys(): utxolib.bitgo.RootWalletKeys {
+  const otherWalletKeys = utxolib.testutil.getKeyTriple("too many secrets");
+  return new utxolib.bitgo.RootWalletKeys(otherWalletKeys);
+}
+
 /**
  * Load a PSBT fixture from JSON file and return the PSBT bytes
  */
@@ -72,13 +78,17 @@ describe("parseTransactionWithWalletKeys", function () {
     const networkName = utxolib.getNetworkName(network);
 
     describe(`network: ${networkName}`, function () {
-      it("should parse transaction and identify internal/external outputs", function () {
-        // Load PSBT from fixture
-        const psbtBytes = loadPsbtFixture(networkName);
-        const rootWalletKeys = loadWalletKeysFromFixture(networkName);
+      let psbtBytes: Buffer;
+      let bitgoPsbt: BitGoPsbt;
+      let rootWalletKeys: utxolib.bitgo.RootWalletKeys;
+
+      before(function () {
+        psbtBytes = loadPsbtFixture(networkName);
+        bitgoPsbt = fixedScriptWallet.BitGoPsbt.fromBytes(psbtBytes, networkName);
+        rootWalletKeys = loadWalletKeysFromFixture(networkName);
+      });
 
-        // Parse with WASM
-        const bitgoPsbt = fixedScriptWallet.BitGoPsbt.fromBytes(psbtBytes, networkName);
+      it("should parse transaction and identify internal/external outputs", function () {
         const parsed = bitgoPsbt.parseTransactionWithWalletKeys(rootWalletKeys, {
           outputScripts: [replayProtectionScript],
         });
@@ -144,6 +154,79 @@ describe("parseTransactionWithWalletKeys", function () {
         assert.ok(typeof parsed.virtualSize === "number", "Virtual size should be a number");
         assert.ok(parsed.virtualSize > 0, "Virtual size should be > 0");
       });
+
+      it("should fail to parse with other wallet keys", function () {
+        assert.throws(
+          () => {
+            bitgoPsbt.parseTransactionWithWalletKeys(getOtherWalletKeys(), {
+              outputScripts: [replayProtectionScript],
+            });
+          },
+          (error: Error) => {
+            return error.message.includes(
+              "Failed to parse transaction: Input 0: wallet validation failed",
+            );
+          },
+        );
+      });
+
+      it("should recognize output for other wallet keys", function () {
+        const parsedOutputs = bitgoPsbt.parseOutputsWithWalletKeys(getOtherWalletKeys());
+
+        // Should return an array of parsed outputs
+        assert.ok(Array.isArray(parsedOutputs), "Should return an array");
+        assert.ok(parsedOutputs.length > 0, "Should have at least one output");
+
+        // Verify all outputs have proper structure
+        parsedOutputs.forEach((output, i) => {
+          assert.ok(output.script instanceof Uint8Array, `Output ${i} script should be Uint8Array`);
+          assert.ok(typeof output.value === "bigint", `Output ${i} value should be bigint`);
+          assert.ok(output.value > 0n, `Output ${i} value should be > 0`);
+          // Address can be null for non-standard scripts
+          assert.ok(
+            typeof output.address === "string" || output.address === null,
+            `Output ${i} address should be string or null`,
+          );
+          // scriptId can be null for external outputs
+          assert.ok(
+            output.scriptId === null ||
+              (typeof output.scriptId === "object" &&
+                typeof output.scriptId.chain === "number" &&
+                typeof output.scriptId.index === "number"),
+            `Output ${i} scriptId should be null or an object with chain and index`,
+          );
+        });
+
+        // Compare with the original wallet keys to verify we get different results
+        const originalParsedOutputs = bitgoPsbt.parseOutputsWithWalletKeys(rootWalletKeys);
+
+        // Should have the same number of outputs
+        assert.strictEqual(
+          parsedOutputs.length,
+          originalParsedOutputs.length,
+          "Should parse the same number of outputs",
+        );
+
+        // Find outputs that belong to the other wallet keys (scriptId !== null)
+        const otherWalletOutputs = parsedOutputs.filter((o) => o.scriptId !== null);
+
+        // Should have exactly one output for the other wallet keys
+        assert.strictEqual(
+          otherWalletOutputs.length,
+          1,
+          "Should have exactly one output belonging to the other wallet keys",
+        );
+
+        // Verify that this output is marked as external (scriptId === null) under regular wallet keys
+        const otherWalletOutputIndex = parsedOutputs.findIndex((o) => o.scriptId !== null);
+        const sameOutputWithRegularKeys = originalParsedOutputs[otherWalletOutputIndex];
+
+        assert.strictEqual(
+          sameOutputWithRegularKeys.scriptId,
+          null,
+          "The output belonging to other wallet keys should be marked as external (scriptId === null) when parsed with regular wallet keys",
+        );
+      });
     });
   });