feat(wasm-utxo): refactor transaction parsing API

OttoAllmendinger · llm-git · OttoAllmendinger · commit c8dde9b75ea6 · 2026-02-16T10:54:02.000+01:00
Refactor the PSBT transaction parsing interface to use structured options objects instead of individual parameters. This improves readability and makes the API more maintainable for future extensions. Specifically: - Add `ParseTransactionOptions` and `ParseOutputsOptions` types - Update `parseTransactionWithWalletKeys` and `parseOutputsWithWalletKeys` to use these option objects - Update all call sites to use the new API pattern Issue: BTC-2650 Co-authored-by: llm-git <llm-git@ttll.de>
diff --git a/packages/wasm-utxo/js/fixedScriptWallet/BitGoPsbt.ts b/packages/wasm-utxo/js/fixedScriptWallet/BitGoPsbt.ts
@@ -115,6 +115,15 @@ export type AddWalletOutputOptions = {
   value: bigint;
 };
 
+export type ParseTransactionOptions = {
+  replayProtection: ReplayProtectionArg;
+  payGoPubkeys?: ECPairArg[];
+};
+
+export type ParseOutputsOptions = {
+  payGoPubkeys?: ECPairArg[];
+};
+
 export class BitGoPsbt implements IPsbtIntrospectionWithAddress {
   protected constructor(protected _wasm: WasmBitGoPsbt) {}
 
@@ -424,18 +433,18 @@ export class BitGoPsbt implements IPsbtIntrospectionWithAddress {
   /**
    * Parse transaction with wallet keys to identify wallet inputs/outputs
    * @param walletKeys - The wallet keys to use for identification
-   * @param replayProtection - Scripts that are allowed as inputs without wallet validation
-   * @param payGoPubkeys - Optional public keys for PayGo attestation verification
+   * @param options - Options for parsing
+   * @param options.replayProtection - Scripts that are allowed as inputs without wallet validation
+   * @param options.payGoPubkeys - Optional public keys for PayGo attestation verification
    * @returns Parsed transaction information
    */
   parseTransactionWithWalletKeys(
     walletKeys: WalletKeysArg,
-    replayProtection: ReplayProtectionArg,
-    payGoPubkeys?: ECPairArg[],
+    options: ParseTransactionOptions,
   ): ParsedTransaction {
     const keys = RootWalletKeys.from(walletKeys);
-    const rp = ReplayProtection.from(replayProtection, this._wasm.network());
-    const pubkeys = payGoPubkeys?.map((arg) => ECPair.from(arg).wasm);
+    const rp = ReplayProtection.from(options.replayProtection, this._wasm.network());
+    const pubkeys = options.payGoPubkeys?.map((arg) => ECPair.from(arg).wasm);
     return this._wasm.parse_transaction_with_wallet_keys(
       keys.wasm,
       rp.wasm,
@@ -451,16 +460,17 @@ export class BitGoPsbt implements IPsbtIntrospectionWithAddress {
    * wallet than the inputs.
    *
    * @param walletKeys - The wallet keys to use for identification
-   * @param payGoPubkeys - Optional public keys for PayGo attestation verification
+   * @param options - Optional options for parsing
+   * @param options.payGoPubkeys - Optional public keys for PayGo attestation verification
    * @returns Array of parsed outputs
    * @note This method does NOT validate wallet inputs. It only parses outputs.
    */
   parseOutputsWithWalletKeys(
     walletKeys: WalletKeysArg,
-    payGoPubkeys?: ECPairArg[],
+    options?: ParseOutputsOptions,
   ): ParsedOutput[] {
     const keys = RootWalletKeys.from(walletKeys);
-    const pubkeys = payGoPubkeys?.map((arg) => ECPair.from(arg).wasm);
+    const pubkeys = options?.payGoPubkeys?.map((arg) => ECPair.from(arg).wasm);
     return this._wasm.parse_outputs_with_wallet_keys(keys.wasm, pubkeys) as ParsedOutput[];
   }
 
@@ -719,7 +729,7 @@ export class BitGoPsbt implements IPsbtIntrospectionWithAddress {
    * const counterpartyPsbt = BitGoPsbt.fromBytes(counterpartyPsbtBytes, network);
    * psbt.combineMusig2Nonces(counterpartyPsbt);
    * // Sign MuSig2 key path inputs
-   * const parsed = psbt.parseTransactionWithWalletKeys(walletKeys, replayProtection);
+   * const parsed = psbt.parseTransactionWithWalletKeys(walletKeys, { replayProtection });
    * for (let i = 0; i < parsed.inputs.length; i++) {
    *   if (parsed.inputs[i].scriptType === "p2trMusig2KeyPath") {
    *     psbt.sign(i, userXpriv);
diff --git a/packages/wasm-utxo/js/fixedScriptWallet/index.ts b/packages/wasm-utxo/js/fixedScriptWallet/index.ts
@@ -28,6 +28,8 @@ export {
   type AddOutputOptions,
   type AddWalletInputOptions,
   type AddWalletOutputOptions,
+  type ParseTransactionOptions,
+  type ParseOutputsOptions,
 } from "./BitGoPsbt.js";
 
 // Zcash-specific PSBT subclass
diff --git a/packages/wasm-utxo/test/acid-test/acidTest.test.ts b/packages/wasm-utxo/test/acid-test/acidTest.test.ts
@@ -95,7 +95,7 @@ describe("AcidTest", function () {
       // Verify no signatures present
       const rpKey = test.getReplayProtectionKey();
       const replayProtection = { publicKeys: [rpKey.publicKey] };
-      const parsed = psbt.parseTransactionWithWalletKeys(test.rootWalletKeys, replayProtection);
+      const parsed = psbt.parseTransactionWithWalletKeys(test.rootWalletKeys, { replayProtection });
       const user = test.rootWalletKeys.userKey();
       const backup = test.rootWalletKeys.backupKey();
       const bitgo = test.rootWalletKeys.bitgoKey();
@@ -128,7 +128,7 @@ describe("AcidTest", function () {
       // Verify one signature per input (user only)
       const rpKey = test.getReplayProtectionKey();
       const replayProtection = { publicKeys: [rpKey.publicKey] };
-      const parsed = psbt.parseTransactionWithWalletKeys(test.rootWalletKeys, replayProtection);
+      const parsed = psbt.parseTransactionWithWalletKeys(test.rootWalletKeys, { replayProtection });
       const user = test.rootWalletKeys.userKey();
       const backup = test.rootWalletKeys.backupKey();
       const bitgo = test.rootWalletKeys.bitgoKey();
@@ -175,7 +175,7 @@ describe("AcidTest", function () {
       // Verify two signatures per input (user + bitgo or user + backup)
       const rpKey = test.getReplayProtectionKey();
       const replayProtection = { publicKeys: [rpKey.publicKey] };
-      const parsed = psbt.parseTransactionWithWalletKeys(test.rootWalletKeys, replayProtection);
+      const parsed = psbt.parseTransactionWithWalletKeys(test.rootWalletKeys, { replayProtection });
       const user = test.rootWalletKeys.userKey();
       const backup = test.rootWalletKeys.backupKey();
       const bitgo = test.rootWalletKeys.bitgoKey();
diff --git a/packages/wasm-utxo/test/benchmark/signing.ts b/packages/wasm-utxo/test/benchmark/signing.ts
@@ -173,7 +173,9 @@ function benchmarkPerInputSign(
   // Clone PSBT for this benchmark
   const testPsbt = BitGoPsbt.fromBytes(psbt.serialize(), "bitcoin");
 
-  const parsed = testPsbt.parseTransactionWithWalletKeys(walletKeys, { publicKeys: [] });
+  const parsed = testPsbt.parseTransactionWithWalletKeys(walletKeys, {
+    replayProtection: { publicKeys: [] },
+  });
 
   // For MuSig2, generate nonces first (not timed)
   if (scriptType.isMuSig2KeyPath) {
diff --git a/packages/wasm-utxo/test/fixedScript/dogecoinLOLAmount.ts b/packages/wasm-utxo/test/fixedScript/dogecoinLOLAmount.ts
@@ -33,7 +33,9 @@ describe("Dogecoin large output limit amount (LOL amounts) (1-in/1-out)", functi
     psbt.addWalletInput({ txid, vout: 0, value }, walletKeys, { scriptId: { chain: 0, index: 0 } });
     psbt.addWalletOutput(walletKeys, { chain: 0, index: 0, value });
 
-    const parsed = psbt.parseTransactionWithWalletKeys(walletKeys, { publicKeys: [] });
+    const parsed = psbt.parseTransactionWithWalletKeys(walletKeys, {
+      replayProtection: { publicKeys: [] },
+    });
     assert.strictEqual(parsed.inputs.length, 1);
     assert.strictEqual(parsed.outputs.length, 1);
     assert.strictEqual(parsed.inputs[0].value, value);
diff --git a/packages/wasm-utxo/test/fixedScript/parseTransactionWithWalletKeys.ts b/packages/wasm-utxo/test/fixedScript/parseTransactionWithWalletKeys.ts
@@ -68,7 +68,7 @@ describe("parseTransactionWithWalletKeys", function () {
 
       it("should parse transaction and identify internal/external outputs", function () {
         const parsed = bitgoPsbt.parseTransactionWithWalletKeys(rootWalletKeys, {
-          publicKeys: [replayProtectionKey],
+          replayProtection: { publicKeys: [replayProtectionKey] },
         });
 
         // Verify all inputs have addresses and values
@@ -190,7 +190,7 @@ describe("parseTransactionWithWalletKeys", function () {
 
       it("should parse inputs with correct scriptType", function () {
         const parsed = bitgoPsbt.parseTransactionWithWalletKeys(rootWalletKeys, {
-          publicKeys: [replayProtectionKey],
+          replayProtection: { publicKeys: [replayProtectionKey] },
         });
 
         // Verify all inputs have scriptType matching fixture
@@ -245,7 +245,7 @@ describe("parseTransactionWithWalletKeys", function () {
         assert.throws(
           () => {
             bitgoPsbt.parseTransactionWithWalletKeys(getOtherWalletKeys(), {
-              publicKeys: [replayProtectionKey],
+              replayProtection: { publicKeys: [replayProtectionKey] },
             });
           },
           (error: Error) => {
diff --git a/packages/wasm-utxo/test/fixedScript/paygoAttestation.ts b/packages/wasm-utxo/test/fixedScript/paygoAttestation.ts
@@ -129,7 +129,7 @@ describe("PayGo Attestation", function () {
         "xpub661MyMwAqRbcFtXgS5sYJABqqG9YLmC4Q1Rdap9gSE8NqtwybGhePY2gZ29ESFjqJoCu1Rupje8YtGqsefD265TMg7usUDFdp6W1EGMcet8",
         "xpub661MyMwAqRbcFtXgS5sYJABqqG9YLmC4Q1Rdap9gSE8NqtwybGhePY2gZ29ESFjqJoCu1Rupje8YtGqsefD265TMg7usUDFdp6W1EGMcet8",
       ],
-      [pubkey],
+      { payGoPubkeys: [pubkey] },
     );
 
     assert.strictEqual(outputs.length, 1);
diff --git a/packages/wasm-utxo/test/fixedScript/psbtReconstruction.ts b/packages/wasm-utxo/test/fixedScript/psbtReconstruction.ts
@@ -82,7 +82,7 @@ describe("PSBT reconstruction", function () {
         // Parse the original PSBT to get inputs/outputs
         const replayProtectionKey = loadReplayProtectionKeyFromFixture(fixture);
         const parsedTx = originalPsbt.parseTransactionWithWalletKeys(rootWalletKeys, {
-          publicKeys: [replayProtectionKey],
+          replayProtection: { publicKeys: [replayProtectionKey] },
         });
 
         // Parse outputs with other wallet keys to detect outputs from different wallet
@@ -211,7 +211,7 @@ describe("PSBT reconstruction", function () {
       it("should include sequence in parsed inputs", function () {
         const replayProtectionKey = loadReplayProtectionKeyFromFixture(fixture);
         const parsedTx = originalPsbt.parseTransactionWithWalletKeys(rootWalletKeys, {
-          publicKeys: [replayProtectionKey],
+          replayProtection: { publicKeys: [replayProtectionKey] },
         });
 
         // Verify all inputs have sequence field
@@ -237,7 +237,7 @@ describe("PSBT reconstruction", function () {
 
         const replayProtectionKey = loadReplayProtectionKeyFromFixture(fixture);
         const parsedTx = originalPsbt.parseTransactionWithWalletKeys(rootWalletKeys, {
-          publicKeys: [replayProtectionKey],
+          replayProtection: { publicKeys: [replayProtectionKey] },
         });
         const parsedOutputsOther = originalPsbt.parseOutputsWithWalletKeys(otherWalletKeys);
 
diff --git a/packages/wasm-utxo/test/fixedScript/signAndVerifySignature.ts b/packages/wasm-utxo/test/fixedScript/signAndVerifySignature.ts
@@ -163,7 +163,7 @@ function verifyAllInputSignatures(
   signatureStage: SignatureStage,
 ): void {
   const parsed = bitgoPsbt.parseTransactionWithWalletKeys(rootWalletKeys, {
-    publicKeys: [replayProtectionKey],
+    replayProtection: { publicKeys: [replayProtectionKey] },
   });
 
   fixture.psbtInputs.forEach((input, index) => {
