Implement background job for transaction rebroadcasting

Introduces a `RebroadcastPolicy` to manage the automatic rebroadcasting
of unconfirmed transactions with exponential backoff. This prevents
excessive network spam while systematically retrying stuck transactions.

The feature is enabled by default but can be disabled via the builder:
`builder.set_auto_rebroadcast_unconfirmed(false)`.

Configuration options:
- min_rebroadcast_interval: Base delay between attempts (seconds)
- max_broadcast_attempts: Total attempts before abandonment
- backoff_factor: Multiplier for exponential delay increase

Sensible defaults are provided (300s, 24 attempts, 1.5x backoff).

Author: Camillarhi

bindings/ldk_node.udl

@@ -13,6 +13,7 @@ dictionary Config {
 	u64 probing_liquidity_limit_multiplier;
 	AnchorChannelsConfig? anchor_channels_config;
 	RouteParametersConfig? route_parameters;
+	boolean auto_rebroadcast_unconfirmed_tx;
 };
 
 dictionary AnchorChannelsConfig {
@@ -266,6 +267,8 @@ 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(PaymentId payment_id);
 };
 
 interface FeeRate {
@@ -351,6 +354,7 @@ enum NodeError {
 	"InvalidBlindedPaths",
 	"AsyncPaymentServicesDisabled",
 	"HrnParsingFailed",
+	"InvalidTransaction",
 };
 
 dictionary NodeStatus {
@@ -450,7 +454,7 @@ interface ClosureReason {
 
 [Enum]
 interface PaymentKind {
-	Onchain(Txid txid, ConfirmationStatus status);
+	Onchain(Txid txid, ConfirmationStatus status, Transaction? 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);
@@ -916,3 +920,6 @@ typedef string LSPSDateTime;
 
 [Custom]
 typedef string ScriptBuf;
+
+[Custom]
+typedef string Transaction;

src/config.rs

@@ -28,6 +28,9 @@ const DEFAULT_LDK_WALLET_SYNC_INTERVAL_SECS: u64 = 30;
 const DEFAULT_FEE_RATE_CACHE_UPDATE_INTERVAL_SECS: u64 = 60 * 10;
 const DEFAULT_PROBING_LIQUIDITY_LIMIT_MULTIPLIER: u64 = 3;
 const DEFAULT_ANCHOR_PER_CHANNEL_RESERVE_SATS: u64 = 25_000;
+const DEFAULT_MIN_REBROADCAST_INTERVAL_SECS: u64 = 300;
+const DEFAULT_MAX_BROADCAST_ATTEMPTS: u32 = 24;
+const DEFAULT_BACKOFF_FACTOR: f32 = 1.5;
 
 /// The default log level.
 pub const DEFAULT_LOG_LEVEL: LogLevel = LogLevel::Debug;
@@ -107,6 +110,9 @@ pub(crate) const EXTERNAL_PATHFINDING_SCORES_SYNC_TIMEOUT_SECS: u64 = 5;
 // The timeout after which we abort a parsing/looking up an HRN resolution.
 pub(crate) const HRN_RESOLUTION_TIMEOUT_SECS: u64 = 5;
 
+// 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.
 ///
@@ -128,6 +134,7 @@ pub(crate) const HRN_RESOLUTION_TIMEOUT_SECS: u64 = 5;
 /// | `log_level`                            | Debug              |
 /// | `anchor_channels_config`               | Some(..)           |
 /// | `route_parameters`                   | None               |
+/// | `auto_rebroadcast_unconfirmed_tx`      | true               |
 ///
 /// See [`AnchorChannelsConfig`] and [`RouteParametersConfig`] for more information regarding their
 /// respective default values.
@@ -192,6 +199,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 route_parameters: Option<RouteParametersConfig>,
+	/// This will determine whether to automatically rebroadcast unconfirmed transactions
+	/// (e.g., channel funding or sweep transactions).
+	///
+	/// If enabled, the node will periodically attempt to rebroadcast any unconfirmed transactions to
+	/// increase propagation and confirmation likelihood. This is helpful in cases where transactions
+	/// were dropped by the mempool or not widely propagated.
+	///
+	/// Defaults to `true`. Disabling this may be desired for privacy-sensitive use cases or low-bandwidth
+	/// environments, but may result in slower or failed confirmations if transactions are not re-announced.
+	pub auto_rebroadcast_unconfirmed_tx: bool,
 }
 
 impl Default for Config {
@@ -206,6 +223,7 @@ impl Default for Config {
 			anchor_channels_config: Some(AnchorChannelsConfig::default()),
 			route_parameters: None,
 			node_alias: None,
+			auto_rebroadcast_unconfirmed_tx: true,
 		}
 	}
 }
@@ -561,6 +579,49 @@ pub enum AsyncPaymentsRole {
 	Server,
 }
 
+/// 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_secs: 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_secs: DEFAULT_MIN_REBROADCAST_INTERVAL_SECS,
+			max_broadcast_attempts: DEFAULT_MAX_BROADCAST_ATTEMPTS,
+			backoff_factor: DEFAULT_BACKOFF_FACTOR,
+		}
+	}
+}
+
 #[cfg(test)]
 mod tests {
 	use std::str::FromStr;

src/error.rs

@@ -131,6 +131,8 @@ pub enum Error {
 	AsyncPaymentServicesDisabled,
 	/// Parsing a Human-Readable Name has failed.
 	HrnParsingFailed,
+	/// The given transaction is invalid.
+	InvalidTransaction,
 }
 
 impl fmt::Display for Error {
@@ -213,6 +215,7 @@ impl fmt::Display for Error {
 			Self::HrnParsingFailed => {
 				write!(f, "Failed to parse a human-readable name.")
 			},
+			Self::InvalidTransaction => write!(f, "The given transaction is invalid."),
 		}
 	}
 }

