Merge #306: Add docs + test on required use of xpub for multipath constructor

e647ed2 docs: add wording on required use of xpub for multipath constructor (thunderbiscuit)

Pull request description:

  This PR makes explicit a limitation of the `Wallet::create_from_two_path_descriptor` method, in that you must use public descriptors to build the wallet using this constructor, meaning you can only build watch-only wallets.

  I also added a test to showcase this and the error returned.

  See [my comment here](#275 (comment)) for more:

  From what I can tell the issue is that miniscript cannot parse an xprv (I saw a comment from Sanket about this somewhere but now I can't find it anymore) if the multipath contains hardened derivation paths, and therefore miniscipt cannot ensure the xprv will be parsable into public keys in all cases? Something like that. But our arguments for bdk wallet constructors require the `IntoWalletDescriptor` trait:

  ```rust
  pub trait IntoWalletDescriptor {
      /// Convert to wallet descriptor
      fn into_wallet_descriptor(
          self,
          secp: &SecpCtx,
          network: Network,
      ) -> Result<(ExtendedDescriptor, KeyMap), DescriptorError>;
  }

  pub type ExtendedDescriptor = Descriptor<DescriptorPublicKey>;
  ```

  In other words, upon creation, the wallet will always try to parse the descriptor string into its public form, and here since it cannot be done by miniscript we fail to build.

  ### Changelog notice

  No changelog notice.

  ### Checklists

  #### All Submissions:

  * [x] I've signed all my commits
  * [x] I followed the [contribution guidelines](https://github.com/bitcoindevkit/bdk/blob/master/CONTRIBUTING.md)
  * [x] I ran `just p` before pushing

ACKs for top commit:
  ValuedMammal:
    ACK e647ed2
  oleonardolima:
    utACK e647ed2

Tree-SHA512: 15085dedc07c69f9e04876c174c4a8d54d186f0b04c6d1bf8ea76829cccdbf3f3644b7169392be5d03f0b983e4db6fd01afda6fb97ae348438f585cdde3fc08b

Author: ValuedMammal

wallet/src/wallet/mod.rs

@@ -399,15 +399,17 @@ impl Wallet {
     /// Build a new [`Wallet`] from a two-path descriptor.
     ///
     /// This function parses a multipath descriptor with exactly 2 paths and creates a wallet
-    /// using the existing receive and change wallet creation logic.
+    /// using the existing receive and change wallet creation logic. Note that you can only use this
+    /// method with public extended keys (`xpub` prefix) to create watch-only wallets.
     ///
     /// Multipath descriptors follow [BIP 389] and allow defining both receive and change
     /// derivation paths in a single descriptor using the `<0;1>` syntax.
     ///
     /// If you have previously created a wallet, use [`load`](Self::load) instead.
     ///
     /// # Errors
-    /// Returns an error if the descriptor is invalid or not a 2-path multipath descriptor.
+    /// Returns an error if the descriptor is invalid, not a 2-path multipath descriptor, or if
+    /// the descriptor provided contains an extended private key (`xprv` prefix).
     ///
     /// # Synopsis
     ///
@@ -1224,7 +1226,7 @@ impl Wallet {
         txs
     }
 
-    /// Return the balance, separated into available, trusted-pending, untrusted-pending and
+    /// Return the balance, separated into available, trusted-pending, untrusted-pending, and
     /// immature values.
     pub fn balance(&self) -> Balance {
         self.indexed_graph.graph().balance(
@@ -2794,6 +2796,7 @@ macro_rules! doctest_wallet {
 #[cfg(test)]
 mod test {
     use super::*;
+    use crate::miniscript::Error::Unexpected;
     use crate::test_utils::get_test_tr_single_sig_xprv_and_change_desc;
     use crate::test_utils::insert_tx;
 
@@ -2894,6 +2897,17 @@ mod test {
         let wallet = params.network(Network::Testnet).create_wallet_no_persist();
         assert!(matches!(wallet, Err(DescriptorError::MultiPath)));
 
+        // Test with a private descriptor
+        // You get a Miniscript(Unexpected("Can't make an extended private key with multiple paths
+        // into a public key.")) error.
+        let private_multipath_descriptor = "wpkh(tprv8ZgxMBicQKsPdWAHbugK2tjtVtRjKGixYVZUdL7xLHMgXZS6BFbFi1UDb1CHT25Z5PU1F9j7wGxwUiRhqz9E3nZRztikGUV6HoRDYcqPhM4/84'/1'/0'/<0;1>/*)";
+        let params = Wallet::create_from_two_path_descriptor(private_multipath_descriptor);
+        let wallet = params.network(Network::Testnet).create_wallet_no_persist();
+        assert!(matches!(
+            wallet,
+            Err(DescriptorError::Miniscript(Unexpected(..)))
+        ));
+
         // Test with invalid 3-path multipath descriptor
         let three_path_descriptor = "wpkh([9a6a2580/84'/1'/0']tpubDDnGNapGEY6AZAdQbfRJgMg9fvz8pUBrLwvyvUqEgcUfgzM6zc2eVK4vY9x9L5FJWdX8WumXuLEDV5zDZnTfbn87vLe9XceCFwTu9so9Kks/<0;1;2>/*)";
         let params = Wallet::create_from_two_path_descriptor(three_path_descriptor);