Add new payment type and metadata bytes

Adds two new payment `Method`s for identifying payments with custom
`min_final_cltv_expiry_delta` as payments with LDK or user payment
hashes.

The `min_final_cltv_expiry_delta` value is packed into the metadata
bytes of the payment secret, taking up 12 bits.

Author: dunxen

fuzz/src/chanmon_consistency.rs

@@ -333,7 +333,7 @@ fn get_payment_secret_hash(dest: &ChanMan, payment_id: &mut u8) -> Option<(Payme
 	let mut payment_hash;
 	for _ in 0..256 {
 		payment_hash = PaymentHash(Sha256::hash(&[*payment_id; 1]).into_inner());
-		if let Ok(payment_secret) = dest.create_inbound_payment_for_hash(payment_hash, None, 3600) {
+		if let Ok(payment_secret) = dest.create_inbound_payment_for_hash(payment_hash, None, 3600, None) {
 			return Some((payment_secret, payment_hash));
 		}
 		*payment_id = payment_id.wrapping_add(1);

fuzz/src/full_stack.rs

@@ -599,7 +599,7 @@ pub fn do_test(data: &[u8], logger: &Arc<dyn Logger>) {
 				let payment_hash = PaymentHash(Sha256::from_engine(sha).into_inner());
 				// Note that this may fail - our hashes may collide and we'll end up trying to
 				// double-register the same payment_hash.
-				let _ = channelmanager.create_inbound_payment_for_hash(payment_hash, None, 1);
+				let _ = channelmanager.create_inbound_payment_for_hash(payment_hash, None, 1, None);
 			},
 			9 => {
 				for payment in payments_received.drain(..) {

lightning-invoice/src/utils.rs

@@ -160,6 +160,7 @@ where
 				.duration_since(UNIX_EPOCH)
 				.expect("Time must be > 1970")
 				.as_secs(),
+			min_final_cltv_expiry_delta,
 		)
 		.map_err(|_| SignOrCreationError::CreationError(CreationError::InvalidAmount))?;
 		(payment_hash, payment_secret)
@@ -173,6 +174,7 @@ where
 				.duration_since(UNIX_EPOCH)
 				.expect("Time must be > 1970")
 				.as_secs(),
+			min_final_cltv_expiry_delta,
 		)
 		.map_err(|_| SignOrCreationError::CreationError(CreationError::InvalidAmount))?
 	};
@@ -382,7 +384,7 @@ fn _create_invoice_from_channelmanager_and_duration_since_epoch<M: Deref, T: Der
 	// `create_inbound_payment` only returns an error if the amount is greater than the total bitcoin
 	// supply.
 	let (payment_hash, payment_secret) = channelmanager
-		.create_inbound_payment(amt_msat, invoice_expiry_delta_secs)
+		.create_inbound_payment(amt_msat, invoice_expiry_delta_secs, min_final_cltv_expiry_delta)
 		.map_err(|()| SignOrCreationError::CreationError(CreationError::InvalidAmount))?;
 	_create_invoice_from_channelmanager_and_duration_since_epoch_with_payment_hash(
 		channelmanager, node_signer, logger, network, amt_msat, description, duration_since_epoch,
@@ -409,7 +411,8 @@ pub fn create_invoice_from_channelmanager_and_duration_since_epoch_with_payment_
 		L::Target: Logger,
 {
 	let payment_secret = channelmanager
-		.create_inbound_payment_for_hash(payment_hash,amt_msat, invoice_expiry_delta_secs)
+		.create_inbound_payment_for_hash(payment_hash, amt_msat, invoice_expiry_delta_secs,
+			min_final_cltv_expiry_delta)
 		.map_err(|()| SignOrCreationError::CreationError(CreationError::InvalidAmount))?;
 	_create_invoice_from_channelmanager_and_duration_since_epoch_with_payment_hash(
 		channelmanager, node_signer, logger, network, amt_msat,
@@ -440,6 +443,10 @@ fn _create_invoice_from_channelmanager_and_duration_since_epoch_with_payment_has
 	let our_node_pubkey = channelmanager.get_our_node_id();
 	let channels = channelmanager.list_channels();
 
+	if min_final_cltv_expiry_delta.is_some() && min_final_cltv_expiry_delta.unwrap() < MIN_FINAL_CLTV_EXPIRY_DELTA {
+		return Err(SignOrCreationError::CreationError(CreationError::MinFinalCltvExpiryDeltaTooShort));
+	}
+
 	log_trace!(logger, "Creating invoice with payment hash {}", log_bytes!(payment_hash.0));
 
 	let invoice = match description {
@@ -742,6 +749,22 @@ mod test {
 		assert_eq!(events.len(), 2);
 	}
 
+	#[test]
+	fn test_create_invoice_with_custom_min_final_cltv_delta() {
+		let chanmon_cfgs = create_chanmon_cfgs(2);
+		let node_cfgs = create_node_cfgs(2, &chanmon_cfgs);
+		let node_chanmgrs = create_node_chanmgrs(2, &node_cfgs, &[None, None]);
+		let nodes = create_network(2, &node_cfgs, &node_chanmgrs);
+		let description_hash = crate::Sha256(Hash::hash("Testing description_hash".as_bytes()));
+		let invoice = crate::utils::create_invoice_from_channelmanager_with_description_hash_and_duration_since_epoch(
+			&nodes[1].node, nodes[1].keys_manager, nodes[1].logger, Currency::BitcoinTestnet,
+			Some(10_000), description_hash, Duration::from_secs(1234567), 3600, None,
+		).unwrap();
+		assert_eq!(invoice.amount_pico_btc(), Some(100_000));
+		assert_eq!(invoice.min_final_cltv_expiry_delta(), MIN_FINAL_CLTV_EXPIRY_DELTA as u64);
+		assert_eq!(invoice.description(), InvoiceDescription::Hash(&crate::Sha256(Sha256::hash("Testing description_hash".as_bytes()))));
+	}
+
 	#[test]
 	fn test_create_invoice_with_description_hash() {
 		let chanmon_cfgs = create_chanmon_cfgs(2);
@@ -1113,7 +1136,7 @@ mod test {
 		create_unannounced_chan_between_nodes_with_value(&nodes, 0, 2, 100000, 10001);
 
 		let payment_amt = 20_000;
-		let (payment_hash, _payment_secret) = nodes[1].node.create_inbound_payment(Some(payment_amt), 3600).unwrap();
+		let (payment_hash, _payment_secret) = nodes[1].node.create_inbound_payment(Some(payment_amt), 3600, None).unwrap();
 		let route_hints = vec![
 			nodes[1].node.get_phantom_route_hints(),
 			nodes[2].node.get_phantom_route_hints(),

lightning/src/ln/channelmanager.rs

@@ -1918,6 +1918,7 @@ where
 		// final_expiry_too_soon
 		// We have to have some headroom to broadcast on chain if we have the preimage, so make sure
 		// we have at least HTLC_FAIL_BACK_BUFFER blocks to go.
+		//
 		// Also, ensure that, in the case of an unknown preimage for the received payment hash, our
 		// payment logic has enough time to fail the HTLC backward before our onchain logic triggers a
 		// channel closure (see HTLC_FAIL_BACK_BUFFER rationale).
@@ -3184,10 +3185,21 @@ where
 												let payment_preimage = match inbound_payment::verify(payment_hash, &payment_data, self.highest_seen_timestamp.load(Ordering::Acquire) as u64, &self.inbound_payment_key, &self.logger) {
 													Ok(payment_preimage) => payment_preimage,
 													Err(()) => {
+														log_trace!(self.logger, "Failing new HTLC with payment_hash {} as payment verification failed", log_bytes!(payment_hash.0));
 														fail_htlc!(claimable_htlc, payment_hash);
 														continue
 													}
 												};
+												if let Some(min_final_cltv_expiry_delta) = inbound_payment::get_custom_min_final_cltv_expiry_delta(
+													payment_data.payment_secret, &self.inbound_payment_key) {
+													let expected_min_expiry_height = (self.current_best_block().height() + min_final_cltv_expiry_delta as u32) as u64;
+													if (cltv_expiry as u64) < expected_min_expiry_height {
+														log_trace!(self.logger, "Failing new HTLC with payment_hash {} as its CLTV expiry was too soon (had {}, earliest expected {})",
+															log_bytes!(payment_hash.0), cltv_expiry, expected_min_expiry_height);
+														fail_htlc!(claimable_htlc, payment_hash);
+														continue;
+													}
+												}
 												check_total_value!(payment_data, payment_preimage);
 											},
 											OnionPayload::Spontaneous(preimage) => {
@@ -5270,12 +5282,18 @@ where
 	///
 	/// Errors if `min_value_msat` is greater than total bitcoin supply.
 	///
+	/// If `min_final_cltv_expiry_delta` is set to some value, then the payment will not be receivable
+	/// on versions of LDK prior to 0.0.114.
+	///
 	/// [`claim_funds`]: Self::claim_funds
 	/// [`PaymentClaimable`]: events::Event::PaymentClaimable
 	/// [`PaymentClaimable::payment_preimage`]: events::Event::PaymentClaimable::payment_preimage
 	/// [`create_inbound_payment_for_hash`]: Self::create_inbound_payment_for_hash
-	pub fn create_inbound_payment(&self, min_value_msat: Option<u64>, invoice_expiry_delta_secs: u32) -> Result<(PaymentHash, PaymentSecret), ()> {
-		inbound_payment::create(&self.inbound_payment_key, min_value_msat, invoice_expiry_delta_secs, &self.entropy_source, self.highest_seen_timestamp.load(Ordering::Acquire) as u64)
+	pub fn create_inbound_payment(&self, min_value_msat: Option<u64>, invoice_expiry_delta_secs: u32,
+		min_final_cltv_expiry_delta: Option<u16>) -> Result<(PaymentHash, PaymentSecret), ()> {
+		inbound_payment::create(&self.inbound_payment_key, min_value_msat, invoice_expiry_delta_secs,
+			&self.entropy_source, self.highest_seen_timestamp.load(Ordering::Acquire) as u64,
+			min_final_cltv_expiry_delta)
 	}
 
 	/// Legacy version of [`create_inbound_payment`]. Use this method if you wish to share
@@ -5336,10 +5354,16 @@ where
 	///
 	/// Errors if `min_value_msat` is greater than total bitcoin supply.
 	///
+	/// If `min_final_cltv_expiry_delta` is set to some value, then the payment will not be receivable
+	/// on versions of LDK prior to 0.0.114.
+	///
 	/// [`create_inbound_payment`]: Self::create_inbound_payment
 	/// [`PaymentClaimable`]: events::Event::PaymentClaimable
-	pub fn create_inbound_payment_for_hash(&self, payment_hash: PaymentHash, min_value_msat: Option<u64>, invoice_expiry_delta_secs: u32) -> Result<PaymentSecret, ()> {
-		inbound_payment::create_from_hash(&self.inbound_payment_key, min_value_msat, payment_hash, invoice_expiry_delta_secs, self.highest_seen_timestamp.load(Ordering::Acquire) as u64)
+	pub fn create_inbound_payment_for_hash(&self, payment_hash: PaymentHash, min_value_msat: Option<u64>,
+		invoice_expiry_delta_secs: u32, min_final_cltv_expiry: Option<u16>) -> Result<PaymentSecret, ()> {
+		inbound_payment::create_from_hash(&self.inbound_payment_key, min_value_msat, payment_hash,
+			invoice_expiry_delta_secs, self.highest_seen_timestamp.load(Ordering::Acquire) as u64,
+			min_final_cltv_expiry)
 	}
 
 	/// Legacy version of [`create_inbound_payment_for_hash`]. Use this method if you wish to share
@@ -8459,7 +8483,7 @@ pub mod bench {
 				payment_preimage.0[0..8].copy_from_slice(&payment_count.to_le_bytes());
 				payment_count += 1;
 				let payment_hash = PaymentHash(Sha256::hash(&payment_preimage.0[..]).into_inner());
-				let payment_secret = $node_b.create_inbound_payment_for_hash(payment_hash, None, 7200).unwrap();
+				let payment_secret = $node_b.create_inbound_payment_for_hash(payment_hash, None, 7200, None).unwrap();
 
 				$node_a.send_payment(&route, payment_hash, &Some(payment_secret), PaymentId(payment_hash.0)).unwrap();
 				let payment_event = SendEvent::from_event($node_a.get_and_clear_pending_msg_events().pop().unwrap());

lightning/src/ln/functional_test_utils.rs

@@ -1437,17 +1437,22 @@ macro_rules! get_payment_preimage_hash {
 		}
 	};
 	($dest_node: expr, $min_value_msat: expr) => {
+		{
+			crate::get_payment_preimage_hash!($dest_node, $min_value_msat, None)
+		}
+	};
+	($dest_node: expr, $min_value_msat: expr, $min_final_cltv_expiry_delta: expr) => {
 		{
 			use bitcoin::hashes::Hash as _;
 			let mut payment_count = $dest_node.network_payment_count.borrow_mut();
 			let payment_preimage = $crate::ln::PaymentPreimage([*payment_count; 32]);
 			*payment_count += 1;
 			let payment_hash = $crate::ln::PaymentHash(
 				bitcoin::hashes::sha256::Hash::hash(&payment_preimage.0[..]).into_inner());
-			let payment_secret = $dest_node.node.create_inbound_payment_for_hash(payment_hash, $min_value_msat, 7200).unwrap();
+			let payment_secret = $dest_node.node.create_inbound_payment_for_hash(payment_hash, $min_value_msat, 7200, $min_final_cltv_expiry_delta).unwrap();
 			(payment_preimage, payment_hash, payment_secret)
 		}
-	}
+	};
 }
 
 #[macro_export]