Track unknown BOLT11 manual claims

Gate manual claiming for unknown custom-hash BOLT11 payments
behind a config flag.

Nodes that do not opt in fail these payments back without storing or
queueing user events.

Co-Authored-By: HAL 9000

Author: tnull

CHANGELOG.md

@@ -12,6 +12,11 @@
   persisted by LDK Node v0.2.1 or earlier (which stored `payment_id` as
   optional) will fail to deserialize on read; users upgrading from those
   versions need to drain pending events before the upgrade.
+- Applications using the BOLT 11 manual-claiming receive APIs
+  (`receive_*_for_hash`) now need to set
+  `Config::manually_claim_unknown_bolt11_payments` to `true`. Otherwise
+  matching inbound HTLCs will be failed back instead of emitting
+  `Event::PaymentClaimable`.
 
 ## Feature and API updates
 - The Bitcoin Core RPC and REST chain-source builder methods now accept an optional

src/config.rs

@@ -155,6 +155,7 @@ pub(crate) const LIQUIDITY_DISCOVERY_RETRY_MAX_DELAY: Duration = Duration::from_
 /// | `route_parameters`                     | None                                 |
 /// | `tor_config`                           | None                                 |
 /// | `hrn_config`                           | HumanReadableNamesConfig::default()  |
+/// | `manually_claim_unknown_bolt11_payments` | false                              |
 ///
 /// See [`AnchorChannelsConfig`] and [`RouteParametersConfig`] for more information regarding their
 /// respective default values.
@@ -219,6 +220,17 @@ pub struct Config {
 	///
 	/// [BIP 353]: https://github.com/bitcoin/bips/blob/master/bip-0353.mediawiki
 	pub hrn_config: HumanReadableNamesConfig,
+	/// Whether to emit [`Event::PaymentClaimable`] for unknown BOLT 11 payments that were created
+	/// with a user-provided payment hash and therefore need to be manually claimed.
+	///
+	/// If disabled, such payments are failed back without being added to the payment store.
+	///
+	/// **Warning:** Enabling this may let any holder of a valid invoice generated by this node tie
+	/// up inbound HTLC slots and grow the persisted event queue until the payment is claimed,
+	/// failed, or times out.
+	///
+	/// [`Event::PaymentClaimable`]: crate::Event::PaymentClaimable
+	pub manually_claim_unknown_bolt11_payments: bool,
 }
 
 impl Default for Config {
@@ -235,6 +247,7 @@ impl Default for Config {
 			route_parameters: None,
 			node_alias: None,
 			hrn_config: HumanReadableNamesConfig::default(),
+			manually_claim_unknown_bolt11_payments: false,
 		}
 	}
 }

src/event.rs

@@ -194,15 +194,21 @@ pub enum Event {
 		/// The caveat described above the `total_fee_earned_msat` field applies here as well.
 		outbound_amount_forwarded_msat: Option<u64>,
 	},
-	/// A payment for a previously-registered payment hash has been received.
+	/// A BOLT 11 payment with a user-provided payment hash has been received.
 	///
 	/// This needs to be manually claimed by supplying the correct preimage to [`claim_for_hash`].
 	///
+	/// This event is only emitted for unknown payments if
+	/// [`Config::manually_claim_unknown_bolt11_payments`] is enabled. Enabling it may let any
+	/// holder of a valid invoice generated by this node tie up inbound HTLC slots and grow the
+	/// persisted event queue until the payment is claimed, failed, or times out.
+	///
 	/// If the provided parameters don't match the expectations or the preimage can't be
 	/// retrieved in time, should be failed-back via [`fail_for_hash`].
 	///
 	/// Note claiming will necessarily fail after the `claim_deadline` has been reached.
 	///
+	/// [`Config::manually_claim_unknown_bolt11_payments`]: crate::config::Config::manually_claim_unknown_bolt11_payments
 	/// [`claim_for_hash`]: crate::payment::Bolt11Payment::claim_for_hash
 	/// [`fail_for_hash`]: crate::payment::Bolt11Payment::fail_for_hash
 	PaymentClaimable {
@@ -906,45 +912,99 @@ where
 					}
 				}
 
