Set UpdateAddHTLC::hold_htlc for offline payees

As part of supporting sending payments as an often-offline sender, the sender
needs to be able to set a flag in their update_add_htlc message indicating that
the HTLC should be held until receipt of a release_held_htlc onion message from
the often-offline payment recipient.

The prior commits laid groundwork to finally set the flag here in this commit.

See-also <lightning/bolts#989>

Author: valentinewallace

lightning/src/ln/channel.rs

@@ -9066,7 +9066,7 @@ where
 					onion_routing_packet: (**onion_packet).clone(),
 					skimmed_fee_msat: htlc.skimmed_fee_msat,
 					blinding_point: htlc.blinding_point,
-					hold_htlc: None, // Will be set by the async sender when support is added
+					hold_htlc: htlc.source.hold_htlc_at_next_hop().then(|| ()),
 				});
 			}
 		}

lightning/src/ln/channelmanager.rs

@@ -842,6 +842,13 @@ impl HTLCSource {
 			_ => None,
 		}
 	}
+
+	pub(crate) fn hold_htlc_at_next_hop(&self) -> bool {
+		match self {
+			Self::OutboundRoute { hold_htlc, .. } => hold_htlc.is_some(),
+			_ => false,
+		}
+	}
 }
 
 /// This enum is used to specify which error data to send to peers when failing back an HTLC
@@ -4930,6 +4937,7 @@ where
 			invoice_request: None,
 			bolt12_invoice: None,
 			session_priv_bytes,
+			hold_htlc_at_next_hop: false,
 		})
 	}
 
@@ -4945,6 +4953,7 @@ where
 			invoice_request,
 			bolt12_invoice,
 			session_priv_bytes,
+			hold_htlc_at_next_hop,
 		} = args;
 		// The top-level caller should hold the total_consistency_lock read lock.
 		debug_assert!(self.total_consistency_lock.try_write().is_err());
@@ -5026,7 +5035,7 @@ where
 							first_hop_htlc_msat: htlc_msat,
 							payment_id,
 							bolt12_invoice: bolt12_invoice.cloned(),
-							hold_htlc: None,
+							hold_htlc: hold_htlc_at_next_hop.then(|| ()),
 						};
 						let send_res = chan.send_htlc_and_commit(
 							htlc_msat,
@@ -5412,19 +5421,35 @@ where
 				},
 			};
 
-			let enqueue_held_htlc_available_res = self.flow.enqueue_held_htlc_available(
-				invoice,
-				payment_id,
-				self.get_peers_for_blinded_path(),
-			);
-			if enqueue_held_htlc_available_res.is_err() {
-				self.abandon_payment_with_reason(
+			// If the call to `Self::hold_htlc_channels` succeeded, then we are a private node and can
+			// hold the HTLCs for this payment at our next-hop channel counterparty until the recipient
+			// comes online. This allows us to go offline after locking in the HTLCs.
+			if let Ok(channels) = hold_htlc_channels_res {
+				if let Err(e) =
+					self.send_payment_for_static_invoice_no_persist(payment_id, channels)
+				{
+					log_trace!(
+						self.logger,
+						"Failed to send held HTLC with payment id {}: {:?}",
+						payment_id,
+						e
+					);
+				}
+			} else {
+				let enqueue_held_htlc_available_res = self.flow.enqueue_held_htlc_available(
+					invoice,
 					payment_id,
-					PaymentFailureReason::BlindedPathCreationFailed,
+					self.get_peers_for_blinded_path(),
 				);
-				res = Err(Bolt12PaymentError::BlindedPathCreationFailed);
-				return NotifyOption::DoPersist;
-			};
+				if enqueue_held_htlc_available_res.is_err() {
+					self.abandon_payment_with_reason(
+						payment_id,
+						PaymentFailureReason::BlindedPathCreationFailed,
+					);
+					res = Err(Bolt12PaymentError::BlindedPathCreationFailed);
+					return NotifyOption::DoPersist;
+				};
+			}
 
 			NotifyOption::DoPersist
 		});
@@ -5469,26 +5494,15 @@ where
 		}
 	}
 
