TxBuilder

class TxBuilder

A transaction builder.

After creating the TxBuilder, you set options on it until finally calling .finish to consume the builder and generate the transaction.

Each method on the TxBuilder returns an instance of a new TxBuilder with the option set/added.

Samples


fun main() { 
   //sampleStart 
   val faucetAddress = Address("tb1ql7w62elx9ucw4pj5lgw4l028hmuw80sndtntxt")
// TxBuilderResult is a data class, which means you can use destructuring declarations on it to
// open it up into its component parts
val (psbt, txDetails) = TxBuilder()
    .addRecipient(faucetAddress.scriptPubkey(), 1000uL)
    .feeRate(1.2f)
    .finish(wallet)

println("Txid is ${txDetails.txid}")
wallet.sign(psbt) 
   //sampleEnd
}

fun main() { 
   //sampleStart 
   val faucetAddress = Address("tb1ql7w62elx9ucw4pj5lgw4l028hmuw80sndtntxt")
val txBuilderResult: TxBuilderResult = TxBuilder()
    .addRecipient(faucetAddress.scriptPubkey(), 1000uL)
    .feeRate(1.2f)
    .finish(wallet)

val psbt = txBuilderResult.psbt
val txDetails = txBuilderResult.transactionDetails

println("Txid is ${txDetails.txid}")
wallet.sign(psbt) 
   //sampleEnd
}

Constructors

Link copied to clipboard
fun TxBuilder()

Functions

Link copied to clipboard
fun addData(data: List<UByte>): TxBuilder

Add data as an output using OP_RETURN.

Link copied to clipboard
fun addRecipient(script: Script, amount: ULong): TxBuilder

Add a recipient to the internal list.

Link copied to clipboard
fun addUnspendable(unspendable: OutPoint): TxBuilder

Add a utxo to the internal list of unspendable utxos. It’s important to note that the "must-be-spent" utxos added with TxBuilder.addUtxo have priority over this. See the Rust docs of the two linked methods for more details.

Link copied to clipboard
fun addUtxo(outpoint: OutPoint): TxBuilder

Add an outpoint 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.

Link copied to clipboard
fun addUtxos(outpoints: List<OutPoint>): TxBuilder

Add the list of outpoints to the internal list of UTXOs that must be spent. If an error occurs while adding any of the UTXOs then none of them are added and the error is returned. 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.

Link copied to clipboard
fun doNotSpendChange(): TxBuilder

Do not spend change outputs. This effectively adds all the change outputs to the "unspendable" list. See TxBuilder.unspendable.

Link copied to clipboard
fun drainTo(script: Script): TxBuilder

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 ScriptPubKey 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 drainTo without setting any ordinary recipients with addRecipient (but it is perfectly fine to add recipients as well). If you choose not to set any recipients, you should either provide the utxos that the transaction should spend via addUtxos, or set drainWallet to spend all of them. When bumping the fees of a transaction made with this option, you probably want to use BumpFeeTxBuilder.allowShrinking to allow this output to be reduced to pay for the extra fees.

Link copied to clipboard
fun drainWallet(): TxBuilder

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

Link copied to clipboard
fun enableRbf(): TxBuilder

Enable signaling RBF. This will use the default nsequence value of 0xFFFFFFFD.

Link copied to clipboard
fun enableRbfWithSequence(nsequence: UInt): TxBuilder

Enable signaling RBF with a specific 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. If the nsequence is higher than 0xFFFFFFFD an error will be thrown, since it would not be a valid nSequence to signal RBF.

Link copied to clipboard
fun feeAbsolute(feeAmount: ULong): TxBuilder

Set an absolute fee.

Link copied to clipboard
fun feeRate(satPerVbyte: Float): TxBuilder

Set a custom fee rate.

Link copied to clipboard
fun finish(wallet: Wallet): TxBuilderResult

Finish building the transaction. Returns a TxBuilderResult.

Link copied to clipboard
fun manuallySelectedOnly(): TxBuilder

Only spend utxos added by add_utxo. The wallet will not add additional utxos to the transaction even if they are needed to make the transaction valid.

Link copied to clipboard
fun onlySpendChange(): TxBuilder

Only spend change outputs. This effectively adds all the non-change outputs to the "unspendable" list. See TxBuilder.unspendable.

Link copied to clipboard
fun setRecipients(recipients: List<ScriptAmount>): TxBuilder

Set the list of recipients by providing a list of ScriptAmount.

Link copied to clipboard
fun unspendable(unspendable: List<OutPoint>): TxBuilder

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.addUtxo have priority over these. See the Rust docs of the two linked methods for more details.