Implement RBF fee bumping for unconfirmed transactions

Add `Replace-by-Fee` functionality to allow users to increase fees on
pending outbound transactions, improving confirmation likelihood during
network congestion.

- Uses BDK's `build_fee_bump` for transaction replacement
- Validates transaction eligibility: must be outbound and unconfirmed
- Implements fee rate estimation with safety limits
- Maintains payment history consistency across wallet updates
- Includes integration tests for various RBF scenarios

Author: Camillarhi

bindings/ldk_node.udl

@@ -234,6 +234,8 @@ interface OnchainPayment {
 	Txid send_all_to_address([ByRef]Address address, boolean retain_reserve, FeeRate? fee_rate);
 	[Throws=NodeError]
 	void rebroadcast_transaction(PaymentId payment_id);
+	[Throws=NodeError]
+	Txid bump_fee_rbf(PaymentId payment_id);
 };
 
 interface FeeRate {

src/payment/onchain.rs

@@ -132,4 +132,18 @@ impl OnchainPayment {
 	pub fn rebroadcast_transaction(&self, payment_id: PaymentId) -> Result<(), Error> {
 		self.wallet.rebroadcast_transaction(payment_id)
 	}
+
+	/// Attempt to bump the fee of an unconfirmed transaction using Replace-by-Fee (RBF).
+	///
+	/// This creates a new transaction that replaces the original one, increasing the fee by the
+	/// specified increment to improve its chances of confirmation. The original transaction must
+	/// be signaling RBF replaceability for this to succeed.
+	///
+	/// The new transaction will have the same outputs as the original but with a
+	/// higher fee, resulting in faster confirmation potential.
+	///
+	/// Returns the Txid of the new replacement transaction if successful.
+	pub fn bump_fee_rbf(&self, payment_id: PaymentId) -> Result<Txid, Error> {
+		self.wallet.bump_fee_rbf(payment_id)
+	}
 }

src/wallet/mod.rs

@@ -5,6 +5,7 @@
 // http://opensource.org/licenses/MIT>, at your option. You may not use this file except in
 // accordance with one or both of these licenses.
 
+use bdk_wallet::error::{BuildFeeBumpError, CreateTxError};
 use persist::KVStoreWalletPersister;
 
 use crate::config::{Config, RebroadcastPolicy};
@@ -789,6 +790,167 @@ where
 		log_info!(self.logger, "No details found for payment {} in store", payment_id);
 		return Err(Error::InvalidPaymentId);
 	}
