Merge pull request #308 from tnull/2024-06-manual-payment-hash-registrations

Author: tnull

bindings/ldk_node.udl

@@ -100,10 +100,18 @@ interface Bolt11Payment {
 	[Throws=NodeError]
 	void send_probes_using_amount([ByRef]Bolt11Invoice invoice, u64 amount_msat);
 	[Throws=NodeError]
+	void claim_for_hash(PaymentHash payment_hash, u64 claimable_amount_msat, PaymentPreimage preimage);
+	[Throws=NodeError]
+	void fail_for_hash(PaymentHash payment_hash);
+	[Throws=NodeError]
 	Bolt11Invoice receive(u64 amount_msat, [ByRef]string description, u32 expiry_secs);
 	[Throws=NodeError]
+	Bolt11Invoice receive_for_hash(u64 amount_msat, [ByRef]string description, u32 expiry_secs, PaymentHash payment_hash);
+	[Throws=NodeError]
 	Bolt11Invoice receive_variable_amount([ByRef]string description, u32 expiry_secs);
 	[Throws=NodeError]
+	Bolt11Invoice receive_variable_amount_for_hash([ByRef]string description, u32 expiry_secs, PaymentHash payment_hash);
+	[Throws=NodeError]
 	Bolt11Invoice receive_via_jit_channel(u64 amount_msat, [ByRef]string description, u32 expiry_secs, u64? max_lsp_fee_limit_msat);
 	[Throws=NodeError]
 	Bolt11Invoice receive_variable_amount_via_jit_channel([ByRef]string description, u32 expiry_secs, u64? max_proportional_lsp_fee_limit_ppm_msat);
@@ -222,6 +230,7 @@ interface Event {
 	PaymentSuccessful(PaymentId? payment_id, PaymentHash payment_hash, u64? fee_paid_msat);
 	PaymentFailed(PaymentId? payment_id, PaymentHash payment_hash, PaymentFailureReason? reason);
 	PaymentReceived(PaymentId? payment_id, PaymentHash payment_hash, u64 amount_msat);
+	PaymentClaimable(PaymentId payment_id, PaymentHash payment_hash, u64 claimable_amount_msat, u32? claim_deadline);
 	ChannelPending(ChannelId channel_id, UserChannelId user_channel_id, ChannelId former_temporary_channel_id, PublicKey counterparty_node_id, OutPoint funding_txo);
 	ChannelReady(ChannelId channel_id, UserChannelId user_channel_id, PublicKey? counterparty_node_id);
 	ChannelClosed(ChannelId channel_id, UserChannelId user_channel_id, PublicKey? counterparty_node_id, ClosureReason? reason);
@@ -285,6 +294,7 @@ dictionary PaymentDetails {
 	u64? amount_msat;
 	PaymentDirection direction;
 	PaymentStatus status;
+	u64 latest_update_timestamp;
 };
 
 [NonExhaustive]

src/event.rs

@@ -84,6 +84,28 @@ pub enum Event {
 		/// The value, in thousandths of a satoshi, that has been received.
 		amount_msat: u64,
 	},
+	/// A payment for a previously-registered payment hash has been received.
+	///
+	/// This needs to be manually claimed by supplying the correct preimage to [`claim_for_hash`].
+	///
+	/// If the 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.
+	///
+	/// [`claim_for_hash`]: crate::payment::Bolt11Payment::claim_for_hash
+	/// [`fail_for_hash`]: crate::payment::Bolt11Payment::fail_for_hash
+	PaymentClaimable {
+		/// A local identifier used to track the payment.
+		payment_id: PaymentId,
+		/// The hash of the payment.
+		payment_hash: PaymentHash,
+		/// The value, in thousandths of a satoshi, that is claimable.
+		claimable_amount_msat: u64,
+		/// The block height at which this payment will be failed back and will no longer be
+		/// eligible for claiming.
+		claim_deadline: Option<u32>,
+	},
 	/// A channel has been created and is pending confirmation on-chain.
 	ChannelPending {
 		/// The `channel_id` of the channel.
@@ -156,6 +178,12 @@ impl_writeable_tlv_based_enum!(Event,
 		(1, counterparty_node_id, option),
 		(2, user_channel_id, required),
 		(3, reason, upgradable_option),
+	},
+	(6, PaymentClaimable) => {
+		(0, payment_hash, required),
+		(2, payment_id, required),
+		(4, claimable_amount_msat, required),
+		(6, claim_deadline, option),
 	};
 );
 
@@ -434,12 +462,31 @@ where
 				receiver_node_id: _,
 				via_channel_id: _,
 				via_user_channel_id: _,
-				claim_deadline: _,
+				claim_deadline,
 				onion_fields: _,
 				counterparty_skimmed_fee_msat,
 			} => {
 				let payment_id = PaymentId(payment_hash.0);
 				if let Some(info) = self.payment_store.get(&payment_id) {
+					if info.direction == PaymentDirection::Outbound {
+						log_info!(
+							self.logger,
+							"Refused inbound payment with ID {}: circular payments are unsupported.",
+							payment_id
+						);
+						self.channel_manager.fail_htlc_backwards(&payment_hash);
+
+						let update = PaymentDetailsUpdate {
+							status: Some(PaymentStatus::Failed),
+							..PaymentDetailsUpdate::new(payment_id)
+						};
+						self.payment_store.update(&update).unwrap_or_else(|e| {
+							log_error!(self.logger, "Failed to access payment store: {}", e);
+							panic!("Failed to access payment store");
+						});
+						return;
+					}
+
 					if info.status == PaymentStatus::Succeeded
 						|| matches!(info.kind, PaymentKind::Spontaneous { .. })
 					{
@@ -500,6 +547,38 @@ where
 						});
 						return;
 					}
+
+					// 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"
+								);
+
+								self.event_queue
+									.add_event(Event::PaymentClaimable {
+										payment_id,
+										payment_hash,
+										claimable_amount_msat: amount_msat,
+										claim_deadline,
+									})
+									.unwrap_or_else(|e| {
+										log_error!(
+											self.logger,
+											"Failed to push to event queue: {}",
+											e
+										);
+										panic!("Failed to push to event queue");
+									});
+								return;
+							}
+						},
+						_ => {},
+					}
 				}
 
 				log_info!(
@@ -519,19 +598,21 @@ where
 						..
 					} => {
 						let offer_id = payment_context.offer_id;
-						let payment = PaymentDetails {
-							id: payment_id,
-							kind: PaymentKind::Bolt12Offer {
-								hash: Some(payment_hash),
-								preimage: payment_preimage,
-								secret: Some(payment_secret),
-								offer_id,
-							},
-							amount_msat: Some(amount_msat),
-							direction: PaymentDirection::Inbound,
-							status: PaymentStatus::Pending,
+						let kind = PaymentKind::Bolt12Offer {
+							hash: Some(payment_hash),
+							preimage: payment_preimage,
+							secret: Some(payment_secret),
+							offer_id,
 						};
 
+						let payment = PaymentDetails::new(
+							payment_id,
+							kind,
+							Some(amount_msat),
+							PaymentDirection::Inbound,
+							PaymentStatus::Pending,
+						);
+
 						match self.payment_store.insert(payment) {
 							Ok(false) => (),
 							Ok(true) => {
@@ -559,17 +640,19 @@ where
 					},
 					PaymentPurpose::SpontaneousPayment(preimage) => {
 						// Since it's spontaneous, we insert it now into our store.
-						let payment = PaymentDetails {
-							id: payment_id,
-							kind: PaymentKind::Spontaneous {
-								hash: payment_hash,
-								preimage: Some(preimage),
-							},
-							amount_msat: Some(amount_msat),
-							direction: PaymentDirection::Inbound,
-							status: PaymentStatus::Pending,
+						let kind = PaymentKind::Spontaneous {
+							hash: payment_hash,
+							preimage: Some(preimage),
 						};
 
+						let payment = PaymentDetails::new(
+							payment_id,
+							kind,
+							Some(amount_msat),
+							PaymentDirection::Inbound,
+							PaymentStatus::Pending,
+						);
+
 						match self.payment_store.insert(payment) {
 							Ok(false) => (),
 							Ok(true) => {