Enhance onchain transaction management

- Implement background job for rebroadcasting unconfirmed transactions with max attempt limit
- Add RBF (Replace-by-Fee) functionality allowing users to bump fees on outbound unconfirmed transactions
- Remove stale pending payments marked as PaymentStatus::Pending to prevent infinite pending states
- Detect and handle double spends by removing replaced unconfirmed transactions from store

Author: Camillarhi

bindings/ldk_node.udl

@@ -13,13 +13,20 @@ dictionary Config {
 	u64 probing_liquidity_limit_multiplier;
 	AnchorChannelsConfig? anchor_channels_config;
 	SendingParameters? sending_parameters;
+	RebroadcastPolicy rebroadcast_policy;
 };
 
 dictionary AnchorChannelsConfig {
 	sequence<PublicKey> trusted_peers_no_reserve;
 	u64 per_channel_reserve_sats;
 };
 
+dictionary RebroadcastPolicy {
+	u64 min_rebroadcast_interval;
+	u32 max_broadcast_attempts;
+	f32 backoff_factor;
+};
+
 dictionary BackgroundSyncConfig {
 	u64 onchain_wallet_sync_interval_secs;
 	u64 lightning_wallet_sync_interval_secs;
@@ -227,6 +234,10 @@ interface OnchainPayment {
 	Txid send_to_address([ByRef]Address address, u64 amount_sats, FeeRate? fee_rate);
 	[Throws=NodeError]
 	Txid send_all_to_address([ByRef]Address address, boolean retain_reserve, FeeRate? fee_rate);
+	[Throws=NodeError]
+	void rebroadcast_transaction(Txid txid);
+	[Throws=NodeError]
+	Txid bump_fee_rbf(Txid txid, u64 fee_bump_increment);
 };
 
 interface FeeRate {
@@ -404,7 +415,7 @@ interface ClosureReason {
 
 [Enum]
 interface PaymentKind {
-	Onchain(Txid txid, ConfirmationStatus status);
+	Onchain(Txid txid, ConfirmationStatus status, sequence<u8>? raw_tx, u64? last_broadcast_time, u32 broadcast_attempts);
 	Bolt11(PaymentHash hash, PaymentPreimage? preimage, PaymentSecret? secret);
 	Bolt11Jit(PaymentHash hash, PaymentPreimage? preimage, PaymentSecret? secret, u64? counterparty_skimmed_fee_msat, LSPFeeLimits lsp_fee_limits);
 	Bolt12Offer(PaymentHash? hash, PaymentPreimage? preimage, PaymentSecret? secret, OfferId offer_id, UntrustedString? payer_note, u64? quantity);

src/config.rs

@@ -94,6 +94,9 @@ pub(crate) const RGS_SYNC_TIMEOUT_SECS: u64 = 5;
 /// The length in bytes of our wallets' keys seed.
 pub const WALLET_KEYS_SEED_LEN: usize = 64;
 
+// The time in-between unconfirmed transaction broadcasts.
+pub(crate) const UNCONFIRMED_TX_BROADCAST_INTERVAL: Duration = Duration::from_secs(300);
+
 #[derive(Debug, Clone)]
 /// Represents the configuration of an [`Node`] instance.
 ///
@@ -179,6 +182,16 @@ pub struct Config {
 	/// **Note:** If unset, default parameters will be used, and you will be able to override the
 	/// parameters on a per-payment basis in the corresponding method calls.
 	pub sending_parameters: Option<SendingParameters>,
+	/// Policy for controlling transaction rebroadcasting behavior.
+	///
+	/// This policy determines how and when unconfirmed transactions are rebroadcast to the network
+	/// to improve confirmation reliability.
+	///
+	/// ### Default Behavior
+	/// - Minimum interval: 300 seconds (5 minutes)
+	/// - Maximum attempts: 24
+	/// - Exponential backoff factor: 1.5 (50% increase each attempt)
+	pub rebroadcast_policy: RebroadcastPolicy,
 }
 
 impl Default for Config {
@@ -193,6 +206,7 @@ impl Default for Config {
 			anchor_channels_config: Some(AnchorChannelsConfig::default()),
 			sending_parameters: None,
 			node_alias: None,
+			rebroadcast_policy: RebroadcastPolicy::default(),
 		}
 	}
 }
@@ -534,6 +548,45 @@ impl From<MaxDustHTLCExposure> for LdkMaxDustHTLCExposure {
 	}
 }
 
+/// Policy for controlling transaction rebroadcasting behavior.
+///
+/// Determines the strategy for resending unconfirmed transactions to the network
+/// to ensure they remain in mempools and eventually get confirmed.
+#[derive(Clone, Debug)]
+pub struct RebroadcastPolicy {
+	/// Minimum time between rebroadcast attempts in seconds.
+	///
+	/// This prevents excessive network traffic by ensuring a minimum delay
+	/// between consecutive rebroadcast attempts.
+	///
+	/// **Recommended values**: 60-600 seconds (1-10 minutes)
+	pub min_rebroadcast_interval: u64,
+	/// Maximum number of broadcast attempts before giving up.
+	///
+	/// After reaching this limit, the transaction will no longer be rebroadcast
+	/// automatically. Manual intervention may be required.
+	///
+	/// **Recommended values**: 12-48 attempts
+	pub max_broadcast_attempts: u32,
+	/// Exponential backoff factor for increasing intervals between attempts.
+	///
+	/// Each subsequent rebroadcast wait time is multiplied by this factor,
+	/// creating an exponential backoff pattern.
+	///
+	/// - `1.0`: No backoff (constant interval)
+	/// - `1.5`: 50% increase each attempt
+	/// - `2.0`: 100% increase (doubling) each attempt
+	///
+	/// **Recommended values**: 1.2-2.0
+	pub backoff_factor: f32,
+}
+
+impl Default for RebroadcastPolicy {
+	fn default() -> Self {
+		Self { min_rebroadcast_interval: 300, max_broadcast_attempts: 24, backoff_factor: 1.5 }
+	}
+}
+
 #[cfg(test)]
 mod tests {
 	use std::str::FromStr;

src/ffi/types.rs

@@ -12,7 +12,7 @@
 
 pub use crate::config::{
 	default_config, AnchorChannelsConfig, BackgroundSyncConfig, ElectrumSyncConfig,
-	EsploraSyncConfig, MaxDustHTLCExposure,
+	EsploraSyncConfig, MaxDustHTLCExposure, RebroadcastPolicy,
 };
 pub use crate::graph::{ChannelInfo, ChannelUpdateInfo, NodeAnnouncementInfo, NodeInfo};
 pub use crate::liquidity::{LSPS1OrderStatus, LSPS2ServiceConfig, OnchainPaymentInfo, PaymentInfo};

src/lib.rs

@@ -129,6 +129,7 @@ use config::{
 	default_user_config, may_announce_channel, ChannelConfig, Config,
 	BACKGROUND_TASK_SHUTDOWN_TIMEOUT_SECS, LDK_EVENT_HANDLER_SHUTDOWN_TIMEOUT_SECS,
 	NODE_ANN_BCAST_INTERVAL, PEER_RECONNECTION_INTERVAL, RGS_SYNC_INTERVAL,
+	UNCONFIRMED_TX_BROADCAST_INTERVAL,
 };
 use connection::ConnectionManager;
 use event::{EventHandler, EventQueue};
@@ -428,6 +429,34 @@ impl Node {
 			}
 		}, runtime_handle);
 
+		// Regularly rebroadcast unconfirmed transactions.
+		let rebroadcast_wallet = Arc::clone(&self.wallet);
+		let rebroadcast_logger = Arc::clone(&self.logger);
+		let mut stop_rebroadcast = self.stop_sender.subscribe();
+		cancellable_background_tasks.spawn_on(
+			async move {
+				let mut interval = tokio::time::interval(UNCONFIRMED_TX_BROADCAST_INTERVAL);
+				interval.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
+				loop {
+					tokio::select! {
+						_ = stop_rebroadcast.changed() => {
+							log_debug!(
+								rebroadcast_logger,
+								"Stopping rebroadcasting unconfirmed transactions."
+							);
+							return;
+						}
+						_ = interval.tick() => {
+							if let Err(e) = rebroadcast_wallet.rebroadcast_unconfirmed_transactions() {
+								log_error!(rebroadcast_logger, "Background rebroadcast failed: {}", e);
+							}
+						}
+					}
+				}
+			},
+			runtime_handle,
+		);
+
 		// Regularly broadcast node announcements.
 		let bcast_cm = Arc::clone(&self.channel_manager);
 		let bcast_pm = Arc::clone(&self.peer_manager);

src/payment/onchain.rs

@@ -122,4 +122,31 @@ impl OnchainPayment {
 		let fee_rate_opt = maybe_map_fee_rate_opt!(fee_rate);
 		self.wallet.send_to_address(address, send_amount, fee_rate_opt)
 	}
+
+	/// Manually trigger a rebroadcast of a specific transaction according to the default policy.
+	///
+	/// This is useful if you suspect a transaction may not have propagated properly through the
+	/// network and you want to attempt to rebroadcast it immediately rather than waiting for the
+	/// automatic background job to handle it.
+	///
+	/// updating the attempt count and last broadcast time for the transaction in the payment store.
+	pub fn rebroadcast_transaction(&self, txid: Txid) -> Result<(), Error> {
+		self.wallet.rebroadcast_transaction(txid)?;
+		Ok(())
+	}
+
+	/// 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.
+	///
+	/// `fee_bump_increment` specifies the additional fee amount in satoshis to add to the
+	/// transaction. 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, txid: Txid, fee_bump_increment: u64) -> Result<Txid, Error> {
+		self.wallet.bump_fee_rbf(txid, fee_bump_increment)
+	}
 }