+
+	pub(crate) fn bump_fee_rbf(&self, payment_id: PaymentId) -> Result<Txid, Error> {
+		let old_payment =
+			self.payment_store.get(&payment_id).ok_or(Error::InvalidPaymentId)?.clone();
+
+		let mut locked_wallet = self.inner.lock().unwrap();
+
+		let txid = Txid::from_slice(&payment_id.0).expect("32 bytes");
+
+		let wallet_tx = locked_wallet.get_tx(txid).ok_or(Error::InvalidPaymentId)?;
+		let (sent, received) = locked_wallet.sent_and_received(&wallet_tx.tx_node.tx);
+
+		if sent <= received {
+			log_error!(
+				self.logger,
+				"Transaction {} is not an outbound payment (sent: {}, received: {})",
+				txid,
+				sent,
+				received
+			);
+			return Err(Error::InvalidPaymentId);
+		}
+
+		if old_payment.direction != PaymentDirection::Outbound {
+			log_error!(self.logger, "Transaction {} is not an outbound payment", txid);
+			return Err(Error::InvalidPaymentId);
+		}
+
+		if let PaymentKind::Onchain { status, .. } = &old_payment.kind {
+			match status {
+				ConfirmationStatus::Confirmed { .. } => {
+					log_error!(
+						self.logger,
+						"Transaction {} is already confirmed and cannot be fee bumped",
+						txid
+					);
+					return Err(Error::InvalidPaymentId);
+				},
+				ConfirmationStatus::Unconfirmed => {},
+			}
+		}
+
+		let confirmation_target = ConfirmationTarget::OnchainPayment;
+		let estimated_fee_rate = self.fee_estimator.estimate_fee_rate(confirmation_target);
+
+		log_info!(self.logger, "Bumping fee to {}", estimated_fee_rate);
+
+		let mut psbt = {
+			let mut builder = locked_wallet.build_fee_bump(txid).map_err(|e| {
+				log_error!(self.logger, "BDK fee bump failed for {}: {:?}", txid, e);
+				match e {
+					BuildFeeBumpError::TransactionNotFound(_) => Error::InvalidPaymentId,
+					BuildFeeBumpError::TransactionConfirmed(_) => Error::InvalidPaymentId,
+					BuildFeeBumpError::IrreplaceableTransaction(_) => Error::InvalidPaymentId,
+					BuildFeeBumpError::FeeRateUnavailable => Error::InvalidPaymentId,
+					_ => Error::InvalidFeeRate,
+				}
+			})?;
+
+			builder.fee_rate(estimated_fee_rate);
+
+			match builder.finish() {
+				Ok(psbt) => Ok(psbt),
+				Err(CreateTxError::FeeRateTooLow { required }) => {
+					log_info!(self.logger, "BDK requires higher fee rate: {}", required);
+
+					// Safety check
+					const MAX_REASONABLE_FEE_RATE_SAT_VB: u64 = 1000;
+					if required.to_sat_per_vb_ceil() > MAX_REASONABLE_FEE_RATE_SAT_VB {
+						log_error!(
+							self.logger,
+							"BDK requires unreasonably high fee rate: {} sat/vB",
+							required.to_sat_per_vb_ceil()
+						);
+						return Err(Error::InvalidFeeRate);
+					}
+
+					let mut builder = locked_wallet.build_fee_bump(txid).map_err(|e| {
+						log_error!(self.logger, "BDK fee bump retry failed for {}: {:?}", txid, e);
+						Error::InvalidFeeRate
+					})?;
+
+					builder.fee_rate(required);
+					builder.finish().map_err(|e| {
+						log_error!(
+							self.logger,
+							"Failed to finish PSBT with required fee rate: {:?}",
+							e
+						);
+						Error::InvalidFeeRate
+					})
+				},
+				Err(e) => {
+					log_error!(self.logger, "Failed to create fee bump PSBT: {:?}", e);
+					Err(Error::InvalidFeeRate)
+				},
+			}?
+		};
+
+		match locked_wallet.sign(&mut psbt, SignOptions::default()) {
+			Ok(finalized) => {
+				if !finalized {
+					return Err(Error::OnchainTxCreationFailed);
+				}
+			},
+			Err(err) => {
+				log_error!(self.logger, "Failed to create transaction: {}", err);
+				return Err(err.into());
+			},
+		}
+
+		let mut locked_persister = self.persister.lock().unwrap();
+		locked_wallet.persist(&mut locked_persister).map_err(|e| {
+			log_error!(self.logger, "Failed to persist wallet: {}", e);
+			Error::PersistenceFailed
+		})?;
+
+		let fee_bumped_tx = psbt.extract_tx().map_err(|e| {
+			log_error!(self.logger, "Failed to extract transaction: {}", e);
+			e
+		})?;
+
+		let new_txid = fee_bumped_tx.compute_txid();
+
+		self.broadcaster.broadcast_transactions(&[&fee_bumped_tx]);
+
+		let new_fee = locked_wallet.calculate_fee(&fee_bumped_tx).unwrap_or(Amount::ZERO);
+		let new_fee_sats = new_fee.to_sat();
+
+		let payment_details = PaymentDetails {
+			id: PaymentId(new_txid.to_byte_array()),
+			kind: PaymentKind::Onchain {
+				txid: new_txid,
+				status: ConfirmationStatus::Unconfirmed,
+				raw_tx: Some(fee_bumped_tx),
+				last_broadcast_time: Some(
+					SystemTime::now()
+						.duration_since(UNIX_EPOCH)
+						.unwrap_or(Duration::from_secs(0))
+						.as_secs(),
+				),
+				broadcast_attempts: Some(1),
+			},
+			amount_msat: old_payment.amount_msat,
+			fee_paid_msat: Some(new_fee_sats * 1000),
+			direction: old_payment.direction,
+			status: PaymentStatus::Pending,
+			latest_update_timestamp: SystemTime::now()
+				.duration_since(UNIX_EPOCH)
+				.unwrap_or(Duration::from_secs(0))
+				.as_secs(),
+		};
+
+		self.payment_store.remove(&payment_id)?;
+
+		self.payment_store.insert_or_update(payment_details)?;
+
+		log_info!(self.logger, "RBF successful: replaced {} with {}", txid, new_txid);
+
+		Ok(new_txid)
+	}
 }
 
 impl<B: Deref, E: Deref, L: Deref> Listen for Wallet<B, E, L>

tests/integration_tests_rust.rs

@@ -33,9 +33,9 @@ use lightning::util::persist::KVStore;
 use lightning_invoice::{Bolt11InvoiceDescription, Description};
 use lightning_types::payment::{PaymentHash, PaymentPreimage};
 
-use bitcoin::address::NetworkUnchecked;
 use bitcoin::hashes::sha256::Hash as Sha256Hash;
 use bitcoin::hashes::Hash;
+use bitcoin::{address::NetworkUnchecked, Txid};
 use bitcoin::{Address, Amount, ScriptBuf};
 use log::LevelFilter;
 
@@ -671,6 +671,129 @@ fn onchain_wallet_recovery() {
 	);
 }
 
