Add FundingSigned event

The `FundingSigned` event indicates that we have received
`funding_signed` message from our counterparty but we are yet to
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

@@ -532,6 +532,35 @@ 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 sent us `funding_signed` message but we are
+	/// yet to broadcast the funding transaction.
+	///
+	/// This event is only emitted if you called
+	/// [`ChannelManager::unsafe_manual_funding_transaction_generated`] instead of
+	/// [`ChannelManager::funding_transaction_generated`]. 
+	///
+	/// Upon receiving this event, it is your responsibility to broadcast the funding transaction.
+	///
+	/// [`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
+	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,
+	},
 	/// 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`].
 	///
@@ -969,9 +998,15 @@ pub enum Event {
 	/// Used to indicate that a channel with the given `channel_id` is being opened and pending
 	/// confirmation on-chain.
 	///
+	/// Note that this event wont be emitted for channels created using
+	/// [`ChannelManager::unsafe_manual_funding_transaction_generated`]:
+	///
 	/// This event is emitted when the funding transaction has been signed and is broadcast to the
 	/// network. For 0conf channels it will be immediately followed by the corresponding
 	/// [`Event::ChannelReady`] event.
+	///
+	/// [`ChannelManager::unsafe_manual_funding_transaction_generated`]:
+	/// crate::ln::channelmanager::ChannelManager::unsafe_manual_funding_transaction_generated
 	ChannelPending {
 		/// The `channel_id` of the channel that is pending confirmation.
 		channel_id: ChannelId,
@@ -1447,7 +1482,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`.
@@ -1884,6 +1927,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: Version::TWO, 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

@@ -1530,6 +1530,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,
@@ -1547,6 +1550,14 @@ 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>,
+
+	/// Using this flag will prevent the funding transaction from being broadcasted 
+	/// and will allow the user to manually broadcast it.
+	///
+	/// The funding transaction can be accessed through the [`Event::FundingSigned`] event.
+	///
+	/// [`Event::FundingSigned`]: crate::events::Event::FundingSigned
+	manually_broadcast_outbound_channels: Option<()>,
 }
 
 impl<SP: Deref> ChannelContext<SP> where SP::Target: SignerProvider  {
@@ -1867,6 +1878,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))]
@@ -1878,6 +1890,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)
@@ -2088,6 +2102,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))]
@@ -2098,6 +2113,7 @@ impl<SP: Deref> ChannelContext<SP> where SP::Target: SignerProvider  {
 
 			blocked_monitor_updates: Vec::new(),
 			local_initiated_shutdown: None,
+			manually_broadcast_outbound_channels: None,
 		})
 	}
 
@@ -2118,6 +2134,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 {
@@ -2339,6 +2359,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)
 	}
@@ -2365,13 +2389,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) {
@@ -2388,6 +2424,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.
@@ -2424,11 +2465,23 @@ 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 [`Events::FundingSigned`] event.
+	///
+	/// [`Event::FundingSigned`]: crate::events::Event::FundingSigned
+	pub fn mark_channel_as_manual_broadcast(&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
@@ -5219,10 +5272,11 @@ impl<SP: Deref> Channel<SP> where
 		// (re-)broadcast the funding transaction as we may have declined to broadcast it when we
 		// first received the funding_signed.
 		let mut funding_broadcastable =
-			if self.context.is_outbound() &&
-				(matches!(self.context.channel_state, ChannelState::AwaitingChannelReady(flags) if !flags.is_set(AwaitingChannelReadyFlags::WAITING_FOR_BATCH)) ||
-				matches!(self.context.channel_state, ChannelState::ChannelReady(_)))
-			{
+			if self.context.manually_broadcast_outbound_channels.is_none() 
+				&& self.context.is_outbound() 
+				&& (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()
 			} else { None };
 		// That said, if the funding transaction is already confirmed (ie we're active with a
@@ -8767,6 +8821,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,
@@ -8818,6 +8873,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(())
@@ -9106,6 +9163,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;
@@ -9118,6 +9176,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;
 
@@ -9159,6 +9218,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 {
@@ -9382,6 +9443,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))]
@@ -9393,6 +9455,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,