src/ffi/types.rs

@@ -1248,6 +1248,21 @@ impl UniffiCustomTypeConverter for LSPSDateTime {
 	}
 }
 
+impl UniffiCustomTypeConverter for Transaction {
+	type Builtin = String;
+	fn into_custom(val: Self::Builtin) -> uniffi::Result<Self> {
+		if let Some(bytes) = hex_utils::to_vec(&val) {
+			if let Ok(tx) = bitcoin::consensus::deserialize::<Transaction>(&bytes) {
+				return Ok(tx);
+			}
+		}
+		Err(Error::InvalidTransaction.into())
+	}
+	fn from_custom(obj: Self) -> Self::Builtin {
+		hex_utils::to_string(&bitcoin::consensus::serialize(&obj))
+	}
+}
+
 #[cfg(test)]
 mod tests {
 	use std::num::NonZeroU64;

src/lib.rs

@@ -124,7 +124,7 @@ pub use builder::NodeBuilder as Builder;
 use chain::ChainSource;
 use config::{
 	default_user_config, may_announce_channel, AsyncPaymentsRole, ChannelConfig, Config,
-	NODE_ANN_BCAST_INTERVAL, PEER_RECONNECTION_INTERVAL, RGS_SYNC_INTERVAL,
+	NODE_ANN_BCAST_INTERVAL, PEER_RECONNECTION_INTERVAL, RGS_SYNC_INTERVAL, UNCONFIRMED_TX_BROADCAST_INTERVAL,
 };
 use connection::ConnectionManager;
 pub use error::Error as NodeError;
@@ -459,6 +459,33 @@ impl Node {
 			}
 		});
 
+		// 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();
+		if self.config.auto_rebroadcast_unconfirmed_tx {
+			self.runtime.spawn_cancellable_background_task(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);
+							}
+						}
+					}
+				}
+			});
+		}
+
 		// Regularly broadcast node announcements.
 		let bcast_cm = Arc::clone(&self.channel_manager);
 		let bcast_pm = Arc::clone(&self.peer_manager);

src/payment/onchain.rs

@@ -17,6 +17,11 @@ use crate::logger::{log_info, LdkLogger, Logger};
 use crate::types::{ChannelManager, Wallet};
 use crate::wallet::OnchainSendAmount;
 
+use bitcoin::{Address, Txid};
+use lightning::ln::channelmanager::PaymentId;
+
+use std::sync::{Arc, RwLock};
+
 #[cfg(not(feature = "uniffi"))]
 type FeeRate = bitcoin::FeeRate;
 #[cfg(feature = "uniffi")]