+#[test]
+fn onchain_fee_bump_rbf() {
+	let (bitcoind, electrsd) = setup_bitcoind_and_electrsd();
+	let chain_source = TestChainSource::Esplora(&electrsd);
+	let (node_a, node_b) = setup_two_nodes(&chain_source, false, true, false);
+
+	// Fund both nodes
+	let addr_a = node_a.onchain_payment().new_address().unwrap();
+	let addr_b = node_b.onchain_payment().new_address().unwrap();
+
+	let premine_amount_sat = 500_000;
+	premine_and_distribute_funds(
+		&bitcoind.client,
+		&electrsd.client,
+		vec![addr_a.clone(), addr_b.clone()],
+		Amount::from_sat(premine_amount_sat),
+	);
+
+	node_a.sync_wallets().unwrap();
+	node_b.sync_wallets().unwrap();
+
+	// Send a transaction from node_b to node_a that we'll later bump
+	let amount_to_send_sats = 100_000;
+	let txid =
+		node_b.onchain_payment().send_to_address(&addr_a, amount_to_send_sats, None).unwrap();
+	wait_for_tx(&electrsd.client, txid);
+	node_a.sync_wallets().unwrap();
+	node_b.sync_wallets().unwrap();
+
+	let payment_id = PaymentId(txid.to_byte_array());
+	let original_payment = node_b.payment(&payment_id).unwrap();
+	let original_fee = original_payment.fee_paid_msat.unwrap();
+
+	// Non-existent payment id
+	let fake_txid =
+		Txid::from_str("0000000000000000000000000000000000000000000000000000000000000000").unwrap();
+	let invalid_payment_id = PaymentId(fake_txid.to_byte_array());
+	assert_eq!(
+		Err(NodeError::InvalidPaymentId),
+		node_b.onchain_payment().bump_fee_rbf(invalid_payment_id)
+	);
+
+	// Bump an inbound payment
+	assert_eq!(Err(NodeError::InvalidPaymentId), node_a.onchain_payment().bump_fee_rbf(payment_id));
+
+	// Successful fee bump
+	let new_txid = node_b.onchain_payment().bump_fee_rbf(payment_id).unwrap();
+	wait_for_tx(&electrsd.client, new_txid);
+
+	// Sleep to allow for transaction propagation
+	std::thread::sleep(std::time::Duration::from_secs(5));
+
+	node_a.sync_wallets().unwrap();
+	node_b.sync_wallets().unwrap();
+
+	// Verify old payment is removed and new payment exists
+	assert!(node_b.payment(&payment_id).is_none(), "Old payment should be removed");
+
+	let new_payment_id = PaymentId(new_txid.to_byte_array());
+	let new_payment = node_b.payment(&new_payment_id).unwrap();
+
+	// Verify payment properties
+	assert_eq!(new_payment.amount_msat, Some(amount_to_send_sats * 1000));
+	assert_eq!(new_payment.direction, PaymentDirection::Outbound);
+	assert_eq!(new_payment.status, PaymentStatus::Pending);
+
+	// Verify fee increased
+	assert!(
+		new_payment.fee_paid_msat > Some(original_fee),
+		"Fee should increase after RBF bump. Original: {}, New: {}",
+		original_fee,
+		new_payment.fee_paid_msat.unwrap()
+	);
+
+	// Multiple consecutive bumps
+	let second_bump_txid = node_b.onchain_payment().bump_fee_rbf(new_payment_id).unwrap();
+	wait_for_tx(&electrsd.client, second_bump_txid);
+
+	// Sleep to allow for transaction propagation
+	std::thread::sleep(std::time::Duration::from_secs(5));
+
+	node_a.sync_wallets().unwrap();
+	node_b.sync_wallets().unwrap();
+
+	assert!(node_b.payment(&new_payment_id).is_none(), "First bump payment should be removed");
+
+	let second_payment_id = PaymentId(second_bump_txid.to_byte_array());
+	let second_payment = node_b.payment(&second_payment_id).unwrap();
+
+	assert!(
+		second_payment.fee_paid_msat > new_payment.fee_paid_msat,
+		"Second bump should have higher fee than first bump"
+	);
+
+	// Confirm the transaction and try to bump again (should fail)
+	generate_blocks_and_wait(&bitcoind.client, &electrsd.client, 6);
+	node_a.sync_wallets().unwrap();
+	node_b.sync_wallets().unwrap();
+
+	assert_eq!(
+		Err(NodeError::InvalidPaymentId),
+		node_b.onchain_payment().bump_fee_rbf(second_payment_id)
+	);
+
+	// Verify final payment is confirmed
+	let final_payment = node_b.payment(&second_payment_id).unwrap();
+	assert_eq!(final_payment.status, PaymentStatus::Succeeded);
+	match final_payment.kind {
+		PaymentKind::Onchain { status, .. } => {
+			assert!(matches!(status, ConfirmationStatus::Confirmed { .. }));
+		},
+		_ => panic!("Unexpected payment kind"),
+	}
+
+	// Verify node A received the funds correctly
+	let node_a_received_payment = node_a.list_payments_with_filter(
+		|p| matches!(p.kind, PaymentKind::Onchain { txid, .. } if txid == second_bump_txid),
+	);
+	assert_eq!(node_a_received_payment.len(), 1);
+	assert_eq!(node_a_received_payment[0].amount_msat, Some(amount_to_send_sats * 1000));
+	assert_eq!(node_a_received_payment[0].status, PaymentStatus::Succeeded);
+}
+
 #[test]
 fn test_rbf_via_mempool() {
 	run_rbf_test(false);