Struct TxSender

pub struct TxSender {
    pub signer: Actor,
    pub rpc: ExtendedBitcoinRpc,
    pub db: Database,
    pub btc_syncer_consumer_id: String,
    paramset: &'static ProtocolParamset,
    cached_spendinfo: TaprootSpendInfo,
    http_client: Client,
    pub mempool_api_host: Option<String>,
    pub mempool_api_endpoint: Option<String>,
}

Manages the process of sending Bitcoin transactions, including handling fee bumping strategies like Replace-By-Fee (RBF) and Child-Pays-For-Parent (CPFP).

It interacts with a Bitcoin Core RPC endpoint (ExtendedBitcoinRpc) to query network state (like fee rates) and submit transactions. It uses a Database to persist transaction state, track confirmation status, and manage associated data like fee payer UTXOs. The Actor provides signing capabilities for transactions controlled by this service.

Fields

signer: Actor

rpc: ExtendedBitcoinRpc

db: Database

btc_syncer_consumer_id: String

paramset: &'static ProtocolParamset

cached_spendinfo: TaprootSpendInfo

http_client: Client

mempool_api_host: Option<String>

mempool_api_endpoint: Option<String>

Implementations

impl TxSender

async fn create_fee_payer_utxo( &self, bumped_id: u32, tx: &Transaction, fee_rate: FeeRate, total_fee_payer_amount: Amount, fee_payer_utxos_len: usize, ) -> Result<(), SendTxError>

Creates and broadcasts a new “fee payer” UTXO to be used for CPFP transactions.

This function is called when a CPFP attempt fails due to insufficient funds in the existing confirmed fee payer UTXOs associated with a transaction (bumped_id). It calculates the required fee based on the parent transaction (tx) and the current fee_rate, adding a buffer (3x required fee + dust limit) to handle potential fee spikes. It then sends funds to the TxSender’s own signer address using the RPC’s send_to_address and saves the resulting UTXO information (outpoint, amount) to the database, linking it to the bumped_id.

Arguments

• bumped_id - The database ID of the parent transaction requiring the fee bump.
• tx - The parent transaction itself.
• fee_rate - The target fee rate for the CPFP package.
• total_fee_payer_amount - The sum of amounts in currently available confirmed fee payer UTXOs.
• fee_payer_utxos_len - The number of currently available confirmed fee payer UTXOs.

async fn create_child_tx( &self, p2a_anchor: OutPoint, anchor_sat: Amount, fee_payer_utxos: Vec<SpendableTxIn>, parent_tx_size: Weight, fee_rate: FeeRate, ) -> Result<Transaction, SendTxError>

Creates a Child-Pays-For-Parent (CPFP) child transaction.

This transaction spends:

1. The designated “P2A anchor” output of the parent transaction (p2a_anchor).
2. One or more confirmed “fee payer” UTXOs (fee_payer_utxos) controlled by the signer.

It calculates the total fee required (required_fee) to make the combined parent + child package attractive to miners at the target fee_rate. The required_fee is paid entirely by this child transaction.

The remaining value (total input value - required_fee) is sent to the change_address.

Signing

We sign the input spending the P2A anchor and all fee payer UTXOs.

Returns

The constructed and partially signed child transaction.

async fn create_package( &self, tx: Transaction, fee_rate: FeeRate, fee_payer_utxos: Vec<SpendableTxIn>, ) -> Result<Vec<Transaction>, SendTxError>

Creates a transaction package for CPFP submission.

Finds the P2A anchor output in the parent transaction (tx), then constructs the child transaction using create_child_tx.

Returns

• Vec<Transaction>: Parent transaction followed by the child transaction ready for submission via the submitpackage RPC.

async fn get_confirmed_fee_payer_utxos( &self, try_to_send_id: u32, ) -> Result<Vec<SpendableTxIn>, SendTxError>

Retrieves confirmed fee payer UTXOs associated with a specific send attempt.

Queries the database for UTXOs linked to try_to_send_id that are marked as confirmed. These UTXOs are controlled by the TxSender’s signer and are intended to be spent by a CPFP child transaction.

