diff --git a/crates/wallet/src/wallet/mod.rs b/crates/wallet/src/wallet/mod.rs index c6d02d77cd..53e0e32ecf 100644 --- a/crates/wallet/src/wallet/mod.rs +++ b/crates/wallet/src/wallet/mod.rs @@ -559,7 +559,7 @@ impl Wallet { /// /// For non-wildcard descriptors this returns the same address at every provided index. /// - /// # Panics (TODO: document panics for address methods) + /// # Panics /// /// This panics when the caller requests for an address of derivation index greater than the /// [BIP32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki) max index. @@ -589,7 +589,9 @@ impl Wallet { /// This will increment the keychain's derivation index. If the keychain's descriptor doesn't /// contain a wildcard or every address is already revealed up to the maximum derivation /// index defined in [BIP32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki), - /// then the last revealed address will be returned. + /// then the last revealed address will be returned. Note that if this wallet only has one + /// keychain, then by default this method and similar ones will only derive addresses using + /// the external keychain. /// /// **WARNING**: To avoid address reuse you must persist the changes resulting from one or more /// calls to this method before closing the wallet. For example: @@ -709,6 +711,8 @@ impl Wallet { /// Note if the returned iterator is empty you can reveal more addresses /// by using [`reveal_next_address`](Self::reveal_next_address) or /// [`reveal_addresses_to`](Self::reveal_addresses_to). + /// + /// Returns an empty iterator if the provided keychain doesn't exist. pub fn list_unused_addresses( &self, keychain: KeychainKind, @@ -1073,9 +1077,8 @@ impl Wallet { /// Set the keymap for a given keychain. /// - /// Note this is a no-op if the given keychain is not assigned a descriptor - /// because we won't know the context (segwit, taproot, etc) in which to create - /// signatures. + /// Note this is a no-op if the given keychain has no descriptor because we won't + /// know the context (segwit, taproot, etc) in which to create signatures. pub fn set_keymap(&mut self, keychain: KeychainKind, keymap: KeyMap) { let wallet_signers = match keychain { KeychainKind::External => Arc::make_mut(&mut self.signers), @@ -1763,10 +1766,13 @@ impl Wallet { } /// Returns the descriptor used to create addresses for a particular `keychain`. + /// /// It's the "public" version of the wallet's descriptor, meaning a new descriptor that has /// the same structure but with the all secret keys replaced by their corresponding public key. - /// /// This can be used to build a watch-only version of a wallet. + /// + /// If this wallet has no internal keychain, then it returns the descriptor of the + /// external keychain. pub fn public_descriptor(&self, keychain: KeychainKind) -> &ExtendedDescriptor { self.indexed_graph .index diff --git a/crates/wallet/src/wallet/tx_builder.rs b/crates/wallet/src/wallet/tx_builder.rs index 962edd56f6..9d0adc729d 100644 --- a/crates/wallet/src/wallet/tx_builder.rs +++ b/crates/wallet/src/wallet/tx_builder.rs @@ -481,7 +481,8 @@ impl<'a, Cs> TxBuilder<'a, Cs> { /// Do not spend change outputs /// /// This effectively adds all the change outputs to the "unspendable" list. See - /// [`TxBuilder::unspendable`]. + /// [`TxBuilder::unspendable`]. This method assumes the presence of an internal + /// keychain, otherwise it has no effect. pub fn do_not_spend_change(&mut self) -> &mut Self { self.params.change_policy = ChangeSpendPolicy::ChangeForbidden; self @@ -490,14 +491,16 @@ impl<'a, Cs> TxBuilder<'a, Cs> { /// Only spend change outputs /// /// This effectively adds all the non-change outputs to the "unspendable" list. See - /// [`TxBuilder::unspendable`]. + /// [`TxBuilder::unspendable`]. This method assumes the presence of an internal + /// keychain, otherwise it has no effect. pub fn only_spend_change(&mut self) -> &mut Self { self.params.change_policy = ChangeSpendPolicy::OnlyChange; self } /// Set a specific [`ChangeSpendPolicy`]. See [`TxBuilder::do_not_spend_change`] and - /// [`TxBuilder::only_spend_change`] for some shortcuts. + /// [`TxBuilder::only_spend_change`] for some shortcuts. This method assumes the presence + /// of an internal keychain, otherwise it has no effect. pub fn change_policy(&mut self, change_policy: ChangeSpendPolicy) -> &mut Self { self.params.change_policy = change_policy; self