-				if let Some(info) = payment_info {
+				let should_emit_payment_claimable = if let Some(info) = payment_info.as_ref() {
 					// If this is known by the store but ChannelManager doesn't know the preimage,
-					// the payment has been registered via `_for_hash` variants and needs to be manually claimed via
-					// user interaction.
-					match info.kind {
-						PaymentKind::Bolt11 { preimage, .. } => {
-							if purpose.preimage().is_none() {
-								debug_assert!(
-									preimage.is_none(),
-									"We would have registered the preimage if we knew"
-								);
+					// the payment needs to be manually claimed via user interaction.
+					match &info.kind {
+						PaymentKind::Bolt11 { preimage, .. } if purpose.preimage().is_none() => {
+							debug_assert!(
+								preimage.is_none(),
+								"We would have registered the preimage if we knew"
+							);
+							true
+						},
+						_ => false,
+					}
+				} else if let PaymentPurpose::Bolt11InvoicePayment {
+					payment_preimage: None,
+					payment_secret,
+					..
+				} = &purpose
+				{
+					if !self.config.manually_claim_unknown_bolt11_payments {
+						log_info!(
+								self.logger,
+								"Refusing unknown BOLT11 payment with hash {} as manual claiming is disabled",
+								hex_utils::to_string(&payment_hash.0),
+							);
+						self.channel_manager.fail_htlc_backwards(&payment_hash);
+						return Ok(());
+					}
 
-								let custom_records = onion_fields
-									.map(|cf| {
-										cf.custom_tlvs().into_iter().map(|tlv| tlv.into()).collect()
-									})
-									.unwrap_or_default();
-								let event = Event::PaymentClaimable {
-									payment_id,
-									payment_hash,
-									claimable_amount_msat: amount_msat,
-									claim_deadline,
-									custom_records,
-								};
-								match self.event_queue.add_event(event).await {
-									Ok(_) => return Ok(()),
-									Err(e) => {
-										log_error!(
-											self.logger,
-											"Failed to push to event queue: {}",
-											e
-										);
-										return Err(ReplayEvent());
-									},
-								};
-							}
+					let invoice_amount_msat =
+						amount_msat.saturating_add(counterparty_skimmed_fee_msat);
+					let kind = PaymentKind::Bolt11 {
+						hash: payment_hash,
+						preimage: None,
+						secret: Some(*payment_secret),
+						counterparty_skimmed_fee_msat: if counterparty_skimmed_fee_msat > 0 {
+							Some(counterparty_skimmed_fee_msat)
+						} else {
+							None
+						},
+					};
+
+					let payment = PaymentDetails::new(
+						payment_id,
+						kind,
+						Some(invoice_amount_msat),
+						None,
+						PaymentDirection::Inbound,
+						PaymentStatus::Pending,
+					);
+
+					match self.payment_store.insert(payment).await {
+						Ok(false) => (),
+						Ok(true) => {
+							log_error!(
+								self.logger,
+								"Bolt11InvoicePayment with ID {} was previously known",
+								payment_id,
+							);
+							debug_assert!(false);
+						},
+						Err(e) => {
+							log_error!(
+								self.logger,
+								"Failed to insert payment with ID {}: {}",
+								payment_id,
+								e
+							);
+							return Err(ReplayEvent());
 						},
-						_ => {},
 					}
+					true
+				} else {
+					false
+				};
+				if should_emit_payment_claimable {
+					let custom_records = onion_fields
+						.map(|cf| cf.custom_tlvs().into_iter().map(|tlv| tlv.into()).collect())
+						.unwrap_or_default();
+					let event = Event::PaymentClaimable {
+						payment_id,
+						payment_hash,
+						claimable_amount_msat: amount_msat,
+						claim_deadline,
+						custom_records,
+					};
+					match self.event_queue.add_event(event).await {
+						Ok(_) => return Ok(()),
+						Err(e) => {
+							log_error!(self.logger, "Failed to push to event queue: {}", e);
+							return Err(ReplayEvent());
+						},
+					};
 				}
 
 				log_info!(