drainTo
Sets the address to drain excess coins to.
Usually, when there are excess coins they are sent to a change address generated by the wallet. This option replaces the usual change address with an arbitrary script_pubkey of your choosing. Just as with a change output, if the drain output is not needed (the excess coins are too small) it will not be included in the resulting transaction. The only difference is that it is valid to use drain_to
without setting any ordinary recipients with add_recipient
(but it is perfectly fine to add recipients as well).
If you choose not to set any recipients, you should provide the utxos that the transaction should spend via add_utxos
. drain_to
is very useful for draining all the coins in a wallet with drain_wallet
to a single address.