Add ChannelReady event

This adds a `ChannelReady` event that is emitted as soon as a new
channel becomes usable, i.e., after both sides have sent
`channel_ready`.

Author: tnull

fuzz/src/chanmon_consistency.rs

@@ -872,6 +872,7 @@ pub fn do_test<Out: Output>(data: &[u8], underlying_out: Out) {
 							// looking like probes.
 						},
 						events::Event::PaymentForwarded { .. } if $node == 1 => {},
+						events::Event::ChannelReady { .. } => {},
 						events::Event::PendingHTLCsForwardable { .. } => {
 							nodes[$node].process_pending_htlc_forwards();
 						},

lightning-background-processor/src/lib.rs

@@ -988,9 +988,12 @@ mod tests {
 
 		// Set up a background event handler for FundingGenerationReady events.
 		let (sender, receiver) = std::sync::mpsc::sync_channel(1);
-		let event_handler = move |event: &Event| {
-			sender.send(handle_funding_generation_ready!(event, channel_value)).unwrap();
+		let event_handler = move |event: &Event| match event {
+			Event::FundingGenerationReady{ .. } => sender.send(handle_funding_generation_ready!(event, channel_value)).unwrap(),
+			Event::ChannelReady { .. } => {},
+			_ => panic!("Unexpected event: {:?}", event),
 		};
+
 		let bg_processor = BackgroundProcessor::start(persister, event_handler, nodes[0].chain_monitor.clone(), nodes[0].node.clone(), nodes[0].no_gossip_sync(), nodes[0].peer_manager.clone(), nodes[0].logger.clone(), Some(nodes[0].scorer.clone()));
 
 		// Open a channel and check that the FundingGenerationReady event was handled.
@@ -1014,20 +1017,25 @@ mod tests {
 
 		// Set up a background event handler for SpendableOutputs events.
 		let (sender, receiver) = std::sync::mpsc::sync_channel(1);
-		let event_handler = move |event: &Event| sender.send(event.clone()).unwrap();
+		let event_handler = move |event: &Event| match event {
+			Event::SpendableOutputs { .. } => sender.send(event.clone()).unwrap(),
+			Event::ChannelReady { .. } => {},
+			Event::ChannelClosed { .. } => {},
+			_ => panic!("Unexpected event: {:?}", event),
+		};
 		let persister = Arc::new(Persister::new(data_dir));
 		let bg_processor = BackgroundProcessor::start(persister, event_handler, nodes[0].chain_monitor.clone(), nodes[0].node.clone(), nodes[0].no_gossip_sync(), nodes[0].peer_manager.clone(), nodes[0].logger.clone(), Some(nodes[0].scorer.clone()));
 
 		// Force close the channel and check that the SpendableOutputs event was handled.
 		nodes[0].node.force_close_broadcasting_latest_txn(&nodes[0].node.list_channels()[0].channel_id, &nodes[1].node.get_our_node_id()).unwrap();
 		let commitment_tx = nodes[0].tx_broadcaster.txn_broadcasted.lock().unwrap().pop().unwrap();
 		confirm_transaction_depth(&mut nodes[0], &commitment_tx, BREAKDOWN_TIMEOUT as u32);
+
 		let event = receiver
 			.recv_timeout(Duration::from_secs(EVENT_DEADLINE))
-			.expect("SpendableOutputs not handled within deadline");
+			.expect("Events not handled within deadline");
 		match event {
 			Event::SpendableOutputs { .. } => {},
-			Event::ChannelClosed { .. } => {},
 			_ => panic!("Unexpected event: {:?}", event),
 		}
 

lightning-invoice/src/utils.rs

@@ -869,6 +869,9 @@ mod test {
 		get_event_msg!(nodes[2], MessageSendEvent::SendChannelUpdate, nodes[0].node.get_our_node_id());
 		nodes[0].node.handle_channel_ready(&nodes[2].node.get_our_node_id(), &as_channel_ready);
 		get_event_msg!(nodes[0], MessageSendEvent::SendChannelUpdate, nodes[2].node.get_our_node_id());
+		
+		expect_channel_ready_event!(nodes[0], nodes[2].node.get_our_node_id());
+		expect_channel_ready_event!(nodes[2], nodes[0].node.get_our_node_id());
 
 		// As `msgs::ChannelUpdate` was never handled for the participating node(s) of the second
 		// channel, the channel will never be assigned any `counterparty.forwarding_info`.
@@ -1257,6 +1260,8 @@ mod test {
 		get_event_msg!(nodes[1], MessageSendEvent::SendChannelUpdate, nodes[3].node.get_our_node_id());
 		nodes[3].node.handle_channel_ready(&nodes[1].node.get_our_node_id(), &as_channel_ready);
 		get_event_msg!(nodes[3], MessageSendEvent::SendChannelUpdate, nodes[1].node.get_our_node_id());
+		expect_channel_ready_event!(nodes[1], nodes[3].node.get_our_node_id());
+		expect_channel_ready_event!(nodes[3], nodes[1].node.get_our_node_id());
 
 		// As `msgs::ChannelUpdate` was never handled for the participating node(s) of the third
 		// channel, the channel will never be assigned any `counterparty.forwarding_info`.

lightning/src/ln/chanmon_update_fail_tests.rs

@@ -1915,6 +1915,8 @@ fn do_during_funding_monitor_fail(confirm_a_first: bool, restore_b_before_conf:
 		node.gossip_sync.handle_channel_update(&as_update).unwrap();
 		node.gossip_sync.handle_channel_update(&bs_update).unwrap();
 	}
+	expect_channel_ready_event!(nodes[1], nodes[0].node.get_our_node_id());
+	expect_channel_ready_event!(nodes[0], nodes[1].node.get_our_node_id());
 
 	send_payment(&nodes[0], &[&nodes[1]], 8000000);
 	close_channel(&nodes[0], &nodes[1], &channel_id, funding_tx, true);

lightning/src/ln/channel.rs

@@ -736,6 +736,9 @@ pub(super) struct Channel<Signer: Sign> {
 	// don't currently support node id aliases and eventually privacy should be provided with
 	// blinded paths instead of simple scid+node_id aliases.
 	outbound_scid_alias: u64,
+
+	// We track whether we already emitted a `ChannelReady` event.
+	channel_ready_event_emitted: bool,
 }
 
 #[cfg(any(test, fuzzing))]
@@ -1063,6 +1066,8 @@ impl<Signer: Sign> Channel<Signer> {
 			latest_inbound_scid_alias: None,
 			outbound_scid_alias,
 
+			channel_ready_event_emitted: false,
+
 			#[cfg(any(test, fuzzing))]
 			historical_inbound_htlc_fulfills: HashSet::new(),
 
@@ -1397,6 +1402,8 @@ impl<Signer: Sign> Channel<Signer> {
 			latest_inbound_scid_alias: None,
 			outbound_scid_alias,
 
+			channel_ready_event_emitted: false,
+
 			#[cfg(any(test, fuzzing))]
 			historical_inbound_htlc_fulfills: HashSet::new(),
 
@@ -4598,6 +4605,16 @@ impl<Signer: Sign> Channel<Signer> {
 		self.prev_config.map(|prev_config| prev_config.0)
 	}
 
+	// Checks whether we should emit a `ChannelReady` event.
+	pub(crate) fn should_emit_channel_ready_event(&mut self) -> bool {
+		self.is_usable() && !self.channel_ready_event_emitted
+	}
+
+	// Remembers that we already emitted a `ChannelReady` event.
+	pub(crate) fn set_channel_ready_event_emitted(&mut self) {
+		self.channel_ready_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.
@@ -6230,6 +6247,8 @@ impl<Signer: Sign> Writeable for Channel<Signer> {
 			if self.holder_max_htlc_value_in_flight_msat != Self::get_holder_max_htlc_value_in_flight_msat(self.channel_value_satoshis, &old_max_in_flight_percent_config)
 			{ Some(self.holder_max_htlc_value_in_flight_msat) } else { None };
 
+		let channel_ready_event_emitted = Some(self.channel_ready_event_emitted);
+
 		write_tlv_fields!(writer, {
 			(0, self.announcement_sigs, option),
 			// minimum_depth and counterparty_selected_channel_reserve_satoshis used to have a
@@ -6252,6 +6271,7 @@ impl<Signer: Sign> Writeable for Channel<Signer> {
 			(17, self.announcement_sigs_state, required),
 			(19, self.latest_inbound_scid_alias, option),
 			(21, self.outbound_scid_alias, required),
+			(23, channel_ready_event_emitted, option),
 		});
 
 		Ok(())
@@ -6509,6 +6529,7 @@ impl<'a, Signer: Sign, K: Deref> ReadableArgs<(&'a K, u32)> for Channel<Signer>
 		let mut announcement_sigs_state = Some(AnnouncementSigsState::NotSent);
 		let mut latest_inbound_scid_alias = None;
 		let mut outbound_scid_alias = None;
+		let mut channel_ready_event_emitted = None;
 
 		read_tlv_fields!(reader, {
 			(0, announcement_sigs, option),
@@ -6526,6 +6547,7 @@ impl<'a, Signer: Sign, K: Deref> ReadableArgs<(&'a K, u32)> for Channel<Signer>
 			(17, announcement_sigs_state, option),
 			(19, latest_inbound_scid_alias, option),
 			(21, outbound_scid_alias, option),
+			(23, channel_ready_event_emitted, option),
 		});
 
 		if let Some(preimages) = preimages_opt {
@@ -6666,6 +6688,8 @@ impl<'a, Signer: Sign, K: Deref> ReadableArgs<(&'a K, u32)> for Channel<Signer>
 			// 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),
 
+			channel_ready_event_emitted: channel_ready_event_emitted.unwrap_or(false),
+
 			#[cfg(any(test, fuzzing))]
 			historical_inbound_htlc_fulfills,
 

lightning/src/ln/channelmanager.rs

@@ -1466,6 +1466,20 @@ macro_rules! send_channel_ready {
 	}
 }
 
+macro_rules! emit_channel_ready_event {
+	($pending_events: expr, $channel: expr) => {
+		if $channel.should_emit_channel_ready_event() {
+			$pending_events.push(events::Event::ChannelReady {
+				channel_id: $channel.channel_id(),
+				user_channel_id: $channel.get_user_id(),
+				counterparty_node_id: $channel.get_counterparty_node_id(),
+				channel_type: $channel.get_channel_type().clone(),
+			});
+			$channel.set_channel_ready_event_emitted();
+		}
+	}
+}
+
 macro_rules! handle_chan_restoration_locked {
 	($self: ident, $channel_lock: expr, $channel_state: expr, $channel_entry: expr,
 	 $raa: expr, $commitment_update: expr, $order: expr, $chanmon_update: expr,
@@ -1509,6 +1523,11 @@ macro_rules! handle_chan_restoration_locked {
 				});
 			}
 
+			{
+				let mut pending_events = $self.pending_events.lock().unwrap();
+				emit_channel_ready_event!(pending_events, $channel_entry.get_mut());
+			}
+
 			let funding_broadcastable: Option<Transaction> = $funding_broadcastable; // Force type-checking to resolve
 			if let Some(monitor_update) = chanmon_update {
 				// We only ever broadcast a funding transaction in response to a funding_signed
@@ -4672,6 +4691,12 @@ impl<M: Deref, T: Deref, K: Deref, F: Deref, L: Deref> ChannelManager<M, T, K, F
 						});
 					}
 				}
+
+				{
+					let mut pending_events = self.pending_events.lock().unwrap();
+					emit_channel_ready_event!(pending_events, chan.get_mut());
+				}
+
 				Ok(())
 			},
 			hash_map::Entry::Vacant(_) => Err(MsgHandleErrInternal::send_err_msg_no_close("Failed to find corresponding channel".to_owned(), msg.channel_id))
@@ -5829,6 +5854,12 @@ where
 							log_trace!(self.logger, "Sending channel_ready WITHOUT channel_update for {}", log_bytes!(channel.channel_id()));
 						}
 					}
+
+					{
+						let mut pending_events = self.pending_events.lock().unwrap();
+						emit_channel_ready_event!(pending_events, channel);
+					}
+
 					if let Some(announcement_sigs) = announcement_sigs {
 						log_trace!(self.logger, "Sending announcement_signatures for channel {}", log_bytes!(channel.channel_id()));
 						pending_msg_events.push(events::MessageSendEvent::SendAnnouncementSignatures {
@@ -7813,6 +7844,9 @@ mod tests {
 		let (channel_ready, _) = create_chan_between_nodes_with_value_confirm(&nodes[0], &nodes[1], &tx);
 		let (announcement, nodes_0_update, nodes_1_update) = create_chan_between_nodes_with_value_b(&nodes[0], &nodes[1], &channel_ready);
 		update_nodes_with_chan_announce(&nodes, 0, 1, &announcement, &nodes_0_update, &nodes_1_update);
+		expect_channel_ready_event!(nodes[0], nodes[1].node.get_our_node_id());
+		expect_channel_ready_event!(nodes[1], nodes[0].node.get_our_node_id());
+
 
 		nodes[0].node.close_channel(channel_id, &nodes[1].node.get_our_node_id()).unwrap();
 		nodes[1].node.handle_shutdown(&nodes[0].node.get_our_node_id(), &channelmanager::provided_init_features(), &get_event_msg!(nodes[0], MessageSendEvent::SendShutdown, nodes[1].node.get_our_node_id()));
@@ -7981,6 +8015,24 @@ pub mod bench {
 			_ => panic!(),
 		}
 
+		let events_a = node_a.get_and_clear_pending_events();
+		assert_eq!(events_a.len(), 1);
+		match events_a[0] {
+			Event::ChannelReady{ ref counterparty_node_id, .. } => {
+				assert_eq!(*counterparty_node_id, node_b.get_our_node_id());
+			},
+			_ => panic!("Unexpected event"),
+		}
+
+		let events_b = node_b.get_and_clear_pending_events();
+		assert_eq!(events_b.len(), 1);
+		match events_b[0] {
+			Event::ChannelReady{ ref counterparty_node_id, .. } => {
+				assert_eq!(*counterparty_node_id, node_a.get_our_node_id());
+			},
+			_ => panic!("Unexpected event"),
+		}
+
 		let dummy_graph = NetworkGraph::new(genesis_hash, &logger_a);
 
 		let mut payment_count: u64 = 0;

lightning/src/ln/functional_test_utils.rs

@@ -407,9 +407,26 @@ pub fn create_chan_between_nodes<'a, 'b, 'c, 'd>(node_a: &'a Node<'b, 'c, 'd>, n
 	create_chan_between_nodes_with_value(node_a, node_b, 100000, 10001, a_flags, b_flags)
 }
 
+#[macro_export]
+#[cfg(any(test, feature = "_bench_unstable", feature = "_test_utils"))]
+macro_rules! expect_channel_ready_event {
+	($node: expr, $expected_counterparty_node_id: expr) => {
+		let events = $node.node.get_and_clear_pending_events();
+		assert_eq!(events.len(), 1);
+		match events[0] {
+			$crate::util::events::Event::ChannelReady{ ref counterparty_node_id, .. } => {
+				assert_eq!($expected_counterparty_node_id, *counterparty_node_id);
+			},
+			_ => panic!("Unexpected event"),
+		}
+	}
+}
+
 pub fn create_chan_between_nodes_with_value<'a, 'b, 'c, 'd>(node_a: &'a Node<'b, 'c, 'd>, node_b: &'a Node<'b, 'c, 'd>, channel_value: u64, push_msat: u64, a_flags: InitFeatures, b_flags: InitFeatures) -> (msgs::ChannelAnnouncement, msgs::ChannelUpdate, msgs::ChannelUpdate, [u8; 32], Transaction) {
 	let (channel_ready, channel_id, tx) = create_chan_between_nodes_with_value_a(node_a, node_b, channel_value, push_msat, a_flags, b_flags);
 	let (announcement, as_update, bs_update) = create_chan_between_nodes_with_value_b(node_a, node_b, &channel_ready);
+	expect_channel_ready_event!(node_a, node_b.node.get_our_node_id());
+	expect_channel_ready_event!(node_b, node_a.node.get_our_node_id());
 	(announcement, as_update, bs_update, channel_id, tx)
 }
 
@@ -741,6 +758,9 @@ pub fn open_zero_conf_channel<'a, 'b, 'c, 'd>(initiator: &'a Node<'b, 'c, 'd>, r
 	assert_eq!(initiator.node.list_usable_channels().len(), initiator_channels + 1);
 	assert_eq!(receiver.node.list_usable_channels().len(), receiver_channels + 1);
 
+	expect_channel_ready_event!(initiator, receiver.node.get_our_node_id());
+	expect_channel_ready_event!(receiver, initiator.node.get_our_node_id());
+
 	(tx, as_channel_ready.channel_id)
 }
 
@@ -870,8 +890,10 @@ pub fn create_unannounced_chan_between_nodes_with_value<'a, 'b, 'c, 'd>(nodes: &
 	connect_blocks(&nodes[b], CHAN_CONFIRM_DEPTH - 1);
 	let as_channel_ready = get_event_msg!(nodes[a], MessageSendEvent::SendChannelReady, nodes[b].node.get_our_node_id());
 	nodes[a].node.handle_channel_ready(&nodes[b].node.get_our_node_id(), &get_event_msg!(nodes[b], MessageSendEvent::SendChannelReady, nodes[a].node.get_our_node_id()));
+	expect_channel_ready_event!(nodes[a], nodes[b].node.get_our_node_id());
 	let as_update = get_event_msg!(nodes[a], MessageSendEvent::SendChannelUpdate, nodes[b].node.get_our_node_id());
 	nodes[b].node.handle_channel_ready(&nodes[a].node.get_our_node_id(), &as_channel_ready);
+	expect_channel_ready_event!(nodes[b], nodes[a].node.get_our_node_id());
 	let bs_update = get_event_msg!(nodes[b], MessageSendEvent::SendChannelUpdate, nodes[a].node.get_our_node_id());
 
 	nodes[a].node.handle_channel_update(&nodes[b].node.get_our_node_id(), &bs_update);