Add min_final_cltv_expiry parameter to invoice utils

Author: dunxen

lightning-invoice/src/de.rs

@@ -22,7 +22,7 @@ use secp256k1;
 use secp256k1::ecdsa::{RecoveryId, RecoverableSignature};
 use secp256k1::PublicKey;
 
-use super::{Invoice, Sha256, TaggedField, ExpiryTime, MinFinalCltvExpiry, Fallback, PayeePubKey, InvoiceSignature, PositiveTimestamp,
+use super::{Invoice, Sha256, TaggedField, ExpiryTime, MinFinalCltvExpiryDelta, Fallback, PayeePubKey, InvoiceSignature, PositiveTimestamp,
 	SemanticError, PrivateRoute, ParseError, ParseOrSemanticError, Description, RawTaggedField, Currency, RawHrp, SiPrefix, RawInvoice,
 	constants, SignedRawInvoice, RawDataPart, InvoiceFeatures};
 
@@ -452,7 +452,7 @@ impl FromBase32 for TaggedField {
 			constants::TAG_EXPIRY_TIME =>
 				Ok(TaggedField::ExpiryTime(ExpiryTime::from_base32(field_data)?)),
 			constants::TAG_MIN_FINAL_CLTV_EXPIRY_DELTA =>
-				Ok(TaggedField::MinFinalCltvExpiry(MinFinalCltvExpiry::from_base32(field_data)?)),
+				Ok(TaggedField::MinFinalCltvExpiryDelta(MinFinalCltvExpiryDelta::from_base32(field_data)?)),
 			constants::TAG_FALLBACK =>
 				Ok(TaggedField::Fallback(Fallback::from_base32(field_data)?)),
 			constants::TAG_PRIVATE_ROUTE =>
@@ -523,13 +523,13 @@ impl FromBase32 for ExpiryTime {
 	}
 }
 
-impl FromBase32 for MinFinalCltvExpiry {
+impl FromBase32 for MinFinalCltvExpiryDelta {
 	type Err = ParseError;
 
-	fn from_base32(field_data: &[u5]) -> Result<MinFinalCltvExpiry, ParseError> {
+	fn from_base32(field_data: &[u5]) -> Result<MinFinalCltvExpiryDelta, ParseError> {
 		let expiry = parse_int_be::<u64, u5>(field_data, 32);
 		if let Some(expiry) = expiry {
-			Ok(MinFinalCltvExpiry(expiry))
+			Ok(MinFinalCltvExpiryDelta(expiry))
 		} else {
 			Err(ParseError::IntegerOverflowError)
 		}
@@ -841,13 +841,13 @@ mod test {
 
 	#[test]
 	fn test_parse_min_final_cltv_expiry_delta() {
-		use crate::MinFinalCltvExpiry;
+		use crate::MinFinalCltvExpiryDelta;
 		use bech32::FromBase32;
 
 		let input = from_bech32("pr".as_bytes());
-		let expected = Ok(MinFinalCltvExpiry(35));
+		let expected = Ok(MinFinalCltvExpiryDelta(35));
 
-		assert_eq!(MinFinalCltvExpiry::from_base32(&input), expected);
+		assert_eq!(MinFinalCltvExpiryDelta::from_base32(&input), expected);
 	}
 
 	#[test]

lightning-invoice/src/lib.rs

@@ -410,7 +410,7 @@ pub enum TaggedField {
 	PayeePubKey(PayeePubKey),
 	DescriptionHash(Sha256),
 	ExpiryTime(ExpiryTime),
-	MinFinalCltvExpiry(MinFinalCltvExpiry),
+	MinFinalCltvExpiryDelta(MinFinalCltvExpiryDelta),
 	Fallback(Fallback),
 	PrivateRoute(PrivateRoute),
 	PaymentSecret(PaymentSecret),
@@ -440,7 +440,7 @@ pub struct ExpiryTime(Duration);
 
 /// `min_final_cltv_expiry_delta` to use for the last HTLC in the route
 #[derive(Clone, Debug, Hash, Eq, PartialEq)]
-pub struct MinFinalCltvExpiry(pub u64);
+pub struct MinFinalCltvExpiryDelta(pub u64);
 
 // TODO: better types instead onf byte arrays
 /// Fallback address in case no LN payment is possible
@@ -656,7 +656,7 @@ impl<D: tb::Bool, H: tb::Bool, C: tb::Bool, S: tb::Bool> InvoiceBuilder<D, H, tb
 impl<D: tb::Bool, H: tb::Bool, T: tb::Bool, S: tb::Bool> InvoiceBuilder<D, H, T, tb::False, S> {
 	/// Sets `min_final_cltv_expiry_delta`.
 	pub fn min_final_cltv_expiry_delta(mut self, min_final_cltv_expiry_delta: u64) -> InvoiceBuilder<D, H, T, tb::True, S> {
-		self.tagged_fields.push(TaggedField::MinFinalCltvExpiry(MinFinalCltvExpiry(min_final_cltv_expiry_delta)));
+		self.tagged_fields.push(TaggedField::MinFinalCltvExpiryDelta(MinFinalCltvExpiryDelta(min_final_cltv_expiry_delta)));
 		self.set_flags()
 	}
 }
@@ -925,8 +925,8 @@ impl RawInvoice {
 		find_extract!(self.known_tagged_fields(), TaggedField::ExpiryTime(ref x), x)
 	}
 
-	pub fn min_final_cltv_expiry_delta(&self) -> Option<&MinFinalCltvExpiry> {
-		find_extract!(self.known_tagged_fields(), TaggedField::MinFinalCltvExpiry(ref x), x)
+	pub fn min_final_cltv_expiry_delta(&self) -> Option<&MinFinalCltvExpiryDelta> {
+		find_extract!(self.known_tagged_fields(), TaggedField::MinFinalCltvExpiryDelta(ref x), x)
 	}
 
 	pub fn payment_secret(&self) -> Option<&PaymentSecret> {
@@ -1297,7 +1297,7 @@ impl TaggedField {
 			TaggedField::PayeePubKey(_) => constants::TAG_PAYEE_PUB_KEY,
 			TaggedField::DescriptionHash(_) => constants::TAG_DESCRIPTION_HASH,
 			TaggedField::ExpiryTime(_) => constants::TAG_EXPIRY_TIME,
-			TaggedField::MinFinalCltvExpiry(_) => constants::TAG_MIN_FINAL_CLTV_EXPIRY_DELTA,
+			TaggedField::MinFinalCltvExpiryDelta(_) => constants::TAG_MIN_FINAL_CLTV_EXPIRY_DELTA,
 			TaggedField::Fallback(_) => constants::TAG_FALLBACK,
 			TaggedField::PrivateRoute(_) => constants::TAG_PRIVATE_ROUTE,
 			TaggedField::PaymentSecret(_) => constants::TAG_PAYMENT_SECRET,
@@ -1444,6 +1444,9 @@ pub enum CreationError {
 	///
 	/// [phantom invoices]: crate::utils::create_phantom_invoice
 	MissingRouteHints,
+
+	/// The provided `min_final_cltv_expiry_delta` was less than `MIN_FINAL_CLTV_EXPIRY_DELTA`.
+	MinFinalCltvExpiryDeltaTooShort,
 }
 
 impl Display for CreationError {
@@ -1454,6 +1457,8 @@ impl Display for CreationError {
 			CreationError::TimestampOutOfBounds => f.write_str("The Unix timestamp of the supplied date is less than zero or greater than 35-bits"),
 			CreationError::InvalidAmount => f.write_str("The supplied millisatoshi amount was greater than the total bitcoin supply"),
 			CreationError::MissingRouteHints => f.write_str("The invoice required route hints and they weren't provided"),
+			CreationError::MinFinalCltvExpiryDeltaTooShort => f.write_str(
+				"The supplied final CLTV expiry delta was less than LDK's `MIN_FINAL_CLTV_EXPIRY_DELTA`"),
 		}
 	}
 }

lightning-invoice/src/payment.rs

@@ -2113,7 +2113,7 @@ mod tests {
 
 		assert!(invoice_payer.pay_invoice(&create_invoice_from_channelmanager_and_duration_since_epoch(
 			&nodes[1].node, nodes[1].keys_manager, nodes[1].logger, Currency::Bitcoin,
-			Some(100_010_000), "Invoice".to_string(), duration_since_epoch(), 3600).unwrap())
+			Some(100_010_000), "Invoice".to_string(), duration_since_epoch(), 3600, None).unwrap())
 			.is_ok());
 		let htlc_msgs = nodes[0].node.get_and_clear_pending_msg_events();
 		assert_eq!(htlc_msgs.len(), 2);
@@ -2158,7 +2158,7 @@ mod tests {
 
 		assert!(invoice_payer.pay_invoice(&create_invoice_from_channelmanager_and_duration_since_epoch(
 			&nodes[1].node, nodes[1].keys_manager, nodes[1].logger, Currency::Bitcoin,
-			Some(100_010_000), "Invoice".to_string(), duration_since_epoch(), 3600).unwrap())
+			Some(100_010_000), "Invoice".to_string(), duration_since_epoch(), 3600, None).unwrap())
 			.is_ok());
 		let htlc_msgs = nodes[0].node.get_and_clear_pending_msg_events();
 		assert_eq!(htlc_msgs.len(), 2);
@@ -2239,7 +2239,7 @@ mod tests {
 
 		assert!(invoice_payer.pay_invoice(&create_invoice_from_channelmanager_and_duration_since_epoch(
 			&nodes[1].node, nodes[1].keys_manager, nodes[1].logger, Currency::Bitcoin,
-			Some(100_010_000), "Invoice".to_string(), duration_since_epoch(), 3600).unwrap())
+			Some(100_010_000), "Invoice".to_string(), duration_since_epoch(), 3600, None).unwrap())
 			.is_ok());
 		let htlc_updates = SendEvent::from_node(&nodes[0]);
 		check_added_monitors!(nodes[0], 1);

lightning-invoice/src/ser.rs

@@ -3,7 +3,7 @@ use core::fmt::{Display, Formatter};
 use bech32::{ToBase32, u5, WriteBase32, Base32Len};
 use crate::prelude::*;
 
-use super::{Invoice, Sha256, TaggedField, ExpiryTime, MinFinalCltvExpiry, Fallback, PayeePubKey, InvoiceSignature, PositiveTimestamp,
+use super::{Invoice, Sha256, TaggedField, ExpiryTime, MinFinalCltvExpiryDelta, Fallback, PayeePubKey, InvoiceSignature, PositiveTimestamp,
 	PrivateRoute, Description, RawTaggedField, Currency, RawHrp, SiPrefix, constants, SignedRawInvoice, RawDataPart};
 
 /// Converts a stream of bytes written to it to base32. On finalization the according padding will
@@ -313,13 +313,13 @@ impl Base32Len for ExpiryTime {
 	}
 }
 
-impl ToBase32 for MinFinalCltvExpiry {
+impl ToBase32 for MinFinalCltvExpiryDelta {
 	fn write_base32<W: WriteBase32>(&self, writer: &mut W) -> Result<(), <W as WriteBase32>::Err> {
 		writer.write(&encode_int_be_base32(self.0))
 	}
 }
 
-impl Base32Len for MinFinalCltvExpiry {
+impl Base32Len for MinFinalCltvExpiryDelta {
 	fn base32_len(&self) -> usize {
 		encoded_int_be_base32_size(self.0)
 	}
@@ -434,7 +434,7 @@ impl ToBase32 for TaggedField {
 			TaggedField::ExpiryTime(ref duration) => {
 				write_tagged_field(writer, constants::TAG_EXPIRY_TIME, duration)
 			},
-			TaggedField::MinFinalCltvExpiry(ref expiry) => {
+			TaggedField::MinFinalCltvExpiryDelta(ref expiry) => {
 				write_tagged_field(writer, constants::TAG_MIN_FINAL_CLTV_EXPIRY_DELTA, expiry)
 			},
 			TaggedField::Fallback(ref fallback_address) => {

lightning-invoice/src/utils.rs

@@ -235,9 +235,12 @@ where
 ///
 /// `invoice_expiry_delta_secs` describes the number of seconds that the invoice is valid for
 /// in excess of the current time.
+/// You can specify a custom `min_final_cltv_expiry_delta`, or let LDK default it to
+/// `MIN_FINAL_CLTV_EXPIRY_DELTA`. The provided expiry must be at least `MIN_FINAL_CLTV_EXPIRY_DELTA`.
 pub fn create_invoice_from_channelmanager<M: Deref, T: Deref, K: Deref, F: Deref, L: Deref>(
 	channelmanager: &ChannelManager<M, T, K, F, L>, keys_manager: K, logger: L,
-	network: Currency, amt_msat: Option<u64>, description: String, invoice_expiry_delta_secs: u32
+	network: Currency, amt_msat: Option<u64>, description: String, invoice_expiry_delta_secs: u32,
+	min_final_cltv_expiry_delta: Option<u32>,
 ) -> Result<Invoice, SignOrCreationError<()>>
 where
 	M::Target: chain::Watch<<K::Target as KeysInterface>::Signer>,
@@ -251,7 +254,7 @@ where
 		.expect("for the foreseeable future this shouldn't happen");
 	create_invoice_from_channelmanager_and_duration_since_epoch(
 		channelmanager, keys_manager, logger, network, amt_msat, description, duration,
-		invoice_expiry_delta_secs
+		invoice_expiry_delta_secs, min_final_cltv_expiry_delta,
 	)
 }
 
@@ -268,7 +271,7 @@ where
 pub fn create_invoice_from_channelmanager_with_description_hash<M: Deref, T: Deref, K: Deref, F: Deref, L: Deref>(
 	channelmanager: &ChannelManager<M, T, K, F, L>, keys_manager: K, logger: L,
 	network: Currency, amt_msat: Option<u64>, description_hash: Sha256,
-	invoice_expiry_delta_secs: u32
+	invoice_expiry_delta_secs: u32, min_final_cltv_expiry_delta: Option<u32>,
 ) -> Result<Invoice, SignOrCreationError<()>>
 where
 	M::Target: chain::Watch<<K::Target as KeysInterface>::Signer>,
@@ -285,7 +288,7 @@ where
 
 	create_invoice_from_channelmanager_with_description_hash_and_duration_since_epoch(
 		channelmanager, keys_manager, logger, network, amt_msat,
-		description_hash, duration, invoice_expiry_delta_secs
+		description_hash, duration, invoice_expiry_delta_secs, min_final_cltv_expiry_delta,
 	)
 }
 
@@ -295,7 +298,7 @@ where
 pub fn create_invoice_from_channelmanager_with_description_hash_and_duration_since_epoch<M: Deref, T: Deref, K: Deref, F: Deref, L: Deref>(
 	channelmanager: &ChannelManager<M, T, K, F, L>, keys_manager: K, logger: L,
 	network: Currency, amt_msat: Option<u64>, description_hash: Sha256,
-	duration_since_epoch: Duration, invoice_expiry_delta_secs: u32
+	duration_since_epoch: Duration, invoice_expiry_delta_secs: u32, min_final_cltv_expiry_delta: Option<u32>,
 ) -> Result<Invoice, SignOrCreationError<()>>
 where
 	M::Target: chain::Watch<<K::Target as KeysInterface>::Signer>,
@@ -307,7 +310,7 @@ where
 	_create_invoice_from_channelmanager_and_duration_since_epoch(
 		channelmanager, keys_manager, logger, network, amt_msat,
 		InvoiceDescription::Hash(&description_hash),
-		duration_since_epoch, invoice_expiry_delta_secs
+		duration_since_epoch, invoice_expiry_delta_secs, min_final_cltv_expiry_delta,
 	)
 }
 
@@ -317,7 +320,7 @@ where
 pub fn create_invoice_from_channelmanager_and_duration_since_epoch<M: Deref, T: Deref, K: Deref, F: Deref, L: Deref>(
 	channelmanager: &ChannelManager<M, T, K, F, L>, keys_manager: K, logger: L,
 	network: Currency, amt_msat: Option<u64>, description: String, duration_since_epoch: Duration,
-	invoice_expiry_delta_secs: u32
+	invoice_expiry_delta_secs: u32, min_final_cltv_expiry_delta: Option<u32>,
 ) -> Result<Invoice, SignOrCreationError<()>>
 where
 	M::Target: chain::Watch<<K::Target as KeysInterface>::Signer>,
@@ -331,14 +334,14 @@ where
 		InvoiceDescription::Direct(
 			&Description::new(description).map_err(SignOrCreationError::CreationError)?,
 		),
-		duration_since_epoch, invoice_expiry_delta_secs
+		duration_since_epoch, invoice_expiry_delta_secs, min_final_cltv_expiry_delta,
 	)
 }
 
 fn _create_invoice_from_channelmanager_and_duration_since_epoch<M: Deref, T: Deref, K: Deref, F: Deref, L: Deref>(
 	channelmanager: &ChannelManager<M, T, K, F, L>, keys_manager: K, logger: L,
 	network: Currency, amt_msat: Option<u64>, description: InvoiceDescription,
-	duration_since_epoch: Duration, invoice_expiry_delta_secs: u32
+	duration_since_epoch: Duration, invoice_expiry_delta_secs: u32, min_final_cltv_expiry_delta: Option<u32>,
 ) -> Result<Invoice, SignOrCreationError<()>>
 where
 	M::Target: chain::Watch<<K::Target as KeysInterface>::Signer>,
@@ -347,6 +350,10 @@ where
 	F::Target: FeeEstimator,
 	L::Target: Logger,
 {
+	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));
+	}
+
 	// `create_inbound_payment` only returns an error if the amount is greater than the total bitcoin
 	// supply.
 	let (payment_hash, payment_secret) = channelmanager
@@ -370,7 +377,7 @@ where
 		.payment_hash(Hash::from_slice(&payment_hash.0).unwrap())
 		.payment_secret(payment_secret)
 		.basic_mpp()
-		.min_final_cltv_expiry_delta(MIN_FINAL_CLTV_EXPIRY_DELTA.into())
+		.min_final_cltv_expiry_delta(min_final_cltv_expiry_delta.unwrap_or(MIN_FINAL_CLTV_EXPIRY_DELTA).into())
 		.expiry_time(Duration::from_secs(invoice_expiry_delta_secs.into()));
 	if let Some(amt) = amt_msat {
 		invoice = invoice.amount_milli_satoshis(amt);
@@ -683,7 +690,7 @@ impl<'a, S: Score> Score for ScorerAccountingForInFlightHtlcs<'a, S> {
 #[cfg(test)]
 mod test {
 	use core::time::Duration;
-	use crate::{Currency, Description, InvoiceDescription};
+	use crate::{Currency, Description, InvoiceDescription, SignOrCreationError, CreationError};
 	use bitcoin_hashes::Hash;
 	use bitcoin_hashes::sha256::Hash as Sha256;
 	use lightning::chain::keysinterface::PhantomKeysManager;
@@ -710,8 +717,9 @@ mod test {
 		let invoice = create_invoice_from_channelmanager_and_duration_since_epoch(
 			&nodes[1].node, nodes[1].keys_manager, nodes[1].logger, Currency::BitcoinTestnet,
 			Some(10_000), "test".to_string(), Duration::from_secs(1234567),
-			non_default_invoice_expiry_secs).unwrap();
+			non_default_invoice_expiry_secs, None).unwrap();
 		assert_eq!(invoice.amount_pico_btc(), Some(100_000));
+		// If no `min_final_cltv_expiry_delta` is specified, then it should be `MIN_FINAL_CLTV_EXPIRY_DELTA`.
 		assert_eq!(invoice.min_final_cltv_expiry_delta(), MIN_FINAL_CLTV_EXPIRY_DELTA as u64);
 		assert_eq!(invoice.description(), InvoiceDescription::Direct(&Description("test".to_string())));
 		assert_eq!(invoice.expiry_time(), Duration::from_secs(non_default_invoice_expiry_secs.into()));
@@ -775,7 +783,7 @@ mod test {
 		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
+			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);
@@ -967,7 +975,7 @@ mod test {
 		let invoice = create_invoice_from_channelmanager_and_duration_since_epoch(
 			&invoice_node.node, invoice_node.keys_manager, invoice_node.logger,
 			Currency::BitcoinTestnet, invoice_amt, "test".to_string(), Duration::from_secs(1234567),
-			3600).unwrap();
+			3600, None).unwrap();
 		let hints = invoice.private_routes();
 
 		for hint in hints {
@@ -1494,4 +1502,33 @@ mod test {
 		}
 		assert!(chan_ids_to_match.is_empty(), "Unmatched short channel ids: {:?}", chan_ids_to_match);
 	}
+
+	#[test]
+	fn test_create_invoice_with_valid_custom_min_final_cltv_expiry_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 invoice = crate::utils::create_invoice_from_channelmanager_and_duration_since_epoch(
+			&nodes[1].node, nodes[1].keys_manager, nodes[1].logger, Currency::BitcoinTestnet,
+			Some(10_000), "Some description".into(), Duration::from_secs(1234567), 3600, Some(30),
+		).unwrap();
+		assert_eq!(invoice.min_final_cltv_expiry_delta(), 30 as u64);
+	}
+
+	#[test]
+	fn test_create_invoice_fails_with_invalid_custom_min_final_cltv_expiry_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 result = crate::utils::create_invoice_from_channelmanager_and_duration_since_epoch(
+			&nodes[1].node, nodes[1].keys_manager, nodes[1].logger, Currency::BitcoinTestnet,
+			Some(10_000), "Some description".into(), Duration::from_secs(1234567), 3600, Some(MIN_FINAL_CLTV_EXPIRY_DELTA - 1),
+		);
+		match result {
+			Err(SignOrCreationError::CreationError(CreationError::MinFinalCltvExpiryDeltaTooShort)) => {},
+			_ => panic!(),
+		}
+	}
 }