Add ChannelManager::fail_htlc_backwards_with_reason

Author: alecchendev

lightning/src/ln/channelmanager.rs

@@ -3477,6 +3477,35 @@ where
 		}
 	}
 
+	/// This is a variant of [`ChannelManager::fail_htlc_backwards`] that allows you to specify the
+	/// reason for the failure.
+	/// 
+	/// Indicates that the preimage for payment_hash is unknown or the received amount is incorrect
+	/// after a PaymentClaimable event, failing the HTLC back to its origin and freeing resources
+	/// along the path (including in our own channel on which we received it).
+	///
+	/// Note that in some cases around unclean shutdown, it is possible the payment may have
+	/// already been claimed by you via [`ChannelManager::claim_funds`] prior to you seeing (a
+	/// second copy of) the [`events::Event::PaymentClaimable`] event. Alternatively, the payment
+	/// may have already been failed automatically by LDK if it was nearing its expiration time.
+	///
+	/// While LDK will never claim a payment automatically on your behalf (i.e. without you calling
+	/// [`ChannelManager::claim_funds`]), you should still monitor for
+	/// [`events::Event::PaymentClaimed`] events even for payments you intend to fail, especially on
+	/// startup during which time claims that were in-progress at shutdown may be replayed.
+	pub fn fail_htlc_backwards_with_reason(&self, payment_hash: &PaymentHash, reason: &HTLCFailReason) {
+		let _persistence_guard = PersistenceNotifierGuard::notify_on_drop(&self.total_consistency_lock, &self.persistence_notifier);
+
+		let removed_source = self.claimable_payments.lock().unwrap().claimable_htlcs.remove(payment_hash);
+		if let Some((_, mut sources)) = removed_source {
+			for htlc in sources.drain(..) {
+				let source = HTLCSource::PreviousHopData(htlc.prev_hop);
+				let receiver = HTLCDestination::FailedPayment { payment_hash: *payment_hash };
+				self.fail_htlc_backwards_internal(&source, &payment_hash, reason, receiver);
+			}
+		}
+	}
+
 	/// Gets an HTLC onion failure code and error data for an `UPDATE` error, given the error code
 	/// that we want to return and a channel.
 	///