Add UpdateAddHTLC::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 update_add struct.

See-also <lightning/bolts#989>

Author: valentinewallace

lightning/src/ln/blinded_payment_tests.rs

@@ -1522,6 +1522,7 @@ fn update_add_msg(
 		onion_routing_packet,
 		skimmed_fee_msat: None,
 		blinding_point,
+		hold_htlc: None,
 	}
 }
 

lightning/src/ln/channel.rs

@@ -9045,6 +9045,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
 				});
 			}
 		}

lightning/src/ln/functional_tests.rs

@@ -2288,6 +2288,7 @@ pub fn fail_backward_pending_htlc_upon_channel_failure() {
 			onion_routing_packet,
 			skimmed_fee_msat: None,
 			blinding_point: None,
+			hold_htlc: None,
 		};
 		nodes[0].node.handle_update_add_htlc(node_b_id, &update_add_htlc);
 	}

lightning/src/ln/htlc_reserve_unit_tests.rs

@@ -835,6 +835,7 @@ pub fn do_test_fee_spike_buffer(cfg: Option<UserConfig>, htlc_fails: bool) {
 		onion_routing_packet: onion_packet,
 		skimmed_fee_msat: None,
 		blinding_point: None,
+		hold_htlc: None,
 	};
 
 	nodes[1].node.handle_update_add_htlc(node_a_id, &msg);
@@ -1072,6 +1073,7 @@ pub fn test_chan_reserve_violation_inbound_htlc_outbound_channel() {
 		onion_routing_packet: onion_packet,
 		skimmed_fee_msat: None,
 		blinding_point: None,
+		hold_htlc: None,
 	};
 
 	nodes[0].node.handle_update_add_htlc(node_b_id, &msg);
@@ -1255,6 +1257,7 @@ pub fn test_chan_reserve_violation_inbound_htlc_inbound_chan() {
 		onion_routing_packet: onion_packet,
 		skimmed_fee_msat: None,
 		blinding_point: None,
+		hold_htlc: None,
 	};
 
 	nodes[1].node.handle_update_add_htlc(node_a_id, &msg);
@@ -1637,6 +1640,7 @@ pub fn test_update_add_htlc_bolt2_receiver_check_max_htlc_limit() {
 		onion_routing_packet: onion_packet.clone(),
 		skimmed_fee_msat: None,
 		blinding_point: None,
+		hold_htlc: None,
 	};
 
 	for i in 0..50 {
@@ -2242,6 +2246,7 @@ pub fn do_test_dust_limit_fee_accounting(can_afford: bool) {
 		onion_routing_packet,
 		skimmed_fee_msat: None,
 		blinding_point: None,
+		hold_htlc: None,
 	};
 
 	nodes[1].node.handle_update_add_htlc(node_a_id, &msg);

lightning/src/ln/msgs.rs

@@ -765,6 +765,11 @@ pub struct UpdateAddHTLC {
 	/// Provided if we are relaying or receiving a payment within a blinded path, to decrypt the onion
 	/// routing packet and the recipient-provided encrypted payload within.
 	pub blinding_point: Option<PublicKey>,
+	/// Set to `Some` if the sender wants the receiver of this message to hold onto this HTLC until
+	/// receipt of a [`ReleaseHeldHtlc`] onion message from the payment recipient.
+	///
+	/// [`ReleaseHeldHtlc`]: crate::onion_message::async_payments::ReleaseHeldHtlc
+	pub hold_htlc: Option<()>,
 }
 
 /// An onion message to be sent to or received from a peer.
@@ -3350,7 +3355,10 @@ impl_writeable_msg!(UpdateAddHTLC, {
 	onion_routing_packet,
 }, {
 	(0, blinding_point, option),
-	(65537, skimmed_fee_msat, option)
+	(65537, skimmed_fee_msat, option),
+	// TODO: currently we may fail to read the `ChannelManager` if we write a new even TLV in this message
+	// and then downgrade. Once this is fixed, update the type here to match BOLTs PR 989.
+	(75537, hold_htlc, option),
 });
 
 impl LengthReadable for OnionMessage {
@@ -5847,6 +5855,7 @@ mod tests {
 			onion_routing_packet,
 			skimmed_fee_msat: None,
 			blinding_point: None,
+			hold_htlc: None,
 		};
 		let encoded_value = update_add_htlc.encode();
 		let target_value = <Vec<u8>>::from_hex("020202020202020202020202020202020202020202020202020202020202020200083a840000034d32144668701144760101010101010101010101010101010101010101010101010101010101010101000c89d4ff031b84c5567b126440995d3ed5aaba0565d71e1834604819ff9c17f5e9d5dd078f010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101010202020202020202020202020202020202020202020202020202020202020202").unwrap();

lightning/src/ln/onion_payment.rs

@@ -753,6 +753,7 @@ mod tests {
 			onion_routing_packet,
 			skimmed_fee_msat: None,
 			blinding_point: None,
+			hold_htlc: None,
 		}
 	}
 

lightning/src/ln/payment_tests.rs

@@ -5017,6 +5017,7 @@ fn peel_payment_onion_custom_tlvs() {
 		skimmed_fee_msat: None,
 		onion_routing_packet,
 		blinding_point: None,
+		hold_htlc: None,
 	};
 	let peeled_onion = crate::ln::onion_payment::peel_payment_onion(
 		&update_add,