Struct TxBuilder

Source

pub struct TxBuilder { /* private fields */ }

Expand description

A TxBuilder is created by calling build_tx on a wallet. After assigning it, you set options on it until finally calling finish to consume the builder and generate the transaction.

Implementations§

Source §

impl TxBuilder

Source

pub fn new() -> Self

Source

pub fn add_global_xpubs(&self) -> Arc<Self>

Fill-in the PSBT_GLOBAL_XPUB field with the extended keys contained in both the external and internal descriptors.

This is useful for offline signers that take part to a multisig. Some hardware wallets like BitBox and ColdCard are known to require this.

Source

pub fn exclude_unconfirmed(&self) -> Arc<Self>

Exclude outpoints whose enclosing transaction is unconfirmed. This is a shorthand for exclude_below_confirmations(1).

Source

pub fn exclude_below_confirmations(&self, min_confirms: u32) -> Arc<Self>

Excludes any outpoints whose enclosing transaction has fewer than min_confirms confirmations.

min_confirms is the minimum number of confirmations a transaction must have in order for its outpoints to remain spendable.

Passing 0 will include all transactions (no filtering).
Passing 1 will exclude all unconfirmed transactions (equivalent to exclude_unconfirmed).
Passing 6 will only allow outpoints from transactions with at least 6 confirmations.

If you chain this with other filtering methods, the final set of unspendable outpoints will be the union of all filters.

Source

pub fn add_recipient(&self, script: &Script, amount: Arc<Amount>) -> Arc<Self>

Add a recipient to the internal list of recipients.

Source

pub fn set_recipients(&self, recipients: Vec<ScriptAmount>) -> Arc<Self>

Replace the recipients already added with a new list of recipients.

Source

pub fn add_unspendable(&self, unspendable: OutPoint) -> Arc<Self>

Add a utxo to the internal list of unspendable utxos.

It’s important to note that the “must-be-spent” utxos added with TxBuilder::add_utxo have priority over this.

Source

pub fn unspendable(&self, unspendable: Vec<OutPoint>) -> Arc<Self>

Replace the internal list of unspendable utxos with a new list.

It’s important to note that the “must-be-spent” utxos added with TxBuilder::add_utxo have priority over these.

Source

pub fn add_utxo(&self, outpoint: OutPoint) -> Arc<Self>

Add a utxo to the internal list of utxos that must be spent.

These have priority over the “unspendable” utxos, meaning that if a utxo is present both in the “utxos” and the “unspendable” list, it will be spent.

Source

pub fn add_utxos(&self, outpoints: Vec<OutPoint>) -> Arc<Self>

Add the list of outpoints to the internal list of UTXOs that must be spent.

Source

pub fn policy_path( &self, policy_path: HashMap<String, Vec<u64>>, keychain: KeychainKind, ) -> Arc<Self>

The TxBuilder::policy_path is a complex API. See the Rust docs for complete information: https://docs.rs/bdk_wallet/latest/bdk_wallet/struct.TxBuilder.html#method.policy_path

Source

pub fn change_policy(&self, change_policy: ChangeSpendPolicy) -> Arc<Self>

Set a specific ChangeSpendPolicy. See TxBuilder::do_not_spend_change and TxBuilder::only_spend_change for some shortcuts. This method assumes the presence of an internal keychain, otherwise it has no effect.

Source

pub fn do_not_spend_change(&self) -> Arc<Self>

Do not spend change outputs.

This effectively adds all the change outputs to the “unspendable” list. See TxBuilder::unspendable. This method assumes the presence of an internal keychain, otherwise it has no effect.

Source

pub fn only_spend_change(&self) -> Arc<Self>

Only spend change outputs.

This effectively adds all the non-change outputs to the “unspendable” list. See TxBuilder::unspendable. This method assumes the presence of an internal keychain, otherwise it has no effect.

Source

pub fn manually_selected_only(&self) -> Arc<Self>

Only spend utxos added by TxBuilder::add_utxo.

The wallet will not add additional utxos to the transaction even if they are needed to make the transaction valid.

Source

pub fn fee_rate(&self, fee_rate: &FeeRate) -> Arc<Self>

Set a custom fee rate.

This method sets the mining fee paid by the transaction as a rate on its size. This means that the total fee paid is equal to fee_rate times the size of the transaction. Default is 1 sat/vB in accordance with Bitcoin Core’s default relay policy.

Note that this is really a minimum feerate – it’s possible to overshoot it slightly since adding a change output to drain the remaining excess might not be viable.

Source

pub fn fee_absolute(&self, fee_amount: Arc<Amount>) -> Arc<Self>

Set an absolute fee The fee_absolute method refers to the absolute transaction fee in Amount. If anyone sets both the fee_absolute method and the fee_rate method, the FeePolicy enum will be set by whichever method was called last, as the FeeRate and FeeAmount are mutually exclusive.

Note that this is really a minimum absolute fee – it’s possible to overshoot it slightly since adding a change output to drain the remaining excess might not be viable.

Source

pub fn drain_wallet(&self) -> Arc<Self>

Spend all the available inputs. This respects filters like TxBuilder::unspendable and the change policy.

Source

pub fn drain_to(&self, script: &Script) -> Arc<Self>

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.

Source

pub fn set_exact_sequence(&self, nsequence: u32) -> Arc<Self>

Set an exact nSequence value.

This can cause conflicts if the wallet’s descriptors contain an “older” (OP_CSV) operator and the given nsequence is lower than the CSV value.

Source

pub fn add_data(&self, data: Vec<u8>) -> Arc<Self>

Add data as an output using OP_RETURN.

Source

pub fn current_height(&self, height: u32) -> Arc<Self>

Set the current blockchain height.

This will be used to:

Set the nLockTime for preventing fee sniping. Note: This will be ignored if you manually specify a nlocktime using TxBuilder::nlocktime.
Decide whether coinbase outputs are mature or not. If the coinbase outputs are not mature at current_height, we ignore them in the coin selection. If you want to create a transaction that spends immature coinbase inputs, manually add them using TxBuilder::add_utxos. In both cases, if you don’t provide a current height, we use the last sync height.

Source

pub fn nlocktime(&self, locktime: LockTime) -> Arc<Self>

Use a specific nLockTime while creating the transaction.

This can cause conflicts if the wallet’s descriptors contain an “after” (OP_CLTV) operator.

Source

pub fn allow_dust(&self, allow_dust: bool) -> Arc<Self>

Set whether or not the dust limit is checked.

Note: by avoiding a dust limit check you may end up with a transaction that is non-standard.

Source

pub fn version(&self, version: i32) -> Arc<Self>

Build a transaction with a specific version.

The version should always be greater than 0 and greater than 1 if the wallet’s descriptors contain an “older” (OP_CSV) operator.

Source

pub fn finish(&self, wallet: &Arc<Wallet>) -> Result<Arc<Psbt>, CreateTxError>

Finish building the transaction.

Uses the thread-local random number generator (rng).

Returns a new Psbt per BIP174.

WARNING: To avoid change address reuse you must persist the changes resulting from one or more calls to this method before closing the wallet. See Wallet::reveal_next_address.