Returns

• Vec<SpendableTxIn>: SpendableTxIns of the confirmed fee payer UTXOs that are ready to be included as inputs in the CPFP child tx.

async fn _bump_fees_of_unconfirmed_fee_payer_txs( &self, bumped_id: u32, fee_rate: FeeRate, ) -> Result<(), SendTxError>

Attempts to bump the fees of unconfirmed “fee payer” UTXOs using RBF.

Fee payer UTXOs are created to fund CPFP child transactions. However, these fee payer creation transactions might themselves get stuck due to low fees. This function identifies such unconfirmed fee payer transactions associated with a parent transaction (bumped_id) and attempts to RBF them using the provided fee_rate.

This ensures the fee payer UTXOs confirm quickly, making them available to be spent by the actual CPFP child transaction.

Arguments

• bumped_id - The database ID of the parent transaction whose fee payer UTXOs need bumping.
• fee_rate - The target fee rate for bumping the fee payer transactions.

pub(super) async fn send_cpfp_tx( &self, try_to_send_id: u32, tx: Transaction, tx_metadata: Option<TxMetadata>, fee_rate: FeeRate, ) -> Result<(), SendTxError>

Sends a transaction using the Child-Pays-For-Parent (CPFP) strategy.

Logic:

1. Check Unconfirmed Fee Payers: Ensures no unconfirmed fee payer UTXOs exist for this try_to_send_id. If they do, returns SendTxError::UnconfirmedFeePayerUTXOsLeft as they need to confirm before being spendable by the child.
2. Get Confirmed Fee Payers: Retrieves the available confirmed fee payer UTXOs.
3. Create Package: Calls create_package to build the vec![parent_tx, child_tx]. The child_tx spends the parent’s anchor output and the fee payer UTXOs, paying a fee calculated for the whole package.
4. Test Mempool Accept (Debug step): Uses testmempoolaccept RPC to check if the package is likely to be accepted by the network before submitting.
5. Submit Package: Uses the submitpackage RPC to atomically submit the parent and child transactions. Bitcoin Core evaluates the fee rate of the package together.
6. Handle Results: Checks the submitpackage result. If successful or already in mempool, updates the effective fee rate in the database. If failed, logs an error.

Arguments

• try_to_send_id - The database ID tracking this send attempt.
• tx - The parent transaction requiring the fee bump.
• tx_metadata - Optional metadata associated with the transaction.
• fee_rate - The target fee rate for the CPFP package.

impl TxSender

pub fn is_bridge_tx_nonstandard(&self, tx: &Transaction) -> bool

Checks if a bridge transaction is nonstandard. Keep in mind that these are not all cases where a transaction is nonstandard. We only check non-standard types that clementine generates by default in non-standard mode. Currently checks these cases:

1. The transaction contains 0 sat non-anchor (only checks our specific anchor address) and non-op return output.
2. The transaction weight is bigger than 400k

Arguments:

• tx - The transaction to check.

Returns:

• true if the transaction is nonstandard, false otherwise.

pub async fn send_testnet4_nonstandard_tx( &self, tx: &Transaction, try_to_send_id: u32, ) -> Result<(), SendTxError>

Sends a nonstandard transaction to testnet4 using the mempool.space accelerator.

Arguments:

• tx - The transaction to send.

Returns:

• Ok(()) if the transaction is sent successfully to the accelerator.
• Err(SendTxError) if the transaction is not sent successfully to the accelerator.

Note: Mempool.space accelerator doesn’t accept transactions if: - At least one of the transaction’s inputs is signed with either the SIGHASH_NONE or SIGHASH_ANYONECANPAY flag, which may allow a third party to replace the transaction. - The number of signature operations multiplied by 20 exceeds the transaction’s weight. Mempool Space API docs Mempool Space Accelerator FAQ

impl TxSender

pub async fn calculate_bump_feerate( &self, txid: &Txid, new_feerate: FeeRate, ) -> Result<Option<Amount>, SendTxError>