+	/// If we want the HTLCs for this payment to be held at the next-hop channel counterparty, use
+	/// [`Self::hold_htlc_channels`] and pass the resulting channels in here.
 	fn send_payment_for_static_invoice(
-		&self, payment_id: PaymentId,
+		&self, payment_id: PaymentId, first_hops: Vec<ChannelDetails>,
 	) -> Result<(), Bolt12PaymentError> {
-		let best_block_height = self.best_block.read().unwrap().height;
 		let mut res = Ok(());
 		PersistenceNotifierGuard::optionally_notify(self, || {
-			let outbound_pmts_res = self.pending_outbound_payments.send_payment_for_static_invoice(
-				payment_id,
-				&self.router,
-				self.list_usable_channels(),
-				|| self.compute_inflight_htlcs(),
-				&self.entropy_source,
-				&self.node_signer,
-				&self,
-				&self.secp_ctx,
-				best_block_height,
-				&self.logger,
-				&self.pending_events,
-				|args| self.send_payment_along_path(args),
-			);
+			let outbound_pmts_res =
+				self.send_payment_for_static_invoice_no_persist(payment_id, first_hops);
 			match outbound_pmts_res {
 				Err(Bolt12PaymentError::UnexpectedInvoice)
 				| Err(Bolt12PaymentError::DuplicateInvoice) => {
@@ -5504,6 +5518,27 @@ where
 		res
 	}
 
+	/// Useful if the caller is already triggering a persist of the `ChannelManager`.
+	fn send_payment_for_static_invoice_no_persist(
+		&self, payment_id: PaymentId, first_hops: Vec<ChannelDetails>,
+	) -> Result<(), Bolt12PaymentError> {
+		let best_block_height = self.best_block.read().unwrap().height;
+		self.pending_outbound_payments.send_payment_for_static_invoice(
+			payment_id,
+			&self.router,
+			first_hops,
+			|| self.compute_inflight_htlcs(),
+			&self.entropy_source,
+			&self.node_signer,
+			&self,
+			&self.secp_ctx,
+			best_block_height,
+			&self.logger,
+			&self.pending_events,
+			|args| self.send_payment_along_path(args),
+		)
+	}
+
 	/// If we are holding an HTLC on behalf of an often-offline sender, this method allows us to
 	/// create a path for the sender to use as the reply path when they send the recipient a
 	/// [`HeldHtlcAvailable`] onion message, so the recipient's [`ReleaseHeldHtlc`] response will be
@@ -14781,7 +14816,9 @@ where
 	fn handle_release_held_htlc(&self, _message: ReleaseHeldHtlc, context: AsyncPaymentsContext) {
 		match context {
 			AsyncPaymentsContext::OutboundPayment { payment_id } => {
-				if let Err(e) = self.send_payment_for_static_invoice(payment_id) {
+				if let Err(e) =
+					self.send_payment_for_static_invoice(payment_id, self.list_usable_channels())
+				{
 					log_trace!(
 						self.logger,
 						"Failed to release held HTLC with payment id {}: {:?}",

lightning/src/ln/outbound_payment.rs

@@ -832,6 +832,7 @@ pub(super) struct SendAlongPathArgs<'a> {
 	pub invoice_request: Option<&'a InvoiceRequest>,
 	pub bolt12_invoice: Option<&'a PaidBolt12Invoice>,
 	pub session_priv_bytes: [u8; 32],
+	pub hold_htlc_at_next_hop: bool,
 }
 
 pub(super) struct OutboundPayments {
@@ -1064,26 +1065,29 @@ impl OutboundPayments {
 
 		let payment_params = Some(route_params.payment_params.clone());
 		let mut outbounds = self.pending_outbound_payments.lock().unwrap();
-		let onion_session_privs = match outbounds.entry(payment_id) {
+		let (onion_session_privs, hold_htlcs_at_next_hop) = match outbounds.entry(payment_id) {
 			hash_map::Entry::Occupied(entry) => match entry.get() {
 				PendingOutboundPayment::InvoiceReceived { .. } => {
 					let (retryable_payment, onion_session_privs) = Self::create_pending_payment(
 						payment_hash, recipient_onion.clone(), keysend_preimage, None, Some(bolt12_invoice.clone()), &route,
 						Some(retry_strategy), payment_params, entropy_source, best_block_height,
 					);
 					*entry.into_mut() = retryable_payment;
-					onion_session_privs
+					(onion_session_privs, false)
 				},
 				PendingOutboundPayment::StaticInvoiceReceived { .. } => {
-					let invreq = if let PendingOutboundPayment::StaticInvoiceReceived { invoice_request, .. } = entry.remove() {
-						invoice_request
-					} else { unreachable!() };
+					let (invreq, hold_htlcs_at_next_hop) =
+						if let PendingOutboundPayment::StaticInvoiceReceived {
+							invoice_request, hold_htlcs_at_next_hop, ..
+						} = entry.remove() {
+							(invoice_request, hold_htlcs_at_next_hop)
+						} else { unreachable!() };
 					let (retryable_payment, onion_session_privs) = Self::create_pending_payment(
 						payment_hash, recipient_onion.clone(), keysend_preimage, Some(invreq), Some(bolt12_invoice.clone()), &route,
 						Some(retry_strategy), payment_params, entropy_source, best_block_height
 					);
 					outbounds.insert(payment_id, retryable_payment);
-					onion_session_privs
+					(onion_session_privs, hold_htlcs_at_next_hop)
 				},
 				_ => return Err(Bolt12PaymentError::DuplicateInvoice),
 			},
@@ -1093,7 +1097,7 @@ impl OutboundPayments {
 
 		let result = self.pay_route_internal(
 			&route, payment_hash, &recipient_onion, keysend_preimage, invoice_request, Some(&bolt12_invoice), payment_id,
-			Some(route_params.final_value_msat), &onion_session_privs, false, node_signer,
+			Some(route_params.final_value_msat), &onion_session_privs, hold_htlcs_at_next_hop, node_signer,
 			best_block_height, &send_payment_along_path
 		);
 		log_info!(
@@ -2130,7 +2134,7 @@ impl OutboundPayments {
 			let path_res = send_payment_along_path(SendAlongPathArgs {
 				path: &path, payment_hash: &payment_hash, recipient_onion, total_value,
 				cur_height, payment_id, keysend_preimage: &keysend_preimage, invoice_request,
-				bolt12_invoice,
+				bolt12_invoice, hold_htlc_at_next_hop: hold_htlcs_at_next_hop,
 				session_priv_bytes: *session_priv_bytes
 			});
 			results.push(path_res);