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.
This commit is contained in:
LLFourn
2021-07-12 16:26:29 +10:00
parent 618e0d3700
commit 7597645ed6
3 changed files with 5 additions and 6 deletions

View File

@@ -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
///