Calculates the appropriate fee rate for a Replace-By-Fee (RBF) transaction.

This method determines the effective fee rate needed to successfully replace an existing transaction in the mempool. It follows Bitcoin’s RBF rules by:

1. Retrieving the original transaction and calculating its current fee rate
2. Ensuring the new fee rate is higher than the original by at least the minimum required incremental relay fee
3. Comparing the calculated minimum bump fee rate with the requested target fee rate and selecting the higher of the two

Arguments

• txid - The transaction ID of the original transaction to be replaced
• new_feerate - The target fee rate requested for the replacement transaction

Returns

• Ok(Some(Amount)) - The effective fee rate (in satoshis per vbyte) to use for the replacement
• Ok(None) - If the original transaction already has a higher fee rate than requested
• Err(...) - If there was an error retrieving or analyzing the original transaction

pub async fn fill_in_utxo_info( &self, psbt: &mut String, ) -> Result<(), SendTxError>

pub async fn copy_witnesses( &self, psbt: String, initial_tx: &Transaction, ) -> Result<String, SendTxError>

Given a PSBT with inputs, fill in the existing witnesses from the original tx This allows us to create a finalized PSBT if the original tx had SinglePlusAnyoneCanPay signatures. If the original tx did not have S+AP, these signatures will be added. The expected behavior is for them to be replaced using RbfSigningInfo.

Returns

The PSBT as a base64-encoded string.

pub async fn create_funded_psbt( &self, tx: &Transaction, fee_rate: FeeRate, ) -> Result<WalletCreateFundedPsbtResult, SendTxError>

pub async fn attempt_sign_psbt( &self, psbt: String, rbf_signing_info: RbfSigningInfo, ) -> Result<String, SendTxError>

Given a PSBT with inputs that’ve been signed by the wallet except for our new input, we have to sign the first input with our self.signer actor.

Assumes that the first input is the input with our key.

Returns

The signed PSBT as a base64-encoded string.

pub fn handle_err( &self, err_msg: impl AsRef<str>, err_state: impl Into<String>, try_to_send_id: u32, )

pub fn verify_new_inputs(&self, psbt: &str, original_tx: &Transaction) -> bool

This function verifies that the wallet has added a funding input to the PSBT.

This is required for a transaction to be added to the wallet.

pub async fn get_tx_fee(&self, tx: &Transaction) -> Result<Amount, SendTxError>

pub(super) async fn send_rbf_tx( &self, try_to_send_id: u32, tx: Transaction, tx_metadata: Option<TxMetadata>, fee_rate: FeeRate, rbf_signing_info: Option<RbfSigningInfo>, ) -> Result<(), SendTxError>

Sends or bumps a transaction using the Replace-By-Fee (RBF) strategy.

It interacts with the database to track the latest RBF attempt (last_rbf_txid).

Logic:

1. Check for Existing RBF Tx: Retrieves last_rbf_txid for the try_to_send_id.

2. Bump Existing Tx: If psbt_bump_fee exists, it calls rpc.psbt_bump_fee.

   • This internally uses the Bitcoin Core psbtbumpfee RPC.
   • We then sign the inputs that we can using our Actor and have the wallet sign the rest.

3. Send Initial RBF Tx: If no last_rbf_txid exists (first attempt):

   • It uses fund_raw_transaction RPC to let the wallet add (potentially) inputs, outputs, set the fee according to fee_rate, and mark the transaction as replaceable.
   • Uses sign_raw_transaction_with_wallet RPC to sign the funded transaction.
   • Uses send_raw_transaction RPC to broadcast the initial RBF transaction.
   • Saves the resulting txid to the database as the last_rbf_txid.

Arguments

• try_to_send_id - The database ID tracking this send attempt.
• tx - The original transaction intended for RBF (used only on the first attempt).
• tx_metadata - Optional metadata associated with the transaction.
• fee_rate - The target fee rate for the RBF replacement.

impl TxSender

