feat(wasm-utxo): implement ReplayProtection class

Add a dedicated ReplayProtection class to handle replay protection inputs
in transactions. The implementation supports creating replay protection
from public keys, output scripts, or addresses, providing a cleaner API
than the previous approach using plain objects.

Issue: BTC-2786

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

Author: OttoAllmendinger

packages/wasm-utxo/js/fixedScriptWallet/BitGoPsbt.ts

@@ -1,20 +1,13 @@
 import { BitGoPsbt as WasmBitGoPsbt } from "../wasm/wasm_utxo.js";
 import { type WalletKeysArg, RootWalletKeys } from "./RootWalletKeys.js";
+import { type ReplayProtectionArg, ReplayProtection } from "./ReplayProtection.js";
 import { type BIP32Arg, BIP32 } from "../bip32.js";
 import { type ECPairArg, ECPair } from "../ecpair.js";
 import type { UtxolibName } from "../utxolibCompat.js";
 import type { CoinName } from "../coinName.js";
 
 export type NetworkName = UtxolibName | CoinName;
 
-type ReplayProtection =
-  | {
-      outputScripts: Uint8Array[];
-    }
-  | {
-      addresses: string[];
-    };
-
 export type ScriptId = { chain: number; index: number };
 
 export type InputScriptType =
