Add _delta suffix to min_final_cltv_expiry

This matches the spec and helps avoid any confusion around
naming. We're also then consistent with `cltv_expiry` in an HTLC being
the actual block height value for the CLTV and not a delta.

Author: dunxen

lightning-invoice/src/de.rs

@@ -451,7 +451,7 @@ impl FromBase32 for TaggedField {
 				Ok(TaggedField::DescriptionHash(Sha256::from_base32(field_data)?)),
 			constants::TAG_EXPIRY_TIME =>
 				Ok(TaggedField::ExpiryTime(ExpiryTime::from_base32(field_data)?)),
-			constants::TAG_MIN_FINAL_CLTV_EXPIRY =>
+			constants::TAG_MIN_FINAL_CLTV_EXPIRY_DELTA =>
 				Ok(TaggedField::MinFinalCltvExpiry(MinFinalCltvExpiry::from_base32(field_data)?)),
 			constants::TAG_FALLBACK =>
 				Ok(TaggedField::Fallback(Fallback::from_base32(field_data)?)),
@@ -840,7 +840,7 @@ mod test {
 	}
 
 	#[test]
-	fn test_parse_min_final_cltv_expiry() {
+	fn test_parse_min_final_cltv_expiry_delta() {
 		use crate::MinFinalCltvExpiry;
 		use bech32::FromBase32;
 

lightning-invoice/src/lib.rs

@@ -154,11 +154,11 @@ pub const DEFAULT_EXPIRY_TIME: u64 = 3600;
 /// Default minimum final CLTV expiry as defined by [BOLT 11].
 ///
 /// Note that this is *not* the same value as rust-lightning's minimum CLTV expiry, which is
-/// provided in [`MIN_FINAL_CLTV_EXPIRY`].
+/// provided in [`MIN_FINAL_CLTV_EXPIRY_DELTA`].
 ///
 /// [BOLT 11]: https://github.com/lightning/bolts/blob/master/11-payment-encoding.md
-/// [`MIN_FINAL_CLTV_EXPIRY`]: lightning::ln::channelmanager::MIN_FINAL_CLTV_EXPIRY
-pub const DEFAULT_MIN_FINAL_CLTV_EXPIRY: u64 = 18;
+/// [`MIN_FINAL_CLTV_EXPIRY_DELTA`]: lightning::ln::channelmanager::MIN_FINAL_CLTV_EXPIRY_DELTA
+pub const DEFAULT_MIN_FINAL_CLTV_EXPIRY_DELTA: u64 = 18;
 
 /// Builder for `Invoice`s. It's the most convenient and advised way to use this library. It ensures
 /// that only a semantically and syntactically correct Invoice can be built using it.
@@ -199,7 +199,7 @@ pub const DEFAULT_MIN_FINAL_CLTV_EXPIRY: u64 = 18;
 /// 	.payment_hash(payment_hash)
 /// 	.payment_secret(payment_secret)
 /// 	.current_timestamp()
-/// 	.min_final_cltv_expiry(144)
+/// 	.min_final_cltv_expiry_delta(144)
 /// 	.build_signed(|hash| {
 /// 		Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)
 /// 	})
@@ -438,7 +438,7 @@ pub struct PayeePubKey(pub PublicKey);
 #[derive(Clone, Debug, Hash, Eq, PartialEq)]
 pub struct ExpiryTime(Duration);
 
-/// `min_final_cltv_expiry` to use for the last HTLC in the route
+/// `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);
 
@@ -475,7 +475,7 @@ pub mod constants {
 	pub const TAG_PAYEE_PUB_KEY: u8 = 19;
 	pub const TAG_DESCRIPTION_HASH: u8 = 23;
 	pub const TAG_EXPIRY_TIME: u8 = 6;
-	pub const TAG_MIN_FINAL_CLTV_EXPIRY: u8 = 24;
+	pub const TAG_MIN_FINAL_CLTV_EXPIRY_DELTA: u8 = 24;
 	pub const TAG_FALLBACK: u8 = 9;
 	pub const TAG_PRIVATE_ROUTE: u8 = 3;
 	pub const TAG_PAYMENT_SECRET: u8 = 16;
@@ -654,9 +654,9 @@ 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`.
-	pub fn min_final_cltv_expiry(mut self, min_final_cltv_expiry: u64) -> InvoiceBuilder<D, H, T, tb::True, S> {
-		self.tagged_fields.push(TaggedField::MinFinalCltvExpiry(MinFinalCltvExpiry(min_final_cltv_expiry)));
+	/// 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.set_flags()
 	}
 }
@@ -925,7 +925,7 @@ impl RawInvoice {
 		find_extract!(self.known_tagged_fields(), TaggedField::ExpiryTime(ref x), x)
 	}
 
-	pub fn min_final_cltv_expiry(&self) -> Option<&MinFinalCltvExpiry> {
+	pub fn min_final_cltv_expiry_delta(&self) -> Option<&MinFinalCltvExpiry> {
 		find_extract!(self.known_tagged_fields(), TaggedField::MinFinalCltvExpiry(ref x), x)
 	}
 
@@ -1239,12 +1239,12 @@ impl Invoice {
 			.unwrap_or_else(|| Duration::new(u64::max_value(), 1_000_000_000 - 1)) < at_time
 	}
 
-	/// Returns the invoice's `min_final_cltv_expiry` time, if present, otherwise
-	/// [`DEFAULT_MIN_FINAL_CLTV_EXPIRY`].
-	pub fn min_final_cltv_expiry(&self) -> u64 {
-		self.signed_invoice.min_final_cltv_expiry()
+	/// Returns the invoice's `min_final_cltv_expiry_delta` time, if present, otherwise
+	/// [`DEFAULT_MIN_FINAL_CLTV_EXPIRY_DELTA`].
+	pub fn min_final_cltv_expiry_delta(&self) -> u64 {
+		self.signed_invoice.min_final_cltv_expiry_delta()
 			.map(|x| x.0)
-			.unwrap_or(DEFAULT_MIN_FINAL_CLTV_EXPIRY)
+			.unwrap_or(DEFAULT_MIN_FINAL_CLTV_EXPIRY_DELTA)
 	}
 
 	/// Returns a list of all fallback addresses
@@ -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,
+			TaggedField::MinFinalCltvExpiry(_) => constants::TAG_MIN_FINAL_CLTV_EXPIRY_DELTA,
 			TaggedField::Fallback(_) => constants::TAG_FALLBACK,
 			TaggedField::PrivateRoute(_) => constants::TAG_PRIVATE_ROUTE,
 			TaggedField::PaymentSecret(_) => constants::TAG_PAYMENT_SECRET,
@@ -1800,7 +1800,7 @@ mod test {
 		let builder = InvoiceBuilder::new(Currency::Bitcoin)
 			.payment_hash(sha256::Hash::from_slice(&[0;32][..]).unwrap())
 			.duration_since_epoch(Duration::from_secs(1234567))
-			.min_final_cltv_expiry(144);
+			.min_final_cltv_expiry_delta(144);
 
 		let too_long_string = String::from_iter(
 			(0..1024).map(|_| '?')
@@ -1918,7 +1918,7 @@ mod test {
 			.duration_since_epoch(Duration::from_secs(1234567))
 			.payee_pub_key(public_key.clone())
 			.expiry_time(Duration::from_secs(54321))
-			.min_final_cltv_expiry(144)
+			.min_final_cltv_expiry_delta(144)
 			.fallback(Fallback::PubKeyHash([0;20]))
 			.private_route(route_1.clone())
 			.private_route(route_2.clone())
@@ -1944,7 +1944,7 @@ mod test {
 		);
 		assert_eq!(invoice.payee_pub_key(), Some(&public_key));
 		assert_eq!(invoice.expiry_time(), Duration::from_secs(54321));
-		assert_eq!(invoice.min_final_cltv_expiry(), 144);
+		assert_eq!(invoice.min_final_cltv_expiry_delta(), 144);
 		assert_eq!(invoice.fallbacks(), vec![&Fallback::PubKeyHash([0;20])]);
 		assert_eq!(invoice.private_routes(), vec![&PrivateRoute(route_1), &PrivateRoute(route_2)]);
 		assert_eq!(
@@ -1985,7 +1985,7 @@ mod test {
 			.unwrap();
 		let invoice = Invoice::from_signed(signed_invoice).unwrap();
 
-		assert_eq!(invoice.min_final_cltv_expiry(), DEFAULT_MIN_FINAL_CLTV_EXPIRY);
+		assert_eq!(invoice.min_final_cltv_expiry_delta(), DEFAULT_MIN_FINAL_CLTV_EXPIRY_DELTA);
 		assert_eq!(invoice.expiry_time(), Duration::from_secs(DEFAULT_EXPIRY_TIME));
 		assert!(!invoice.would_expire(Duration::from_secs(1234568)));
 	}

lightning-invoice/src/payment.rs

@@ -455,7 +455,7 @@ where
 		let route_params = RouteParameters {
 			payment_params,
 			final_value_msat: invoice.amount_milli_satoshis().or(amount_msats).unwrap(),
-			final_cltv_expiry_delta: invoice.min_final_cltv_expiry() as u32,
+			final_cltv_expiry_delta: invoice.min_final_cltv_expiry_delta() as u32,
 		};
 
 		let send_payment = |route: &Route| {
@@ -787,7 +787,7 @@ mod tests {
 			.payment_hash(payment_hash)
 			.payment_secret(PaymentSecret([0; 32]))
 			.duration_since_epoch(duration_since_epoch())
-			.min_final_cltv_expiry(144)
+			.min_final_cltv_expiry_delta(144)
 			.amount_milli_satoshis(128)
 			.build_signed(|hash| {
 				Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)
@@ -813,7 +813,7 @@ mod tests {
 			.payment_hash(payment_hash)
 			.payment_secret(PaymentSecret([0; 32]))
 			.duration_since_epoch(duration_since_epoch())
-			.min_final_cltv_expiry(144)
+			.min_final_cltv_expiry_delta(144)
 			.build_signed(|hash| {
 				Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)
 			})
@@ -832,7 +832,7 @@ mod tests {
 			.payment_hash(payment_hash)
 			.payment_secret(PaymentSecret([0; 32]))
 			.duration_since_epoch(duration)
-			.min_final_cltv_expiry(144)
+			.min_final_cltv_expiry_delta(144)
 			.amount_milli_satoshis(128)
 			.build_signed(|hash| {
 				Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)
@@ -1688,7 +1688,7 @@ mod tests {
 			RouteParameters {
 				payment_params,
 				final_value_msat,
-				final_cltv_expiry_delta: invoice.min_final_cltv_expiry() as u32,
+				final_cltv_expiry_delta: invoice.min_final_cltv_expiry_delta() as u32,
 			}
 		}
 	}

lightning-invoice/src/ser.rs

@@ -435,7 +435,7 @@ impl ToBase32 for TaggedField {
 				write_tagged_field(writer, constants::TAG_EXPIRY_TIME, duration)
 			},
 			TaggedField::MinFinalCltvExpiry(ref expiry) => {
-				write_tagged_field(writer, constants::TAG_MIN_FINAL_CLTV_EXPIRY, expiry)
+				write_tagged_field(writer, constants::TAG_MIN_FINAL_CLTV_EXPIRY_DELTA, expiry)
 			},
 			TaggedField::Fallback(ref fallback_address) => {
 				write_tagged_field(writer, constants::TAG_FALLBACK, fallback_address)

lightning-invoice/src/utils.rs

@@ -10,7 +10,7 @@ use lightning::chain;
 use lightning::chain::chaininterface::{BroadcasterInterface, FeeEstimator};
 use lightning::chain::keysinterface::{Recipient, KeysInterface};
 use lightning::ln::{PaymentHash, PaymentPreimage, PaymentSecret};
-use lightning::ln::channelmanager::{ChannelDetails, ChannelManager, PaymentId, PaymentSendFailure, MIN_FINAL_CLTV_EXPIRY};
+use lightning::ln::channelmanager::{ChannelDetails, ChannelManager, PaymentId, PaymentSendFailure, MIN_FINAL_CLTV_EXPIRY_DELTA};
 #[cfg(feature = "std")]
 use lightning::ln::channelmanager::{PhantomRouteHints, MIN_CLTV_EXPIRY_DELTA};
 use lightning::ln::inbound_payment::{create, create_from_hash, ExpandedKey};
@@ -179,7 +179,7 @@ where
 		.current_timestamp()
 		.payment_hash(Hash::from_slice(&payment_hash.0).unwrap())
 		.payment_secret(payment_secret)
-		.min_final_cltv_expiry(MIN_FINAL_CLTV_EXPIRY.into())
+		.min_final_cltv_expiry_delta(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);
@@ -370,7 +370,7 @@ where
 		.payment_hash(Hash::from_slice(&payment_hash.0).unwrap())
 		.payment_secret(payment_secret)
 		.basic_mpp()
-		.min_final_cltv_expiry(MIN_FINAL_CLTV_EXPIRY.into())
+		.min_final_cltv_expiry_delta(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);
@@ -688,7 +688,7 @@ mod test {
 	use bitcoin_hashes::sha256::Hash as Sha256;
 	use lightning::chain::keysinterface::PhantomKeysManager;
 	use lightning::ln::{PaymentPreimage, PaymentHash};
-	use lightning::ln::channelmanager::{self, PhantomRouteHints, MIN_FINAL_CLTV_EXPIRY, PaymentId};
+	use lightning::ln::channelmanager::{self, PhantomRouteHints, MIN_FINAL_CLTV_EXPIRY_DELTA, PaymentId};
 	use lightning::ln::functional_test_utils::*;
 	use lightning::ln::msgs::ChannelMessageHandler;
 	use lightning::routing::router::{PaymentParameters, RouteParameters, find_route};
@@ -712,7 +712,7 @@ mod test {
 			Some(10_000), "test".to_string(), Duration::from_secs(1234567),
 			non_default_invoice_expiry_secs).unwrap();
 		assert_eq!(invoice.amount_pico_btc(), Some(100_000));
-		assert_eq!(invoice.min_final_cltv_expiry(), MIN_FINAL_CLTV_EXPIRY as u64);
+		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()));
 
@@ -732,7 +732,7 @@ mod test {
 		let route_params = RouteParameters {
 			payment_params,
 			final_value_msat: invoice.amount_milli_satoshis().unwrap(),
-			final_cltv_expiry_delta: invoice.min_final_cltv_expiry() as u32,
+			final_cltv_expiry_delta: invoice.min_final_cltv_expiry_delta() as u32,
 		};
 		let first_hops = nodes[0].node.list_usable_channels();
 		let network_graph = &node_cfgs[0].network_graph;
@@ -778,7 +778,7 @@ mod test {
 			Some(10_000), description_hash, Duration::from_secs(1234567), 3600
 		).unwrap();
 		assert_eq!(invoice.amount_pico_btc(), Some(100_000));
-		assert_eq!(invoice.min_final_cltv_expiry(), MIN_FINAL_CLTV_EXPIRY as u64);
+		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()))));
 	}
 
@@ -1028,7 +1028,7 @@ mod test {
 			nodes[1].node.get_payment_preimage(payment_hash, payment_secret).unwrap()
 		};
 
-		assert_eq!(invoice.min_final_cltv_expiry(), MIN_FINAL_CLTV_EXPIRY as u64);
+		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.route_hints().len(), 2);
 		assert_eq!(invoice.expiry_time(), Duration::from_secs(non_default_invoice_expiry_secs.into()));
@@ -1040,7 +1040,7 @@ mod test {
 		let params = RouteParameters {
 			payment_params,
 			final_value_msat: invoice.amount_milli_satoshis().unwrap(),
-			final_cltv_expiry_delta: invoice.min_final_cltv_expiry() as u32,
+			final_cltv_expiry_delta: invoice.min_final_cltv_expiry_delta() as u32,
 		};
 		let first_hops = nodes[0].node.list_usable_channels();
 		let network_graph = &node_cfgs[0].network_graph;
@@ -1161,7 +1161,7 @@ mod test {
 		)
 		.unwrap();
 		assert_eq!(invoice.amount_pico_btc(), Some(200_000));
-		assert_eq!(invoice.min_final_cltv_expiry(), MIN_FINAL_CLTV_EXPIRY as u64);
+		assert_eq!(invoice.min_final_cltv_expiry_delta(), MIN_FINAL_CLTV_EXPIRY_DELTA as u64);
 		assert_eq!(invoice.expiry_time(), Duration::from_secs(non_default_invoice_expiry_secs.into()));
 		assert_eq!(invoice.description(), InvoiceDescription::Hash(&crate::Sha256(Sha256::hash("Description hash phantom invoice".as_bytes()))));
 	}

lightning-invoice/tests/ser_de.rs

@@ -246,7 +246,7 @@ fn get_test_tuples() -> Vec<(String, SignedRawInvoice, bool, bool)> {
 					"462264ede7e14047e9b249da94fefc47f41f7d02ee9b091815a5506bc8abf75f"
 				).unwrap())
 				.expiry_time(Duration::from_secs(604800))
-				.min_final_cltv_expiry(10)
+				.min_final_cltv_expiry_delta(10)
 				.description("Blockstream Store: 88.85 USD for Blockstream Ledger Nano S x 1, \"Back In My Day\" Sticker x 2, \"I Got Lightning Working\" Sticker x 2 and 1 more items".to_owned())
 				.private_route(RouteHint(vec![RouteHintHop {
 					src_node_id: PublicKey::from_slice(&hex::decode(

lightning/src/ln/channelmanager.rs

@@ -950,12 +950,12 @@ pub const MIN_CLTV_EXPIRY_DELTA: u16 = 6*7;
 pub(super) const CLTV_FAR_FAR_AWAY: u32 = 14 * 24 * 6;
 
 /// Minimum CLTV difference between the current block height and received inbound payments.
-/// Invoices generated for payment to us must set their `min_final_cltv_expiry` field to at least
+/// Invoices generated for payment to us must set their `min_final_cltv_expiry_delta` field to at least
 /// this value.
 // Note that we fail if exactly HTLC_FAIL_BACK_BUFFER + 1 was used, so we need to add one for
 // any payments to succeed. Further, we don't want payments to fail if a block was found while
 // a payment was being routed, so we add an extra block to be safe.
-pub const MIN_FINAL_CLTV_EXPIRY: u32 = HTLC_FAIL_BACK_BUFFER + 3;
+pub const MIN_FINAL_CLTV_EXPIRY_DELTA: u32 = HTLC_FAIL_BACK_BUFFER + 3;
 
 // Check that our CLTV_EXPIRY is at least CLTV_CLAIM_BUFFER + ANTI_REORG_DELAY + LATENCY_GRACE_PERIOD_BLOCKS,
 // ie that if the next-hop peer fails the HTLC within
@@ -5612,8 +5612,8 @@ impl<M: Deref, T: Deref, K: Deref, F: Deref, L: Deref> ChannelManager<M, T, K, F
 	/// If you need exact expiry semantics, you should enforce them upon receipt of
 	/// [`PaymentReceived`].
 	///
-	/// Note that invoices generated for inbound payments should have their `min_final_cltv_expiry`
-	/// set to at least [`MIN_FINAL_CLTV_EXPIRY`].
+	/// Note that invoices generated for inbound payments should have their `min_final_cltv_expiry_delta`
+	/// set to at least [`MIN_FINAL_CLTV_EXPIRY_DELTA`].
 	///
 	/// Note that a malicious eavesdropper can intuit whether an inbound payment was created by
 	/// `create_inbound_payment` or `create_inbound_payment_for_hash` based on runtime.