Track how our HTLCs are resolved on-chain persistently

This tracks how any HTLC outputs in broadcast commitment
transactions are resolved on-chain, storing the result of the HTLC
resolution persistently in the ChannelMonitor.

This can be used to determine which outputs may still be available
for claiming on-chain.

Author: TheBlueMatt

lightning/src/chain/channelmonitor.rs

@@ -369,6 +369,11 @@ impl OnchainEventEntry {
 				// it's broadcastable when we see the previous block.
 				conf_threshold = cmp::max(conf_threshold, self.height + csv as u32 - 1);
 			},
+			OnchainEvent::HTLCSpendConfirmation { on_to_local_output_csv: Some(csv), .. } => {
+				// A CSV'd transaction is confirmable in block (input height) + CSV delay, which means
+				// it's broadcastable when we see the previous block.
+				conf_threshold = cmp::max(conf_threshold, self.height + csv as u32 - 1);
+			},
 			_ => {},
 		}
 		conf_threshold
@@ -390,6 +395,7 @@ enum OnchainEvent {
 		source: HTLCSource,
 		payment_hash: PaymentHash,
 		onchain_value_satoshis: Option<u64>,
+		input_idx: Option<u32>,
 	},
 	MaturingOutput {
 		descriptor: SpendableOutputDescriptor,
@@ -402,6 +408,12 @@ enum OnchainEvent {
 		/// commitment transaction, and this is the delay on the to_self output).
 		on_local_output_csv: Option<u16>,
 	},
+	HTLCSpendConfirmation {
+		input_idx: u32,
+		/// Only set if the claim was made by us with a preimage
+		our_preimage: Option<PaymentPreimage>,
+		on_to_local_output_csv: Option<u16>,
+	},
 }
 
 impl Writeable for OnchainEventEntry {
@@ -438,6 +450,7 @@ impl_writeable_tlv_based_enum_upgradable!(OnchainEvent,
 		(0, source, required),
 		(1, onchain_value_satoshis, option),
 		(2, payment_hash, required),
+		(3, input_idx, option),
 	},
 	(1, MaturingOutput) => {
 		(0, descriptor, required),
@@ -446,6 +459,12 @@ impl_writeable_tlv_based_enum_upgradable!(OnchainEvent,
 		(0, txid, required),
 		(2, on_local_output_csv, option),
 	},
+	(5, HTLCSpendConfirmation) => {
+		(0, input_idx, required),
+		(2, our_preimage, option),
+		(4, on_to_local_output_csv, option),
+	},
+
 );
 
 #[cfg_attr(any(test, feature = "fuzztarget", feature = "_test_utils"), derive(PartialEq))]
@@ -506,6 +525,19 @@ impl_writeable_tlv_based_enum_upgradable!(ChannelMonitorUpdateStep,
 	},
 );
 
+/// An HTLC which has been irrevocably resolved on-chain, and has reached ANTI_REORG_DELAY.
+#[derive(PartialEq)]
+struct HTLCIrrevocablyResolved {
+	input_idx: u32,
+	/// Only set if the HTLC claim was ours using a payment preimage
+	payment_preimage: Option<PaymentPreimage>,
+}
+
+impl_writeable_tlv_based!(HTLCIrrevocablyResolved, {
+	(0, input_idx, required),
+	(2, payment_preimage, option),
+});
+
 /// A ChannelMonitor handles chain events (blocks connected and disconnected) and generates
 /// on-chain transactions to ensure no loss of funds occurs.
 ///
