Add support for handling "actions" after a monitor update completes

This adds a new enum, `MonitorUpdateCompletionAction` and a method
to execute the "actions". They are intended to be done once a
(potentially-async) `ChannelMonitorUpdate` persistence completes,
however this behavior will be implemented in a future PR. For now,
this adds the relevant infrastructure which will allow us to
prepare `claim_funds` for better monitor async handling.

Author: TheBlueMatt

lightning/src/ln/channelmanager.rs

@@ -453,6 +453,14 @@ enum BackgroundEvent {
 	ClosingMonitorUpdate((OutPoint, ChannelMonitorUpdate)),
 }
 
+pub(crate) enum MonitorUpdateCompletionAction {
+	/// Indicates that a payment ultimately destined for us was claimed and we should surface an
+	/// [`events::Event::PaymentClaimed`] to the user iff no such event has already been surfaced.
+	PaymentClaimed { payment_hash: PaymentHash },
+	/// Indicates an [`events::Event`] should be surfaced to the user.
+	SurfaceEvent { event: events::Event },
+}
+
 /// State we hold per-peer. In the future we should put channels in here, but for now we only hold
 /// the latest Init features we heard from the peer.
 struct PeerState {
@@ -4581,6 +4589,29 @@ impl<M: Deref, T: Deref, K: Deref, F: Deref, L: Deref> ChannelManager<M, T, K, F
 		self.our_network_pubkey.clone()
 	}
 
+	fn handle_monitor_update_completion_actions<I: IntoIterator<Item=MonitorUpdateCompletionAction>>(&self, actions: I) {
+		let mut actions = actions.into_iter().peekable();
+		if actions.peek().is_some() {
+			let mut pending_events = self.pending_events.lock().unwrap();
+			for action in actions {
+				match action {
+					MonitorUpdateCompletionAction::PaymentClaimed { payment_hash } => {
+						if let Some(PendingClaimingPayment { amount_msat, payment_purpose: purpose, receiver_node_id }) =
+							self.pending_claimed_payments.lock().unwrap().remove(&payment_hash)
+						{
+							pending_events.push(events::Event::PaymentClaimed {
+								payment_hash, purpose, amount_msat, receiver_node_id: Some(receiver_node_id),
+							});
+						}
+					},
+					MonitorUpdateCompletionAction::SurfaceEvent { event } => {
+						pending_events.push(event);
+					},
+				}
+			}
+		}
+	}
+
 	/// Handles a channel reentering a functional state, either due to reconnect or a monitor
 	/// update completion.
 	fn handle_channel_resumption(&self, pending_msg_events: &mut Vec<MessageSendEvent>,