Track inbound payments by PaymentId

CHANGELOG.md

@@ -7,6 +7,16 @@
   a persisted `ChannelClosed` event.
 - Users of the VSS storage backend must upgrade their VSS server to at least version
   `v0.1.0-alpha.0` before upgrading LDK Node.
+- The `payment_id` field on the `PaymentSuccessful`, `PaymentFailed`, and
+  `PaymentReceived` events is now a required (non-optional) `PaymentId`. Events
+  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

benches/payments.rs

@@ -75,12 +75,8 @@ async fn send_payments(node_a: Arc<Node>, node_b: Arc<Node>) -> std::time::Durat
 	while success_count < total_payments {
 		match node_a.next_event_async().await {
 			Event::PaymentSuccessful { payment_id, payment_hash, .. } => {
-				if let Some(id) = payment_id {
-					success_count += 1;
-					println!("{}: Payment with id {:?} completed", payment_hash.0.as_hex(), id);
-				} else {
-					println!("Payment completed (no payment_id)");
-				}
+				success_count += 1;
+				println!("{}: Payment with id {:?} completed", payment_hash.0.as_hex(), payment_id);
 			},
 			Event::PaymentFailed { payment_id, payment_hash, .. } => {
 				println!("{}: Payment {:?} failed", payment_hash.unwrap().0.as_hex(), payment_id);

bindings/python/src/ldk_node/test_ldk_node.py

@@ -235,7 +235,7 @@ def test_spontaneous_payment(self):
         self.assertEqual(received_event.custom_records, custom_tlvs)
 
         sender_payment = node_1.payment(keysend_payment_id)
-        receiver_payment = node_2.payment(keysend_payment_id)
+        receiver_payment = node_2.payment(received_event.payment_id)
 
         self.assertIsNotNone(sender_payment)
         self.assertIsNotNone(receiver_payment)

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,
 		}
 	}
 }