Merge pull request #4353 from tnull/2026-01-broadcast-type-refactor

Refactor `BroadcasterInterface` to include `TransactionType`

Author: TheBlueMatt

fuzz/src/chanmon_consistency.rs

@@ -36,7 +36,9 @@ use bitcoin::WPubkeyHash;
 use lightning::blinded_path::message::{BlindedMessagePath, MessageContext, MessageForwardNode};
 use lightning::blinded_path::payment::{BlindedPaymentPath, ReceiveTlvs};
 use lightning::chain;
-use lightning::chain::chaininterface::{BroadcasterInterface, ConfirmationTarget, FeeEstimator};
+use lightning::chain::chaininterface::{
+	TransactionType, BroadcasterInterface, ConfirmationTarget, FeeEstimator,
+};
 use lightning::chain::channelmonitor::{ChannelMonitor, MonitorEvent};
 use lightning::chain::transaction::OutPoint;
 use lightning::chain::{
@@ -159,8 +161,8 @@ pub struct TestBroadcaster {
 	txn_broadcasted: RefCell<Vec<Transaction>>,
 }
 impl BroadcasterInterface for TestBroadcaster {
-	fn broadcast_transactions(&self, txs: &[&Transaction]) {
-		for tx in txs {
+	fn broadcast_transactions(&self, txs: &[(&Transaction, TransactionType)]) {
+		for (tx, _broadcast_type) in txs {
 			self.txn_broadcasted.borrow_mut().push((*tx).clone());
 		}
 	}

fuzz/src/full_stack.rs

@@ -35,7 +35,9 @@ use lightning::ln::funding::{FundingTxInput, SpliceContribution};
 use lightning::blinded_path::message::{BlindedMessagePath, MessageContext, MessageForwardNode};
 use lightning::blinded_path::payment::{BlindedPaymentPath, ReceiveTlvs};
 use lightning::chain;
-use lightning::chain::chaininterface::{BroadcasterInterface, ConfirmationTarget, FeeEstimator};
+use lightning::chain::chaininterface::{
+	TransactionType, BroadcasterInterface, ConfirmationTarget, FeeEstimator,
+};
 use lightning::chain::chainmonitor;
 use lightning::chain::transaction::OutPoint;
 use lightning::chain::{BestBlock, ChannelMonitorUpdateStatus, Confirm, Listen};
@@ -188,8 +190,8 @@ struct TestBroadcaster {
 	txn_broadcasted: Mutex<Vec<Transaction>>,
 }
 impl BroadcasterInterface for TestBroadcaster {
-	fn broadcast_transactions(&self, txs: &[&Transaction]) {
-		let owned_txs: Vec<Transaction> = txs.iter().map(|tx| (*tx).clone()).collect();
+	fn broadcast_transactions(&self, txs: &[(&Transaction, TransactionType)]) {
+		let owned_txs: Vec<Transaction> = txs.iter().map(|(tx, _)| (*tx).clone()).collect();
 		self.txn_broadcasted.lock().unwrap().extend(owned_txs);
 	}
 }

lightning-liquidity/src/lsps2/service.rs

@@ -40,7 +40,7 @@ use crate::prelude::{new_hash_map, HashMap};
 use crate::sync::{Arc, Mutex, MutexGuard, RwLock};
 use crate::utils::async_poll::dummy_waker;
 
-use lightning::chain::chaininterface::BroadcasterInterface;
+use lightning::chain::chaininterface::{BroadcasterInterface, TransactionType};
 use lightning::events::HTLCHandlingFailureType;
 use lightning::ln::channelmanager::{AChannelManager, FailureCode, InterceptId};
 use lightning::ln::msgs::{ErrorAction, LightningError};
@@ -2019,23 +2019,24 @@ where
 		// (for example when a forwarded HTLC nears expiry). Broadcasting funding after a
 		// close could then confirm the commitment and trigger unintended on‑chain handling.
 		// To avoid this, we check ChannelManager’s view (`is_channel_ready`) before broadcasting.
-		let channel_id_opt = jit_channel.get_channel_id();
-		if let Some(ch_id) = channel_id_opt {
+		if let Some(ch_id) = jit_channel.get_channel_id() {
 			let is_channel_ready = self
 				.channel_manager
 				.get_cm()
 				.list_channels()
 				.into_iter()
 				.any(|cd| cd.channel_id == ch_id && cd.is_channel_ready);
+
 			if !is_channel_ready {
 				return;
 			}
-		} else {
-			return;
-		}
 
-		if let Some(funding_tx) = jit_channel.get_funding_tx() {
-			self.tx_broadcaster.broadcast_transactions(&[funding_tx]);
+			if let Some(funding_tx) = jit_channel.get_funding_tx() {
+				self.tx_broadcaster.broadcast_transactions(&[(
+					funding_tx,
+					TransactionType::Funding { channel_ids: vec![ch_id] },
+				)]);
+			}
 		}
 	}
 }

lightning/src/chain/chaininterface.rs

@@ -15,10 +15,97 @@
 
 use core::{cmp, ops::Deref};
 
+use crate::ln::types::ChannelId;
 use crate::prelude::*;
 
 use bitcoin::transaction::Transaction;
 
+/// Represents the class of transaction being broadcast.
+///
+/// This is used to provide context about the type of transaction being broadcast, which may be
+/// useful for logging, filtering, or prioritization purposes.
+#[derive(Clone, Debug, Hash, PartialEq, Eq)]
+pub enum TransactionType {
+	/// A funding transaction establishing a new channel.
+	///
+	/// If we initiated the channel the transaction given to
+	/// [`ChannelManager::funding_transaction_generated`] will be broadcast with this type.
+	///
+	/// [`ChannelManager::funding_transaction_generated`]: crate::ln::channelmanager::ChannelManager::funding_transaction_generated
+	Funding {
+		/// The IDs of the channels being funded.
+		///
+		/// A single funding transaction may establish multiple channels when using batch funding.
+		channel_ids: Vec<ChannelId>,
+	},
+	/// A transaction cooperatively closing a channel.
+	///
+	/// A transaction of this type will be broadcast when cooperatively closing a channel via
+	/// [`ChannelManager::close_channel`] or if the counterparty closes the channel.
+	///
+	/// [`ChannelManager::close_channel`]: crate::ln::channelmanager::ChannelManager::close_channel
+	CooperativeClose {
+		/// The ID of the channel being closed.
+		channel_id: ChannelId,
+	},
+	/// A transaction being broadcast to force-close the channel.
+	///
+	/// A transaction of this type will be broadcast when unilaterally closing a channel via
+	/// [`ChannelManager::force_close_broadcasting_latest_txn`] or if the counterparty force-closes
+	/// the channel.
+	///
+	/// [`ChannelManager::force_close_broadcasting_latest_txn`]: crate::ln::channelmanager::ChannelManager::force_close_broadcasting_latest_txn
+	UnilateralClose {
+		/// The ID of the channel being force-closed.
+		channel_id: ChannelId,
+	},
+	/// An anchor bumping transaction used for CPFP fee-bumping a closing transaction.
+	///
+	/// This will be broadcast after an anchor channel has been closed. See
+	/// [`BumpTransactionEvent`] for more information.
+	///
+	/// [`BumpTransactionEvent`]: crate::events::bump_transaction::BumpTransactionEvent
+	AnchorBump {
+		/// The ID of the channel whose closing transaction is being fee-bumped.
+		channel_id: ChannelId,
+	},
+	/// A transaction which is resolving an output spendable by both us and our counterparty.
+	///
+	/// When a channel closes via the unilateral close path, there may be transaction outputs which
+	/// are spendable by either our counterparty or us and represent some lightning state. In order
+	/// to resolve that state, the [`ChannelMonitor`] will spend any such outputs, ensuring funds
+	/// are only available to us prior to generating an [`Event::SpendableOutputs`]. This
+	/// transaction is one such transaction - resolving in-flight HTLCs or punishing our
+	/// counterparty if they broadcasted an outdated state.
+	///
+	/// [`ChannelMonitor`]: crate::chain::ChannelMonitor
+	/// [`Event::SpendableOutputs`]: crate::events::Event::SpendableOutputs
+	Claim {
+		/// The ID of the channel from which outputs are being claimed.
+		channel_id: ChannelId,
+	},
+	/// A transaction generated by the [`OutputSweeper`], sweeping [`SpendableOutputDescriptor`]s
+	/// to the user's wallet.
+	///
+	/// [`OutputSweeper`]: crate::util::sweep::OutputSweeper
+	/// [`SpendableOutputDescriptor`]: crate::sign::SpendableOutputDescriptor
+	Sweep {
+		/// The IDs of the channels from which outputs are being swept, if known.
+		///
+		/// A single sweep transaction may aggregate outputs from multiple channels.
+		channel_ids: Vec<ChannelId>,
+	},
+	/// A splice transaction modifying an existing channel's funding.
+	///
+	/// A transaction of this type will be broadcast as a result of a [`ChannelManager::splice_channel`] operation.
+	///
+	/// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
+	Splice {
+		/// The ID of the channel being spliced.
+		channel_id: ChannelId,
+	},
+}
+
 // TODO: Define typed abstraction over feerates to handle their conversions.
 pub(crate) fn compute_feerate_sat_per_1000_weight(fee_sat: u64, weight: u64) -> u32 {
 	(fee_sat * 1000 / weight).try_into().unwrap_or(u32::max_value())
@@ -45,11 +132,14 @@ pub trait BroadcasterInterface {
 	///
 	/// Bitcoin transaction packages are defined in BIP 331 and here:
 	/// <https://github.com/bitcoin/bitcoin/blob/master/doc/policy/packages.md>
-	fn broadcast_transactions(&self, txs: &[&Transaction]);
+	///
+	/// Each transaction is paired with a [`TransactionType`] indicating the class of transaction
+	/// being broadcast, which may be useful for logging, filtering, or prioritization.
+	fn broadcast_transactions(&self, txs: &[(&Transaction, TransactionType)]);
 }
 
 impl<T: BroadcasterInterface + ?Sized, B: Deref<Target = T>> BroadcasterInterface for B {
-	fn broadcast_transactions(&self, txs: &[&Transaction]) {
+	fn broadcast_transactions(&self, txs: &[(&Transaction, TransactionType)]) {
 		self.deref().broadcast_transactions(txs)
 	}
 }

lightning/src/chain/channelmonitor.rs

@@ -1879,8 +1879,9 @@ impl<Signer: EcdsaChannelSigner> ChannelMonitor<Signer> {
 			initial_holder_commitment_tx.trust().commitment_number();
 
 		let onchain_tx_handler = OnchainTxHandler::new(
-			channel_parameters.channel_value_satoshis, channel_keys_id, destination_script.into(),
-			keys, channel_parameters.clone(), initial_holder_commitment_tx.clone(), secp_ctx
+			channel_id, channel_parameters.channel_value_satoshis, channel_keys_id,
+			destination_script.into(), keys, channel_parameters.clone(),
+			initial_holder_commitment_tx.clone(), secp_ctx,
 		);
 
 		let funding_outpoint = channel_parameters.funding_outpoint
@@ -6491,7 +6492,7 @@ impl<'a, 'b, ES: EntropySource, SP: SignerProvider> ReadableArgs<(&'a ES, &'b SP
 				return Err(DecodeError::InvalidValue);
 			}
 		}
-		let onchain_tx_handler: OnchainTxHandler<SP::EcdsaSigner> = ReadableArgs::read(
+		let mut onchain_tx_handler: OnchainTxHandler<SP::EcdsaSigner> = ReadableArgs::read(
 			reader, (entropy_source, signer_provider, channel_value_satoshis, channel_keys_id)
 		)?;
 
@@ -6587,6 +6588,7 @@ impl<'a, 'b, ES: EntropySource, SP: SignerProvider> ReadableArgs<(&'a ES, &'b SP
 		}
 
 		let channel_id = channel_id.unwrap_or(ChannelId::v1_from_funding_outpoint(outpoint));
+		onchain_tx_handler.set_channel_id(channel_id);
 
 		let (current_holder_commitment_tx, current_holder_htlc_data) = {
 			let holder_commitment_tx = onchain_tx_handler.current_holder_commitment_tx();

lightning/src/chain/mod.rs

@@ -20,7 +20,6 @@ use bitcoin::secp256k1::PublicKey;
 
 use crate::chain::channelmonitor::{ChannelMonitor, ChannelMonitorUpdate, MonitorEvent};
 use crate::chain::transaction::{OutPoint, TransactionData};
-use crate::impl_writeable_tlv_based;
 use crate::ln::types::ChannelId;
 use crate::sign::ecdsa::EcdsaChannelSigner;
 use crate::sign::HTLCDescriptor;

lightning/src/chain/onchaintx.rs

@@ -23,7 +23,9 @@ use bitcoin::transaction::OutPoint as BitcoinOutPoint;
 use bitcoin::transaction::Transaction;
 
 use crate::chain::chaininterface::ConfirmationTarget;
-use crate::chain::chaininterface::{BroadcasterInterface, FeeEstimator, LowerBoundedFeeEstimator};
+use crate::chain::chaininterface::{
+	BroadcasterInterface, FeeEstimator, LowerBoundedFeeEstimator, TransactionType,
+};
 use crate::chain::channelmonitor::ANTI_REORG_DELAY;
 use crate::chain::package::{PackageSolvingData, PackageTemplate};
 use crate::chain::transaction::MaybeSignedTransaction;
@@ -33,6 +35,7 @@ use crate::ln::chan_utils::{
 	HTLCOutputInCommitment, HolderCommitmentTransaction,
 };
 use crate::ln::msgs::DecodeError;
+use crate::ln::types::ChannelId;
 use crate::sign::{ecdsa::EcdsaChannelSigner, EntropySource, HTLCDescriptor, SignerProvider};
 use crate::util::logger::Logger;
 use crate::util::ser::{
@@ -220,6 +223,7 @@ pub(crate) enum FeerateStrategy {
 /// do RBF bumping if possible.
 #[derive(Clone)]
 pub struct OnchainTxHandler<ChannelSigner: EcdsaChannelSigner> {
+	channel_id: ChannelId,
 	channel_value_satoshis: u64,   // Deprecated as of 0.2.
 	channel_keys_id: [u8; 32],     // Deprecated as of 0.2.
 	destination_script: ScriptBuf, // Deprecated as of 0.2.
@@ -282,7 +286,8 @@ impl<ChannelSigner: EcdsaChannelSigner> PartialEq for OnchainTxHandler<ChannelSi
 	#[rustfmt::skip]
 	fn eq(&self, other: &Self) -> bool {
 		// `signer`, `secp_ctx`, and `pending_claim_events` are excluded on purpose.
-		self.channel_value_satoshis == other.channel_value_satoshis &&
+		self.channel_id == other.channel_id &&
+			self.channel_value_satoshis == other.channel_value_satoshis &&
 			self.channel_keys_id == other.channel_keys_id &&
 			self.destination_script == other.destination_script &&
 			self.holder_commitment == other.holder_commitment &&
@@ -345,6 +350,14 @@ impl<ChannelSigner: EcdsaChannelSigner> OnchainTxHandler<ChannelSigner> {
 		write_tlv_fields!(writer, {});
 		Ok(())
 	}
+
+	// `ChannelMonitor`s already track the `channel_id`, however, due to the derserialization order
+	// there we can't make use of `ReadableArgs` to hand it into `OnchainTxHandler`'s
+	// deserialization logic directly. Instead we opt to initialize it with 0s and override it
+	// after reading the respective field via this method.
+	pub(crate) fn set_channel_id(&mut self, channel_id: ChannelId) {
+		self.channel_id = channel_id;
+	}
 }
 
 impl<'a, 'b, ES: EntropySource, SP: SignerProvider> ReadableArgs<(&'a ES, &'b SP, u64, [u8; 32])>
@@ -366,7 +379,7 @@ impl<'a, 'b, ES: EntropySource, SP: SignerProvider> ReadableArgs<(&'a ES, &'b SP
 		let prev_holder_commitment = Readable::read(reader)?;
 		let _prev_holder_htlc_sigs: Option<Vec<Option<(usize, Signature)>>> = Readable::read(reader)?;
 
-		let channel_parameters = ReadableArgs::<Option<u64>>::read(reader, Some(channel_value_satoshis))?;
+		let channel_parameters: ChannelTransactionParameters = ReadableArgs::<Option<u64>>::read(reader, Some(channel_value_satoshis))?;
 
 		// Read the serialized signer bytes, but don't deserialize them, as we'll obtain our signer
 		// by re-deriving the private key material.
@@ -420,10 +433,17 @@ impl<'a, 'b, ES: EntropySource, SP: SignerProvider> ReadableArgs<(&'a ES, &'b SP
 
 		read_tlv_fields!(reader, {});
 
+		// `ChannelMonitor`s already track the `channel_id`, however, due to the derserialization
+		// order there we can't make use of `ReadableArgs` to hand it in directly. Instead we opt
+		// to initialize it with 0s and override it after reading the respective field via
+		// `OnchainTxHandler::set_channel_id`.
+		let channel_id = ChannelId([0u8; 32]);
+
 		let mut secp_ctx = Secp256k1::new();
 		secp_ctx.seeded_randomize(&entropy_source.get_secure_random_bytes());
 
 		Ok(OnchainTxHandler {
+			channel_id,
 			channel_value_satoshis,
 			channel_keys_id,
 			destination_script,
@@ -443,11 +463,13 @@ impl<'a, 'b, ES: EntropySource, SP: SignerProvider> ReadableArgs<(&'a ES, &'b SP
 
 impl<ChannelSigner: EcdsaChannelSigner> OnchainTxHandler<ChannelSigner> {
 	pub(crate) fn new(
-		channel_value_satoshis: u64, channel_keys_id: [u8; 32], destination_script: ScriptBuf,
-		signer: ChannelSigner, channel_parameters: ChannelTransactionParameters,
+		channel_id: ChannelId, channel_value_satoshis: u64, channel_keys_id: [u8; 32],
+		destination_script: ScriptBuf, signer: ChannelSigner,
+		channel_parameters: ChannelTransactionParameters,
 		holder_commitment: HolderCommitmentTransaction, secp_ctx: Secp256k1<secp256k1::All>,
 	) -> Self {
 		OnchainTxHandler {
+			channel_id,
 			channel_value_satoshis,
 			channel_keys_id,
 			destination_script,
@@ -511,7 +533,7 @@ impl<ChannelSigner: EcdsaChannelSigner> OnchainTxHandler<ChannelSigner> {
 							if tx.is_fully_signed() {
 								let log_start = if feerate_was_bumped { "Broadcasting RBF-bumped" } else { "Rebroadcasting" };
 								log_info!(logger, "{} onchain {}", log_start, log_tx!(tx.0));
-								broadcaster.broadcast_transactions(&[&tx.0]);
+								broadcaster.broadcast_transactions(&[(&tx.0, TransactionType::Claim { channel_id: self.channel_id })]);
 							} else {
 								log_info!(logger, "Waiting for signature of unsigned onchain transaction {}", tx.0.compute_txid());
 							}
@@ -853,7 +875,7 @@ impl<ChannelSigner: EcdsaChannelSigner> OnchainTxHandler<ChannelSigner> {
 					OnchainClaim::Tx(tx) => {
 						if tx.is_fully_signed() {
 							log_info!(logger, "Broadcasting onchain {}", log_tx!(tx.0));
-							broadcaster.broadcast_transactions(&[&tx.0]);
+							broadcaster.broadcast_transactions(&[(&tx.0, TransactionType::Claim { channel_id: self.channel_id })]);
 						} else {
 							log_info!(logger, "Waiting for signature of unsigned onchain transaction {}", tx.0.compute_txid());
 						}
@@ -1071,7 +1093,7 @@ impl<ChannelSigner: EcdsaChannelSigner> OnchainTxHandler<ChannelSigner> {
 					OnchainClaim::Tx(bump_tx) => {
 						if bump_tx.is_fully_signed() {
 							log_info!(logger, "Broadcasting RBF-bumped onchain {}", log_tx!(bump_tx.0));
-							broadcaster.broadcast_transactions(&[&bump_tx.0]);
+							broadcaster.broadcast_transactions(&[(&bump_tx.0, TransactionType::Claim { channel_id: self.channel_id })]);
 						} else {
 							log_info!(logger, "Waiting for signature of RBF-bumped unsigned onchain transaction {}",
 								bump_tx.0.compute_txid());
@@ -1168,7 +1190,7 @@ impl<ChannelSigner: EcdsaChannelSigner> OnchainTxHandler<ChannelSigner> {
 					OnchainClaim::Tx(bump_tx) => {
 						if bump_tx.is_fully_signed() {
 							log_info!(logger, "Broadcasting onchain {}", log_tx!(bump_tx.0));
-							broadcaster.broadcast_transactions(&[&bump_tx.0]);
+							broadcaster.broadcast_transactions(&[(&bump_tx.0, TransactionType::Claim { channel_id: self.channel_id })]);
 						} else {
 							log_info!(logger, "Waiting for signature of unsigned onchain transaction {}", bump_tx.0.compute_txid());
 						}
@@ -1262,6 +1284,7 @@ mod tests {
 	};
 	use crate::ln::channel_keys::{DelayedPaymentBasepoint, HtlcBasepoint, RevocationBasepoint};
 	use crate::ln::functional_test_utils::create_dummy_block;
+	use crate::ln::types::ChannelId;
 	use crate::sign::{ChannelDerivationParameters, ChannelSigner, HTLCDescriptor, InMemorySigner};
 	use crate::types::payment::{PaymentHash, PaymentPreimage};
 	use crate::util::test_utils::{TestBroadcaster, TestFeeEstimator, TestLogger};
@@ -1346,6 +1369,7 @@ mod tests {
 		let holder_commit = HolderCommitmentTransaction::dummy(1000000, funding_outpoint, nondust_htlcs);
 		let destination_script = ScriptBuf::new();
 		let mut tx_handler = OnchainTxHandler::new(
+			ChannelId::from_bytes([0; 32]),
 			1000000,
 			[0; 32],
 			destination_script.clone(),