From f8c9b092fdeab598431a0d05e4ccb914c2ca0a4f Mon Sep 17 00:00:00 2001 From: Jeffrey Czyz Date: Thu, 13 Jul 2023 13:32:40 -0500 Subject: [PATCH] Qualify the BOLT 12 invoice type To avoid a naming conflict in bindings with BOLT 11 invoices, qualify the BOLT 12 invoice type. --- fuzz/src/invoice_deser.rs | 4 +- lightning/src/offers/invoice.rs | 117 ++++++++++++------------ lightning/src/offers/invoice_error.rs | 12 +-- lightning/src/offers/invoice_request.rs | 46 +++++----- lightning/src/offers/offer.rs | 19 ++-- lightning/src/offers/refund.rs | 32 +++---- lightning/src/onion_message/offers.rs | 14 +-- lightning/src/routing/router.rs | 6 +- 8 files changed, 125 insertions(+), 125 deletions(-) diff --git a/fuzz/src/invoice_deser.rs b/fuzz/src/invoice_deser.rs index 7b93fd38d..34bb955e2 100644 --- a/fuzz/src/invoice_deser.rs +++ b/fuzz/src/invoice_deser.rs @@ -8,13 +8,13 @@ // licenses. use crate::utils::test_logger; -use lightning::offers::invoice::Invoice; +use lightning::offers::invoice::Bolt12Invoice; use lightning::util::ser::Writeable; use std::convert::TryFrom; #[inline] pub fn do_test(data: &[u8], _out: Out) { - if let Ok(invoice) = Invoice::try_from(data.to_vec()) { + if let Ok(invoice) = Bolt12Invoice::try_from(data.to_vec()) { let mut bytes = Vec::with_capacity(data.len()); invoice.write(&mut bytes).unwrap(); assert_eq!(data, bytes); diff --git a/lightning/src/offers/invoice.rs b/lightning/src/offers/invoice.rs index fb1f78fd6..9a09e58ac 100644 --- a/lightning/src/offers/invoice.rs +++ b/lightning/src/offers/invoice.rs @@ -9,9 +9,9 @@ //! Data structures and encoding for `invoice` messages. //! -//! An [`Invoice`] can be built from a parsed [`InvoiceRequest`] for the "offer to be paid" flow or -//! from a [`Refund`] as an "offer for money" flow. The expected recipient of the payment then sends -//! the invoice to the intended payer, who will then pay it. +//! A [`Bolt12Invoice`] can be built from a parsed [`InvoiceRequest`] for the "offer to be paid" +//! flow or from a [`Refund`] as an "offer for money" flow. The expected recipient of the payment +//! then sends the invoice to the intended payer, who will then pay it. //! //! The payment recipient must include a [`PaymentHash`], so as to reveal the preimage upon payment //! receipt, and one or more [`BlindedPath`]s for the payer to use when sending the payment. @@ -128,7 +128,7 @@ const DEFAULT_RELATIVE_EXPIRY: Duration = Duration::from_secs(7200); pub(super) const SIGNATURE_TAG: &'static str = concat!("lightning", "invoice", "signature"); -/// Builds an [`Invoice`] from either: +/// Builds a [`Bolt12Invoice`] from either: /// - an [`InvoiceRequest`] for the "offer to be paid" flow or /// - a [`Refund`] for the "offer for money" flow. /// @@ -146,17 +146,17 @@ pub struct InvoiceBuilder<'a, S: SigningPubkeyStrategy> { signing_pubkey_strategy: core::marker::PhantomData, } -/// Indicates how [`Invoice::signing_pubkey`] was set. +/// Indicates how [`Bolt12Invoice::signing_pubkey`] was set. /// /// This is not exported to bindings users as builder patterns don't map outside of move semantics. pub trait SigningPubkeyStrategy {} -/// [`Invoice::signing_pubkey`] was explicitly set. +/// [`Bolt12Invoice::signing_pubkey`] was explicitly set. /// /// This is not exported to bindings users as builder patterns don't map outside of move semantics. pub struct ExplicitSigningPubkey {} -/// [`Invoice::signing_pubkey`] was derived. +/// [`Bolt12Invoice::signing_pubkey`] was derived. /// /// This is not exported to bindings users as builder patterns don't map outside of move semantics. pub struct DerivedSigningPubkey {} @@ -271,8 +271,9 @@ impl<'a, S: SigningPubkeyStrategy> InvoiceBuilder<'a, S> { }) } - /// Sets the [`Invoice::relative_expiry`] as seconds since [`Invoice::created_at`]. Any expiry - /// that has already passed is valid and can be checked for using [`Invoice::is_expired`]. + /// Sets the [`Bolt12Invoice::relative_expiry`] as seconds since [`Bolt12Invoice::created_at`]. + /// Any expiry that has already passed is valid and can be checked for using + /// [`Bolt12Invoice::is_expired`]. /// /// Successive calls to this method will override the previous setting. pub fn relative_expiry(mut self, relative_expiry_secs: u32) -> Self { @@ -281,7 +282,7 @@ impl<'a, S: SigningPubkeyStrategy> InvoiceBuilder<'a, S> { self } - /// Adds a P2WSH address to [`Invoice::fallbacks`]. + /// Adds a P2WSH address to [`Bolt12Invoice::fallbacks`]. /// /// Successive calls to this method will add another address. Caller is responsible for not /// adding duplicate addresses and only calling if capable of receiving to P2WSH addresses. @@ -294,7 +295,7 @@ impl<'a, S: SigningPubkeyStrategy> InvoiceBuilder<'a, S> { self } - /// Adds a P2WPKH address to [`Invoice::fallbacks`]. + /// Adds a P2WPKH address to [`Bolt12Invoice::fallbacks`]. /// /// Successive calls to this method will add another address. Caller is responsible for not /// adding duplicate addresses and only calling if capable of receiving to P2WPKH addresses. @@ -307,7 +308,7 @@ impl<'a, S: SigningPubkeyStrategy> InvoiceBuilder<'a, S> { self } - /// Adds a P2TR address to [`Invoice::fallbacks`]. + /// Adds a P2TR address to [`Bolt12Invoice::fallbacks`]. /// /// Successive calls to this method will add another address. Caller is responsible for not /// adding duplicate addresses and only calling if capable of receiving to P2TR addresses. @@ -320,7 +321,7 @@ impl<'a, S: SigningPubkeyStrategy> InvoiceBuilder<'a, S> { self } - /// Sets [`Invoice::features`] to indicate MPP may be used. Otherwise, MPP is disallowed. + /// Sets [`Bolt12Invoice::features`] to indicate MPP may be used. Otherwise, MPP is disallowed. pub fn allow_mpp(mut self) -> Self { self.invoice.fields_mut().features.set_basic_mpp_optional(); self @@ -328,7 +329,7 @@ impl<'a, S: SigningPubkeyStrategy> InvoiceBuilder<'a, S> { } impl<'a> InvoiceBuilder<'a, ExplicitSigningPubkey> { - /// Builds an unsigned [`Invoice`] after checking for valid semantics. It can be signed by + /// Builds an unsigned [`Bolt12Invoice`] after checking for valid semantics. It can be signed by /// [`UnsignedInvoice::sign`]. pub fn build(self) -> Result, SemanticError> { #[cfg(feature = "std")] { @@ -343,10 +344,10 @@ impl<'a> InvoiceBuilder<'a, ExplicitSigningPubkey> { } impl<'a> InvoiceBuilder<'a, DerivedSigningPubkey> { - /// Builds a signed [`Invoice`] after checking for valid semantics. + /// Builds a signed [`Bolt12Invoice`] after checking for valid semantics. pub fn build_and_sign( self, secp_ctx: &Secp256k1 - ) -> Result { + ) -> Result { #[cfg(feature = "std")] { if self.invoice.is_offer_or_refund_expired() { return Err(SemanticError::AlreadyExpired); @@ -364,7 +365,7 @@ impl<'a> InvoiceBuilder<'a, DerivedSigningPubkey> { } } -/// A semantically valid [`Invoice`] that hasn't been signed. +/// A semantically valid [`Bolt12Invoice`] that hasn't been signed. pub struct UnsignedInvoice<'a> { invreq_bytes: &'a Vec, invoice: InvoiceContents, @@ -379,7 +380,7 @@ impl<'a> UnsignedInvoice<'a> { /// Signs the invoice using the given function. /// /// This is not exported to bindings users as functions aren't currently mapped. - pub fn sign(self, sign: F) -> Result> + pub fn sign(self, sign: F) -> Result> where F: FnOnce(&Message) -> Result { @@ -402,7 +403,7 @@ impl<'a> UnsignedInvoice<'a> { }; signature_tlv_stream.write(&mut bytes).unwrap(); - Ok(Invoice { + Ok(Bolt12Invoice { bytes, contents: self.invoice, signature, @@ -410,39 +411,37 @@ impl<'a> UnsignedInvoice<'a> { } } -/// An `Invoice` is a payment request, typically corresponding to an [`Offer`] or a [`Refund`]. +/// A `Bolt12Invoice` is a payment request, typically corresponding to an [`Offer`] or a [`Refund`]. /// /// An invoice may be sent in response to an [`InvoiceRequest`] in the case of an offer or sent /// directly after scanning a refund. It includes all the information needed to pay a recipient. /// -/// This is not exported to bindings users as its name conflicts with the BOLT 11 Invoice type. -/// /// [`Offer`]: crate::offers::offer::Offer /// [`Refund`]: crate::offers::refund::Refund /// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest #[derive(Clone, Debug)] #[cfg_attr(test, derive(PartialEq))] -pub struct Invoice { +pub struct Bolt12Invoice { bytes: Vec, contents: InvoiceContents, signature: Signature, } -/// The contents of an [`Invoice`] for responding to either an [`Offer`] or a [`Refund`]. +/// The contents of an [`Bolt12Invoice`] for responding to either an [`Offer`] or a [`Refund`]. /// /// [`Offer`]: crate::offers::offer::Offer /// [`Refund`]: crate::offers::refund::Refund #[derive(Clone, Debug)] #[cfg_attr(test, derive(PartialEq))] enum InvoiceContents { - /// Contents for an [`Invoice`] corresponding to an [`Offer`]. + /// Contents for an [`Bolt12Invoice`] corresponding to an [`Offer`]. /// /// [`Offer`]: crate::offers::offer::Offer ForOffer { invoice_request: InvoiceRequestContents, fields: InvoiceFields, }, - /// Contents for an [`Invoice`] corresponding to a [`Refund`]. + /// Contents for an [`Bolt12Invoice`] corresponding to a [`Refund`]. /// /// [`Refund`]: crate::offers::refund::Refund ForRefund { @@ -464,7 +463,7 @@ struct InvoiceFields { signing_pubkey: PublicKey, } -impl Invoice { +impl Bolt12Invoice { /// A complete description of the purpose of the originating offer or refund. Intended to be /// displayed to the user but with the caveat that it has not been verified in any way. pub fn description(&self) -> PrintableString { @@ -475,7 +474,7 @@ impl Invoice { /// needed for routing payments across them. /// /// Blinded paths provide recipient privacy by obfuscating its node id. Note, however, that this - /// privacy is lost if a public node id is used for [`Invoice::signing_pubkey`]. + /// privacy is lost if a public node id is used for [`Bolt12Invoice::signing_pubkey`]. pub fn payment_paths(&self) -> &[(BlindedPayInfo, BlindedPath)] { &self.contents.fields().payment_paths[..] } @@ -485,8 +484,8 @@ impl Invoice { self.contents.fields().created_at } - /// Duration since [`Invoice::created_at`] when the invoice has expired and therefore should no - /// longer be paid. + /// Duration since [`Bolt12Invoice::created_at`] when the invoice has expired and therefore + /// should no longer be paid. pub fn relative_expiry(&self) -> Duration { self.contents.fields().relative_expiry.unwrap_or(DEFAULT_RELATIVE_EXPIRY) } @@ -579,7 +578,7 @@ impl Invoice { self.contents.fields().signing_pubkey } - /// Signature of the invoice verified using [`Invoice::signing_pubkey`]. + /// Signature of the invoice verified using [`Bolt12Invoice::signing_pubkey`]. pub fn signature(&self) -> Signature { self.signature } @@ -716,7 +715,7 @@ impl InvoiceFields { } } -impl Writeable for Invoice { +impl Writeable for Bolt12Invoice { fn write(&self, writer: &mut W) -> Result<(), io::Error> { WithoutLength(&self.bytes).write(writer) } @@ -728,12 +727,12 @@ impl Writeable for InvoiceContents { } } -impl TryFrom> for Invoice { +impl TryFrom> for Bolt12Invoice { type Error = ParseError; fn try_from(bytes: Vec) -> Result { let parsed_invoice = ParsedMessage::::try_from(bytes)?; - Invoice::try_from(parsed_invoice) + Bolt12Invoice::try_from(parsed_invoice) } } @@ -840,7 +839,7 @@ type PartialInvoiceTlvStreamRef<'a> = ( InvoiceTlvStreamRef<'a>, ); -impl TryFrom> for Invoice { +impl TryFrom> for Bolt12Invoice { type Error = ParseError; fn try_from(invoice: ParsedMessage) -> Result { @@ -860,7 +859,7 @@ impl TryFrom> for Invoice { let pubkey = contents.fields().signing_pubkey; merkle::verify_signature(&signature, SIGNATURE_TAG, &bytes, pubkey)?; - Ok(Invoice { bytes, contents, signature }) + Ok(Bolt12Invoice { bytes, contents, signature }) } } @@ -944,7 +943,7 @@ impl TryFrom for InvoiceContents { #[cfg(test)] mod tests { - use super::{DEFAULT_RELATIVE_EXPIRY, FallbackAddress, FullInvoiceTlvStreamRef, Invoice, InvoiceTlvStreamRef, SIGNATURE_TAG}; + use super::{Bolt12Invoice, DEFAULT_RELATIVE_EXPIRY, FallbackAddress, FullInvoiceTlvStreamRef, InvoiceTlvStreamRef, SIGNATURE_TAG}; use bitcoin::blockdata::script::Script; use bitcoin::hashes::Hash; @@ -1066,7 +1065,7 @@ mod tests { ), ); - if let Err(e) = Invoice::try_from(buffer) { + if let Err(e) = Bolt12Invoice::try_from(buffer) { panic!("error parsing invoice: {:?}", e); } } @@ -1144,7 +1143,7 @@ mod tests { ), ); - if let Err(e) = Invoice::try_from(buffer) { + if let Err(e) = Bolt12Invoice::try_from(buffer) { panic!("error parsing invoice: {:?}", e); } } @@ -1494,14 +1493,14 @@ mod tests { let mut buffer = Vec::new(); invoice.write(&mut buffer).unwrap(); - if let Err(e) = Invoice::try_from(buffer) { + if let Err(e) = Bolt12Invoice::try_from(buffer) { panic!("error parsing invoice: {:?}", e); } let mut tlv_stream = invoice.as_tlv_stream(); tlv_stream.3.paths = None; - match Invoice::try_from(tlv_stream.to_bytes()) { + match Bolt12Invoice::try_from(tlv_stream.to_bytes()) { Ok(_) => panic!("expected error"), Err(e) => assert_eq!(e, ParseError::InvalidSemantics(SemanticError::MissingPaths)), } @@ -1509,7 +1508,7 @@ mod tests { let mut tlv_stream = invoice.as_tlv_stream(); tlv_stream.3.blindedpay = None; - match Invoice::try_from(tlv_stream.to_bytes()) { + match Bolt12Invoice::try_from(tlv_stream.to_bytes()) { Ok(_) => panic!("expected error"), Err(e) => assert_eq!(e, ParseError::InvalidSemantics(SemanticError::InvalidPayInfo)), } @@ -1518,7 +1517,7 @@ mod tests { let mut tlv_stream = invoice.as_tlv_stream(); tlv_stream.3.paths = Some(Iterable(empty_payment_paths.iter().map(|(_, path)| path))); - match Invoice::try_from(tlv_stream.to_bytes()) { + match Bolt12Invoice::try_from(tlv_stream.to_bytes()) { Ok(_) => panic!("expected error"), Err(e) => assert_eq!(e, ParseError::InvalidSemantics(SemanticError::MissingPaths)), } @@ -1528,7 +1527,7 @@ mod tests { let mut tlv_stream = invoice.as_tlv_stream(); tlv_stream.3.blindedpay = Some(Iterable(payment_paths.iter().map(|(payinfo, _)| payinfo))); - match Invoice::try_from(tlv_stream.to_bytes()) { + match Bolt12Invoice::try_from(tlv_stream.to_bytes()) { Ok(_) => panic!("expected error"), Err(e) => assert_eq!(e, ParseError::InvalidSemantics(SemanticError::InvalidPayInfo)), } @@ -1549,14 +1548,14 @@ mod tests { let mut buffer = Vec::new(); invoice.write(&mut buffer).unwrap(); - if let Err(e) = Invoice::try_from(buffer) { + if let Err(e) = Bolt12Invoice::try_from(buffer) { panic!("error parsing invoice: {:?}", e); } let mut tlv_stream = invoice.as_tlv_stream(); tlv_stream.3.created_at = None; - match Invoice::try_from(tlv_stream.to_bytes()) { + match Bolt12Invoice::try_from(tlv_stream.to_bytes()) { Ok(_) => panic!("expected error"), Err(e) => { assert_eq!(e, ParseError::InvalidSemantics(SemanticError::MissingCreationTime)); @@ -1580,7 +1579,7 @@ mod tests { let mut buffer = Vec::new(); invoice.write(&mut buffer).unwrap(); - match Invoice::try_from(buffer) { + match Bolt12Invoice::try_from(buffer) { Ok(invoice) => assert_eq!(invoice.relative_expiry(), Duration::from_secs(3600)), Err(e) => panic!("error parsing invoice: {:?}", e), } @@ -1601,14 +1600,14 @@ mod tests { let mut buffer = Vec::new(); invoice.write(&mut buffer).unwrap(); - if let Err(e) = Invoice::try_from(buffer) { + if let Err(e) = Bolt12Invoice::try_from(buffer) { panic!("error parsing invoice: {:?}", e); } let mut tlv_stream = invoice.as_tlv_stream(); tlv_stream.3.payment_hash = None; - match Invoice::try_from(tlv_stream.to_bytes()) { + match Bolt12Invoice::try_from(tlv_stream.to_bytes()) { Ok(_) => panic!("expected error"), Err(e) => { assert_eq!(e, ParseError::InvalidSemantics(SemanticError::MissingPaymentHash)); @@ -1631,14 +1630,14 @@ mod tests { let mut buffer = Vec::new(); invoice.write(&mut buffer).unwrap(); - if let Err(e) = Invoice::try_from(buffer) { + if let Err(e) = Bolt12Invoice::try_from(buffer) { panic!("error parsing invoice: {:?}", e); } let mut tlv_stream = invoice.as_tlv_stream(); tlv_stream.3.amount = None; - match Invoice::try_from(tlv_stream.to_bytes()) { + match Bolt12Invoice::try_from(tlv_stream.to_bytes()) { Ok(_) => panic!("expected error"), Err(e) => assert_eq!(e, ParseError::InvalidSemantics(SemanticError::MissingAmount)), } @@ -1660,7 +1659,7 @@ mod tests { let mut buffer = Vec::new(); invoice.write(&mut buffer).unwrap(); - match Invoice::try_from(buffer) { + match Bolt12Invoice::try_from(buffer) { Ok(invoice) => { let mut features = Bolt12InvoiceFeatures::empty(); features.set_basic_mpp_optional(); @@ -1705,7 +1704,7 @@ mod tests { let mut buffer = Vec::new(); invoice.write(&mut buffer).unwrap(); - match Invoice::try_from(buffer) { + match Bolt12Invoice::try_from(buffer) { Ok(invoice) => { assert_eq!( invoice.fallbacks(), @@ -1749,14 +1748,14 @@ mod tests { let mut buffer = Vec::new(); invoice.write(&mut buffer).unwrap(); - if let Err(e) = Invoice::try_from(buffer) { + if let Err(e) = Bolt12Invoice::try_from(buffer) { panic!("error parsing invoice: {:?}", e); } let mut tlv_stream = invoice.as_tlv_stream(); tlv_stream.3.node_id = None; - match Invoice::try_from(tlv_stream.to_bytes()) { + match Bolt12Invoice::try_from(tlv_stream.to_bytes()) { Ok(_) => panic!("expected error"), Err(e) => { assert_eq!(e, ParseError::InvalidSemantics(SemanticError::MissingSigningPubkey)); @@ -1767,7 +1766,7 @@ mod tests { let mut tlv_stream = invoice.as_tlv_stream(); tlv_stream.3.node_id = Some(&invalid_pubkey); - match Invoice::try_from(tlv_stream.to_bytes()) { + match Bolt12Invoice::try_from(tlv_stream.to_bytes()) { Ok(_) => panic!("expected error"), Err(e) => { assert_eq!(e, ParseError::InvalidSemantics(SemanticError::InvalidSigningPubkey)); @@ -1789,7 +1788,7 @@ mod tests { .invoice .write(&mut buffer).unwrap(); - match Invoice::try_from(buffer) { + match Bolt12Invoice::try_from(buffer) { Ok(_) => panic!("expected error"), Err(e) => assert_eq!(e, ParseError::InvalidSemantics(SemanticError::MissingSignature)), } @@ -1812,7 +1811,7 @@ mod tests { let mut buffer = Vec::new(); invoice.write(&mut buffer).unwrap(); - match Invoice::try_from(buffer) { + match Bolt12Invoice::try_from(buffer) { Ok(_) => panic!("expected error"), Err(e) => { assert_eq!(e, ParseError::InvalidSignature(secp256k1::Error::InvalidSignature)); @@ -1838,7 +1837,7 @@ mod tests { BigSize(32).write(&mut encoded_invoice).unwrap(); [42u8; 32].write(&mut encoded_invoice).unwrap(); - match Invoice::try_from(encoded_invoice) { + match Bolt12Invoice::try_from(encoded_invoice) { Ok(_) => panic!("expected error"), Err(e) => assert_eq!(e, ParseError::Decode(DecodeError::InvalidValue)), } diff --git a/lightning/src/offers/invoice_error.rs b/lightning/src/offers/invoice_error.rs index e843264b4..7345bc14d 100644 --- a/lightning/src/offers/invoice_error.rs +++ b/lightning/src/offers/invoice_error.rs @@ -17,27 +17,27 @@ use crate::util::string::UntrustedString; use crate::prelude::*; -/// An error in response to an [`InvoiceRequest`] or an [`Invoice`]. +/// An error in response to an [`InvoiceRequest`] or an [`Bolt12Invoice`]. /// /// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest -/// [`Invoice`]: crate::offers::invoice::Invoice +/// [`Bolt12Invoice`]: crate::offers::invoice::Bolt12Invoice #[derive(Clone, Debug)] #[cfg_attr(test, derive(PartialEq))] pub struct InvoiceError { - /// The field in the [`InvoiceRequest`] or the [`Invoice`] that contained an error. + /// The field in the [`InvoiceRequest`] or the [`Bolt12Invoice`] that contained an error. /// /// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest - /// [`Invoice`]: crate::offers::invoice::Invoice + /// [`Bolt12Invoice`]: crate::offers::invoice::Bolt12Invoice pub erroneous_field: Option, /// An explanation of the error. pub message: UntrustedString, } -/// The field in the [`InvoiceRequest`] or the [`Invoice`] that contained an error. +/// The field in the [`InvoiceRequest`] or the [`Bolt12Invoice`] that contained an error. /// /// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest -/// [`Invoice`]: crate::offers::invoice::Invoice +/// [`Bolt12Invoice`]: crate::offers::invoice::Bolt12Invoice #[derive(Clone, Debug)] #[cfg_attr(test, derive(PartialEq))] pub struct ErroneousField { diff --git a/lightning/src/offers/invoice_request.rs b/lightning/src/offers/invoice_request.rs index f51d25267..f5cb439b5 100644 --- a/lightning/src/offers/invoice_request.rs +++ b/lightning/src/offers/invoice_request.rs @@ -11,12 +11,12 @@ //! //! An [`InvoiceRequest`] can be built from a parsed [`Offer`] as an "offer to be paid". It is //! typically constructed by a customer and sent to the merchant who had published the corresponding -//! offer. The recipient of the request responds with an [`Invoice`]. +//! offer. The recipient of the request responds with a [`Bolt12Invoice`]. //! //! For an "offer for money" (e.g., refund, ATM withdrawal), where an offer doesn't exist as a //! precursor, see [`Refund`]. //! -//! [`Invoice`]: crate::offers::invoice::Invoice +//! [`Bolt12Invoice`]: crate::offers::invoice::Bolt12Invoice //! [`Refund`]: crate::offers::refund::Refund //! //! ``` @@ -247,7 +247,7 @@ impl<'a, 'b, P: PayerIdStrategy, T: secp256k1::Signing> InvoiceRequestBuilder<'a fn build_without_checks(mut self) -> (UnsignedInvoiceRequest<'a>, Option, Option<&'b Secp256k1>) { - // Create the metadata for stateless verification of an Invoice. + // Create the metadata for stateless verification of a Bolt12Invoice. let mut keys = None; let secp_ctx = self.secp_ctx.clone(); if self.invoice_request.payer.0.has_derivation_material() { @@ -381,12 +381,12 @@ impl<'a> UnsignedInvoiceRequest<'a> { } } -/// An `InvoiceRequest` is a request for an [`Invoice`] formulated from an [`Offer`]. +/// An `InvoiceRequest` is a request for a [`Bolt12Invoice`] formulated from an [`Offer`]. /// /// An offer may provide choices such as quantity, amount, chain, features, etc. An invoice request /// specifies these such that its recipient can send an invoice for payment. /// -/// [`Invoice`]: crate::offers::invoice::Invoice +/// [`Bolt12Invoice`]: crate::offers::invoice::Bolt12Invoice /// [`Offer`]: crate::offers::offer::Offer #[derive(Clone, Debug)] #[cfg_attr(test, derive(PartialEq))] @@ -396,9 +396,9 @@ pub struct InvoiceRequest { signature: Signature, } -/// The contents of an [`InvoiceRequest`], which may be shared with an [`Invoice`]. +/// The contents of an [`InvoiceRequest`], which may be shared with an [`Bolt12Invoice`]. /// -/// [`Invoice`]: crate::offers::invoice::Invoice +/// [`Bolt12Invoice`]: crate::offers::invoice::Bolt12Invoice #[derive(Clone, Debug)] #[cfg_attr(test, derive(PartialEq))] pub(super) struct InvoiceRequestContents { @@ -492,8 +492,8 @@ impl InvoiceRequest { /// Creates an [`InvoiceBuilder`] for the request with the given required fields. /// /// Unless [`InvoiceBuilder::relative_expiry`] is set, the invoice will expire two hours after - /// `created_at`, which is used to set [`Invoice::created_at`]. Useful for `no-std` builds where - /// [`std::time::SystemTime`] is not available. + /// `created_at`, which is used to set [`Bolt12Invoice::created_at`]. Useful for `no-std` builds + /// where [`std::time::SystemTime`] is not available. /// /// The caller is expected to remember the preimage of `payment_hash` in order to claim a payment /// for the invoice. @@ -507,7 +507,7 @@ impl InvoiceRequest { /// /// This is not exported to bindings users as builder patterns don't map outside of move semantics. /// - /// [`Invoice::created_at`]: crate::offers::invoice::Invoice::created_at + /// [`Bolt12Invoice::created_at`]: crate::offers::invoice::Bolt12Invoice::created_at pub fn respond_with_no_std( &self, payment_paths: Vec<(BlindedPayInfo, BlindedPath)>, payment_hash: PaymentHash, created_at: core::time::Duration @@ -520,14 +520,14 @@ impl InvoiceRequest { } /// Creates an [`InvoiceBuilder`] for the request using the given required fields and that uses - /// derived signing keys from the originating [`Offer`] to sign the [`Invoice`]. Must use the - /// same [`ExpandedKey`] as the one used to create the offer. + /// derived signing keys from the originating [`Offer`] to sign the [`Bolt12Invoice`]. Must use + /// the same [`ExpandedKey`] as the one used to create the offer. /// /// See [`InvoiceRequest::respond_with`] for further details. /// /// This is not exported to bindings users as builder patterns don't map outside of move semantics. /// - /// [`Invoice`]: crate::offers::invoice::Invoice + /// [`Bolt12Invoice`]: crate::offers::invoice::Bolt12Invoice #[cfg(feature = "std")] pub fn verify_and_respond_using_derived_keys( &self, payment_paths: Vec<(BlindedPayInfo, BlindedPath)>, payment_hash: PaymentHash, @@ -543,14 +543,14 @@ impl InvoiceRequest { } /// Creates an [`InvoiceBuilder`] for the request using the given required fields and that uses - /// derived signing keys from the originating [`Offer`] to sign the [`Invoice`]. Must use the - /// same [`ExpandedKey`] as the one used to create the offer. + /// derived signing keys from the originating [`Offer`] to sign the [`Bolt12Invoice`]. Must use + /// the same [`ExpandedKey`] as the one used to create the offer. /// /// See [`InvoiceRequest::respond_with_no_std`] for further details. /// /// This is not exported to bindings users as builder patterns don't map outside of move semantics. /// - /// [`Invoice`]: crate::offers::invoice::Invoice + /// [`Bolt12Invoice`]: crate::offers::invoice::Bolt12Invoice pub fn verify_and_respond_using_derived_keys_no_std( &self, payment_paths: Vec<(BlindedPayInfo, BlindedPath)>, payment_hash: PaymentHash, created_at: core::time::Duration, expanded_key: &ExpandedKey, secp_ctx: &Secp256k1 @@ -569,10 +569,10 @@ impl InvoiceRequest { } /// Verifies that the request was for an offer created using the given key. Returns the derived - /// keys need to sign an [`Invoice`] for the request if they could be extracted from the + /// keys need to sign an [`Bolt12Invoice`] for the request if they could be extracted from the /// metadata. /// - /// [`Invoice`]: crate::offers::invoice::Invoice + /// [`Bolt12Invoice`]: crate::offers::invoice::Bolt12Invoice pub fn verify( &self, key: &ExpandedKey, secp_ctx: &Secp256k1 ) -> Result, ()> { @@ -789,7 +789,7 @@ mod tests { use crate::ln::features::InvoiceRequestFeatures; use crate::ln::inbound_payment::ExpandedKey; use crate::ln::msgs::{DecodeError, MAX_VALUE_MSAT}; - use crate::offers::invoice::{Invoice, SIGNATURE_TAG as INVOICE_SIGNATURE_TAG}; + use crate::offers::invoice::{Bolt12Invoice, SIGNATURE_TAG as INVOICE_SIGNATURE_TAG}; use crate::offers::merkle::{SignError, SignatureTlvStreamRef, self}; use crate::offers::offer::{Amount, OfferBuilder, OfferTlvStreamRef, Quantity}; use crate::offers::parse::{ParseError, SemanticError}; @@ -930,7 +930,7 @@ mod tests { let mut encoded_invoice = bytes; signature_tlv_stream.write(&mut encoded_invoice).unwrap(); - let invoice = Invoice::try_from(encoded_invoice).unwrap(); + let invoice = Bolt12Invoice::try_from(encoded_invoice).unwrap(); assert!(!invoice.verify(&expanded_key, &secp_ctx)); // Fails verification with altered metadata @@ -954,7 +954,7 @@ mod tests { let mut encoded_invoice = bytes; signature_tlv_stream.write(&mut encoded_invoice).unwrap(); - let invoice = Invoice::try_from(encoded_invoice).unwrap(); + let invoice = Bolt12Invoice::try_from(encoded_invoice).unwrap(); assert!(!invoice.verify(&expanded_key, &secp_ctx)); } @@ -1000,7 +1000,7 @@ mod tests { let mut encoded_invoice = bytes; signature_tlv_stream.write(&mut encoded_invoice).unwrap(); - let invoice = Invoice::try_from(encoded_invoice).unwrap(); + let invoice = Bolt12Invoice::try_from(encoded_invoice).unwrap(); assert!(!invoice.verify(&expanded_key, &secp_ctx)); // Fails verification with altered payer id @@ -1024,7 +1024,7 @@ mod tests { let mut encoded_invoice = bytes; signature_tlv_stream.write(&mut encoded_invoice).unwrap(); - let invoice = Invoice::try_from(encoded_invoice).unwrap(); + let invoice = Bolt12Invoice::try_from(encoded_invoice).unwrap(); assert!(!invoice.verify(&expanded_key, &secp_ctx)); } diff --git a/lightning/src/offers/offer.rs b/lightning/src/offers/offer.rs index 9c8489778..fd705a901 100644 --- a/lightning/src/offers/offer.rs +++ b/lightning/src/offers/offer.rs @@ -319,8 +319,8 @@ impl<'a, M: MetadataStrategy, T: secp256k1::Signing> OfferBuilder<'a, M, T> { /// An `Offer` is a potentially long-lived proposal for payment of a good or service. /// /// An offer is a precursor to an [`InvoiceRequest`]. A merchant publishes an offer from which a -/// customer may request an [`Invoice`] for a specific quantity and using an amount sufficient to -/// cover that quantity (i.e., at least `quantity * amount`). See [`Offer::amount`]. +/// customer may request an [`Bolt12Invoice`] for a specific quantity and using an amount sufficient +/// to cover that quantity (i.e., at least `quantity * amount`). See [`Offer::amount`]. /// /// Offers may be denominated in currency other than bitcoin but are ultimately paid using the /// latter. @@ -328,7 +328,7 @@ impl<'a, M: MetadataStrategy, T: secp256k1::Signing> OfferBuilder<'a, M, T> { /// Through the use of [`BlindedPath`]s, offers provide recipient privacy. /// /// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest -/// [`Invoice`]: crate::offers::invoice::Invoice +/// [`Bolt12Invoice`]: crate::offers::invoice::Bolt12Invoice #[derive(Clone, Debug)] #[cfg_attr(test, derive(PartialEq))] pub struct Offer { @@ -338,10 +338,11 @@ pub struct Offer { pub(super) contents: OfferContents, } -/// The contents of an [`Offer`], which may be shared with an [`InvoiceRequest`] or an [`Invoice`]. +/// The contents of an [`Offer`], which may be shared with an [`InvoiceRequest`] or a +/// [`Bolt12Invoice`]. /// /// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest -/// [`Invoice`]: crate::offers::invoice::Invoice +/// [`Bolt12Invoice`]: crate::offers::invoice::Bolt12Invoice #[derive(Clone, Debug)] #[cfg_attr(test, derive(PartialEq))] pub(super) struct OfferContents { @@ -451,8 +452,8 @@ impl Offer { /// - derives the [`InvoiceRequest::payer_id`] such that a different key can be used for each /// request, and /// - sets the [`InvoiceRequest::metadata`] when [`InvoiceRequestBuilder::build`] is called such - /// that it can be used by [`Invoice::verify`] to determine if the invoice was requested using - /// a base [`ExpandedKey`] from which the payer id was derived. + /// that it can be used by [`Bolt12Invoice::verify`] to determine if the invoice was requested + /// using a base [`ExpandedKey`] from which the payer id was derived. /// /// Useful to protect the sender's privacy. /// @@ -460,7 +461,7 @@ impl Offer { /// /// [`InvoiceRequest::payer_id`]: crate::offers::invoice_request::InvoiceRequest::payer_id /// [`InvoiceRequest::metadata`]: crate::offers::invoice_request::InvoiceRequest::metadata - /// [`Invoice::verify`]: crate::offers::invoice::Invoice::verify + /// [`Bolt12Invoice::verify`]: crate::offers::invoice::Bolt12Invoice::verify /// [`ExpandedKey`]: crate::ln::inbound_payment::ExpandedKey pub fn request_invoice_deriving_payer_id<'a, 'b, ES: Deref, T: secp256k1::Signing>( &'a self, expanded_key: &ExpandedKey, entropy_source: ES, secp_ctx: &'b Secp256k1 @@ -497,7 +498,7 @@ impl Offer { } /// Creates an [`InvoiceRequestBuilder`] for the offer with the given `metadata` and `payer_id`, - /// which will be reflected in the `Invoice` response. + /// which will be reflected in the `Bolt12Invoice` response. /// /// The `metadata` is useful for including information about the derivation of `payer_id` such /// that invoice response handling can be stateless. Also serves as payer-provided entropy while diff --git a/lightning/src/offers/refund.rs b/lightning/src/offers/refund.rs index 07e759917..35c1726c9 100644 --- a/lightning/src/offers/refund.rs +++ b/lightning/src/offers/refund.rs @@ -10,11 +10,11 @@ //! Data structures and encoding for refunds. //! //! A [`Refund`] is an "offer for money" and is typically constructed by a merchant and presented -//! directly to the customer. The recipient responds with an [`Invoice`] to be paid. +//! directly to the customer. The recipient responds with a [`Bolt12Invoice`] to be paid. //! //! This is an [`InvoiceRequest`] produced *not* in response to an [`Offer`]. //! -//! [`Invoice`]: crate::offers::invoice::Invoice +//! [`Bolt12Invoice`]: crate::offers::invoice::Bolt12Invoice //! [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest //! [`Offer`]: crate::offers::offer::Offer //! @@ -207,12 +207,12 @@ impl<'a, T: secp256k1::Signing> RefundBuilder<'a, T> { } /// Sets [`Refund::quantity`] of items. This is purely for informational purposes. It is useful - /// when the refund pertains to an [`Invoice`] that paid for more than one item from an + /// when the refund pertains to a [`Bolt12Invoice`] that paid for more than one item from an /// [`Offer`] as specified by [`InvoiceRequest::quantity`]. /// /// Successive calls to this method will override the previous setting. /// - /// [`Invoice`]: crate::offers::invoice::Invoice + /// [`Bolt12Invoice`]: crate::offers::invoice::Bolt12Invoice /// [`InvoiceRequest::quantity`]: crate::offers::invoice_request::InvoiceRequest::quantity /// [`Offer`]: crate::offers::offer::Offer pub fn quantity(mut self, quantity: u64) -> Self { @@ -234,7 +234,7 @@ impl<'a, T: secp256k1::Signing> RefundBuilder<'a, T> { self.refund.chain = None; } - // Create the metadata for stateless verification of an Invoice. + // Create the metadata for stateless verification of a Bolt12Invoice. if self.refund.payer.0.has_derivation_material() { let mut metadata = core::mem::take(&mut self.refund.payer.0); @@ -272,13 +272,13 @@ impl<'a, T: secp256k1::Signing> RefundBuilder<'a, T> { } } -/// A `Refund` is a request to send an [`Invoice`] without a preceding [`Offer`]. +/// A `Refund` is a request to send an [`Bolt12Invoice`] without a preceding [`Offer`]. /// /// Typically, after an invoice is paid, the recipient may publish a refund allowing the sender to /// recoup their funds. A refund may be used more generally as an "offer for money", such as with a /// bitcoin ATM. /// -/// [`Invoice`]: crate::offers::invoice::Invoice +/// [`Bolt12Invoice`]: crate::offers::invoice::Bolt12Invoice /// [`Offer`]: crate::offers::offer::Offer #[derive(Clone, Debug)] #[cfg_attr(test, derive(PartialEq))] @@ -287,9 +287,9 @@ pub struct Refund { pub(super) contents: RefundContents, } -/// The contents of a [`Refund`], which may be shared with an [`Invoice`]. +/// The contents of a [`Refund`], which may be shared with an [`Bolt12Invoice`]. /// -/// [`Invoice`]: crate::offers::invoice::Invoice +/// [`Bolt12Invoice`]: crate::offers::invoice::Bolt12Invoice #[derive(Clone, Debug)] #[cfg_attr(test, derive(PartialEq))] pub(super) struct RefundContents { @@ -407,8 +407,8 @@ impl Refund { /// Creates an [`InvoiceBuilder`] for the refund with the given required fields. /// /// Unless [`InvoiceBuilder::relative_expiry`] is set, the invoice will expire two hours after - /// `created_at`, which is used to set [`Invoice::created_at`]. Useful for `no-std` builds where - /// [`std::time::SystemTime`] is not available. + /// `created_at`, which is used to set [`Bolt12Invoice::created_at`]. Useful for `no-std` builds + /// where [`std::time::SystemTime`] is not available. /// /// The caller is expected to remember the preimage of `payment_hash` in order to /// claim a payment for the invoice. @@ -425,7 +425,7 @@ impl Refund { /// /// This is not exported to bindings users as builder patterns don't map outside of move semantics. /// - /// [`Invoice::created_at`]: crate::offers::invoice::Invoice::created_at + /// [`Bolt12Invoice::created_at`]: crate::offers::invoice::Bolt12Invoice::created_at pub fn respond_with_no_std( &self, payment_paths: Vec<(BlindedPayInfo, BlindedPath)>, payment_hash: PaymentHash, signing_pubkey: PublicKey, created_at: Duration @@ -438,13 +438,13 @@ impl Refund { } /// Creates an [`InvoiceBuilder`] for the refund using the given required fields and that uses - /// derived signing keys to sign the [`Invoice`]. + /// derived signing keys to sign the [`Bolt12Invoice`]. /// /// See [`Refund::respond_with`] for further details. /// /// This is not exported to bindings users as builder patterns don't map outside of move semantics. /// - /// [`Invoice`]: crate::offers::invoice::Invoice + /// [`Bolt12Invoice`]: crate::offers::invoice::Bolt12Invoice #[cfg(feature = "std")] pub fn respond_using_derived_keys( &self, payment_paths: Vec<(BlindedPayInfo, BlindedPath)>, payment_hash: PaymentHash, @@ -463,13 +463,13 @@ impl Refund { } /// Creates an [`InvoiceBuilder`] for the refund using the given required fields and that uses - /// derived signing keys to sign the [`Invoice`]. + /// derived signing keys to sign the [`Bolt12Invoice`]. /// /// See [`Refund::respond_with_no_std`] for further details. /// /// This is not exported to bindings users as builder patterns don't map outside of move semantics. /// - /// [`Invoice`]: crate::offers::invoice::Invoice + /// [`Bolt12Invoice`]: crate::offers::invoice::Bolt12Invoice pub fn respond_using_derived_keys_no_std( &self, payment_paths: Vec<(BlindedPayInfo, BlindedPath)>, payment_hash: PaymentHash, created_at: core::time::Duration, expanded_key: &ExpandedKey, entropy_source: ES diff --git a/lightning/src/onion_message/offers.rs b/lightning/src/onion_message/offers.rs index f82afdd61..e335e8aa8 100644 --- a/lightning/src/onion_message/offers.rs +++ b/lightning/src/onion_message/offers.rs @@ -14,7 +14,7 @@ use crate::io::{self, Read}; use crate::ln::msgs::DecodeError; use crate::offers::invoice_error::InvoiceError; use crate::offers::invoice_request::InvoiceRequest; -use crate::offers::invoice::Invoice; +use crate::offers::invoice::Bolt12Invoice; use crate::offers::parse::ParseError; use crate::util::logger::Logger; use crate::util::ser::{Readable, ReadableArgs, Writeable, Writer}; @@ -30,8 +30,8 @@ const INVOICE_ERROR_TLV_TYPE: u64 = 68; /// /// [`OnionMessage`]: crate::ln::msgs::OnionMessage pub trait OffersMessageHandler { - /// Handles the given message by either responding with an [`Invoice`], sending a payment, or - /// replying with an error. + /// Handles the given message by either responding with an [`Bolt12Invoice`], sending a payment, + /// or replying with an error. fn handle_message(&self, message: OffersMessage) -> Option; } @@ -40,15 +40,15 @@ pub trait OffersMessageHandler { /// [`OnionMessage`]: crate::ln::msgs::OnionMessage #[derive(Debug)] pub enum OffersMessage { - /// A request for an [`Invoice`] for a particular [`Offer`]. + /// A request for a [`Bolt12Invoice`] for a particular [`Offer`]. /// /// [`Offer`]: crate::offers::offer::Offer InvoiceRequest(InvoiceRequest), - /// An [`Invoice`] sent in response to an [`InvoiceRequest`] or a [`Refund`]. + /// A [`Bolt12Invoice`] sent in response to an [`InvoiceRequest`] or a [`Refund`]. /// /// [`Refund`]: crate::offers::refund::Refund - Invoice(Invoice), + Invoice(Bolt12Invoice), /// An error from handling an [`OffersMessage`]. InvoiceError(InvoiceError), @@ -75,7 +75,7 @@ impl OffersMessage { fn parse(tlv_type: u64, bytes: Vec) -> Result { match tlv_type { INVOICE_REQUEST_TLV_TYPE => Ok(Self::InvoiceRequest(InvoiceRequest::try_from(bytes)?)), - INVOICE_TLV_TYPE => Ok(Self::Invoice(Invoice::try_from(bytes)?)), + INVOICE_TLV_TYPE => Ok(Self::Invoice(Bolt12Invoice::try_from(bytes)?)), _ => Err(ParseError::Decode(DecodeError::InvalidValue)), } } diff --git a/lightning/src/routing/router.rs b/lightning/src/routing/router.rs index d3539579c..141e7d26c 100644 --- a/lightning/src/routing/router.rs +++ b/lightning/src/routing/router.rs @@ -18,7 +18,7 @@ use crate::ln::PaymentHash; use crate::ln::channelmanager::{ChannelDetails, PaymentId}; use crate::ln::features::{Bolt12InvoiceFeatures, ChannelFeatures, InvoiceFeatures, NodeFeatures}; use crate::ln::msgs::{DecodeError, ErrorAction, LightningError, MAX_VALUE_MSAT}; -use crate::offers::invoice::{BlindedPayInfo, Invoice as Bolt12Invoice}; +use crate::offers::invoice::{BlindedPayInfo, Bolt12Invoice}; use crate::routing::gossip::{DirectedChannelInfo, EffectiveCapacity, ReadOnlyNetworkGraph, NetworkGraph, NodeId, RoutingFees}; use crate::routing::scoring::{ChannelUsage, LockableScore, Score}; use crate::util::ser::{Writeable, Readable, ReadableArgs, Writer}; @@ -271,9 +271,9 @@ impl_writeable_tlv_based!(RouteHop, { }); /// The blinded portion of a [`Path`], if we're routing to a recipient who provided blinded paths in -/// their BOLT12 [`Invoice`]. +/// their [`Bolt12Invoice`]. /// -/// [`Invoice`]: crate::offers::invoice::Invoice +/// [`Bolt12Invoice`]: crate::offers::invoice::Bolt12Invoice #[derive(Clone, Debug, Hash, PartialEq, Eq)] pub struct BlindedTail { /// The hops of the [`BlindedPath`] provided by the recipient. -- 2.39.5