Add FundingTxBroadcastSafe event

The `FundingTxBroadcastSafe` event indicates that we have received
`funding_signed` message from our counterparty and that you should
broadcast the funding transaction.

This event is only emitted if upon generating the funding transaction
you call `ChannelManager::unsafe_manual_funding_transaction_generated`
that will emit this event instead of `ChannelPending` event.

`ChannelManager::unsafe_manual_funding_transaction_generated` wont check
if the funding transaction is signed, those its unsafe. It is manual
because you are responsibile on broadcasting the transaction once the
event is received.

Author: jbesraa

lightning/src/events/mod.rs

@@ -579,6 +579,37 @@ pub enum Event {
 		/// [`UserConfig::manually_accept_inbound_channels`]: crate::util::config::UserConfig::manually_accept_inbound_channels
 		user_channel_id: u128,
 	},
+	/// Used to indicate that the counterparty node has provided the signature(s) required to
+	/// recover our funds in case they go offline.
+	///
+	/// It is safe (and your responsibility) to broadcast the funding transaction upon receiving this
+	/// event.
+	///
+	/// This event is only emitted if you called
+	/// [`ChannelManager::unsafe_manual_funding_transaction_generated`] instead of
+	/// [`ChannelManager::funding_transaction_generated`].
+	///
+	/// [`ChannelManager::unsafe_manual_funding_transaction_generated`]: crate::ln::channelmanager::ChannelManager::unsafe_manual_funding_transaction_generated
+	/// [`ChannelManager::funding_transaction_generated`]: crate::ln::channelmanager::ChannelManager::funding_transaction_generated
+	FundingTxBroadcastSafe {
+		/// The `channel_id` indicating which channel has reached this stage.
+		channel_id: ChannelId,
+		/// The `user_channel_id` value passed in to [`ChannelManager::create_channel`] for outbound
+		/// channels, or to [`ChannelManager::accept_inbound_channel`] for inbound channels if
+		/// [`UserConfig::manually_accept_inbound_channels`] config flag is set to `true`. Otherwise
+		/// `user_channel_id` will be randomized for an inbound channel.
+		///
+		/// [`ChannelManager::create_channel`]: crate::ln::channelmanager::ChannelManager::create_channel
+		/// [`ChannelManager::accept_inbound_channel`]: crate::ln::channelmanager::ChannelManager::accept_inbound_channel
+		/// [`UserConfig::manually_accept_inbound_channels`]: crate::util::config::UserConfig::manually_accept_inbound_channels
+		user_channel_id: u128,
+		/// The outpoint of the channel's funding transaction.
+		funding_txo: OutPoint,
+		/// The `node_id` of the channel counterparty.
+		counterparty_node_id: PublicKey,
+		/// The `temporary_channel_id` this channel used to be known by during channel establishment.
+		former_temporary_channel_id: ChannelId,
+	},
 	/// Indicates that we've been offered a payment and it needs to be claimed via calling
 	/// [`ChannelManager::claim_funds`] with the preimage given in [`PaymentPurpose`].
 	///
@@ -1528,7 +1559,17 @@ impl Writeable for Event {
 					(0, payment_id, required),
 					(2, invoice, required),
 					(4, responder, option),
-				})
+				});
+			},
+			&Event::FundingTxBroadcastSafe { ref channel_id, ref user_channel_id, ref funding_txo, ref counterparty_node_id, ref former_temporary_channel_id} => {
+				43u8.write(writer)?;
+				write_tlv_fields!(writer, {
+					(0, channel_id, required),
+					(2, user_channel_id, required),
+					(4, funding_txo, required),
+					(6, counterparty_node_id, required),
+					(8, former_temporary_channel_id, required),
+				});
 			},
 			// Note that, going forward, all new events must only write data inside of
 			// `write_tlv_fields`. Versions 0.0.101+ will ignore odd-numbered events that write
@@ -1981,6 +2022,27 @@ impl MaybeReadable for Event {
 				};
 				f()
 			},
+			43u8 => {
+				let mut channel_id = RequiredWrapper(None);
+				let mut user_channel_id = RequiredWrapper(None);
+				let mut funding_txo = RequiredWrapper(None);
+				let mut counterparty_node_id = RequiredWrapper(None);
+				let mut former_temporary_channel_id = RequiredWrapper(None);
+				read_tlv_fields!(reader, {
+					(0, channel_id, required),
+					(2, user_channel_id, required),
+					(4, funding_txo, required),
+					(6, counterparty_node_id, required),
+					(8, former_temporary_channel_id, required)
+				});
+				Ok(Some(Event::FundingTxBroadcastSafe {
+					channel_id: channel_id.0.unwrap(),
+					user_channel_id: user_channel_id.0.unwrap(),
+					funding_txo: funding_txo.0.unwrap(),
+					counterparty_node_id: counterparty_node_id.0.unwrap(),
+					former_temporary_channel_id: former_temporary_channel_id.0.unwrap(),
+				}))
+			},
 			// Versions prior to 0.0.100 did not ignore odd types, instead returning InvalidValue.
 			// Version 0.0.100 failed to properly ignore odd types, possibly resulting in corrupt
 			// reads.