@@ -120,4 +125,15 @@ 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, payment_id: PaymentId) -> Result<(), Error> {
+		self.wallet.rebroadcast_transaction(payment_id)
+	}
 }

src/payment/store.rs

@@ -19,6 +19,10 @@ use lightning::{
 use lightning_types::payment::{PaymentHash, PaymentPreimage, PaymentSecret};
 use lightning_types::string::UntrustedString;
 
+use bitcoin::{BlockHash, Transaction, Txid};
+
+use std::time::{Duration, SystemTime, UNIX_EPOCH};
+
 use crate::data_store::{StorableObject, StorableObjectId, StorableObjectUpdate};
 use crate::hex_utils;
 
@@ -291,6 +295,33 @@ impl StorableObject for PaymentDetails {
 			}
 		}
 
+		if let Some(tx) = &update.raw_tx {
+			match self.kind {
+				PaymentKind::Onchain { ref mut raw_tx, .. } => {
+					update_if_necessary!(*raw_tx, tx.clone());
+				},
+				_ => {},
+			}
+		}
+
+		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)
@@ -351,6 +382,12 @@ pub enum PaymentKind {
 		txid: Txid,
 		/// The confirmation status of this payment.
 		status: ConfirmationStatus,
+		/// The raw transaction for rebroadcasting
+		raw_tx: Option<Transaction>,
+		/// Last broadcast attempt timestamp (UNIX seconds)
+		last_broadcast_time: Option<u64>,
+		/// Number of broadcast attempts
+		broadcast_attempts: Option<u32>,
 	},
 	/// A [BOLT 11] payment.
 	///
@@ -448,7 +485,10 @@ pub enum PaymentKind {
 impl_writeable_tlv_based_enum!(PaymentKind,
 	(0, Onchain) => {
 		(0, txid, required),
+		(1, raw_tx, option),
 		(2, status, required),
+		(3, last_broadcast_time, option),
+		(5, broadcast_attempts, option),
 	},
 	(2, Bolt11) => {
 		(0, hash, required),
@@ -540,6 +580,9 @@ pub(crate) struct PaymentDetailsUpdate {
 	pub direction: Option<PaymentDirection>,
 	pub status: Option<PaymentStatus>,
 	pub confirmation_status: Option<ConfirmationStatus>,
+	pub raw_tx: Option<Option<Transaction>>,
+	pub last_broadcast_time: Option<Option<u64>>,
+	pub broadcast_attempts: Option<Option<u32>>,
 }
 
 impl PaymentDetailsUpdate {
@@ -555,6 +598,9 @@ impl PaymentDetailsUpdate {
 			direction: None,
 			status: None,
 			confirmation_status: None,
+			raw_tx: None,
+			last_broadcast_time: None,
+			broadcast_attempts: None,
 		}
 	}
 }
@@ -570,10 +616,17 @@ impl From<&PaymentDetails> for PaymentDetailsUpdate {
 			_ => (None, None, None),
 		};
 
-		let confirmation_status = match value.kind {
-			PaymentKind::Onchain { status, .. } => Some(status),
-			_ => None,
-		};
+		let (confirmation_status, raw_tx, last_broadcast_time, broadcast_attempts) =
+			match &value.kind {
+				PaymentKind::Onchain {
+					status,
+					raw_tx,
+					last_broadcast_time,
+					broadcast_attempts,
+					..
+				} => (Some(*status), raw_tx.clone(), *last_broadcast_time, *broadcast_attempts),
+				_ => (None, None, None, None),
+			};
 
 		let counterparty_skimmed_fee_msat = match value.kind {
 			PaymentKind::Bolt11Jit { counterparty_skimmed_fee_msat, .. } => {
@@ -593,6 +646,9 @@ impl From<&PaymentDetails> for PaymentDetailsUpdate {
 			direction: Some(value.direction),
 			status: Some(value.status),
 			confirmation_status,
+			raw_tx: Some(raw_tx),
+			last_broadcast_time: Some(last_broadcast_time),
+			broadcast_attempts: Some(broadcast_attempts),
 		}
 	}
 }