Add FundingSigned event

*document manual*

*document_safety*

Author: jbesraa

lightning/src/events/mod.rs

@@ -497,6 +497,29 @@ impl_writeable_tlv_based_enum!(PaymentFailureReason,
 /// written as it makes no sense to respond to it after reconnecting to peers).
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub enum Event {
+	/// Used to indicate that the counterparty node has sent `FundingSigned` msg but we are yet to
+	/// broadcast the funding transaction.
+	///
+	/// After you receive this event, you should broadcast the funding transaction and then call
+	//// [`ChannelManager::funding_transaction_broadcasted`]. <-- not implemtened yet
+	/// // should we have some timeout for this?
+	//// [`ChannelManager::funding_transaction_broadcasted`]: crate::ln::channelmanager::ChannelManager::funding_transaction_broadcasted
+	FundingSigned {
+		/// The `channel_id` indicating which channel has completed the `FundingSigned` 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.  This may be zero for objects
+		/// serialized with LDK versions prior to 0.0.113.
+		///
+		/// [`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 funding transaction which was signed by the counterparty.
+		funding_tx: Transaction,
+	},
 	/// Used to indicate that the client should generate a funding transaction with the given
 	/// parameters and then call [`ChannelManager::funding_transaction_generated`].
 	/// Generated in [`ChannelManager`] message handling.
@@ -1446,7 +1469,15 @@ impl Writeable for Event {
 				write_tlv_fields!(writer, {
 					(0, peer_node_id, required),
 				});
-			}
+			},
+			&Event::FundingSigned { ref channel_id, ref user_channel_id, ref funding_tx } => {
+				41u8.write(writer)?;
+				write_tlv_fields!(writer, {
+					(0, channel_id, required),
+					(2, user_channel_id, required),
+					(4, funding_tx, 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
 			// data via `write_tlv_fields`.
@@ -1883,6 +1914,21 @@ impl MaybeReadable for Event {
 				};
 				f()
 			},
+			41u8 => {
+					let mut channel_id = ChannelId::new_zero();
+					let mut user_channel_id: u128 = 0;
+					let mut funding_tx = Transaction { version: 2, lock_time: LockTime::ZERO, input: Vec::new(), output: Vec::new() };
+					read_tlv_fields!(reader, {
+						(0, channel_id, required),
+						(2, user_channel_id, required),
+						(4, funding_tx, required),
+					});
+					Ok(Some(Event::FundingSigned {
+						channel_id,
+						user_channel_id,
+						funding_tx,
+					}))
+			},
 			// 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

@@ -1529,6 +1529,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 `FundingSigned` event.
+	funding_signed_event_emitted: bool,
 
 	// We track whether we already emitted a `ChannelReady` event.
 	channel_ready_event_emitted: bool,
@@ -1546,6 +1549,16 @@ pub(super) struct ChannelContext<SP: Deref> where SP::Target: SignerProvider {
 	/// If we can't release a [`ChannelMonitorUpdate`] until some external action completes, we
 	/// store it here and only release it to the `ChannelManager` once it asks for it.
 	blocked_monitor_updates: Vec<PendingChannelMonitorUpdate>,
+
+	/// Upon receving a `FundingSigned` message, if the channel is
+	/// outbound and we are ready to broadcast the funding
+	/// transaction, LDK will broadcast it and set the channel state
+	/// to `ChannelPending`. 
+	///
+	/// Using this flag will allow you to halt the broadcast of the
+	/// funding transaction and the channel state will be set to
+	/// `FundingSigned`.
+	manually_broadcast_outbound_channels: Option<()>,
 }
 
 impl<SP: Deref> ChannelContext<SP> where SP::Target: SignerProvider  {
@@ -1866,6 +1879,7 @@ impl<SP: Deref> ChannelContext<SP> where SP::Target: SignerProvider  {
 			outbound_scid_alias: 0,
 
 			channel_pending_event_emitted: false,
+			funding_signed_event_emitted: false,
 			channel_ready_event_emitted: false,
 
 			#[cfg(any(test, fuzzing))]
@@ -1877,6 +1891,8 @@ impl<SP: Deref> ChannelContext<SP> where SP::Target: SignerProvider  {
 			local_initiated_shutdown: None,
 
 			blocked_monitor_updates: Vec::new(),
+
+			manually_broadcast_outbound_channels: None,
 		};
 
 		Ok(channel_context)
@@ -2087,6 +2103,7 @@ impl<SP: Deref> ChannelContext<SP> where SP::Target: SignerProvider  {
 			outbound_scid_alias,
 
 			channel_pending_event_emitted: false,
+			funding_signed_event_emitted: false,
 			channel_ready_event_emitted: false,
 
 			#[cfg(any(test, fuzzing))]
@@ -2097,6 +2114,7 @@ impl<SP: Deref> ChannelContext<SP> where SP::Target: SignerProvider  {
 
 			blocked_monitor_updates: Vec::new(),
 			local_initiated_shutdown: None,
+			manually_broadcast_outbound_channels: None,
 		})
 	}
 
@@ -2117,6 +2135,10 @@ impl<SP: Deref> ChannelContext<SP> where SP::Target: SignerProvider  {
 		self.channel_transaction_parameters.is_outbound_from_holder
 	}
 
+	pub fn get_funding_transaction(&self) -> Option<&Transaction> {
+		self.funding_transaction.as_ref()
+	}
+
 	/// Gets the fee we'd want to charge for adding an HTLC output to this Channel
 	/// Allowed in any state (including after shutdown)
 	pub fn get_outbound_forwarding_fee_base_msat(&self) -> u32 {
@@ -2338,6 +2360,10 @@ impl<SP: Deref> ChannelContext<SP> where SP::Target: SignerProvider  {
 		self.config.options.forwarding_fee_proportional_millionths
 	}
 
+	pub fn get_manually_broadcast_outbound_channels(&self) -> Option<()> {
+		self.manually_broadcast_outbound_channels
+	}
+
 	pub fn get_cltv_expiry_delta(&self) -> u16 {
 		cmp::max(self.config.options.cltv_expiry_delta, MIN_CLTV_EXPIRY_DELTA)
 	}
@@ -2364,13 +2390,25 @@ impl<SP: Deref> ChannelContext<SP> where SP::Target: SignerProvider  {
 
 	// Checks whether we should emit a `ChannelPending` event.
 	pub(crate) fn should_emit_channel_pending_event(&mut self) -> bool {
-		self.is_funding_broadcast() && !self.channel_pending_event_emitted
+		self.is_funding_broadcast() && !self.channel_pending_event_emitted && self.manually_broadcast_outbound_channels.is_none()
+	}
+
+	// Checks whether we should emit a `FundingSigned` event.
+	pub(crate) fn should_emit_funding_signed_event(&self) -> bool {
+		self.get_funding_transaction().is_some()
+			&& self.manually_broadcast_outbound_channels.is_some() 
+			&& !self.funding_signed_event_emitted 
 	}
 
 	// Returns whether we already emitted a `ChannelPending` event.
 	pub(crate) fn channel_pending_event_emitted(&self) -> bool {
 		self.channel_pending_event_emitted
 	}
+	
+	// Returns whether we already emitted a `FundingSigned` event.
+	pub(crate) fn funding_signed_event_emitted(&self) -> bool {
+		self.funding_signed_event_emitted
+	}
 
 	// Remembers that we already emitted a `ChannelPending` event.
 	pub(crate) fn set_channel_pending_event_emitted(&mut self) {
@@ -2387,6 +2425,11 @@ impl<SP: Deref> ChannelContext<SP> where SP::Target: SignerProvider  {
 		self.channel_ready_event_emitted = true;
 	}
 
+	// Remembers that we already emitted a `FundingSigned` event.
+	pub(crate) fn set_funding_signed_event_emitted(&mut self) {
+		self.funding_signed_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.
@@ -2423,11 +2466,17 @@ impl<SP: Deref> ChannelContext<SP> where SP::Target: SignerProvider  {
 		did_channel_update
 	}
 
+	///  Fix It
+	pub fn update_manual_channel(&mut self) {
+		self.manually_broadcast_outbound_channels = Some(());
+	}
+
 	/// Returns true if funding_signed was sent/received and the
 	/// funding transaction has been broadcast if necessary.
 	pub fn is_funding_broadcast(&self) -> bool {
-		!self.channel_state.is_pre_funded_state() &&
-			!matches!(self.channel_state, ChannelState::AwaitingChannelReady(flags) if flags.is_set(AwaitingChannelReadyFlags::WAITING_FOR_BATCH))
+			!self.channel_state.is_pre_funded_state() 
+			&& !matches!(self.channel_state, ChannelState::AwaitingChannelReady(flags) if
+				flags.is_set(AwaitingChannelReadyFlags::WAITING_FOR_BATCH))
 	}
 
 	/// Transaction nomenclature is somewhat confusing here as there are many different cases - a
@@ -4131,7 +4180,7 @@ impl<SP: Deref> Channel<SP> where
 					// If we reconnected before sending our `channel_ready` they may still resend theirs.
 					check_reconnection = true;
 				} else if flags.clone().clear(AwaitingChannelReadyFlags::WAITING_FOR_BATCH).is_empty() {
-					self.context.channel_state.set_their_channel_ready();
+						self.context.channel_state.set_their_channel_ready();
 				} else if flags == AwaitingChannelReadyFlags::OUR_CHANNEL_READY {
 					self.context.channel_state = ChannelState::ChannelReady(self.context.channel_state.with_funded_state_flags_mask().into());
 					self.context.update_time_counter += 1;
@@ -5222,10 +5271,13 @@ impl<SP: Deref> Channel<SP> where
 				(matches!(self.context.channel_state, ChannelState::AwaitingChannelReady(flags) if !flags.is_set(AwaitingChannelReadyFlags::WAITING_FOR_BATCH)) ||
 				matches!(self.context.channel_state, ChannelState::ChannelReady(_)))
 			{
-				self.context.funding_transaction.take()
+				// this clone is added so the value can still be accessed after the take
+				// (which is necessary for the FundingSigned event)
+				self.context.funding_transaction.clone().take()
 			} else { None };
 		// That said, if the funding transaction is already confirmed (ie we're active with a
 		// minimum_depth over 0) don't bother re-broadcasting the confirmed funding tx.
+
 		if matches!(self.context.channel_state, ChannelState::ChannelReady(_)) && self.context.minimum_depth != Some(0) {
 			funding_broadcastable = None;
 		}
@@ -8766,6 +8818,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_signed_event_emitted = Some(self.context.funding_signed_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,
@@ -8817,6 +8870,8 @@ impl<SP: Deref> Writeable for Channel<SP> where SP::Target: SignerProvider {
 			(43, malformed_htlcs, optional_vec), // Added in 0.0.119
 			// 45 and 47 are reserved for async signing
 			(49, self.context.local_initiated_shutdown, option), // Added in 0.0.122
+			(51, self.context.manually_broadcast_outbound_channels, option),
+			(53, funding_signed_event_emitted, option)
 		});
 
 		Ok(())
@@ -9105,6 +9160,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_signed_event_emitted = None;
 
 		let mut user_id_high_opt: Option<u64> = None;
 		let mut channel_keys_id: Option<[u8; 32]> = None;
@@ -9117,6 +9173,7 @@ impl<'a, 'b, 'c, ES: Deref, SP: Deref> ReadableArgs<(&'a ES, &'b SP, u32, &'c Ch
 		let mut holding_cell_skimmed_fees_opt: Option<Vec<Option<u64>>> = None;
 
 		let mut is_batch_funding: Option<()> = None;
+		let mut manually_broadcast_outbound_channels: Option<()> = None;
 
 		let mut local_initiated_shutdown: Option<()> = None;
 
@@ -9158,6 +9215,8 @@ impl<'a, 'b, 'c, ES: Deref, SP: Deref> ReadableArgs<(&'a ES, &'b SP, u32, &'c Ch
 			(43, malformed_htlcs, optional_vec), // Added in 0.0.119
 			// 45 and 47 are reserved for async signing
 			(49, local_initiated_shutdown, option),
+			(51, manually_broadcast_outbound_channels, option),
+			(53, funding_signed_event_emitted, option),
 		});
 
 		let (channel_keys_id, holder_signer) = if let Some(channel_keys_id) = channel_keys_id {
@@ -9381,6 +9440,7 @@ impl<'a, 'b, 'c, ES: Deref, SP: Deref> ReadableArgs<(&'a ES, &'b SP, u32, &'c Ch
 				outbound_scid_alias: outbound_scid_alias.unwrap_or(0),
 
 				channel_pending_event_emitted: channel_pending_event_emitted.unwrap_or(true),
+				funding_signed_event_emitted: funding_signed_event_emitted.unwrap_or(true),
 				channel_ready_event_emitted: channel_ready_event_emitted.unwrap_or(true),
 
 				#[cfg(any(test, fuzzing))]
@@ -9392,6 +9452,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(),
+				manually_broadcast_outbound_channels,
 			},
 			#[cfg(any(dual_funding, splicing))]
 			dual_funding_channel_context: None,