@@ -79,13 +72,11 @@ export class BitGoPsbt {
    */
   parseTransactionWithWalletKeys(
     walletKeys: WalletKeysArg,
-    replayProtection: ReplayProtection,
+    replayProtection: ReplayProtectionArg,
   ): ParsedTransaction {
     const keys = RootWalletKeys.from(walletKeys);
-    return this.wasm.parse_transaction_with_wallet_keys(
-      keys.wasm,
-      replayProtection,
-    ) as ParsedTransaction;
+    const rp = ReplayProtection.from(replayProtection, this.wasm.network());
+    return this.wasm.parse_transaction_with_wallet_keys(keys.wasm, rp.wasm) as ParsedTransaction;
   }
 
   /**
@@ -171,8 +162,12 @@ export class BitGoPsbt {
    * @returns true if the input is a replay protection input and has a valid signature, false if no valid signature
    * @throws Error if the input is not a replay protection input, index is out of bounds, or scripts are invalid
    */
-  verifyReplayProtectionSignature(inputIndex: number, replayProtection: ReplayProtection): boolean {
-    return this.wasm.verify_replay_protection_signature(inputIndex, replayProtection);
+  verifyReplayProtectionSignature(
+    inputIndex: number,
+    replayProtection: ReplayProtectionArg,
+  ): boolean {
+    const rp = ReplayProtection.from(replayProtection, this.wasm.network());
+    return this.wasm.verify_replay_protection_signature(inputIndex, rp.wasm);
   }
 
   /**

packages/wasm-utxo/js/fixedScriptWallet/ReplayProtection.ts

@@ -0,0 +1,112 @@
+import { WasmReplayProtection } from "../wasm/wasm_utxo.js";
+import { type ECPairArg, ECPair } from "../ecpair.js";
+
+/**
+ * ReplayProtectionArg represents the various forms that replay protection can take
+ * before being converted to a WasmReplayProtection instance
+ */
+export type ReplayProtectionArg =
+  | ReplayProtection
+  | WasmReplayProtection
+  | {
+      publicKeys: ECPairArg[];
+    }
+  | {
+      /** @deprecated - use publicKeys instead */
+      outputScripts: Uint8Array[];
+    }
+  | {
+      /** @deprecated - use publicKeys instead */
+      addresses: string[];
+    };
+
+/**
+ * ReplayProtection wrapper class for PSBT replay protection inputs
+ */
+export class ReplayProtection {
+  private constructor(private _wasm: WasmReplayProtection) {}
+
+  /**
+   * Create a ReplayProtection instance from a WasmReplayProtection instance (internal use)
+   * @internal
+   */
+  static fromWasm(wasm: WasmReplayProtection): ReplayProtection {
+    return new ReplayProtection(wasm);
+  }
+
+  /**
+   * Convert ReplayProtectionArg to ReplayProtection instance
+   * @param arg - The replay protection in various formats
+   * @param network - Optional network string (required for addresses variant)
+   * @returns ReplayProtection instance
+   */
+  static from(arg: ReplayProtectionArg, network?: string): ReplayProtection {
+    // Short-circuit if already a ReplayProtection instance
+    if (arg instanceof ReplayProtection) {
+      return arg;
+    }
+    // If it's a WasmReplayProtection instance, wrap it
+    if (arg instanceof WasmReplayProtection) {
+      return new ReplayProtection(arg);
+    }
+
+    // Handle object variants
+    if ("publicKeys" in arg) {
+      // Convert ECPairArg to public key bytes
+      const publicKeyBytes = arg.publicKeys.map((key) => ECPair.from(key).publicKey);
+      const wasm = WasmReplayProtection.from_public_keys(publicKeyBytes);
+      return new ReplayProtection(wasm);
+    }
+
+    if ("outputScripts" in arg) {
+      const wasm = WasmReplayProtection.from_output_scripts(arg.outputScripts);
+      return new ReplayProtection(wasm);
+    }
+
+    if ("addresses" in arg) {
+      if (!network) {
+        throw new Error("Network is required when using addresses variant");
+      }
+      const wasm = WasmReplayProtection.from_addresses(arg.addresses, network);
+      return new ReplayProtection(wasm);
+    }
+
+    throw new Error("Invalid ReplayProtectionArg type");
+  }
+
+  /**
+   * Create from public keys (derives P2SH-P2PK output scripts)
+   * @param publicKeys - Array of ECPair instances or arguments
+   * @returns ReplayProtection instance
+   */
+  static fromPublicKeys(publicKeys: ECPairArg[]): ReplayProtection {
+    return ReplayProtection.from({ publicKeys });
+  }
+
+  /**
+   * Create from output scripts
+   * @param outputScripts - Array of output script buffers
+   * @returns ReplayProtection instance
+   */
+  static fromOutputScripts(outputScripts: Uint8Array[]): ReplayProtection {
+    return ReplayProtection.from({ outputScripts });
+  }
+
+  /**
+   * Create from addresses
+   * @param addresses - Array of address strings
+   * @param network - Network string (e.g., "bitcoin", "testnet", "btc", "tbtc")
+   * @returns ReplayProtection instance
+   */
+  static fromAddresses(addresses: string[], network: string): ReplayProtection {
+    return ReplayProtection.from({ addresses }, network);
+  }
+
+  /**
+   * Get the underlying WASM instance (internal use only)
+   * @internal
+   */
+  get wasm(): WasmReplayProtection {
+    return this._wasm;
+  }
+}

packages/wasm-utxo/js/fixedScriptWallet/index.ts

@@ -1,4 +1,5 @@
 export { RootWalletKeys, type WalletKeysArg, type IWalletKeys } from "./RootWalletKeys.js";
+export { ReplayProtection, type ReplayProtectionArg } from "./ReplayProtection.js";
 export { outputScript, address } from "./address.js";
 export {
   BitGoPsbt,

packages/wasm-utxo/js/index.ts

@@ -4,20 +4,25 @@ import * as wasm from "./wasm/wasm_utxo.js";
 // and forgets to include it in the bundle
 void wasm;
 
+// Most exports are namespaced to avoid polluting the top-level namespace
+// and to make imports more explicit (e.g., `import { address } from '@bitgo/wasm-utxo'`)
 export * as address from "./address.js";
 export * as ast from "./ast/index.js";
 export * as utxolibCompat from "./utxolibCompat.js";
 export * as fixedScriptWallet from "./fixedScriptWallet/index.js";
 export * as bip32 from "./bip32.js";
 export * as ecpair from "./ecpair.js";
 
+// Only the most commonly used classes and types are exported at the top level for convenience
 export { ECPair } from "./ecpair.js";
 export { BIP32 } from "./bip32.js";
 
 export type { CoinName } from "./coinName.js";
 export type { Triple } from "./triple.js";
 export type { AddressFormat } from "./address.js";
 
+// TODO: the exports below should be namespaced under `descriptor` in the future
+
 export type DescriptorPkType = "derivable" | "definite" | "string";
 
 export type ScriptContext = "tap" | "segwitv0" | "legacy";

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

@@ -478,7 +478,7 @@ impl BitGoPsbt {
     fn parse_inputs(
         &self,
         wallet_keys: &crate::fixed_script_wallet::RootWalletKeys,
-        replay_protection: &psbt_wallet_input::ReplayProtection,
+        replay_protection: &crate::fixed_script_wallet::ReplayProtection,
     ) -> Result<Vec<ParsedInput>, ParseTransactionError> {
         let psbt = self.psbt();
         let network = self.network();
@@ -669,7 +669,7 @@ impl BitGoPsbt {
         &self,
         secp: &secp256k1::Secp256k1<C>,
         input_index: usize,
-        replay_protection: &psbt_wallet_input::ReplayProtection,
+        replay_protection: &crate::fixed_script_wallet::ReplayProtection,
     ) -> Result<bool, String> {
         use miniscript::bitcoin::{hashes::Hash, sighash::SighashCache};
 
@@ -912,7 +912,7 @@ impl BitGoPsbt {
     pub fn parse_transaction_with_wallet_keys(
         &self,
         wallet_keys: &crate::fixed_script_wallet::RootWalletKeys,
-        replay_protection: &psbt_wallet_input::ReplayProtection,
+        replay_protection: &crate::fixed_script_wallet::ReplayProtection,
     ) -> Result<ParsedTransaction, ParseTransactionError> {
         let psbt = self.psbt();
 
@@ -1324,7 +1324,7 @@ mod tests {
 
         // Create replay protection with this output script
         let replay_protection =
-            psbt_wallet_input::ReplayProtection::new(vec![output_script.clone()]);
+            crate::fixed_script_wallet::ReplayProtection::new(vec![output_script.clone()]);
 
         // Verify the signature exists and is valid
         let has_valid_signature = bitgo_psbt.verify_replay_protection_signature(
@@ -1603,7 +1603,7 @@ mod tests {
         let wallet_keys = wallet_xprv.to_root_wallet_keys();
 
         // Create replay protection with the replay protection script from fixture
-        let replay_protection = psbt_wallet_input::ReplayProtection::new(vec![
+        let replay_protection = crate::fixed_script_wallet::ReplayProtection::new(vec![
             miniscript::bitcoin::ScriptBuf::from_hex("a91420b37094d82a513451ff0ccd9db23aba05bc5ef387")
                 .expect("Failed to parse replay protection output script"),
         ]);

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

@@ -4,26 +4,9 @@ use miniscript::bitcoin::secp256k1::{self, PublicKey};
 use miniscript::bitcoin::{OutPoint, ScriptBuf, TapLeafHash, XOnlyPublicKey};
 
 use crate::bitcoin::bip32::KeySource;
-use crate::fixed_script_wallet::{Chain, RootWalletKeys, WalletScripts};
+use crate::fixed_script_wallet::{Chain, ReplayProtection, RootWalletKeys, WalletScripts};
 use crate::Network;
 
-#[derive(Debug, Clone)]
-pub struct ReplayProtection {
-    pub permitted_output_scripts: Vec<ScriptBuf>,
-}
-
-impl ReplayProtection {
-    pub fn new(permitted_output_scripts: Vec<ScriptBuf>) -> Self {
-        Self {
-            permitted_output_scripts,
-        }
-    }
-
-    pub fn is_replay_protection_input(&self, output_script: &ScriptBuf) -> bool {
-        self.permitted_output_scripts.contains(output_script)
-    }
-}
-
 pub type Bip32DerivationMap = std::collections::BTreeMap<PublicKey, KeySource>;
 
 /// Check if a fingerprint matches any xpub in the wallet

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

@@ -1,11 +1,13 @@
 /// This module contains code for the BitGo Fixed Script Wallets.
 /// These are not based on descriptors.
 pub mod bitgo_psbt;
+pub mod replay_protection;
 mod wallet_keys;
 pub mod wallet_scripts;
 
 #[cfg(test)]
 pub mod test_utils;
 
+pub use replay_protection::*;
 pub use wallet_keys::*;
 pub use wallet_scripts::*;

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

@@ -0,0 +1,36 @@
+use miniscript::bitcoin::{CompressedPublicKey, ScriptBuf};
+
+use crate::fixed_script_wallet::wallet_scripts::ScriptP2shP2pk;
+
+#[derive(Debug, Clone)]
+pub struct ReplayProtection {
+    pub permitted_output_scripts: Vec<ScriptBuf>,
+}
+
+impl ReplayProtection {
+    pub fn new(permitted_output_scripts: Vec<ScriptBuf>) -> Self {
+        Self {
+            permitted_output_scripts,
+        }
+    }
+
+    /// Create from public keys by deriving P2SH-P2PK output scripts
+    /// This is useful for replay protection inputs where we know the public keys
+    /// but want to automatically create the corresponding output scripts
+    pub fn from_public_keys(public_keys: Vec<CompressedPublicKey>) -> Self {
+        let output_scripts = public_keys
+            .into_iter()
+            .map(|key| {
+                let script = ScriptP2shP2pk::new(key);
+                script.output_script()
+            })
+            .collect();
+        Self {
+            permitted_output_scripts: output_scripts,
+        }
+    }
+
+    pub fn is_replay_protection_input(&self, output_script: &ScriptBuf) -> bool {
+        self.permitted_output_scripts.contains(output_script)
+    }
+}