diff --git a/fuzz/src/chanmon_consistency.rs b/fuzz/src/chanmon_consistency.rs index 2fd79819bc3..0caee0801aa 100644 --- a/fuzz/src/chanmon_consistency.rs +++ b/fuzz/src/chanmon_consistency.rs @@ -340,7 +340,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); diff --git a/fuzz/src/full_stack.rs b/fuzz/src/full_stack.rs index a1b1485ac45..fb2740c1de9 100644 --- a/fuzz/src/full_stack.rs +++ b/fuzz/src/full_stack.rs @@ -605,7 +605,7 @@ pub fn do_test(data: &[u8], logger: &Arc) { 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(..) { diff --git a/lightning-invoice/src/de.rs b/lightning-invoice/src/de.rs index 0759698b160..92c1cb5c28f 100644 --- a/lightning-invoice/src/de.rs +++ b/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}; @@ -451,8 +451,8 @@ 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 => - Ok(TaggedField::MinFinalCltvExpiry(MinFinalCltvExpiry::from_base32(field_data)?)), + constants::TAG_MIN_FINAL_CLTV_EXPIRY_DELTA => + 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 { + fn from_base32(field_data: &[u5]) -> Result { let expiry = parse_int_be::(field_data, 32); if let Some(expiry) = expiry { - Ok(MinFinalCltvExpiry(expiry)) + Ok(MinFinalCltvExpiryDelta(expiry)) } else { Err(ParseError::IntegerOverflowError) } @@ -840,14 +840,14 @@ mod test { } #[test] - fn test_parse_min_final_cltv_expiry() { - use crate::MinFinalCltvExpiry; + fn test_parse_min_final_cltv_expiry_delta() { + 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] diff --git a/lightning-invoice/src/lib.rs b/lightning-invoice/src/lib.rs index c01dfa47ba0..17b6e2de2b6 100644 --- a/lightning-invoice/src/lib.rs +++ b/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) /// }) @@ -410,7 +410,7 @@ pub enum TaggedField { PayeePubKey(PayeePubKey), DescriptionHash(Sha256), ExpiryTime(ExpiryTime), - MinFinalCltvExpiry(MinFinalCltvExpiry), + MinFinalCltvExpiryDelta(MinFinalCltvExpiryDelta), Fallback(Fallback), PrivateRoute(PrivateRoute), PaymentSecret(PaymentSecret), @@ -438,9 +438,9 @@ 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); +pub struct MinFinalCltvExpiryDelta(pub u64); // TODO: better types instead onf byte arrays /// Fallback address in case no LN payment is possible @@ -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 InvoiceBuilder InvoiceBuilder { - /// Sets `min_final_cltv_expiry`. - pub fn min_final_cltv_expiry(mut self, min_final_cltv_expiry: u64) -> InvoiceBuilder { - 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 { + self.tagged_fields.push(TaggedField::MinFinalCltvExpiryDelta(MinFinalCltvExpiryDelta(min_final_cltv_expiry_delta))); self.set_flags() } } @@ -929,8 +929,8 @@ impl RawInvoice { find_extract!(self.known_tagged_fields(), TaggedField::ExpiryTime(ref x), x) } - pub fn min_final_cltv_expiry(&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> { @@ -1243,12 +1243,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 @@ -1301,7 +1301,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::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, @@ -1448,6 +1448,11 @@ 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`]. + /// + /// [`MIN_FINAL_CLTV_EXPIRY_DELTA`]: lightning::ln::channelmanager::MIN_FINAL_CLTV_EXPIRY_DELTA + MinFinalCltvExpiryDeltaTooShort, } impl Display for CreationError { @@ -1458,6 +1463,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`"), } } } @@ -1804,7 +1811,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(|_| '?') @@ -1922,7 +1929,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()) @@ -1948,7 +1955,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!( @@ -1989,7 +1996,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))); } diff --git a/lightning-invoice/src/payment.rs b/lightning-invoice/src/payment.rs index 82f1149db1f..a3517264b4a 100644 --- a/lightning-invoice/src/payment.rs +++ b/lightning-invoice/src/payment.rs @@ -431,7 +431,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| { @@ -764,7 +764,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) @@ -790,7 +790,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) }) @@ -809,7 +809,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) @@ -1665,7 +1665,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, } } } @@ -2085,7 +2085,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); @@ -2130,7 +2130,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); @@ -2211,7 +2211,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); diff --git a/lightning-invoice/src/ser.rs b/lightning-invoice/src/ser.rs index 0bb1715e728..f5742289118 100644 --- a/lightning-invoice/src/ser.rs +++ b/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(&self, writer: &mut W) -> Result<(), ::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,8 +434,8 @@ impl ToBase32 for TaggedField { TaggedField::ExpiryTime(ref duration) => { write_tagged_field(writer, constants::TAG_EXPIRY_TIME, duration) }, - TaggedField::MinFinalCltvExpiry(ref expiry) => { - write_tagged_field(writer, constants::TAG_MIN_FINAL_CLTV_EXPIRY, expiry) + TaggedField::MinFinalCltvExpiryDelta(ref 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) diff --git a/lightning-invoice/src/utils.rs b/lightning-invoice/src/utils.rs index 76d5cf38ce6..0d6a1f11667 100644 --- a/lightning-invoice/src/utils.rs +++ b/lightning-invoice/src/utils.rs @@ -10,7 +10,7 @@ use lightning::chain; use lightning::chain::chaininterface::{BroadcasterInterface, FeeEstimator}; use lightning::chain::keysinterface::{Recipient, NodeSigner, SignerProvider, EntropySource}; 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}; @@ -42,6 +42,11 @@ use core::time::Duration; /// `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`] - 3. +/// Note that LDK will add a buffer of 3 blocks to the delta to allow for up to a few new block +/// confirmations during routing. +/// /// Note that the provided `keys_manager`'s `NodeSigner` implementation must support phantom /// invoices in its `sign_invoice` implementation ([`PhantomKeysManager`] satisfies this /// requirement). @@ -51,10 +56,11 @@ use core::time::Duration; /// [`ChannelManager::create_inbound_payment`]: lightning::ln::channelmanager::ChannelManager::create_inbound_payment /// [`ChannelManager::create_inbound_payment_for_hash`]: lightning::ln::channelmanager::ChannelManager::create_inbound_payment_for_hash /// [`PhantomRouteHints::channels`]: lightning::ln::channelmanager::PhantomRouteHints::channels +/// [`MIN_FINAL_CLTV_EXPIRY_DETLA`]: lightning::ln::channelmanager::MIN_FINAL_CLTV_EXPIRY_DELTA pub fn create_phantom_invoice( amt_msat: Option, payment_hash: Option, description: String, invoice_expiry_delta_secs: u32, phantom_route_hints: Vec, entropy_source: ES, - node_signer: NS, logger: L, network: Currency, + node_signer: NS, logger: L, network: Currency, min_final_cltv_expiry_delta: Option, ) -> Result> where ES::Target: EntropySource, @@ -65,7 +71,7 @@ where let description = InvoiceDescription::Direct(&description,); _create_phantom_invoice::( amt_msat, payment_hash, description, invoice_expiry_delta_secs, phantom_route_hints, - entropy_source, node_signer, logger, network, + entropy_source, node_signer, logger, network, min_final_cltv_expiry_delta, ) } @@ -104,7 +110,7 @@ where pub fn create_phantom_invoice_with_description_hash( amt_msat: Option, payment_hash: Option, invoice_expiry_delta_secs: u32, description_hash: Sha256, phantom_route_hints: Vec, entropy_source: ES, - node_signer: NS, logger: L, network: Currency + node_signer: NS, logger: L, network: Currency, min_final_cltv_expiry_delta: Option, ) -> Result> where ES::Target: EntropySource, @@ -114,6 +120,7 @@ where _create_phantom_invoice::( amt_msat, payment_hash, InvoiceDescription::Hash(&description_hash), invoice_expiry_delta_secs, phantom_route_hints, entropy_source, node_signer, logger, network, + min_final_cltv_expiry_delta, ) } @@ -121,7 +128,7 @@ where fn _create_phantom_invoice( amt_msat: Option, payment_hash: Option, description: InvoiceDescription, invoice_expiry_delta_secs: u32, phantom_route_hints: Vec, entropy_source: ES, - node_signer: NS, logger: L, network: Currency, + node_signer: NS, logger: L, network: Currency, min_final_cltv_expiry_delta: Option, ) -> Result> where ES::Target: EntropySource, @@ -136,6 +143,10 @@ where )); } + if min_final_cltv_expiry_delta.is_some() && min_final_cltv_expiry_delta.unwrap().saturating_add(3) < MIN_FINAL_CLTV_EXPIRY_DELTA { + return Err(SignOrCreationError::CreationError(CreationError::MinFinalCltvExpiryDeltaTooShort)); + } + let invoice = match description { InvoiceDescription::Direct(description) => { InvoiceBuilder::new(network).description(description.0.clone()) @@ -155,6 +166,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) @@ -168,6 +180,7 @@ where .duration_since(UNIX_EPOCH) .expect("Time must be > 1970") .as_secs(), + min_final_cltv_expiry_delta, ) .map_err(|_| SignOrCreationError::CreationError(CreationError::InvalidAmount))? }; @@ -179,7 +192,9 @@ 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( + // Add a buffer of 3 to the delta if present, otherwise use LDK's minimum. + min_final_cltv_expiry_delta.map(|x| x.saturating_add(3)).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); @@ -235,9 +250,17 @@ 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`]. +/// Note that LDK will add a buffer of 3 blocks to the delta to allow for up to a few new block +/// confirmations during routing. +/// +/// [`MIN_FINAL_CLTV_EXPIRY_DETLA`]: lightning::ln::channelmanager::MIN_FINAL_CLTV_EXPIRY_DELTA pub fn create_invoice_from_channelmanager( channelmanager: &ChannelManager, node_signer: NS, logger: L, - network: Currency, amt_msat: Option, description: String, invoice_expiry_delta_secs: u32 + network: Currency, amt_msat: Option, description: String, invoice_expiry_delta_secs: u32, + min_final_cltv_expiry_delta: Option, ) -> Result> where M::Target: chain::Watch<::Signer>, @@ -254,7 +277,7 @@ where .expect("for the foreseeable future this shouldn't happen"); create_invoice_from_channelmanager_and_duration_since_epoch( channelmanager, node_signer, logger, network, amt_msat, - description, duration, invoice_expiry_delta_secs + description, duration, invoice_expiry_delta_secs, min_final_cltv_expiry_delta, ) } @@ -268,10 +291,17 @@ 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`]. +/// Note that LDK will add a buffer of 3 blocks to the delta to allow for up to a few new block +/// confirmations during routing. +/// +/// [`MIN_FINAL_CLTV_EXPIRY_DETLA`]: lightning::ln::channelmanager::MIN_FINAL_CLTV_EXPIRY_DELTA pub fn create_invoice_from_channelmanager_with_description_hash( channelmanager: &ChannelManager, node_signer: NS, logger: L, network: Currency, amt_msat: Option, description_hash: Sha256, - invoice_expiry_delta_secs: u32 + invoice_expiry_delta_secs: u32, min_final_cltv_expiry_delta: Option, ) -> Result> where M::Target: chain::Watch<::Signer>, @@ -291,7 +321,7 @@ where create_invoice_from_channelmanager_with_description_hash_and_duration_since_epoch( channelmanager, node_signer, logger, network, amt_msat, - description_hash, duration, invoice_expiry_delta_secs + description_hash, duration, invoice_expiry_delta_secs, min_final_cltv_expiry_delta, ) } @@ -301,7 +331,7 @@ where pub fn create_invoice_from_channelmanager_with_description_hash_and_duration_since_epoch( channelmanager: &ChannelManager, node_signer: NS, logger: L, network: Currency, amt_msat: Option, 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, ) -> Result> where M::Target: chain::Watch<::Signer>, @@ -316,7 +346,7 @@ pub fn create_invoice_from_channelmanager_with_description_hash_and_duration_sin _create_invoice_from_channelmanager_and_duration_since_epoch( channelmanager, node_signer, 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, ) } @@ -326,7 +356,7 @@ pub fn create_invoice_from_channelmanager_with_description_hash_and_duration_sin pub fn create_invoice_from_channelmanager_and_duration_since_epoch( channelmanager: &ChannelManager, node_signer: NS, logger: L, network: Currency, amt_msat: Option, description: String, duration_since_epoch: Duration, - invoice_expiry_delta_secs: u32 + invoice_expiry_delta_secs: u32, min_final_cltv_expiry_delta: Option, ) -> Result> where M::Target: chain::Watch<::Signer>, @@ -343,14 +373,14 @@ pub fn create_invoice_from_channelmanager_and_duration_since_epoch( channelmanager: &ChannelManager, node_signer: NS, logger: L, network: Currency, amt_msat: Option, 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, ) -> Result> where M::Target: chain::Watch<::Signer>, @@ -362,13 +392,18 @@ fn _create_invoice_from_channelmanager_and_duration_since_epoch( channelmanager: &ChannelManager, node_signer: NS, logger: L, network: Currency, amt_msat: Option, description: String, duration_since_epoch: Duration, - invoice_expiry_delta_secs: u32, payment_hash: PaymentHash + invoice_expiry_delta_secs: u32, payment_hash: PaymentHash, min_final_cltv_expiry_delta: Option, ) -> Result> where M::Target: chain::Watch<::Signer>, @@ -391,21 +426,24 @@ 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, InvoiceDescription::Direct( &Description::new(description).map_err(SignOrCreationError::CreationError)?, ), - duration_since_epoch, invoice_expiry_delta_secs, payment_hash, payment_secret + duration_since_epoch, invoice_expiry_delta_secs, payment_hash, payment_secret, + min_final_cltv_expiry_delta, ) } fn _create_invoice_from_channelmanager_and_duration_since_epoch_with_payment_hash( channelmanager: &ChannelManager, node_signer: NS, logger: L, network: Currency, amt_msat: Option, description: InvoiceDescription, duration_since_epoch: Duration, - invoice_expiry_delta_secs: u32, payment_hash: PaymentHash, payment_secret: PaymentSecret + invoice_expiry_delta_secs: u32, payment_hash: PaymentHash, payment_secret: PaymentSecret, + min_final_cltv_expiry_delta: Option, ) -> Result> where M::Target: chain::Watch<::Signer>, @@ -420,6 +458,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().saturating_add(3) < 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 { @@ -435,7 +477,9 @@ fn _create_invoice_from_channelmanager_and_duration_since_epoch_with_payment_has .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( + // Add a buffer of 3 to the delta if present, otherwise use LDK's minimum. + min_final_cltv_expiry_delta.map(|x| x.saturating_add(3)).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); @@ -637,12 +681,12 @@ where #[cfg(test)] mod test { use core::time::Duration; - use crate::{Currency, Description, InvoiceDescription}; + use crate::{Currency, Description, InvoiceDescription, SignOrCreationError, CreationError}; use bitcoin_hashes::{Hash, sha256}; use bitcoin_hashes::sha256::Hash as Sha256; use lightning::chain::keysinterface::{EntropySource, PhantomKeysManager}; use lightning::ln::{PaymentPreimage, PaymentHash}; - use lightning::ln::channelmanager::{PhantomRouteHints, MIN_FINAL_CLTV_EXPIRY, PaymentId}; + use lightning::ln::channelmanager::{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}; @@ -663,9 +707,10 @@ 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)); - assert_eq!(invoice.min_final_cltv_expiry(), MIN_FINAL_CLTV_EXPIRY as u64); + // 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())); @@ -685,7 +730,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; @@ -719,6 +764,44 @@ mod test { assert_eq!(events.len(), 2); } + fn do_create_invoice_min_final_cltv_delta(with_custom_delta: bool) { + 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 custom_min_final_cltv_expiry_delta = Some(50); + + 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), "".into(), Duration::from_secs(1234567), 3600, + if with_custom_delta { custom_min_final_cltv_expiry_delta } else { None }, + ).unwrap(); + assert_eq!(invoice.min_final_cltv_expiry_delta(), if with_custom_delta { + custom_min_final_cltv_expiry_delta.unwrap() + 3 /* Buffer */} else { MIN_FINAL_CLTV_EXPIRY_DELTA } as u64); + } + + #[test] + fn test_create_invoice_custom_min_final_cltv_delta() { + do_create_invoice_min_final_cltv_delta(true); + do_create_invoice_min_final_cltv_delta(false); + } + + #[test] + fn create_invoice_min_final_cltv_delta_equals_htlc_fail_buffer() { + 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 custom_min_final_cltv_expiry_delta = Some(21); + + 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), "".into(), Duration::from_secs(1234567), 3600, + custom_min_final_cltv_expiry_delta, + ).unwrap(); + assert_eq!(invoice.min_final_cltv_expiry_delta(), MIN_FINAL_CLTV_EXPIRY_DELTA as u64); + } + #[test] fn test_create_invoice_with_description_hash() { let chanmon_cfgs = create_chanmon_cfgs(2); @@ -728,10 +811,10 @@ 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(), 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())))); } @@ -745,10 +828,10 @@ mod test { let invoice = crate::utils::create_invoice_from_channelmanager_and_duration_since_epoch_with_payment_hash( &nodes[1].node, nodes[1].keys_manager, nodes[1].logger, Currency::BitcoinTestnet, Some(10_000), "test".to_string(), Duration::from_secs(1234567), 3600, - payment_hash + payment_hash, None, ).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.payment_hash(), &sha256::Hash::from_slice(&payment_hash.0[..]).unwrap()); } @@ -936,7 +1019,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 { @@ -988,7 +1071,8 @@ mod test { let invoice = crate::utils::create_phantom_invoice::<&test_utils::TestKeysInterface, &test_utils::TestKeysInterface, &test_utils::TestLogger>( Some(payment_amt), payment_hash, "test".to_string(), non_default_invoice_expiry_secs, - route_hints, &nodes[1].keys_manager, &nodes[1].keys_manager, &nodes[1].logger, Currency::BitcoinTestnet + route_hints, &nodes[1].keys_manager, &nodes[1].keys_manager, &nodes[1].logger, + Currency::BitcoinTestnet, None, ).unwrap(); let (payment_hash, payment_secret) = (PaymentHash(invoice.payment_hash().into_inner()), *invoice.payment_secret()); let payment_preimage = if user_generated_pmt_hash { @@ -997,7 +1081,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())); @@ -1009,7 +1093,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; @@ -1089,13 +1173,16 @@ 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(), ]; - let invoice = crate::utils::create_phantom_invoice::<&test_utils::TestKeysInterface, &test_utils::TestKeysInterface, &test_utils::TestLogger>(Some(payment_amt), Some(payment_hash), "test".to_string(), 3600, route_hints, &nodes[1].keys_manager, &nodes[1].keys_manager, &nodes[1].logger, Currency::BitcoinTestnet).unwrap(); + let invoice = crate::utils::create_phantom_invoice::<&test_utils::TestKeysInterface, + &test_utils::TestKeysInterface, &test_utils::TestLogger>(Some(payment_amt), Some(payment_hash), + "test".to_string(), 3600, route_hints, &nodes[1].keys_manager, &nodes[1].keys_manager, + &nodes[1].logger, Currency::BitcoinTestnet, None).unwrap(); let chan_0_1 = &nodes[1].node.list_usable_channels()[0]; assert_eq!(invoice.route_hints()[0].0[0].htlc_minimum_msat, chan_0_1.inbound_htlc_minimum_msat); @@ -1126,15 +1213,42 @@ mod test { &test_utils::TestKeysInterface, &test_utils::TestKeysInterface, &test_utils::TestLogger, >( Some(payment_amt), None, non_default_invoice_expiry_secs, description_hash, - route_hints, &nodes[1].keys_manager, &nodes[1].keys_manager, &nodes[1].logger, Currency::BitcoinTestnet + route_hints, &nodes[1].keys_manager, &nodes[1].keys_manager, &nodes[1].logger, + Currency::BitcoinTestnet, None, ) .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())))); } + #[test] + #[cfg(feature = "std")] + fn create_phantom_invoice_with_custom_payment_hash_and_custom_min_final_cltv_delta() { + let chanmon_cfgs = create_chanmon_cfgs(3); + let node_cfgs = create_node_cfgs(3, &chanmon_cfgs); + let node_chanmgrs = create_node_chanmgrs(3, &node_cfgs, &[None, None, None]); + let nodes = create_network(3, &node_cfgs, &node_chanmgrs); + + let payment_amt = 20_000; + let route_hints = vec![ + nodes[1].node.get_phantom_route_hints(), + nodes[2].node.get_phantom_route_hints(), + ]; + let user_payment_preimage = PaymentPreimage([1; 32]); + let payment_hash = Some(PaymentHash(Sha256::hash(&user_payment_preimage.0[..]).into_inner())); + let non_default_invoice_expiry_secs = 4200; + let min_final_cltv_expiry_delta = Some(100); + let invoice = crate::utils::create_phantom_invoice::<&test_utils::TestKeysInterface, + &test_utils::TestKeysInterface, &test_utils::TestLogger>(Some(payment_amt), payment_hash, + "".to_string(), non_default_invoice_expiry_secs, route_hints, &nodes[1].keys_manager, &nodes[1].keys_manager, + &nodes[1].logger, Currency::BitcoinTestnet, min_final_cltv_expiry_delta).unwrap(); + assert_eq!(invoice.amount_pico_btc(), Some(200_000)); + assert_eq!(invoice.min_final_cltv_expiry_delta(), (min_final_cltv_expiry_delta.unwrap() + 3) as u64); + assert_eq!(invoice.expiry_time(), Duration::from_secs(non_default_invoice_expiry_secs.into())); + } + #[test] #[cfg(feature = "std")] fn test_multi_node_hints_includes_single_channels_to_participating_nodes() { @@ -1440,7 +1554,10 @@ mod test { .map(|route_hint| route_hint.phantom_scid) .collect::>(); - let invoice = crate::utils::create_phantom_invoice::<&test_utils::TestKeysInterface, &test_utils::TestKeysInterface, &test_utils::TestLogger>(invoice_amt, None, "test".to_string(), 3600, phantom_route_hints, &invoice_node.keys_manager, &invoice_node.keys_manager, &invoice_node.logger, Currency::BitcoinTestnet).unwrap(); + let invoice = crate::utils::create_phantom_invoice::<&test_utils::TestKeysInterface, + &test_utils::TestKeysInterface, &test_utils::TestLogger>(invoice_amt, None, "test".to_string(), + 3600, phantom_route_hints, &invoice_node.keys_manager, &invoice_node.keys_manager, + &invoice_node.logger, Currency::BitcoinTestnet, None).unwrap(); let invoice_hints = invoice.private_routes(); @@ -1463,4 +1580,20 @@ mod test { } assert!(chan_ids_to_match.is_empty(), "Unmatched short channel ids: {:?}", chan_ids_to_match); } + + #[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 - 4), + ); + match result { + Err(SignOrCreationError::CreationError(CreationError::MinFinalCltvExpiryDeltaTooShort)) => {}, + _ => panic!(), + } + } } diff --git a/lightning-invoice/tests/ser_de.rs b/lightning-invoice/tests/ser_de.rs index ffac702ce1a..272d9062a6e 100644 --- a/lightning-invoice/tests/ser_de.rs +++ b/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( diff --git a/lightning/src/ln/channelmanager.rs b/lightning/src/ln/channelmanager.rs index d08f8da5558..db326a2ecb5 100644 --- a/lightning/src/ln/channelmanager.rs +++ b/lightning/src/ln/channelmanager.rs @@ -874,12 +874,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: u16 = HTLC_FAIL_BACK_BUFFER as u16 + 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 @@ -1914,6 +1914,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). @@ -3181,13 +3182,23 @@ where match claimable_htlc.onion_payload { OnionPayload::Invoice { .. } => { let payment_data = payment_data.unwrap(); - 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, + let (payment_preimage, min_final_cltv_expiry_delta) = match inbound_payment::verify(payment_hash, &payment_data, self.highest_seen_timestamp.load(Ordering::Acquire) as u64, &self.inbound_payment_key, &self.logger) { + Ok(result) => result, 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) = min_final_cltv_expiry_delta { + 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) => { @@ -5273,12 +5284,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, 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, invoice_expiry_delta_secs: u32, + min_final_cltv_expiry_delta: Option) -> 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 @@ -5326,8 +5343,8 @@ where /// If you need exact expiry semantics, you should enforce them upon receipt of /// [`PaymentClaimable`]. /// - /// 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. @@ -5339,10 +5356,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, invoice_expiry_delta_secs: u32) -> Result { - 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, + invoice_expiry_delta_secs: u32, min_final_cltv_expiry: Option) -> Result { + 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 @@ -7369,7 +7392,7 @@ where payment_preimage: match pending_inbound_payments.get(&payment_hash) { Some(inbound_payment) => inbound_payment.payment_preimage, None => match inbound_payment::verify(payment_hash, &hop_data, 0, &expanded_inbound_key, &args.logger) { - Ok(payment_preimage) => payment_preimage, + Ok((payment_preimage, _)) => payment_preimage, Err(()) => { log_error!(args.logger, "Failed to read claimable payment data for HTLC with payment hash {} - was not a pending inbound payment and didn't match our payment key", log_bytes!(payment_hash.0)); return Err(DecodeError::InvalidValue); @@ -8505,7 +8528,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()); diff --git a/lightning/src/ln/functional_test_utils.rs b/lightning/src/ln/functional_test_utils.rs index 566c568b653..868b38e3fda 100644 --- a/lightning/src/ln/functional_test_utils.rs +++ b/lightning/src/ln/functional_test_utils.rs @@ -1447,6 +1447,11 @@ 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(); @@ -1454,10 +1459,10 @@ macro_rules! get_payment_preimage_hash { *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] diff --git a/lightning/src/ln/functional_tests.rs b/lightning/src/ln/functional_tests.rs index 1260561844b..401b46774a8 100644 --- a/lightning/src/ln/functional_tests.rs +++ b/lightning/src/ln/functional_tests.rs @@ -1246,7 +1246,7 @@ fn test_duplicate_htlc_different_direction_onchain() { let (payment_preimage, payment_hash, _) = route_payment(&nodes[0], &vec!(&nodes[1])[..], 900_000); let (route, _, _, _) = get_route_and_payment_hash!(nodes[1], nodes[0], 800_000); - let node_a_payment_secret = nodes[0].node.create_inbound_payment_for_hash(payment_hash, None, 7200).unwrap(); + let node_a_payment_secret = nodes[0].node.create_inbound_payment_for_hash(payment_hash, None, 7200, None).unwrap(); send_along_route_with_secret(&nodes[1], route, &[&[&nodes[0]]], 800_000, payment_hash, node_a_payment_secret); // Provide preimage to node 0 by claiming payment @@ -4712,7 +4712,7 @@ fn test_duplicate_payment_hash_one_failure_one_success() { let (our_payment_preimage, duplicate_payment_hash, _) = route_payment(&nodes[0], &[&nodes[1], &nodes[2]], 900_000); - let payment_secret = nodes[3].node.create_inbound_payment_for_hash(duplicate_payment_hash, None, 7200).unwrap(); + let payment_secret = nodes[3].node.create_inbound_payment_for_hash(duplicate_payment_hash, None, 7200, None).unwrap(); // We reduce the final CLTV here by a somewhat arbitrary constant to keep it under the one-byte // script push size limit so that the below script length checks match // ACCEPTED_HTLC_SCRIPT_WEIGHT. @@ -4925,30 +4925,30 @@ fn do_test_fail_backwards_unrevoked_remote_announce(deliver_last_raa: bool, anno let (_, payment_hash_2, _) = route_payment(&nodes[0], &[&nodes[2], &nodes[3], &nodes[4]], ds_dust_limit*1000); // not added < dust limit + HTLC tx fee let (route, _, _, _) = get_route_and_payment_hash!(nodes[1], nodes[5], ds_dust_limit*1000); // 2nd HTLC: - send_along_route_with_secret(&nodes[1], route.clone(), &[&[&nodes[2], &nodes[3], &nodes[5]]], ds_dust_limit*1000, payment_hash_1, nodes[5].node.create_inbound_payment_for_hash(payment_hash_1, None, 7200).unwrap()); // not added < dust limit + HTLC tx fee + send_along_route_with_secret(&nodes[1], route.clone(), &[&[&nodes[2], &nodes[3], &nodes[5]]], ds_dust_limit*1000, payment_hash_1, nodes[5].node.create_inbound_payment_for_hash(payment_hash_1, None, 7200, None).unwrap()); // not added < dust limit + HTLC tx fee // 3rd HTLC: - send_along_route_with_secret(&nodes[1], route, &[&[&nodes[2], &nodes[3], &nodes[5]]], ds_dust_limit*1000, payment_hash_2, nodes[5].node.create_inbound_payment_for_hash(payment_hash_2, None, 7200).unwrap()); // not added < dust limit + HTLC tx fee + send_along_route_with_secret(&nodes[1], route, &[&[&nodes[2], &nodes[3], &nodes[5]]], ds_dust_limit*1000, payment_hash_2, nodes[5].node.create_inbound_payment_for_hash(payment_hash_2, None, 7200, None).unwrap()); // not added < dust limit + HTLC tx fee // 4th HTLC: let (_, payment_hash_3, _) = route_payment(&nodes[0], &[&nodes[2], &nodes[3], &nodes[4]], 1000000); // 5th HTLC: let (_, payment_hash_4, _) = route_payment(&nodes[0], &[&nodes[2], &nodes[3], &nodes[4]], 1000000); let (route, _, _, _) = get_route_and_payment_hash!(nodes[1], nodes[5], 1000000); // 6th HTLC: - send_along_route_with_secret(&nodes[1], route.clone(), &[&[&nodes[2], &nodes[3], &nodes[5]]], 1000000, payment_hash_3, nodes[5].node.create_inbound_payment_for_hash(payment_hash_3, None, 7200).unwrap()); + send_along_route_with_secret(&nodes[1], route.clone(), &[&[&nodes[2], &nodes[3], &nodes[5]]], 1000000, payment_hash_3, nodes[5].node.create_inbound_payment_for_hash(payment_hash_3, None, 7200, None).unwrap()); // 7th HTLC: - send_along_route_with_secret(&nodes[1], route, &[&[&nodes[2], &nodes[3], &nodes[5]]], 1000000, payment_hash_4, nodes[5].node.create_inbound_payment_for_hash(payment_hash_4, None, 7200).unwrap()); + send_along_route_with_secret(&nodes[1], route, &[&[&nodes[2], &nodes[3], &nodes[5]]], 1000000, payment_hash_4, nodes[5].node.create_inbound_payment_for_hash(payment_hash_4, None, 7200, None).unwrap()); // 8th HTLC: let (_, payment_hash_5, _) = route_payment(&nodes[0], &[&nodes[2], &nodes[3], &nodes[4]], 1000000); // 9th HTLC: let (route, _, _, _) = get_route_and_payment_hash!(nodes[1], nodes[5], ds_dust_limit*1000); - send_along_route_with_secret(&nodes[1], route, &[&[&nodes[2], &nodes[3], &nodes[5]]], ds_dust_limit*1000, payment_hash_5, nodes[5].node.create_inbound_payment_for_hash(payment_hash_5, None, 7200).unwrap()); // not added < dust limit + HTLC tx fee + send_along_route_with_secret(&nodes[1], route, &[&[&nodes[2], &nodes[3], &nodes[5]]], ds_dust_limit*1000, payment_hash_5, nodes[5].node.create_inbound_payment_for_hash(payment_hash_5, None, 7200, None).unwrap()); // not added < dust limit + HTLC tx fee // 10th HTLC: let (_, payment_hash_6, _) = route_payment(&nodes[0], &[&nodes[2], &nodes[3], &nodes[4]], ds_dust_limit*1000); // not added < dust limit + HTLC tx fee // 11th HTLC: let (route, _, _, _) = get_route_and_payment_hash!(nodes[1], nodes[5], 1000000); - send_along_route_with_secret(&nodes[1], route, &[&[&nodes[2], &nodes[3], &nodes[5]]], 1000000, payment_hash_6, nodes[5].node.create_inbound_payment_for_hash(payment_hash_6, None, 7200).unwrap()); + send_along_route_with_secret(&nodes[1], route, &[&[&nodes[2], &nodes[3], &nodes[5]]], 1000000, payment_hash_6, nodes[5].node.create_inbound_payment_for_hash(payment_hash_6, None, 7200, None).unwrap()); // Double-check that six of the new HTLC were added // We now have six HTLCs pending over the dust limit and six HTLCs under the dust limit (ie, @@ -6922,7 +6922,7 @@ fn test_check_htlc_underpaying() { let payment_params = PaymentParameters::from_node_id(nodes[1].node.get_our_node_id()).with_features(nodes[1].node.invoice_features()); let route = get_route(&nodes[0].node.get_our_node_id(), &payment_params, &nodes[0].network_graph.read_only(), None, 10_000, TEST_FINAL_CLTV, nodes[0].logger, &scorer, &random_seed_bytes).unwrap(); let (_, our_payment_hash, _) = get_payment_preimage_hash!(nodes[0]); - let our_payment_secret = nodes[1].node.create_inbound_payment_for_hash(our_payment_hash, Some(100_000), 7200).unwrap(); + let our_payment_secret = nodes[1].node.create_inbound_payment_for_hash(our_payment_hash, Some(100_000), 7200, None).unwrap(); nodes[0].node.send_payment(&route, our_payment_hash, &Some(our_payment_secret), PaymentId(our_payment_hash.0)).unwrap(); check_added_monitors!(nodes[0], 1); @@ -7917,7 +7917,7 @@ fn test_preimage_storage() { create_announced_chan_between_nodes(&nodes, 0, 1).0.contents.short_channel_id; { - let (payment_hash, payment_secret) = nodes[1].node.create_inbound_payment(Some(100_000), 7200).unwrap(); + let (payment_hash, payment_secret) = nodes[1].node.create_inbound_payment(Some(100_000), 7200, None).unwrap(); let (route, _, _, _) = get_route_and_payment_hash!(nodes[0], nodes[1], 100_000); nodes[0].node.send_payment(&route, payment_hash, &Some(payment_secret), PaymentId(payment_hash.0)).unwrap(); check_added_monitors!(nodes[0], 1); @@ -8023,7 +8023,7 @@ fn test_bad_secret_hash() { let random_payment_hash = PaymentHash([42; 32]); let random_payment_secret = PaymentSecret([43; 32]); - let (our_payment_hash, our_payment_secret) = nodes[1].node.create_inbound_payment(Some(100_000), 2).unwrap(); + let (our_payment_hash, our_payment_secret) = nodes[1].node.create_inbound_payment(Some(100_000), 2, None).unwrap(); let (route, _, _, _) = get_route_and_payment_hash!(nodes[0], nodes[1], 100_000); // All the below cases should end up being handled exactly identically, so we macro the @@ -9582,3 +9582,60 @@ fn accept_busted_but_better_fee() { _ => panic!("Unexpected event"), }; } + +fn do_payment_with_custom_min_final_cltv_expiry(valid_delta: bool, use_user_hash: bool) { + let mut 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 min_final_cltv_expiry_delta = 120; + let final_cltv_expiry_delta = if valid_delta { min_final_cltv_expiry_delta + 2 } else { + min_final_cltv_expiry_delta - 2 }; + let recv_value = 100_000; + + create_chan_between_nodes(&nodes[0], &nodes[1]); + + let payment_parameters = PaymentParameters::from_node_id(nodes[1].node.get_our_node_id()); + let (payment_hash, payment_preimage, payment_secret) = if use_user_hash { + let (payment_preimage, payment_hash, payment_secret) = get_payment_preimage_hash!(nodes[1], + Some(recv_value), Some(min_final_cltv_expiry_delta)); + (payment_hash, payment_preimage, payment_secret) + } else { + let (payment_hash, payment_secret) = nodes[1].node.create_inbound_payment(Some(recv_value), 7200, Some(min_final_cltv_expiry_delta)).unwrap(); + (payment_hash, nodes[1].node.get_payment_preimage(payment_hash, payment_secret).unwrap(), payment_secret) + }; + let route = get_route!(nodes[0], payment_parameters, recv_value, final_cltv_expiry_delta as u32).unwrap(); + nodes[0].node.send_payment(&route, payment_hash, &Some(payment_secret), PaymentId(payment_hash.0)).unwrap(); + check_added_monitors!(nodes[0], 1); + let mut events = nodes[0].node.get_and_clear_pending_msg_events(); + assert_eq!(events.len(), 1); + let mut payment_event = SendEvent::from_event(events.pop().unwrap()); + nodes[1].node.handle_update_add_htlc(&nodes[0].node.get_our_node_id(), &payment_event.msgs[0]); + commitment_signed_dance!(nodes[1], nodes[0], payment_event.commitment_msg, false); + expect_pending_htlcs_forwardable!(nodes[1]); + + if valid_delta { + expect_payment_claimable!(nodes[1], payment_hash, payment_secret, recv_value, if use_user_hash { + None } else { Some(payment_preimage) }, nodes[1].node.get_our_node_id()); + + claim_payment(&nodes[0], &vec!(&nodes[1])[..], payment_preimage); + } else { + expect_pending_htlcs_forwardable_and_htlc_handling_failed!(nodes[1], vec![HTLCDestination::FailedPayment { payment_hash }]); + + check_added_monitors!(nodes[1], 1); + + let fail_updates = get_htlc_update_msgs!(nodes[1], nodes[0].node.get_our_node_id()); + nodes[0].node.handle_update_fail_htlc(&nodes[1].node.get_our_node_id(), &fail_updates.update_fail_htlcs[0]); + commitment_signed_dance!(nodes[0], nodes[1], fail_updates.commitment_signed, false, true); + + expect_payment_failed!(nodes[0], payment_hash, true); + } +} + +#[test] +fn test_payment_with_custom_min_cltv_expiry_delta() { + do_payment_with_custom_min_final_cltv_expiry(false, false); + do_payment_with_custom_min_final_cltv_expiry(false, true); + do_payment_with_custom_min_final_cltv_expiry(true, false); + do_payment_with_custom_min_final_cltv_expiry(true, true); +} diff --git a/lightning/src/ln/inbound_payment.rs b/lightning/src/ln/inbound_payment.rs index 0c80ae7bb4a..0c6d6f2b804 100644 --- a/lightning/src/ln/inbound_payment.rs +++ b/lightning/src/ln/inbound_payment.rs @@ -68,6 +68,8 @@ impl ExpandedKey { enum Method { LdkPaymentHash = 0, UserPaymentHash = 1, + LdkPaymentHashCustomFinalCltv = 2, + UserPaymentHashCustomFinalCltv = 3, } impl Method { @@ -75,11 +77,18 @@ impl Method { match bits { bits if bits == Method::LdkPaymentHash as u8 => Ok(Method::LdkPaymentHash), bits if bits == Method::UserPaymentHash as u8 => Ok(Method::UserPaymentHash), + bits if bits == Method::LdkPaymentHashCustomFinalCltv as u8 => Ok(Method::LdkPaymentHashCustomFinalCltv), + bits if bits == Method::UserPaymentHashCustomFinalCltv as u8 => Ok(Method::UserPaymentHashCustomFinalCltv), unknown => Err(unknown), } } } +fn min_final_cltv_expiry_delta_from_metadata(bytes: [u8; METADATA_LEN]) -> u16 { + let expiry_bytes = &bytes[AMT_MSAT_LEN..]; + u16::from_be_bytes([expiry_bytes[0], expiry_bytes[1]]) +} + /// Equivalent to [`crate::ln::channelmanager::ChannelManager::create_inbound_payment`], but no /// `ChannelManager` is required. Useful for generating invoices for [phantom node payments] without /// a `ChannelManager`. @@ -90,12 +99,21 @@ impl Method { /// /// `current_time` is a Unix timestamp representing the current time. /// +/// Note that 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. +/// /// [phantom node payments]: crate::chain::keysinterface::PhantomKeysManager /// [`NodeSigner::get_inbound_payment_key_material`]: crate::chain::keysinterface::NodeSigner::get_inbound_payment_key_material -pub fn create(keys: &ExpandedKey, min_value_msat: Option, invoice_expiry_delta_secs: u32, entropy_source: &ES, current_time: u64) -> Result<(PaymentHash, PaymentSecret), ()> +pub fn create(keys: &ExpandedKey, min_value_msat: Option, + invoice_expiry_delta_secs: u32, entropy_source: &ES, current_time: u64, + min_final_cltv_expiry_delta: Option) -> Result<(PaymentHash, PaymentSecret), ()> where ES::Target: EntropySource { - let metadata_bytes = construct_metadata_bytes(min_value_msat, Method::LdkPaymentHash, invoice_expiry_delta_secs, current_time)?; + let metadata_bytes = construct_metadata_bytes(min_value_msat, if min_final_cltv_expiry_delta.is_some() { + Method::LdkPaymentHashCustomFinalCltv + } else { + Method::LdkPaymentHash + }, invoice_expiry_delta_secs, current_time, min_final_cltv_expiry_delta)?; let mut iv_bytes = [0 as u8; IV_LEN]; let rand_bytes = entropy_source.get_secure_random_bytes(); @@ -117,9 +135,17 @@ pub fn create(keys: &ExpandedKey, min_value_msat: Option, invoic /// /// See [`create`] for information on the `keys` and `current_time` parameters. /// +/// Note that 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. +/// /// [phantom node payments]: crate::chain::keysinterface::PhantomKeysManager -pub fn create_from_hash(keys: &ExpandedKey, min_value_msat: Option, payment_hash: PaymentHash, invoice_expiry_delta_secs: u32, current_time: u64) -> Result { - let metadata_bytes = construct_metadata_bytes(min_value_msat, Method::UserPaymentHash, invoice_expiry_delta_secs, current_time)?; +pub fn create_from_hash(keys: &ExpandedKey, min_value_msat: Option, payment_hash: PaymentHash, + invoice_expiry_delta_secs: u32, current_time: u64, min_final_cltv_expiry_delta: Option) -> Result { + let metadata_bytes = construct_metadata_bytes(min_value_msat, if min_final_cltv_expiry_delta.is_some() { + Method::UserPaymentHashCustomFinalCltv + } else { + Method::UserPaymentHash + }, invoice_expiry_delta_secs, current_time, min_final_cltv_expiry_delta)?; let mut hmac = HmacEngine::::new(&keys.user_pmt_hash_key); hmac.input(&metadata_bytes); @@ -132,7 +158,8 @@ pub fn create_from_hash(keys: &ExpandedKey, min_value_msat: Option, payment Ok(construct_payment_secret(&iv_bytes, &metadata_bytes, &keys.metadata_key)) } -fn construct_metadata_bytes(min_value_msat: Option, payment_type: Method, invoice_expiry_delta_secs: u32, highest_seen_timestamp: u64) -> Result<[u8; METADATA_LEN], ()> { +fn construct_metadata_bytes(min_value_msat: Option, payment_type: Method, + invoice_expiry_delta_secs: u32, highest_seen_timestamp: u64, min_final_cltv_expiry_delta: Option) -> Result<[u8; METADATA_LEN], ()> { if min_value_msat.is_some() && min_value_msat.unwrap() > MAX_VALUE_MSAT { return Err(()); } @@ -148,9 +175,27 @@ fn construct_metadata_bytes(min_value_msat: Option, payment_type: Method, i // than two hours in the future. Thus, we add two hours here as a buffer to ensure we // absolutely never fail a payment too early. // Note that we assume that received blocks have reasonably up-to-date timestamps. - let expiry_bytes = (highest_seen_timestamp + invoice_expiry_delta_secs as u64 + 7200).to_be_bytes(); + let expiry_timestamp = highest_seen_timestamp + invoice_expiry_delta_secs as u64 + 7200; + let mut expiry_bytes = expiry_timestamp.to_be_bytes(); + + // `min_value_msat` should fit in (64 bits - 3 payment type bits =) 61 bits as an unsigned integer. + // This should leave us with a maximum value greater than the 21M BTC supply cap anyway. + if min_value_msat.is_some() && min_value_msat.unwrap() > ((1u64 << 61) - 1) { return Err(()); } + + // `expiry_timestamp` should fit in (64 bits - 2 delta bytes =) 48 bits as an unsigned integer. + // Bitcoin's block header timestamps are actually `u32`s, so we're technically already limited to + // the much smaller maximum timestamp of `u32::MAX` for now, but we check the u64 `expiry_timestamp` + // for future-proofing. + if min_final_cltv_expiry_delta.is_some() && expiry_timestamp > ((1u64 << 48) - 1) { return Err(()); } + + if let Some(min_final_cltv_expiry_delta) = min_final_cltv_expiry_delta { + let bytes = min_final_cltv_expiry_delta.to_be_bytes(); + expiry_bytes[0] |= bytes[0]; + expiry_bytes[1] |= bytes[1]; + } let mut metadata_bytes: [u8; METADATA_LEN] = [0; METADATA_LEN]; + metadata_bytes[..AMT_MSAT_LEN].copy_from_slice(&min_amt_msat_bytes); metadata_bytes[AMT_MSAT_LEN..].copy_from_slice(&expiry_bytes); @@ -175,9 +220,13 @@ fn construct_payment_secret(iv_bytes: &[u8; IV_LEN], metadata_bytes: &[u8; METAD /// secret (and, if supplied by LDK, our payment preimage) to include encrypted metadata about the /// payment. /// -/// The metadata is constructed as: +/// For payments without a custom `min_final_cltv_expiry_delta`, the metadata is constructed as: /// payment method (3 bits) || payment amount (8 bytes - 3 bits) || expiry (8 bytes) -/// and encrypted using a key derived from [`NodeSigner::get_inbound_payment_key_material`]. +/// +/// For payments including a custom `min_final_cltv_expiry_delta`, the metadata is constructed as: +/// payment method (3 bits) || payment amount (8 bytes - 3 bits) || min_final_cltv_expiry_delta (2 bytes) || expiry (6 bytes) +/// +/// In both cases the result is then encrypted using a key derived from [`NodeSigner::get_inbound_payment_key_material`]. /// /// Then on payment receipt, we verify in this method that the payment preimage and payment secret /// match what was constructed. @@ -201,24 +250,27 @@ fn construct_payment_secret(iv_bytes: &[u8; IV_LEN], metadata_bytes: &[u8; METAD /// [`NodeSigner::get_inbound_payment_key_material`]: crate::chain::keysinterface::NodeSigner::get_inbound_payment_key_material /// [`create_inbound_payment`]: crate::ln::channelmanager::ChannelManager::create_inbound_payment /// [`create_inbound_payment_for_hash`]: crate::ln::channelmanager::ChannelManager::create_inbound_payment_for_hash -pub(super) fn verify(payment_hash: PaymentHash, payment_data: &msgs::FinalOnionHopData, highest_seen_timestamp: u64, keys: &ExpandedKey, logger: &L) -> Result, ()> +pub(super) fn verify(payment_hash: PaymentHash, payment_data: &msgs::FinalOnionHopData, + highest_seen_timestamp: u64, keys: &ExpandedKey, logger: &L) -> Result< + (Option, Option), ()> where L::Target: Logger { let (iv_bytes, metadata_bytes) = decrypt_metadata(payment_data.payment_secret, keys); let payment_type_res = Method::from_bits((metadata_bytes[0] & 0b1110_0000) >> METHOD_TYPE_OFFSET); let mut amt_msat_bytes = [0; AMT_MSAT_LEN]; + let mut expiry_bytes = [0; METADATA_LEN - AMT_MSAT_LEN]; amt_msat_bytes.copy_from_slice(&metadata_bytes[..AMT_MSAT_LEN]); + expiry_bytes.copy_from_slice(&metadata_bytes[AMT_MSAT_LEN..]); // Zero out the bits reserved to indicate the payment type. amt_msat_bytes[0] &= 0b00011111; - let min_amt_msat: u64 = u64::from_be_bytes(amt_msat_bytes.into()); - let expiry = u64::from_be_bytes(metadata_bytes[AMT_MSAT_LEN..].try_into().unwrap()); + let mut min_final_cltv_expiry_delta = None; - // Make sure to check to check the HMAC before doing the other checks below, to mitigate timing - // attacks. + // Make sure to check the HMAC before doing the other checks below, to mitigate timing attacks. let mut payment_preimage = None; + match payment_type_res { - Ok(Method::UserPaymentHash) => { + Ok(Method::UserPaymentHash) | Ok(Method::UserPaymentHashCustomFinalCltv) => { let mut hmac = HmacEngine::::new(&keys.user_pmt_hash_key); hmac.input(&metadata_bytes[..]); hmac.input(&payment_hash.0); @@ -227,7 +279,7 @@ pub(super) fn verify(payment_hash: PaymentHash, payment_data: &msgs::F return Err(()) } }, - Ok(Method::LdkPaymentHash) => { + Ok(Method::LdkPaymentHash) | Ok(Method::LdkPaymentHashCustomFinalCltv) => { match derive_ldk_payment_preimage(payment_hash, &iv_bytes, &metadata_bytes, keys) { Ok(preimage) => payment_preimage = Some(preimage), Err(bad_preimage_bytes) => { @@ -242,6 +294,19 @@ pub(super) fn verify(payment_hash: PaymentHash, payment_data: &msgs::F } } + match payment_type_res { + Ok(Method::UserPaymentHashCustomFinalCltv) | Ok(Method::LdkPaymentHashCustomFinalCltv) => { + min_final_cltv_expiry_delta = Some(min_final_cltv_expiry_delta_from_metadata(metadata_bytes)); + // Zero out first two bytes of expiry reserved for `min_final_cltv_expiry_delta`. + expiry_bytes[0] &= 0; + expiry_bytes[1] &= 0; + } + _ => {} + } + + let min_amt_msat: u64 = u64::from_be_bytes(amt_msat_bytes.into()); + let expiry = u64::from_be_bytes(expiry_bytes.try_into().unwrap()); + if payment_data.total_msat < min_amt_msat { log_trace!(logger, "Failing HTLC with payment_hash {} due to total_msat {} being less than the minimum amount of {} msat", log_bytes!(payment_hash.0), payment_data.total_msat, min_amt_msat); return Err(()) @@ -252,20 +317,20 @@ pub(super) fn verify(payment_hash: PaymentHash, payment_data: &msgs::F return Err(()) } - Ok(payment_preimage) + Ok((payment_preimage, min_final_cltv_expiry_delta)) } pub(super) fn get_payment_preimage(payment_hash: PaymentHash, payment_secret: PaymentSecret, keys: &ExpandedKey) -> Result { let (iv_bytes, metadata_bytes) = decrypt_metadata(payment_secret, keys); match Method::from_bits((metadata_bytes[0] & 0b1110_0000) >> METHOD_TYPE_OFFSET) { - Ok(Method::LdkPaymentHash) => { + Ok(Method::LdkPaymentHash) | Ok(Method::LdkPaymentHashCustomFinalCltv) => { derive_ldk_payment_preimage(payment_hash, &iv_bytes, &metadata_bytes, keys) .map_err(|bad_preimage_bytes| APIError::APIMisuseError { err: format!("Payment hash {} did not match decoded preimage {}", log_bytes!(payment_hash.0), log_bytes!(bad_preimage_bytes)) }) }, - Ok(Method::UserPaymentHash) => Err(APIError::APIMisuseError { + Ok(Method::UserPaymentHash) | Ok(Method::UserPaymentHashCustomFinalCltv) => Err(APIError::APIMisuseError { err: "Expected payment type to be LdkPaymentHash, instead got UserPaymentHash".to_string() }), Err(other) => Err(APIError::APIMisuseError { err: format!("Unknown payment type: {}", other) }), diff --git a/lightning/src/ln/payment_tests.rs b/lightning/src/ln/payment_tests.rs index 2a9a180f3a9..b77a33ffdd2 100644 --- a/lightning/src/ln/payment_tests.rs +++ b/lightning/src/ln/payment_tests.rs @@ -910,7 +910,7 @@ fn get_ldk_payment_preimage() { let amt_msat = 60_000; let expiry_secs = 60 * 60; - let (payment_hash, payment_secret) = nodes[1].node.create_inbound_payment(Some(amt_msat), expiry_secs).unwrap(); + let (payment_hash, payment_secret) = nodes[1].node.create_inbound_payment(Some(amt_msat), expiry_secs, None).unwrap(); let payment_params = PaymentParameters::from_node_id(nodes[1].node.get_our_node_id()) .with_features(nodes[1].node.invoice_features()); @@ -1444,7 +1444,7 @@ fn do_test_intercepted_payment(test: InterceptTest) { route_params.final_cltv_expiry_delta, nodes[0].logger, &scorer, &random_seed_bytes ).unwrap(); - let (payment_hash, payment_secret) = nodes[2].node.create_inbound_payment(Some(amt_msat), 60 * 60).unwrap(); + let (payment_hash, payment_secret) = nodes[2].node.create_inbound_payment(Some(amt_msat), 60 * 60, None).unwrap(); nodes[0].node.send_payment(&route, payment_hash, &Some(payment_secret), PaymentId(payment_hash.0)).unwrap(); let payment_event = { { diff --git a/pending_changelog/1878.txt b/pending_changelog/1878.txt new file mode 100644 index 00000000000..775c46e53c3 --- /dev/null +++ b/pending_changelog/1878.txt @@ -0,0 +1,11 @@ +## API Updates +- The functions `inbound_payment::{create, create_from_hash}` and + `channelmanager::{create_inbound_payment, create_inbound_payment_for_hash}` now accept a + `min_final_cltv_expiry_delta` argument. This encodes the `min_final_cltv_expiry_delta` in the + payment secret metadata bytes to be validated on payment receipt. + +## Backwards Compatibility +- If `min_final_cltv_expiry_delta` set for any of `inbound_payment::{create, create_from_hash}` or + `channelmanager::{create_inbound_payment, create_inbound_payment_for_hash}` then the payment will + not be receivable on versions of LDK prior to 0.0.114. +