pub fn new( signer: Actor, rpc: ExtendedBitcoinRpc, db: Database, btc_syncer_consumer_id: String, paramset: &'static ProtocolParamset, mempool_api_host: Option<String>, mempool_api_endpoint: Option<String>, ) -> Self

async fn get_fee_rate(&self) -> Result<FeeRate, SendTxError>

Gets the current recommended fee rate in sat/vb from Mempool Space or Bitcoin Core.

fn calculate_required_fee( parent_tx_weight: Weight, num_fee_payer_utxos: usize, fee_rate: FeeRate, fee_paying_type: FeePayingType, ) -> Result<Amount, SendTxError>

Calculates the total fee required for a transaction package based on the fee bumping strategy.

Arguments

• parent_tx_weight - The weight of the main transaction being bumped.
• num_fee_payer_utxos - The number of fee payer UTXOs used (relevant for child tx size in CPFP).
• fee_rate - The target fee rate (sat/kwu or similar).
• fee_paying_type - The strategy being used (CPFP or RBF).

Calculation Logic

• CPFP: Calculates the weight of the hypothetical child transaction based on the number of fee payer inputs and standard P2TR output sizes. It then calculates the fee based on the combined virtual size (vbytes) of the parent and child transactions, as miners evaluate the package deal.
• RBF: Calculates the weight of the replacement transaction itself (assuming inputs and potentially outputs change slightly). The fee is calculated based on the weight of this single replacement transaction.

Reference for weight estimates: https://bitcoin.stackexchange.com/a/116959

fn is_p2a_anchor(&self, output: &TxOut) -> bool

fn find_p2a_vout(&self, tx: &Transaction) -> Result<usize, SendTxError>

fn btc_per_kvb_to_fee_rate(btc_per_kvb: f64) -> FeeRate

Submit package returns the effective fee rate in btc/kvb. This function converts the btc/kvb to a fee rate in sat/vb.

async fn try_to_send_unconfirmed_txs( &self, new_fee_rate: FeeRate, current_tip_height: u32, ) -> Result<(), SendTxError>

Fetches transactions that are eligible to be sent or bumped from database based on the given fee rate and tip height. Then, places a send transaction request to the Bitcoin based on the fee strategy.

For each eligible transaction (id):

1. Send/Bump Main Tx: Calls send_tx to either perform RBF or CPFP on the main transaction (id) using the new_fee_rate.
2. Handle Errors:
   • SendTxError::UnconfirmedFeePayerUTXOsLeft: Skips the current tx, waiting for fee payers to confirm.
   • SendTxError::InsufficientFeePayerAmount: Calls create_fee_payer_utxo to provision more funds for a future CPFP attempt.
   • Other errors are logged.

Arguments

• new_fee_rate - The current target fee rate based on network conditions.
• current_tip_height - The current blockchain height, used for time-lock checks.

pub fn client(&self) -> TxSenderClient

pub(crate) async fn send_no_funding_tx( &self, try_to_send_id: u32, tx: Transaction, tx_metadata: Option<TxMetadata>, ) -> Result<(), SendTxError>

Sends a transaction that is already fully funded and signed.

This function is used for transactions that do not require fee bumping strategies like RBF or CPFP. The transaction is submitted directly to the Bitcoin network without any modifications.

Arguments

• try_to_send_id - The database ID tracking this send attempt.
• tx - The fully funded and signed transaction ready for broadcast.
• tx_metadata - Optional metadata associated with the transaction for debugging.

Behavior

1. Attempts to broadcast the transaction using send_raw_transaction RPC.
2. Updates the database with success/failure state for debugging purposes.
3. Logs appropriate messages for monitoring and troubleshooting.

Returns

• Ok(()) - If the transaction was successfully broadcast.
• Err(SendTxError) - If the broadcast failed.

Trait Implementations

impl Clone for TxSender

fn clone(&self) -> TxSender

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for TxSender

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl IntoTask for TxSender

type Task = WithDelay<IgnoreError<TxSenderTask>>

fn into_task(self) -> Self::Task

Convert self into a Task