X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=lightning%2Fsrc%2Foffers%2Frefund.rs;h=ce39841df8c9750d9f4e7b717d1e3fb50e967d1a;hb=e94af0c3416744d5af5784e2d1dcf96d6f45b91f;hp=2c8dffeb1516abfa7961d144581d412657861c2a;hpb=4b241357387bcbb5cb51e00c83fab2dbeaebd0b3;p=rust-lightning diff --git a/lightning/src/offers/refund.rs b/lightning/src/offers/refund.rs index 2c8dffeb..ce39841d 100644 --- a/lightning/src/offers/refund.rs +++ b/lightning/src/offers/refund.rs @@ -18,6 +18,8 @@ //! [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest //! [`Offer`]: crate::offers::offer::Offer //! +//! # Example +//! //! ``` //! extern crate bitcoin; //! extern crate core; @@ -70,6 +72,14 @@ //! # Ok(()) //! # } //! ``` +//! +//! # Note +//! +//! If constructing a [`Refund`] for use with a [`ChannelManager`], use +//! [`ChannelManager::create_refund_builder`] instead of [`RefundBuilder::new`]. +//! +//! [`ChannelManager`]: crate::ln::channelmanager::ChannelManager +//! [`ChannelManager::create_refund_builder`]: crate::ln::channelmanager::ChannelManager::create_refund_builder use bitcoin::blockdata::constants::ChainHash; use bitcoin::network::constants::Network; @@ -82,6 +92,7 @@ use crate::sign::EntropySource; use crate::io; use crate::blinded_path::BlindedPath; use crate::ln::PaymentHash; +use crate::ln::channelmanager::PaymentId; use crate::ln::features::InvoiceRequestFeatures; use crate::ln::inbound_payment::{ExpandedKey, IV_LEN, Nonce}; use crate::ln::msgs::{DecodeError, MAX_VALUE_MSAT}; @@ -117,8 +128,16 @@ impl<'a> RefundBuilder<'a, secp256k1::SignOnly> { /// Creates a new builder for a refund using the [`Refund::payer_id`] for the public node id to /// send to if no [`Refund::paths`] are set. Otherwise, it may be a transient pubkey. /// - /// Additionally, sets the required [`Refund::description`], [`Refund::metadata`], and + /// Additionally, sets the required [`Refund::description`], [`Refund::payer_metadata`], and /// [`Refund::amount_msats`]. + /// + /// # Note + /// + /// If constructing a [`Refund`] for use with a [`ChannelManager`], use + /// [`ChannelManager::create_refund_builder`] instead of [`RefundBuilder::new`]. + /// + /// [`ChannelManager`]: crate::ln::channelmanager::ChannelManager + /// [`ChannelManager::create_refund_builder`]: crate::ln::channelmanager::ChannelManager::create_refund_builder pub fn new( description: String, metadata: Vec, payer_id: PublicKey, amount_msats: u64 ) -> Result { @@ -147,18 +166,22 @@ impl<'a, T: secp256k1::Signing> RefundBuilder<'a, T> { /// Also, sets the metadata when [`RefundBuilder::build`] is called such that it can be used to /// verify that an [`InvoiceRequest`] was produced for the refund given an [`ExpandedKey`]. /// + /// The `payment_id` is encrypted in the metadata and should be unique. This ensures that only + /// one invoice will be paid for the refund and that payments can be uniquely identified. + /// /// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest /// [`ExpandedKey`]: crate::ln::inbound_payment::ExpandedKey pub fn deriving_payer_id( description: String, node_id: PublicKey, expanded_key: &ExpandedKey, entropy_source: ES, - secp_ctx: &'a Secp256k1, amount_msats: u64 + secp_ctx: &'a Secp256k1, amount_msats: u64, payment_id: PaymentId ) -> Result where ES::Target: EntropySource { if amount_msats > MAX_VALUE_MSAT { return Err(Bolt12SemanticError::InvalidAmount); } let nonce = Nonce::from_entropy_source(entropy_source); - let derivation_material = MetadataMaterial::new(nonce, expanded_key, IV_BYTES); + let payment_id = Some(payment_id); + let derivation_material = MetadataMaterial::new(nonce, expanded_key, IV_BYTES, payment_id); let metadata = Metadata::DerivedSigningPubkey(derivation_material); Ok(Self { refund: RefundContents { @@ -201,8 +224,16 @@ impl<'a, T: secp256k1::Signing> RefundBuilder<'a, T> { /// called, [`Network::Bitcoin`] is assumed. /// /// Successive calls to this method will override the previous setting. - pub fn chain(mut self, network: Network) -> Self { - self.refund.chain = Some(ChainHash::using_genesis_block(network)); + pub fn chain(self, network: Network) -> Self { + self.chain_hash(ChainHash::using_genesis_block(network)) + } + + /// Sets the [`Refund::chain`] of the given [`ChainHash`] for paying an invoice. If not called, + /// [`Network::Bitcoin`] is assumed. + /// + /// Successive calls to this method will override the previous setting. + pub(crate) fn chain_hash(mut self, chain: ChainHash) -> Self { + self.refund.chain = Some(chain); self } @@ -244,7 +275,7 @@ impl<'a, T: secp256k1::Signing> RefundBuilder<'a, T> { let mut tlv_stream = self.refund.as_tlv_stream(); tlv_stream.0.metadata = None; - if metadata.derives_keys() { + if metadata.derives_payer_keys() { tlv_stream.2.payer_id = None; } @@ -319,7 +350,7 @@ impl Refund { /// /// If `None`, the refund does not expire. pub fn absolute_expiry(&self) -> Option { - self.contents.absolute_expiry + self.contents.absolute_expiry() } /// Whether the refund has expired. @@ -328,46 +359,51 @@ impl Refund { self.contents.is_expired() } + /// Whether the refund has expired given the duration since the Unix epoch. + pub fn is_expired_no_std(&self, duration_since_epoch: Duration) -> bool { + self.contents.is_expired_no_std(duration_since_epoch) + } + /// The issuer of the refund, possibly beginning with `user@domain` or `domain`. Intended to be /// displayed to the user but with the caveat that it has not been verified in any way. pub fn issuer(&self) -> Option { - self.contents.issuer.as_ref().map(|issuer| PrintableString(issuer.as_str())) + self.contents.issuer() } /// Paths to the sender originating from publicly reachable nodes. Blinded paths provide sender /// privacy by obfuscating its node id. pub fn paths(&self) -> &[BlindedPath] { - self.contents.paths.as_ref().map(|paths| paths.as_slice()).unwrap_or(&[]) + self.contents.paths() } /// An unpredictable series of bytes, typically containing information about the derivation of /// [`payer_id`]. /// /// [`payer_id`]: Self::payer_id - pub fn metadata(&self) -> &[u8] { + pub fn payer_metadata(&self) -> &[u8] { self.contents.metadata() } /// A chain that the refund is valid for. pub fn chain(&self) -> ChainHash { - self.contents.chain.unwrap_or_else(|| self.contents.implied_chain()) + self.contents.chain() } /// The amount to refund in msats (i.e., the minimum lightning-payable unit for [`chain`]). /// /// [`chain`]: Self::chain pub fn amount_msats(&self) -> u64 { - self.contents.amount_msats + self.contents.amount_msats() } /// Features pertaining to requesting an invoice. pub fn features(&self) -> &InvoiceRequestFeatures { - &self.contents.features + &self.contents.features() } /// The quantity of an item that refund is for. pub fn quantity(&self) -> Option { - self.contents.quantity + self.contents.quantity() } /// A public node id to send to in the case where there are no [`paths`]. Otherwise, a possibly @@ -375,12 +411,12 @@ impl Refund { /// /// [`paths`]: Self::paths pub fn payer_id(&self) -> PublicKey { - self.contents.payer_id + self.contents.payer_id() } /// Payer provided note to include in the invoice. pub fn payer_note(&self) -> Option { - self.contents.payer_note.as_ref().map(|payer_note| PrintableString(payer_note.as_str())) + self.contents.payer_note() } /// Creates an [`InvoiceBuilder`] for the refund with the given required fields and using the @@ -503,15 +539,30 @@ impl RefundContents { PrintableString(&self.description) } + pub fn absolute_expiry(&self) -> Option { + self.absolute_expiry + } + #[cfg(feature = "std")] pub(super) fn is_expired(&self) -> bool { - match self.absolute_expiry { - Some(seconds_from_epoch) => match SystemTime::UNIX_EPOCH.elapsed() { - Ok(elapsed) => elapsed > seconds_from_epoch, - Err(_) => false, - }, - None => false, - } + SystemTime::UNIX_EPOCH + .elapsed() + .map(|duration_since_epoch| self.is_expired_no_std(duration_since_epoch)) + .unwrap_or(false) + } + + pub(super) fn is_expired_no_std(&self, duration_since_epoch: Duration) -> bool { + self.absolute_expiry + .map(|absolute_expiry| duration_since_epoch > absolute_expiry) + .unwrap_or(false) + } + + pub fn issuer(&self) -> Option { + self.issuer.as_ref().map(|issuer| PrintableString(issuer.as_str())) + } + + pub fn paths(&self) -> &[BlindedPath] { + self.paths.as_ref().map(|paths| paths.as_slice()).unwrap_or(&[]) } pub(super) fn metadata(&self) -> &[u8] { @@ -526,14 +577,37 @@ impl RefundContents { ChainHash::using_genesis_block(Network::Bitcoin) } - pub(super) fn derives_keys(&self) -> bool { - self.payer.0.derives_keys() + pub fn amount_msats(&self) -> u64 { + self.amount_msats + } + + /// Features pertaining to requesting an invoice. + pub fn features(&self) -> &InvoiceRequestFeatures { + &self.features } - pub(super) fn payer_id(&self) -> PublicKey { + /// The quantity of an item that refund is for. + pub fn quantity(&self) -> Option { + self.quantity + } + + /// A public node id to send to in the case where there are no [`paths`]. Otherwise, a possibly + /// transient pubkey. + /// + /// [`paths`]: Self::paths + pub fn payer_id(&self) -> PublicKey { self.payer_id } + /// Payer provided note to include in the invoice. + pub fn payer_note(&self) -> Option { + self.payer_note.as_ref().map(|payer_note| PrintableString(payer_note.as_str())) + } + + pub(super) fn derives_keys(&self) -> bool { + self.payer.0.derives_payer_keys() + } + pub(super) fn as_tlv_stream(&self) -> RefundTlvStreamRef { let payer = PayerTlvStreamRef { metadata: self.payer.0.as_bytes(), @@ -713,6 +787,7 @@ mod tests { use core::time::Duration; use crate::blinded_path::{BlindedHop, BlindedPath}; use crate::sign::KeyMaterial; + use crate::ln::channelmanager::PaymentId; use crate::ln::features::{InvoiceRequestFeatures, OfferFeatures}; use crate::ln::inbound_payment::ExpandedKey; use crate::ln::msgs::{DecodeError, MAX_VALUE_MSAT}; @@ -745,7 +820,7 @@ mod tests { refund.write(&mut buffer).unwrap(); assert_eq!(refund.bytes, buffer.as_slice()); - assert_eq!(refund.metadata(), &[1; 32]); + assert_eq!(refund.payer_metadata(), &[1; 32]); assert_eq!(refund.description(), PrintableString("foo")); assert_eq!(refund.absolute_expiry(), None); #[cfg(feature = "std")] @@ -806,9 +881,10 @@ mod tests { let expanded_key = ExpandedKey::new(&KeyMaterial([42; 32])); let entropy = FixedEntropy {}; let secp_ctx = Secp256k1::new(); + let payment_id = PaymentId([1; 32]); let refund = RefundBuilder - ::deriving_payer_id(desc, node_id, &expanded_key, &entropy, &secp_ctx, 1000) + ::deriving_payer_id(desc, node_id, &expanded_key, &entropy, &secp_ctx, 1000, payment_id) .unwrap() .build().unwrap(); assert_eq!(refund.payer_id(), node_id); @@ -819,7 +895,10 @@ mod tests { .unwrap() .build().unwrap() .sign(recipient_sign).unwrap(); - assert!(invoice.verify(&expanded_key, &secp_ctx)); + match invoice.verify(&expanded_key, &secp_ctx) { + Ok(payment_id) => assert_eq!(payment_id, PaymentId([1; 32])), + Err(()) => panic!("verification failed"), + } let mut tlv_stream = refund.as_tlv_stream(); tlv_stream.2.amount = Some(2000); @@ -832,7 +911,7 @@ mod tests { .unwrap() .build().unwrap() .sign(recipient_sign).unwrap(); - assert!(!invoice.verify(&expanded_key, &secp_ctx)); + assert!(invoice.verify(&expanded_key, &secp_ctx).is_err()); // Fails verification with altered metadata let mut tlv_stream = refund.as_tlv_stream(); @@ -847,7 +926,7 @@ mod tests { .unwrap() .build().unwrap() .sign(recipient_sign).unwrap(); - assert!(!invoice.verify(&expanded_key, &secp_ctx)); + assert!(invoice.verify(&expanded_key, &secp_ctx).is_err()); } #[test] @@ -857,6 +936,7 @@ mod tests { let expanded_key = ExpandedKey::new(&KeyMaterial([42; 32])); let entropy = FixedEntropy {}; let secp_ctx = Secp256k1::new(); + let payment_id = PaymentId([1; 32]); let blinded_path = BlindedPath { introduction_node_id: pubkey(40), @@ -868,7 +948,7 @@ mod tests { }; let refund = RefundBuilder - ::deriving_payer_id(desc, node_id, &expanded_key, &entropy, &secp_ctx, 1000) + ::deriving_payer_id(desc, node_id, &expanded_key, &entropy, &secp_ctx, 1000, payment_id) .unwrap() .path(blinded_path) .build().unwrap(); @@ -879,7 +959,10 @@ mod tests { .unwrap() .build().unwrap() .sign(recipient_sign).unwrap(); - assert!(invoice.verify(&expanded_key, &secp_ctx)); + match invoice.verify(&expanded_key, &secp_ctx) { + Ok(payment_id) => assert_eq!(payment_id, PaymentId([1; 32])), + Err(()) => panic!("verification failed"), + } // Fails verification with altered fields let mut tlv_stream = refund.as_tlv_stream(); @@ -893,7 +976,7 @@ mod tests { .unwrap() .build().unwrap() .sign(recipient_sign).unwrap(); - assert!(!invoice.verify(&expanded_key, &secp_ctx)); + assert!(invoice.verify(&expanded_key, &secp_ctx).is_err()); // Fails verification with altered payer_id let mut tlv_stream = refund.as_tlv_stream(); @@ -908,13 +991,14 @@ mod tests { .unwrap() .build().unwrap() .sign(recipient_sign).unwrap(); - assert!(!invoice.verify(&expanded_key, &secp_ctx)); + assert!(invoice.verify(&expanded_key, &secp_ctx).is_err()); } #[test] fn builds_refund_with_absolute_expiry() { let future_expiry = Duration::from_secs(u64::max_value()); let past_expiry = Duration::from_secs(0); + let now = future_expiry - Duration::from_secs(1_000); let refund = RefundBuilder::new("foo".into(), vec![1; 32], payer_pubkey(), 1000).unwrap() .absolute_expiry(future_expiry) @@ -923,6 +1007,7 @@ mod tests { let (_, tlv_stream, _) = refund.as_tlv_stream(); #[cfg(feature = "std")] assert!(!refund.is_expired()); + assert!(!refund.is_expired_no_std(now)); assert_eq!(refund.absolute_expiry(), Some(future_expiry)); assert_eq!(tlv_stream.absolute_expiry, Some(future_expiry.as_secs())); @@ -934,6 +1019,7 @@ mod tests { let (_, tlv_stream, _) = refund.as_tlv_stream(); #[cfg(feature = "std")] assert!(refund.is_expired()); + assert!(refund.is_expired_no_std(now)); assert_eq!(refund.absolute_expiry(), Some(past_expiry)); assert_eq!(tlv_stream.absolute_expiry, Some(past_expiry.as_secs())); }