Replace set_single_recipient with drain_to

What set_single_recipient does turns out to be useful with multiple
recipients.
Effectively, set_single_recipient was simply creating a change
output that was arbitrarily required to be the only output.
But what if you want to send excess funds to one address but still have
additional recipients who receive a fixed value?
Generalizing this to `drain_to` simplifies the logic and removes several
error cases while also allowing new use cases.

"maintain_single_recipient" is also replaced with "allow_shrinking"
which has more general semantics.

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8ae2ff95c6442d6ba978102524a23da469aa1d00..06bcf98136ff53e8b308f1ec24cc583b94ffa562 100644 (file)
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,7 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Added Bitcoin core RPC added as blockchain backend
 - Added a `verify` feature that can be enable to verify the unconfirmed txs we download against the consensus rules
-- Removed and replaced `set_single_recipient` with more general `allow_shrinking`.
+- Removed and replaced `set_single_recipient` with more general `drain_to` and replaced `maintain_single_recipient` with `allow_shrinking`.
 
 ## [v0.8.0] - [v0.7.0]
 

diff --git a/src/wallet/mod.rs b/src/wallet/mod.rs
index 29f430875e2cdbfd4d3ad944588db6e22d77ed7d..ba0ab8e034248506055bde8678d94d77472af26c 100644 (file)
--- a/src/wallet/mod.rs
+++ b/src/wallet/mod.rs
@@ -3128,7 +3128,7 @@ pub(crate) mod test {
         // them, and make sure that `bump_fee` doesn't try to add more. This fails because we've
         // told the wallet it's not allowed to add more inputs AND it can't reduce the value of the
         // existing output. In other words, bump_fee + manually_selected_only is always an error
-        // unless you've also set "allow_shrinking OR there is a change output".
+        // unless you've also set "allow_shrinking" OR there is a change output.
         let incoming_txid = crate::populate_test_db!(
             wallet.database.borrow_mut(),
             testutils! (@tx ( (@external descriptors, 0) => 25_000 ) (@confirmations 1)),
@@ -3307,7 +3307,7 @@ pub(crate) mod test {
             Some(100),
         );
 
-        // initially make a tx without change by using `set_drain_recipient`
+        // initially make a tx without change by using `drain_to`
         let addr = Address::from_str("2N1Ffz3WaNzbeLFBb51xyFMHYSEUXcbiSoX").unwrap();
         let mut builder = wallet.build_tx();
         builder

diff --git a/src/wallet/tx_builder.rs b/src/wallet/tx_builder.rs
index 20ea19553ee270d59f4252e30d6b0ff2f5999109..3ee2cd71ea21351140b938bb83f61f77df5e902c 100644 (file)
--- a/src/wallet/tx_builder.rs
+++ b/src/wallet/tx_builder.rs
@@ -569,9 +569,8 @@ impl<'a, B, D: BatchDatabase, Cs: CoinSelectionAlgorithm<D>> TxBuilder<'a, B, D,
     /// difference is that it is valid to use `drain_to` without setting any ordinary recipients
     /// with [`add_recipient`] (but it is perfectly find to add recipients as well).
     ///
-    /// When bumping the fees of a transaction made with this option, the user should remeber to
-    /// add [`allow_shrinking`] to correctly update the
-    /// single output instead of adding one more for the change.
+    /// When bumping the fees of a transaction made with this option, you probably want to
+    /// use [`allow_shrinking`] to allow this output to be reduced to pay for the extra fees.
     ///
     /// # Example
     ///