@@ -619,6 +651,9 @@ pub(crate) struct ChannelMonitorImpl<Signer: Sign> {
 	holder_tx_signed: bool,
 
 	funding_spend_confirmed: Option<Txid>,
+	/// The set of HTLCs which have been either claimed or failed on chain and have reached
+	/// ANTI_REORG_DELAY confirmations on the claim/fail transaction.
+	htlcs_resolved_on_chain: Vec<HTLCIrrevocablyResolved>,
 
 	// We simply modify best_block in Channel's block_connected so that serialization is
 	// consistent but hopefully the users' copy handles block_connected in a consistent way.
@@ -679,7 +714,8 @@ impl<Signer: Sign> PartialEq for ChannelMonitorImpl<Signer> {
 			self.outputs_to_watch != other.outputs_to_watch ||
 			self.lockdown_from_offchain != other.lockdown_from_offchain ||
 			self.holder_tx_signed != other.holder_tx_signed ||
-			self.funding_spend_confirmed != other.funding_spend_confirmed
+			self.funding_spend_confirmed != other.funding_spend_confirmed ||
+			self.htlcs_resolved_on_chain != other.htlcs_resolved_on_chain
 		{
 			false
 		} else {
@@ -846,6 +882,7 @@ impl<Signer: Sign> Writeable for ChannelMonitorImpl<Signer> {
 
 		write_tlv_fields!(writer, {
 			(1, self.funding_spend_confirmed, option),
+			(3, self.htlcs_resolved_on_chain, vec_type),
 		});
 
 		Ok(())
@@ -945,6 +982,7 @@ impl<Signer: Sign> ChannelMonitor<Signer> {
 				lockdown_from_offchain: false,
 				holder_tx_signed: false,
 				funding_spend_confirmed: None,
+				htlcs_resolved_on_chain: Vec::new(),
 
 				best_block,
 
@@ -1311,6 +1349,7 @@ macro_rules! fail_unbroadcast_htlcs {
 									source: (**source).clone(),
 									payment_hash: htlc.payment_hash.clone(),
 									onchain_value_satoshis: Some(htlc.amount_msat / 1000),
+									input_idx: None,
 								},
 							};
 							log_trace!($logger, "Failing HTLC with payment_hash {} from {} counterparty commitment tx due to broadcast of {} commitment transaction, waiting for confirmation (at height {})",
@@ -2119,6 +2158,7 @@ impl<Signer: Sign> ChannelMonitorImpl<Signer> {
 				OnchainEvent::HTLCUpdate { source, .. } => Some(source),
 				OnchainEvent::MaturingOutput { .. } => None,
 				OnchainEvent::FundingSpendConfirmation { .. } => None,
+				OnchainEvent::HTLCSpendConfirmation { .. } => None,
 			})
 			.collect();
 		#[cfg(debug_assertions)]
@@ -2127,7 +2167,7 @@ impl<Signer: Sign> ChannelMonitorImpl<Signer> {
 		// Produce actionable events from on-chain events having reached their threshold.
 		for entry in onchain_events_reaching_threshold_conf.drain(..) {
 			match entry.event {
-				OnchainEvent::HTLCUpdate { ref source, payment_hash, onchain_value_satoshis } => {
+				OnchainEvent::HTLCUpdate { ref source, payment_hash, onchain_value_satoshis, input_idx } => {
 					// Check for duplicate HTLC resolutions.
 					#[cfg(debug_assertions)]
 					{
@@ -2151,13 +2191,19 @@ impl<Signer: Sign> ChannelMonitorImpl<Signer> {
 						source: source.clone(),
 						onchain_value_satoshis,
 					}));
+					if let Some(idx) = input_idx {
+						self.htlcs_resolved_on_chain.push(HTLCIrrevocablyResolved { input_idx: idx, payment_preimage: None });
+					}
 				},
 				OnchainEvent::MaturingOutput { descriptor } => {
 					log_debug!(logger, "Descriptor {} has got enough confirmations to be passed upstream", log_spendable!(descriptor));
 					self.pending_events.push(Event::SpendableOutputs {
 						outputs: vec![descriptor]
 					});
 				},
+				OnchainEvent::HTLCSpendConfirmation { input_idx, our_preimage, .. } => {
+					self.htlcs_resolved_on_chain.push(HTLCIrrevocablyResolved { input_idx, payment_preimage: our_preimage });
+				},
 				OnchainEvent::FundingSpendConfirmation { txid, .. } => {
 					self.funding_spend_confirmed = Some(txid);
 				},
@@ -2339,6 +2385,7 @@ impl<Signer: Sign> ChannelMonitorImpl<Signer> {
 				|| (input.witness.len() == 3 && HTLCType::scriptlen_to_htlctype(input.witness[2].len()) == Some(HTLCType::AcceptedHTLC) && input.witness[1].len() == 33);
 			let accepted_preimage_claim = input.witness.len() == 5 && HTLCType::scriptlen_to_htlctype(input.witness[4].len()) == Some(HTLCType::AcceptedHTLC);
 			let offered_preimage_claim = input.witness.len() == 3 && HTLCType::scriptlen_to_htlctype(input.witness[2].len()) == Some(HTLCType::OfferedHTLC);
+			let offered_timeout_claim = input.witness.len() == 5 && HTLCType::scriptlen_to_htlctype(input.witness[2].len()) == Some(HTLCType::OfferedHTLC);
 
 			macro_rules! log_claim {
 				($tx_info: expr, $holder_tx: expr, $htlc: expr, $source_avail: expr) => {
@@ -2398,6 +2445,21 @@ impl<Signer: Sign> ChannelMonitorImpl<Signer> {
 							}
 							if payment_data.is_none() {
 								log_claim!($tx_info, $holder_tx, htlc_output, false);
+								self.onchain_events_awaiting_threshold_conf.push(OnchainEventEntry {
+									txid: tx.txid(), height,
+									event: OnchainEvent::HTLCSpendConfirmation {
+										input_idx: input.previous_output.vout,
+										our_preimage: None,
+										// `payment_data.is_none()` implies that this is our
+										// payment, as we haven't learned anything to cause us to
+										// update another channel or our offchain state. Thus, wait
+										// for the CSV delay before dropping the HTLC from
+										// claimable balance if the claim was an HTLC-Success or
+										// HTLC-Timeout transaction.
+										on_to_local_output_csv: if accepted_preimage_claim || offered_timeout_claim {
+											Some(self.on_holder_tx_csv) } else { None },
+									},
+								});
 								continue 'outer_loop;
 							}
 						}
@@ -2428,6 +2490,15 @@ impl<Signer: Sign> ChannelMonitorImpl<Signer> {
 					if !self.pending_monitor_events.iter().any(
 						|update| if let &MonitorEvent::HTLCEvent(ref upd) = update { upd.source == source } else { false }) {
 						payment_preimage.0.copy_from_slice(&input.witness[3]);
+						self.onchain_events_awaiting_threshold_conf.push(OnchainEventEntry {
+							txid: tx.txid(),
+							height,
+							event: OnchainEvent::HTLCSpendConfirmation {
+								input_idx: input.previous_output.vout,
+								our_preimage: Some(payment_preimage),
+								on_to_local_output_csv: None,
+							},
+						});
 						self.pending_monitor_events.push(MonitorEvent::HTLCEvent(HTLCUpdate {
 							source,
 							payment_preimage: Some(payment_preimage),
@@ -2441,6 +2512,15 @@ impl<Signer: Sign> ChannelMonitorImpl<Signer> {
 							upd.source == source
 						} else { false }) {
 						payment_preimage.0.copy_from_slice(&input.witness[1]);
+						self.onchain_events_awaiting_threshold_conf.push(OnchainEventEntry {
+							txid: tx.txid(),
+							height,
+							event: OnchainEvent::HTLCSpendConfirmation {
+								input_idx: input.previous_output.vout,
+								our_preimage: Some(payment_preimage),
+								on_to_local_output_csv: None,
+							},
+						});
 						self.pending_monitor_events.push(MonitorEvent::HTLCEvent(HTLCUpdate {
 							source,
 							payment_preimage: Some(payment_preimage),
@@ -2458,12 +2538,14 @@ impl<Signer: Sign> ChannelMonitorImpl<Signer> {
 							_ => true,
 						}
 					});
+					let txid = tx.txid();
 					let entry = OnchainEventEntry {
 						txid: tx.txid(),
 						height,
 						event: OnchainEvent::HTLCUpdate {
 							source, payment_hash,
 							onchain_value_satoshis: Some(amount_msat / 1000),
+							input_idx: Some(input.previous_output.vout),
 						},
 					};
 					log_info!(logger, "Failing HTLC with payment_hash {} timeout by a spend tx, waiting for confirmation (at height {})", log_bytes!(payment_hash.0), entry.confirmation_threshold());
@@ -2836,8 +2918,10 @@ impl<'a, Signer: Sign, K: KeysInterface<Signer = Signer>> ReadableArgs<&'a K>
 		}
 
 		let mut funding_spend_confirmed = None;
+		let mut htlcs_resolved_on_chain = Some(Vec::new());
 		read_tlv_fields!(reader, {
 			(1, funding_spend_confirmed, option),
+			(3, htlcs_resolved_on_chain, vec_type),
 		});
 
 		let mut secp_ctx = Secp256k1::new();
@@ -2888,6 +2972,7 @@ impl<'a, Signer: Sign, K: KeysInterface<Signer = Signer>> ReadableArgs<&'a K>
 				lockdown_from_offchain,
 				holder_tx_signed,
 				funding_spend_confirmed,
+				htlcs_resolved_on_chain: htlcs_resolved_on_chain.unwrap(),
 
 				best_block,