Add HTLCSource::OutboundRoute::hold_htlc

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 HTLCSource::OutboundRoute enum variant.

See-also <lightning/bolts#989>

Author: valentinewallace

fuzz/src/process_onion_failure.rs

@@ -120,6 +120,7 @@ fn do_test<Out: test_logger::Output>(data: &[u8], out: Out) {
 		first_hop_htlc_msat: 0,
 		payment_id,
 		bolt12_invoice: None,
+		hold_htlc: None,
 	};
 
 	let failure_len = get_u16!();

lightning/src/ln/channel.rs

@@ -15423,6 +15423,7 @@ mod tests {
 				first_hop_htlc_msat: 548,
 				payment_id: PaymentId([42; 32]),
 				bolt12_invoice: None,
+				hold_htlc: None,
 			},
 			skimmed_fee_msat: None,
 			blinding_point: None,
@@ -15870,6 +15871,7 @@ mod tests {
 			first_hop_htlc_msat: 0,
 			payment_id: PaymentId([42; 32]),
 			bolt12_invoice: None,
+			hold_htlc: None,
 		};
 		let dummy_outbound_output = OutboundHTLCOutput {
 			htlc_id: 0,

lightning/src/ln/channelmanager.rs

@@ -750,6 +750,10 @@ mod fuzzy_channelmanager {
 			/// we can provide proof-of-payment details in payment claim events even after a restart
 			/// with a stale ChannelManager state.
 			bolt12_invoice: Option<PaidBolt12Invoice>,
+			/// Whether we want our next-hop channel peer to hold onto this HTLC until they receive an
+			/// onion message from the often-offline recipient indicating that the recipient is online and
+			/// ready to receive the HTLC.
+			hold_htlc: Option<()>,
 		},
 	}
 
@@ -793,13 +797,15 @@ impl core::hash::Hash for HTLCSource {
 				payment_id,
 				first_hop_htlc_msat,
 				bolt12_invoice,
+				hold_htlc,
 			} => {
 				1u8.hash(hasher);
 				path.hash(hasher);
 				session_priv[..].hash(hasher);
 				payment_id.hash(hasher);
 				first_hop_htlc_msat.hash(hasher);
 				bolt12_invoice.hash(hasher);
+				hold_htlc.hash(hasher);
 			},
 		}
 	}
@@ -813,6 +819,7 @@ impl HTLCSource {
 			first_hop_htlc_msat: 0,
 			payment_id: PaymentId([2; 32]),
 			bolt12_invoice: None,
+			hold_htlc: None,
 		}
 	}
 
@@ -5032,6 +5039,7 @@ where
 							first_hop_htlc_msat: htlc_msat,
 							payment_id,
 							bolt12_invoice: bolt12_invoice.cloned(),
+							hold_htlc: None,
 						};
 						let send_res = chan.send_htlc_and_commit(
 							htlc_msat,
@@ -15190,6 +15198,7 @@ impl Readable for HTLCSource {
 				let mut payment_params: Option<PaymentParameters> = None;
 				let mut blinded_tail: Option<BlindedTail> = None;
 				let mut bolt12_invoice: Option<PaidBolt12Invoice> = None;
+				let mut hold_htlc: Option<()> = None;
 				read_tlv_fields!(reader, {
 					(0, session_priv, required),
 					(1, payment_id, option),
@@ -15198,6 +15207,7 @@ impl Readable for HTLCSource {
 					(5, payment_params, (option: ReadableArgs, 0)),
 					(6, blinded_tail, option),
 					(7, bolt12_invoice, option),
+					(9, hold_htlc, option),
 				});
 				if payment_id.is_none() {
 					// For backwards compat, if there was no payment_id written, use the session_priv bytes
@@ -15221,6 +15231,7 @@ impl Readable for HTLCSource {
 					path,
 					payment_id: payment_id.unwrap(),
 					bolt12_invoice,
+					hold_htlc,
 				})
 			}
 			1 => Ok(HTLCSource::PreviousHopData(Readable::read(reader)?)),
@@ -15238,6 +15249,7 @@ impl Writeable for HTLCSource {
 				ref path,
 				payment_id,
 				bolt12_invoice,
+				hold_htlc,
 			} => {
 				0u8.write(writer)?;
 				let payment_id_opt = Some(payment_id);
@@ -15250,6 +15262,7 @@ impl Writeable for HTLCSource {
 				   (5, None::<PaymentParameters>, option), // payment_params in LDK versions prior to 0.0.115
 				   (6, path.blinded_tail, option),
 				   (7, bolt12_invoice, option),
+					 (9, hold_htlc, option),
 				});
 			},
 			HTLCSource::PreviousHopData(ref field) => {

lightning/src/ln/onion_utils.rs

@@ -3413,6 +3413,7 @@ mod tests {
 			first_hop_htlc_msat: 0,
 			payment_id: PaymentId([1; 32]),
 			bolt12_invoice: None,
+			hold_htlc: None,
 		};
 
 		process_onion_failure(&ctx_full, &logger, &htlc_source, onion_error)
@@ -3603,6 +3604,7 @@ mod tests {
 				first_hop_htlc_msat: dummy_amt_msat,
 				payment_id: PaymentId([1; 32]),
 				bolt12_invoice: None,
+				hold_htlc: None,
 			};
 
 			{
@@ -3791,6 +3793,7 @@ mod tests {
 			first_hop_htlc_msat: 0,
 			payment_id: PaymentId([1; 32]),
 			bolt12_invoice: None,
+			hold_htlc: None,
 		};
 
 		// Iterate over all possible failure positions and check that the cases that can be attributed are.
@@ -3900,6 +3903,7 @@ mod tests {
 			first_hop_htlc_msat: 0,
 			payment_id: PaymentId([1; 32]),
 			bolt12_invoice: None,
+			hold_htlc: None,
 		};
 
 		let decrypted_failure = process_onion_failure(&ctx_full, &logger, &htlc_source, packet);