feat(wasm-utxo): refactor script derivation to use full paths

Refactor derivation to use full BIP32 paths instead of separate chain
and index parameters. Centralize chain/index path construction in
`chain_index_path()` helper.

Replace `from_chain_and_index()` with generic `derive_path()` that
accepts any derivation path. Cache results using the last two Normal
path components.

Move `Chain`, `Scope`, and `ScriptId` types to new `script_id` module.
Add `WalletOutputScript` type to encapsulate script type + derivation
path matching. Implement `from_psbt()` method to match PSBT metadata
against wallet keys.

Add `derivationPath` field to `ParsedInput` and `ParsedOutput` types,
containing full BIP32 path (e.g. "0/1"). Make `scriptId` nullable to
indicate when derivation path is nonstandard or external.

Update JSDoc comments to clarify field semantics.

Issue: BTC-2650

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

Author: OttoAllmendinger

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

@@ -36,17 +36,23 @@ export type ParsedInput = {
   address: string;
   script: Uint8Array;
   value: bigint;
+  /** Set only when the derivation path is chain-standard (chain code encodes script type per BitGo convention). */
   scriptId: ScriptId | null;
   scriptType: InputScriptType;
   sequence: number;
+  /** Full BIP32 derivation path from the wallet xpub (e.g. "0/1"). Null for replay-protection inputs. */
+  derivationPath: string | null;
 };
 
 export type ParsedOutput = {
   address: string | null;
   script: Uint8Array;
   value: bigint;
+  /** Set only when the derivation path is chain-standard (chain code encodes script type per BitGo convention). */
   scriptId: ScriptId | null;
   paygo: boolean;
+  /** Full BIP32 derivation path from the wallet xpub (e.g. "0/1"). Null for external outputs. */
+  derivationPath: string | null;
 };
 
 export type ParsedTransaction = {

packages/wasm-utxo/src/bip322/bitgo_psbt.rs

@@ -8,6 +8,7 @@ use crate::fixed_script_wallet::bitgo_psbt::{
     create_bip32_derivation, create_tap_bip32_derivation, find_kv, BitGoKeyValue, BitGoPsbt,
     ProprietaryKeySubtype,
 };
+use crate::fixed_script_wallet::wallet_scripts::chain_index_path;
 use crate::fixed_script_wallet::wallet_scripts::{
     build_multisig_script_2_of_3, build_p2tr_ns_script, ScriptP2mr, ScriptP2tr,
 };
@@ -88,8 +89,8 @@ pub fn add_bip322_input(
     let chain_enum = Chain::try_from(chain).map_err(|e| format!("Invalid chain: {}", e))?;
     let scripts = WalletScripts::from_wallet_keys(
         wallet_keys,
-        chain_enum,
-        index,
+        chain_enum.script_type,
+        &chain_index_path(chain, index),
         &network.output_script_support(),
     )
     .map_err(|e| e.to_string())?;
@@ -190,7 +191,7 @@ pub fn add_bip322_input(
 
             // Derive pubkeys
             let derived_keys = wallet_keys
-                .derive_for_chain_and_index(chain, index)
+                .derive_path(&chain_index_path(chain, index))
                 .map_err(|e| format!("Failed to derive keys: {}", e))?;
             let pub_triple = to_pub_triple(&derived_keys);
 
@@ -335,8 +336,8 @@ pub fn verify_bip322_tx_input(
     let chain_enum = Chain::try_from(chain).map_err(|e| format!("Invalid chain: {}", e))?;
     let scripts = WalletScripts::from_wallet_keys(
         wallet_keys,
-        chain_enum,
-        index,
+        chain_enum.script_type,
+        &chain_index_path(chain, index),
         &network.output_script_support(),
     )
     .map_err(|e| e.to_string())?;
@@ -427,8 +428,8 @@ pub fn verify_bip322_psbt_input(
     let chain_enum = Chain::try_from(chain).map_err(|e| format!("Invalid chain: {}", e))?;
     let scripts = WalletScripts::from_wallet_keys(
         wallet_keys,
-        chain_enum,
-        index,
+        chain_enum.script_type,
+        &chain_index_path(chain, index),
         &network.output_script_support(),
     )
     .map_err(|e| e.to_string())?;

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

@@ -107,15 +107,16 @@ pub enum BitGoPsbt {
 }
 
 // Re-export types from submodules for convenience
+pub use crate::fixed_script_wallet::{ScriptId, ScriptIdWithValue};
 pub use psbt_wallet_input::{
-    InputScriptType, ParsedInput, ReplayProtectionOptions, ScriptId, WalletInputOptions,
+    InputScriptType, ParsedInput, ReplayProtectionOptions, WalletInputOptions,
 };
 pub use psbt_wallet_output::ParsedOutput;
 
 /// Describes a single input for `from_half_signed_legacy_transaction`.
 pub enum HydrationUnspentInput {
     /// A regular wallet input with derivation chain, index, and value.
-    Wallet(psbt_wallet_input::ScriptIdWithValue),
+    Wallet(ScriptIdWithValue),
     /// A P2SH-P2PK replay protection input. The caller provides the expected pubkey so it can be
     /// validated against the redeemScript embedded in the legacy transaction.
     ReplayProtection {
@@ -187,7 +188,7 @@ impl std::error::Error for ParseTransactionError {}
 /// Get the default sighash type for a network and chain type
 fn get_default_sighash_type(
     network: Network,
-    chain: crate::fixed_script_wallet::wallet_scripts::Chain,
+    chain: crate::fixed_script_wallet::Chain,
 ) -> miniscript::bitcoin::psbt::PsbtSighashType {
     use crate::fixed_script_wallet::wallet_scripts::OutputScriptType;
     use miniscript::bitcoin::sighash::{EcdsaSighashType, TapSighashType};
@@ -506,7 +507,7 @@ impl BitGoPsbt {
         for (i, (tx_in, unspent)) in tx.input.iter().zip(unspents.iter()).enumerate() {
             match unspent {
                 HydrationUnspentInput::Wallet(sv) => {
-                    let script_id = psbt_wallet_input::ScriptId {
+                    let script_id = ScriptId {
                         chain: sv.chain,
                         index: sv.index,
                     };
@@ -897,11 +898,14 @@ impl BitGoPsbt {
         vout: u32,
         value: u64,
         wallet_keys: &crate::fixed_script_wallet::RootWalletKeys,
-        script_id: psbt_wallet_input::ScriptId,
+        script_id: ScriptId,
         options: WalletInputOptions,
     ) -> Result<(), String> {
         use crate::fixed_script_wallet::to_pub_triple;
-        use crate::fixed_script_wallet::wallet_scripts::{Chain, OutputScriptType, WalletScripts};
+        use crate::fixed_script_wallet::wallet_scripts::{
+            chain_index_path, OutputScriptType, WalletScripts,
+        };
+        use crate::fixed_script_wallet::Chain;
         use miniscript::bitcoin::psbt::Input;
         use miniscript::bitcoin::taproot::{LeafVersion, TapLeafHash};
         use miniscript::bitcoin::{transaction::Sequence, Amount, OutPoint, TxIn, TxOut};
@@ -914,12 +918,12 @@ impl BitGoPsbt {
         let chain_enum = Chain::try_from(chain)?;
 
         let derived_keys = wallet_keys
-            .derive_for_chain_and_index(chain, derivation_index)
+            .derive_path(&chain_index_path(chain, derivation_index))
             .map_err(|e| format!("Failed to derive keys: {}", e))?;
         let pub_triple = to_pub_triple(&derived_keys);
 
         let script_support = network.output_script_support();
-        let scripts = WalletScripts::new(&pub_triple, chain_enum, &script_support)
+        let scripts = WalletScripts::new(&pub_triple, chain_enum.script_type, &script_support)
             .map_err(|e| format!("Failed to create wallet scripts: {}", e))?;
 
         let output_script = scripts.output_script();
@@ -1049,7 +1053,7 @@ impl BitGoPsbt {
         vout: u32,
         value: u64,
         wallet_keys: &crate::fixed_script_wallet::RootWalletKeys,
-        script_id: psbt_wallet_input::ScriptId,
+        script_id: ScriptId,
         options: WalletInputOptions,
     ) -> Result<usize, String> {
         let network = self.network();
@@ -1073,7 +1077,7 @@ impl BitGoPsbt {
         vout: u32,
         value: u64,
         wallet_keys: &crate::fixed_script_wallet::RootWalletKeys,
-        script_id: psbt_wallet_input::ScriptId,
+        script_id: ScriptId,
         options: WalletInputOptions,
     ) -> Result<usize, String> {
         let index = self.psbt().inputs.len();
@@ -1104,8 +1108,10 @@ impl BitGoPsbt {
     ) -> Result<usize, String> {
         use crate::fixed_script_wallet::to_pub_triple;
         use crate::fixed_script_wallet::wallet_scripts::{
-            build_tap_tree_for_output, create_tap_bip32_derivation_for_output, Chain, WalletScripts,
+            build_tap_tree_for_output, chain_index_path, create_tap_bip32_derivation_for_output,
+            WalletScripts,
         };
+        use crate::fixed_script_wallet::Chain;
         use miniscript::bitcoin::psbt::Output;
         use miniscript::bitcoin::{Amount, TxOut};
         use std::convert::TryFrom;
@@ -1116,12 +1122,12 @@ impl BitGoPsbt {
         let chain_enum = Chain::try_from(chain)?;
 
         let derived_keys = wallet_keys
-            .derive_for_chain_and_index(chain, derivation_index)
+            .derive_path(&chain_index_path(chain, derivation_index))
             .map_err(|e| format!("Failed to derive keys: {}", e))?;
         let pub_triple = to_pub_triple(&derived_keys);
 
         let script_support = network.output_script_support();
-        let scripts = WalletScripts::new(&pub_triple, chain_enum, &script_support)
+        let scripts = WalletScripts::new(&pub_triple, chain_enum.script_type, &script_support)
             .map_err(|e| format!("Failed to create wallet scripts: {}", e))?;
 
         let output_script = scripts.output_script();
@@ -2385,15 +2391,6 @@ impl BitGoPsbt {
         Ok(())
     }
 
-    /// Parse inputs with wallet keys and replay protection
-    ///
-    /// # Arguments
-    /// - `wallet_keys`: The wallet's root keys for deriving scripts
-    /// - `replay_protection`: Scripts that are allowed as inputs without wallet validation
-    ///
-    /// # Returns
-    /// - `Ok(Vec<ParsedInput>)` with parsed inputs
-    /// - `Err(ParseTransactionError)` if input parsing fails
     fn parse_inputs(
         &self,
         wallet_keys: &crate::fixed_script_wallet::RootWalletKeys,
@@ -3207,6 +3204,7 @@ pub fn to_wallet_keys(
     use crate::fixed_script_wallet::RootWalletKeys;
 
     let inner_psbt = psbt.psbt();
+    let network = psbt.network();
 
     // Collect non-replay-protection inputs (those with derivation info)
     let wallet_inputs: Vec<_> = inner_psbt
@@ -3233,9 +3231,15 @@ pub fn to_wallet_keys(
                 tx_input.previous_output,
             );
             match output_script {
-                Ok((script, _value)) => {
-                    psbt_wallet_input::assert_wallet_input(&wallet_keys, psbt_input, script).is_ok()
-                }
+                Ok((script, _value)) => crate::fixed_script_wallet::WalletOutputScript::from_psbt(
+                    &wallet_keys,
+                    &psbt_input.bip32_derivation,
+                    &psbt_input.tap_key_origins,
+                    psbt_input.witness_script.is_some(),
+                    script,
+                    network,
+                )
+                .is_ok_and(|o| o.is_some()),
                 Err(_) => false,
             }
         });
@@ -3251,6 +3255,7 @@ pub fn to_wallet_keys(
 #[cfg(test)]
 mod tests {
     use super::*;
+    use crate::fixed_script_wallet::wallet_scripts::chain_index_path;
     use crate::fixed_script_wallet::Chain;
     use crate::fixed_script_wallet::RootWalletKeys;
     use crate::fixed_script_wallet::WalletScripts;
@@ -3607,8 +3612,8 @@ mod tests {
             parse_fixture_paths(input_fixture).expect("Failed to parse fixture paths");
         let scripts = WalletScripts::from_wallet_keys(
             &wallet_keys.to_root_wallet_keys(),
-            chain,
-            index,
+            chain.script_type,
+            &chain_index_path(chain.value(), index),
             &network.output_script_support(),
         )
         .expect("Failed to create wallet scripts");
@@ -4220,7 +4225,7 @@ mod tests {
         format: fixtures::TxFormat,
         script_type: fixtures::ScriptType,
     ) -> Result<(), String> {
-        use crate::fixed_script_wallet::bitgo_psbt::psbt_wallet_input::ScriptIdWithValue;
+        use crate::fixed_script_wallet::ScriptIdWithValue;
 
         let is_p2ms = matches!(
             script_type,