Add hold_htlcs field in StaticInvReceived outbounds

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.

We don't yet ever set this flag, but lay the groundwork by including the field
in the outbound payment variant for static invoices.

We also add a helper method to gather channels for nodes that advertise support
for the hold_htlc feature, which will be used in the next commit.

See-also <lightning/bolts#989>

Author: valentinewallace

lightning/src/ln/channelmanager.rs

@@ -5402,12 +5402,14 @@ where
 		&self, invoice: &StaticInvoice, payment_id: PaymentId,
 	) -> Result<(), Bolt12PaymentError> {
 		let mut res = Ok(());
+		let hold_htlc_channels_res = self.hold_htlc_channels();
 		PersistenceNotifierGuard::optionally_notify(self, || {
 			let best_block_height = self.best_block.read().unwrap().height;
 			let features = self.bolt12_invoice_features();
 			let outbound_pmts_res = self.pending_outbound_payments.static_invoice_received(
 				invoice,
 				payment_id,
+				hold_htlc_channels_res.is_ok(),
 				features,
 				best_block_height,
 				self.duration_since_epoch(),
@@ -5447,6 +5449,43 @@ where
 		res
 	}
 
+	/// Returns a list of channels where our counterparty supports
+	/// [`InitFeatures::supports_htlc_hold`], or an error if there are none or we detect that we are
+	/// an announced node. Useful for sending async payments to [`StaticInvoice`]s.
+	fn hold_htlc_channels(&self) -> Result<Vec<ChannelDetails>, ()> {
+		let should_send_async = {
+			let cfg = self.config.read().unwrap();
+			cfg.hold_outbound_htlcs_at_next_hop
+				&& !cfg.channel_handshake_config.announce_for_forwarding
+				&& cfg.channel_handshake_limits.force_announced_channel_preference
+		};
+		if !should_send_async {
+			return Err(());
+		}
+
+		let any_announced_channels = AtomicBool::new(false);
+		let hold_htlc_channels =
+			self.list_funded_channels_with_filter(|&(init_features, _, ref channel)| {
+				// If we have an announced channel, we are a node that is expected to be always-online and
+				// shouldn't be relying on channel counterparties to hold onto our HTLCs for us while
+				// waiting for the payment recipient to come online.
+				if channel.context().should_announce() {
+					any_announced_channels.store(true, Ordering::Relaxed);
+				}
+				if any_announced_channels.load(Ordering::Relaxed) {
+					return false;
+				}
+
+				init_features.supports_htlc_hold() && channel.context().is_live()
+			});
+
+		if any_announced_channels.load(Ordering::Relaxed) || hold_htlc_channels.is_empty() {
+			Err(())
+		} else {
+			Ok(hold_htlc_channels)
+		}
+	}
+
 	fn send_payment_for_static_invoice(
 		&self, payment_id: PaymentId,
 	) -> Result<(), Bolt12PaymentError> {

lightning/src/ln/outbound_payment.rs

@@ -103,6 +103,10 @@ pub(crate) enum PendingOutboundPayment {
 		route_params: RouteParameters,
 		invoice_request: InvoiceRequest,
 		static_invoice: StaticInvoice,
+		// Whether we should pay the static invoice asynchronously, i.e. by setting
+		// [`UpdateAddHTLC::hold_htlc`] so our channel counterparty(s) hold the HTLC(s) for us until the
+		// recipient comes online, allowing us to go offline after locking in the HTLC(s).
+		hold_htlcs_at_next_hop: bool,
 		// The deadline as duration since the Unix epoch for the async recipient to come online,
 		// after which we'll fail the payment.
 		//
@@ -1107,8 +1111,9 @@ impl OutboundPayments {
 	}
 
 	pub(super) fn static_invoice_received<ES: Deref>(
-		&self, invoice: &StaticInvoice, payment_id: PaymentId, features: Bolt12InvoiceFeatures,
-		best_block_height: u32, duration_since_epoch: Duration, entropy_source: ES,
+		&self, invoice: &StaticInvoice, payment_id: PaymentId, hold_htlcs_at_next_hop: bool,
+		features: Bolt12InvoiceFeatures, best_block_height: u32, duration_since_epoch: Duration,
+		entropy_source: ES,
 		pending_events: &Mutex<VecDeque<(events::Event, Option<EventCompletionAction>)>>,
 	) -> Result<(), Bolt12PaymentError>
 	where
@@ -1192,6 +1197,13 @@ impl OutboundPayments {
 							RetryableSendFailure::OnionPacketSizeExceeded,
 						));
 					}
+
+					// If we expect the HTLCs for this payment to be held at our next-hop counterparty, don't
+					// retry the payment. In future iterations of this feature, we will send this payment via
+					// trampoline and the counterparty will retry on our behalf.
+					if hold_htlcs_at_next_hop {
+						*retry_strategy = Retry::Attempts(0);
+					}
 					let absolute_expiry =
 						duration_since_epoch.saturating_add(ASYNC_PAYMENT_TIMEOUT_RELATIVE_EXPIRY);
 
@@ -1200,6 +1212,7 @@ impl OutboundPayments {
 						keysend_preimage,
 						retry_strategy: *retry_strategy,
 						route_params,
+						hold_htlcs_at_next_hop,
 						invoice_request: retryable_invoice_request
 							.take()
 							.ok_or(Bolt12PaymentError::UnexpectedInvoice)?
@@ -2759,6 +2772,12 @@ impl_writeable_tlv_based_enum_upgradable!(PendingOutboundPayment,
 	// HTLCs are in-flight.
 	(9, StaticInvoiceReceived) => {
 		(0, payment_hash, required),
+		// Added in 0.2. If this field is set when this variant is created, the HTLCs are sent
+		// immediately after and the pending outbound is also immediately transitioned to Retryable.
+		// However, if we crash and then downgrade before the transition to Retryable, this payment will
+		// sit in outbounds until it either times out in `remove_stale_payments` or is manually
+		// abandoned.
+		(1, hold_htlcs_at_next_hop, required),
 		(2, keysend_preimage, required),
 		(4, retry_strategy, required),
 		(6, route_params, required),
@@ -3418,6 +3437,7 @@ mod tests {
 			invoice_request: dummy_invoice_request(),
 			static_invoice: dummy_static_invoice(),
 			expiry_time: Duration::from_secs(absolute_expiry + 2),
+			hold_htlcs_at_next_hop: false
 		};
 		outbounds.insert(payment_id, outbound);
 		core::mem::drop(outbounds);
@@ -3468,6 +3488,7 @@ mod tests {
 			invoice_request: dummy_invoice_request(),
 			static_invoice: dummy_static_invoice(),
 			expiry_time: now(),
+			hold_htlcs_at_next_hop: false,
 		};
 		outbounds.insert(payment_id, outbound);
 		core::mem::drop(outbounds);

lightning/src/util/config.rs

@@ -947,6 +947,18 @@ pub struct UserConfig {
 	/// Default value: `false`
 	#[cfg(test)]
 	pub enable_htlc_hold: bool,
+	/// If this is set to true, then if we as an often-offline payer receive a [`StaticInvoice`] to
+	/// pay, we will attempt to hold the corresponding outbound HTLCs with our next-hop channel
+	/// counterparty(s) that support the `htlc_hold` feature. This allows our node to go offline once
+	/// the HTLCs are locked in even though the recipient may not yet be online to receive them.
+	///
+	/// This option only applies if we are a private node, and will be ignored if we are an announced
+	/// node that is expected to be online at all times.
+	///
+	/// Default value: `true`
+	///
+	/// [`StaticInvoice`]: crate::offers::static_invoice::StaticInvoice
+	pub hold_outbound_htlcs_at_next_hop: bool,
 }
 
 impl Default for UserConfig {
@@ -963,6 +975,7 @@ impl Default for UserConfig {
 			enable_dual_funded_channels: false,
 			#[cfg(test)]
 			enable_htlc_hold: false,
+			hold_outbound_htlcs_at_next_hop: true,
 		}
 	}
 }
@@ -983,6 +996,7 @@ impl Readable for UserConfig {
 			accept_intercept_htlcs: Readable::read(reader)?,
 			manually_handle_bolt12_invoices: Readable::read(reader)?,
 			enable_dual_funded_channels: Readable::read(reader)?,
+			hold_outbound_htlcs_at_next_hop: Readable::read(reader)?,
 		})
 	}
 }