lightning/src/ln/channel.rs

@@ -1331,7 +1331,12 @@ pub(super) struct ChannelContext<SP: Deref> where SP::Target: SignerProvider {
 	counterparty_forwarding_info: Option<CounterpartyForwardingInfo>,
 
 	pub(crate) channel_transaction_parameters: ChannelTransactionParameters,
+	/// The transaction which funds this channel. Note that for manually-funded channels (i.e.,
+	/// is_manual_broadcast is true) this will be a dummy empty transaction.
 	funding_transaction: Option<Transaction>,
+	/// This flag indicates that it is the user's responsibility to validated and broadcast the
+	/// funding transaction.
+	is_manual_broadcast: bool,
 	is_batch_funding: Option<()>,
 
 	counterparty_cur_commitment_point: Option<PublicKey>,
@@ -1419,6 +1424,9 @@ pub(super) struct ChannelContext<SP: Deref> where SP::Target: SignerProvider {
 	// We track whether we already emitted a `ChannelPending` event.
 	channel_pending_event_emitted: bool,
 
+	// We track whether we already emitted a `FundingTxBroadcastSafe` event.
+	funding_tx_broadcast_safe_event_emitted: bool,
+
 	// We track whether we already emitted a `ChannelReady` event.
 	channel_ready_event_emitted: bool,
 
@@ -1758,6 +1766,7 @@ impl<SP: Deref> ChannelContext<SP> where SP::Target: SignerProvider  {
 			outbound_scid_alias: 0,
 
 			channel_pending_event_emitted: false,
+			funding_tx_broadcast_safe_event_emitted: false,
 			channel_ready_event_emitted: false,
 
 			#[cfg(any(test, fuzzing))]
@@ -1769,6 +1778,8 @@ impl<SP: Deref> ChannelContext<SP> where SP::Target: SignerProvider  {
 			local_initiated_shutdown: None,
 
 			blocked_monitor_updates: Vec::new(),
+
+			is_manual_broadcast: false,
 		};
 
 		Ok(channel_context)
@@ -1982,6 +1993,7 @@ impl<SP: Deref> ChannelContext<SP> where SP::Target: SignerProvider  {
 			outbound_scid_alias,
 
 			channel_pending_event_emitted: false,
+			funding_tx_broadcast_safe_event_emitted: false,
 			channel_ready_event_emitted: false,
 
 			#[cfg(any(test, fuzzing))]
@@ -1992,6 +2004,7 @@ impl<SP: Deref> ChannelContext<SP> where SP::Target: SignerProvider  {
 
 			blocked_monitor_updates: Vec::new(),
 			local_initiated_shutdown: None,
+			is_manual_broadcast: false,
 		})
 	}
 
@@ -2370,6 +2383,10 @@ impl<SP: Deref> ChannelContext<SP> where SP::Target: SignerProvider  {
 		self.config.options.forwarding_fee_proportional_millionths
 	}
 
+	pub fn is_manual_broadcast(&self) -> bool {
+		self.is_manual_broadcast
+	}
+
 	pub fn get_cltv_expiry_delta(&self) -> u16 {
 		cmp::max(self.config.options.cltv_expiry_delta, MIN_CLTV_EXPIRY_DELTA)
 	}
@@ -2404,6 +2421,11 @@ impl<SP: Deref> ChannelContext<SP> where SP::Target: SignerProvider  {
 		self.channel_pending_event_emitted
 	}
 
+	// Returns whether we already emitted a `FundingTxBroadcastSafe` event.
+	pub(crate) fn funding_tx_broadcast_safe_event_emitted(&self) -> bool {
+		self.funding_tx_broadcast_safe_event_emitted
+	}
+
 	// Remembers that we already emitted a `ChannelPending` event.
 	pub(crate) fn set_channel_pending_event_emitted(&mut self) {
 		self.channel_pending_event_emitted = true;
@@ -2419,6 +2441,11 @@ impl<SP: Deref> ChannelContext<SP> where SP::Target: SignerProvider  {
 		self.channel_ready_event_emitted = true;
 	}
 
+	// Remembers that we already emitted a `FundingTxBroadcastSafe` event.
+	pub(crate) fn set_funding_tx_broadcast_safe_event_emitted(&mut self) {
+		self.funding_tx_broadcast_safe_event_emitted = true;
+	}
+
 	/// Tracks the number of ticks elapsed since the previous [`ChannelConfig`] was updated. Once
 	/// [`EXPIRE_PREV_CONFIG_TICKS`] is reached, the previous config is considered expired and will
 	/// no longer be considered when forwarding HTLCs.
@@ -2455,6 +2482,17 @@ impl<SP: Deref> ChannelContext<SP> where SP::Target: SignerProvider  {
 		did_channel_update
 	}
 
+	/// Marking the channel as manual broadcast is used in order to prevent LDK from automatically
+	/// broadcasting the funding transaction.
+	///
+	/// This is useful if you wish to get hold of the funding transaction before it is broadcasted
+	/// via [`Event::FundingTxBroadcastSafe`] event.
+	///
+	/// [`Event::FundingTxBroadcastSafe`]: crate::events::Event::FundingTxBroadcastSafe
+	pub fn set_manual_broadcast(&mut self) {
+		self.is_manual_broadcast = true;
+	}
+
 	/// Returns true if funding_signed was sent/received and the
 	/// funding transaction has been broadcast if necessary.
 	pub fn is_funding_broadcast(&self) -> bool {
@@ -8705,6 +8743,7 @@ impl<SP: Deref> Writeable for Channel<SP> where SP::Target: SignerProvider {
 
 		let channel_pending_event_emitted = Some(self.context.channel_pending_event_emitted);
 		let channel_ready_event_emitted = Some(self.context.channel_ready_event_emitted);
+		let funding_tx_broadcast_safe_event_emitted = Some(self.context.funding_tx_broadcast_safe_event_emitted);
 
 		// `user_id` used to be a single u64 value. In order to remain backwards compatible with
 		// versions prior to 0.0.113, the u128 is serialized as two separate u64 values. Therefore,
@@ -8717,6 +8756,7 @@ impl<SP: Deref> Writeable for Channel<SP> where SP::Target: SignerProvider {
 		if !self.context.monitor_pending_update_adds.is_empty() {
 			monitor_pending_update_adds = Some(&self.context.monitor_pending_update_adds);
 		}
+		let is_manual_broadcast = Some(self.context.is_manual_broadcast);
 
 		// `current_point` will become optional when async signing is implemented.
 		let cur_holder_commitment_point = Some(self.context.holder_commitment_point.current_point());
@@ -8761,6 +8801,8 @@ impl<SP: Deref> Writeable for Channel<SP> where SP::Target: SignerProvider {
 			(45, cur_holder_commitment_point, option),
 			(47, next_holder_commitment_point, option),
 			(49, self.context.local_initiated_shutdown, option), // Added in 0.0.122
+			(51, is_manual_broadcast, option), // Added in 0.0.124
+			(53, funding_tx_broadcast_safe_event_emitted, option) // Added in 0.0.124
 		});
 
 		Ok(())
@@ -9049,6 +9091,7 @@ impl<'a, 'b, 'c, ES: Deref, SP: Deref> ReadableArgs<(&'a ES, &'b SP, u32, &'c Ch
 		let mut outbound_scid_alias = None;
 		let mut channel_pending_event_emitted = None;
 		let mut channel_ready_event_emitted = None;
+		let mut funding_tx_broadcast_safe_event_emitted = None;
 
 		let mut user_id_high_opt: Option<u64> = None;
 		let mut channel_keys_id: Option<[u8; 32]> = None;
@@ -9072,6 +9115,7 @@ impl<'a, 'b, 'c, ES: Deref, SP: Deref> ReadableArgs<(&'a ES, &'b SP, u32, &'c Ch
 
 		let mut cur_holder_commitment_point_opt: Option<PublicKey> = None;
 		let mut next_holder_commitment_point_opt: Option<PublicKey> = None;
+		let mut is_manual_broadcast = None;
 
 		read_tlv_fields!(reader, {
 			(0, announcement_sigs, option),
@@ -9106,6 +9150,8 @@ impl<'a, 'b, 'c, ES: Deref, SP: Deref> ReadableArgs<(&'a ES, &'b SP, u32, &'c Ch
 			(45, cur_holder_commitment_point_opt, option),
 			(47, next_holder_commitment_point_opt, option),
 			(49, local_initiated_shutdown, option),
+			(51, is_manual_broadcast, option),
+			(53, funding_tx_broadcast_safe_event_emitted, option),
 		});
 
 		let (channel_keys_id, holder_signer) = if let Some(channel_keys_id) = channel_keys_id {
@@ -9346,6 +9392,7 @@ impl<'a, 'b, 'c, ES: Deref, SP: Deref> ReadableArgs<(&'a ES, &'b SP, u32, &'c Ch
 				// Later in the ChannelManager deserialization phase we scan for channels and assign scid aliases if its missing
 				outbound_scid_alias: outbound_scid_alias.unwrap_or(0),
 
+				funding_tx_broadcast_safe_event_emitted: funding_tx_broadcast_safe_event_emitted.unwrap_or(false),
 				channel_pending_event_emitted: channel_pending_event_emitted.unwrap_or(true),
 				channel_ready_event_emitted: channel_ready_event_emitted.unwrap_or(true),
 
@@ -9358,6 +9405,7 @@ impl<'a, 'b, 'c, ES: Deref, SP: Deref> ReadableArgs<(&'a ES, &'b SP, u32, &'c Ch
 				local_initiated_shutdown,
 
 				blocked_monitor_updates: blocked_monitor_updates.unwrap(),
+				is_manual_broadcast: is_manual_broadcast.unwrap_or(false),
 			},
 			#[cfg(any(dual_funding, splicing))]
 			dual_funding_channel_context: None,