src/payment/store.rs

@@ -293,6 +293,24 @@ impl StorableObject for PaymentDetails {
 			}
 		}
 
+		if let Some(attempts) = update.broadcast_attempts {
+			match self.kind {
+				PaymentKind::Onchain { ref mut broadcast_attempts, .. } => {
+					update_if_necessary!(*broadcast_attempts, attempts);
+				},
+				_ => {},
+			}
+		}
+
+		if let Some(broadcast_time) = update.last_broadcast_time {
+			match self.kind {
+				PaymentKind::Onchain { ref mut last_broadcast_time, .. } => {
+					update_if_necessary!(*last_broadcast_time, broadcast_time);
+				},
+				_ => {},
+			}
+		}
+
 		if updated {
 			self.latest_update_timestamp = SystemTime::now()
 				.duration_since(UNIX_EPOCH)
@@ -353,6 +371,12 @@ pub enum PaymentKind {
 		txid: Txid,
 		/// The confirmation status of this payment.
 		status: ConfirmationStatus,
+		/// The raw transaction for rebroadcasting
+		raw_tx: Option<Vec<u8>>,
+		/// Last broadcast attempt timestamp (UNIX seconds)
+		last_broadcast_time: Option<u64>,
+		/// Number of broadcast attempts
+		broadcast_attempts: u32,
 	},
 	/// A [BOLT 11] payment.
 	///
@@ -451,6 +475,9 @@ impl_writeable_tlv_based_enum!(PaymentKind,
 	(0, Onchain) => {
 		(0, txid, required),
 		(2, status, required),
+		(4, raw_tx, option),
+		(10, last_broadcast_time, option),
+		(12, broadcast_attempts, required),
 	},
 	(2, Bolt11) => {
 		(0, hash, required),
@@ -542,6 +569,8 @@ pub(crate) struct PaymentDetailsUpdate {
 	pub direction: Option<PaymentDirection>,
 	pub status: Option<PaymentStatus>,
 	pub confirmation_status: Option<ConfirmationStatus>,
+	pub last_broadcast_time: Option<Option<u64>>,
+	pub broadcast_attempts: Option<u32>,
 }
 
 impl PaymentDetailsUpdate {
@@ -557,6 +586,8 @@ impl PaymentDetailsUpdate {
 			direction: None,
 			status: None,
 			confirmation_status: None,
+			last_broadcast_time: None,
+			broadcast_attempts: None,
 		}
 	}
 }
@@ -572,9 +603,11 @@ impl From<&PaymentDetails> for PaymentDetailsUpdate {
 			_ => (None, None, None),
 		};
 
-		let confirmation_status = match value.kind {
-			PaymentKind::Onchain { status, .. } => Some(status),
-			_ => None,
+		let (confirmation_status, last_broadcast_time, broadcast_attempts) = match value.kind {
+			PaymentKind::Onchain { status, last_broadcast_time, broadcast_attempts, .. } => {
+				(Some(status), last_broadcast_time, broadcast_attempts)
+			},
+			_ => (None, None, 0),
 		};
 
 		let counterparty_skimmed_fee_msat = match value.kind {
@@ -595,6 +628,8 @@ impl From<&PaymentDetails> for PaymentDetailsUpdate {
 			direction: Some(value.direction),
 			status: Some(value.status),
 			confirmation_status,
+			last_broadcast_time: Some(last_broadcast_time),
+			broadcast_attempts: Some(broadcast_attempts),
 		}
 	}
 }