Add ChannelPending event emitted upon funding_signed

Currently, users don't have good way of being notified when channel open
negotiations have succeeded and new channels are pending confirmation on
chain. To this end, we add a new `ChannelPending` event that is emitted
when send or receive a `funding_signed` message, i.e., at the last
moment before waiting for the confirmation period.

Author: tnull

lightning/src/ln/channelmanager.rs

@@ -4564,7 +4564,10 @@ where
 					msg: funding_msg,
 				});
 
-				let monitor_res = self.chain_monitor.watch_channel(monitor.get_funding_txo().0, monitor);
+				let funding_txo = monitor.get_funding_txo().0;
+				let user_channel_id = chan.get_user_id();
+
+				let monitor_res = self.chain_monitor.watch_channel(funding_txo, monitor);
 
 				let chan = e.insert(chan);
 				let mut res = handle_new_monitor_update!(self, monitor_res, 0, peer_state_lock, peer_state,
@@ -4579,6 +4582,14 @@ where
 				// with the funding_signed so the channel can never go on chain).
 				if let Err(MsgHandleErrInternal { shutdown_finish: Some((res, _)), .. }) = &mut res {
 					res.0 = None;
+				} else {
+					let mut pending_events = self.pending_events.lock().unwrap();
+					pending_events.push(events::Event::ChannelPending {
+						channel_id: new_channel_id,
+						counterparty_node_id: *counterparty_node_id,
+						user_channel_id,
+						funding_txo: funding_txo.into_bitcoin_outpoint(),
+					});
 				}
 				res
 			}
@@ -4600,7 +4611,9 @@ where
 			hash_map::Entry::Occupied(mut chan) => {
 				let monitor = try_chan_entry!(self,
 					chan.get_mut().funding_signed(&msg, best_block, &self.signer_provider, &self.logger), chan);
-				let update_res = self.chain_monitor.watch_channel(chan.get().get_funding_txo().unwrap(), monitor);
+				let funding_txo = chan.get().get_funding_txo().unwrap();
+				let user_channel_id = chan.get().get_user_id();
+				let update_res = self.chain_monitor.watch_channel(funding_txo, monitor);
 				let mut res = handle_new_monitor_update!(self, update_res, 0, peer_state_lock, peer_state, per_peer_state, chan);
 				if let Err(MsgHandleErrInternal { ref mut shutdown_finish, .. }) = res {
 					// We weren't able to watch the channel to begin with, so no updates should be made on
@@ -4609,6 +4622,14 @@ where
 					if let Some((ref mut shutdown_finish, _)) = shutdown_finish {
 						shutdown_finish.0.take();
 					}
+				} else {
+					let mut pending_events = self.pending_events.lock().unwrap();
+					pending_events.push(events::Event::ChannelPending {
+						channel_id: msg.channel_id,
+						counterparty_node_id: *counterparty_node_id,
+						user_channel_id,
+						funding_txo: funding_txo.into_bitcoin_outpoint(),
+					});
 				}
 				res
 			},

lightning/src/util/events.rs

@@ -27,9 +27,9 @@ use crate::util::errors::APIError;
 use crate::util::ser::{BigSize, FixedLengthReader, Writeable, Writer, MaybeReadable, Readable, RequiredWrapper, UpgradableRequired, WithoutLength};
 use crate::routing::router::{RouteHop, RouteParameters};
 
-use bitcoin::{PackedLockTime, Transaction};
+use bitcoin::{PackedLockTime, Transaction, OutPoint};
 #[cfg(anchors)]
-use bitcoin::{OutPoint, Txid, TxIn, TxOut, Witness};
+use bitcoin::{Txid, TxIn, TxOut, Witness};
 use bitcoin::blockdata::script::Script;
 use bitcoin::hashes::Hash;
 use bitcoin::hashes::sha256::Hash as Sha256;
@@ -821,12 +821,33 @@ pub enum Event {
 		/// transaction.
 		claim_from_onchain_tx: bool,
 	},
+	/// Used to indicate that a channel with the given `channel_id` is being opened and pending
+	/// confirmation on-chain.
+	///
+	/// This event is emitted when the funding transaction has been signed.
+	ChannelPending {
+		/// The `channel_id` of the channel that is pending confirmation.
+		channel_id: [u8; 32],
+		/// 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 `node_id` of the channel counterparty.
+		counterparty_node_id: PublicKey,
+		/// The outpoint of the channel's funding transaction.
+		funding_txo: OutPoint,
+	},
 	/// Used to indicate that a channel with the given `channel_id` is ready to
 	/// be used. This event is emitted either when the funding transaction has been confirmed
 	/// on-chain, or, in case of a 0conf channel, when both parties have confirmed the channel
 	/// establishment.
 	ChannelReady {
-		/// The channel_id of the channel that is ready.
+		/// The `channel_id` of the channel that is ready.
 		channel_id: [u8; 32],
 		/// The `user_channel_id` value passed in to [`ChannelManager::create_channel`] for outbound
 		/// channels, or to [`ChannelManager::accept_inbound_channel`] for inbound channels if
@@ -837,15 +858,15 @@ pub enum Event {
 		/// [`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 node_id of the channel counterparty.
+		/// The `node_id` of the channel counterparty.
 		counterparty_node_id: PublicKey,
 		/// The features that this channel will operate with.
 		channel_type: ChannelTypeFeatures,
 	},
 	/// Used to indicate that a previously opened channel with the given `channel_id` is in the
 	/// process of closure.
 	ChannelClosed  {
-		/// The channel_id of the channel which has been closed. Note that on-chain transactions
+		/// The `channel_id` of the channel which has been closed. Note that on-chain transactions
 		/// resolving the channel are likely still awaiting confirmation.
 		channel_id: [u8; 32],
 		/// The `user_channel_id` value passed in to [`ChannelManager::create_channel`] for outbound
@@ -1140,6 +1161,15 @@ impl Writeable for Event {
 					(6, channel_type, required),
 				});
 			},
+			&Event::ChannelPending { ref channel_id, ref user_channel_id, ref counterparty_node_id, ref funding_txo } => {
+				31u8.write(writer)?;
+				write_tlv_fields!(writer, {
+					(0, channel_id, required),
+					(2, user_channel_id, required),
+					(4, counterparty_node_id, required),
+					(6, funding_txo, 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`.
@@ -1478,6 +1508,28 @@ impl MaybeReadable for Event {
 				};
 				f()
 			},
+			31u8 => {
+				let f = || {
+					let mut channel_id = [0; 32];
+					let mut user_channel_id: u128 = 0;
+					let mut counterparty_node_id = RequiredWrapper(None);
+					let mut funding_txo = RequiredWrapper(None);
+					read_tlv_fields!(reader, {
+						(0, channel_id, required),
+						(2, user_channel_id, required),
+						(4, counterparty_node_id, required),
+						(6, funding_txo, required),
+					});
+
+					Ok(Some(Event::ChannelReady {
+						channel_id,
+						user_channel_id,
+						counterparty_node_id: counterparty_node_id.0.unwrap(),
+						channel_type: funding_txo.0.unwrap()
+					}))
+				};
+				f()
+			},
 			// 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.