mirrors/rust-lightning
1
0
Fork 0
mirror of https://github.com/lightningdevkit/rust-lightning.git synced 2025-01-19 05:43:55 +01:00
Code Issues Packages Projects Releases Wiki Activity

Qualify the BOLT 12 invoice type

Browse Source 
To avoid a naming conflict in bindings with BOLT 11 invoices, qualify
the BOLT 12 invoice type.
This commit is contained in:
Jeffrey Czyz 2023-07-13 13:32:40 -05:00
parent 3e50011e22
commit f8c9b092fd
No known key found for this signature in database
GPG Key ID: 3A4E08275D5E96D2
8 changed files with 125 additions and 125 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
fuzz/src/invoice_deser.rs
View File

@ -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<Out: test_logger::Output>(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);

117
lightning/src/offers/invoice.rs
View File

@ -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<S>,
}
/// 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<UnsignedInvoice<'a>, 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<T: secp256k1::Signing>(
self, secp_ctx: &Secp256k1<T>
) -> Result<Invoice, SemanticError> {
) -> Result<Bolt12Invoice, SemanticError> {
#[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<u8>,
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<F, E>(self, sign: F) -> Result<Invoice, SignError<E>>
pub fn sign<F, E>(self, sign: F) -> Result<Bolt12Invoice, SignError<E>>
where
F: FnOnce(&Message) -> Result<Signature, E>
{
@ -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<u8>,
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<W: Writer>(&self, writer: &mut W) -> Result<(), io::Error> {
WithoutLength(&self.bytes).write(writer)
}
@ -728,12 +727,12 @@ impl Writeable for InvoiceContents {
}
}
impl TryFrom<Vec<u8>> for Invoice {
impl TryFrom<Vec<u8>> for Bolt12Invoice {
type Error = ParseError;
fn try_from(bytes: Vec<u8>) -> Result<Self, Self::Error> {
let parsed_invoice = ParsedMessage::<FullInvoiceTlvStream>::try_from(bytes)?;
Invoice::try_from(parsed_invoice)
Bolt12Invoice::try_from(parsed_invoice)
}
}
@ -840,7 +839,7 @@ type PartialInvoiceTlvStreamRef<'a> = (
InvoiceTlvStreamRef<'a>,
);
impl TryFrom<ParsedMessage<FullInvoiceTlvStream>> for Invoice {
impl TryFrom<ParsedMessage<FullInvoiceTlvStream>> for Bolt12Invoice {
type Error = ParseError;
fn try_from(invoice: ParsedMessage<FullInvoiceTlvStream>) -> Result<Self, Self::Error> {
@ -860,7 +859,7 @@ impl TryFrom<ParsedMessage<FullInvoiceTlvStream>> 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<PartialInvoiceTlvStream> 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)),
}

12
lightning/src/offers/invoice_error.rs
View File

@ -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<ErroneousField>,
/// 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 {

46
lightning/src/offers/invoice_request.rs
View File

@ -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<KeyPair>, Option<&'b Secp256k1<T>>)
{
// 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<T: secp256k1::Signing>(
&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<T: secp256k1::Signing>(
&self, payment_paths: Vec<(BlindedPayInfo, BlindedPath)>, payment_hash: PaymentHash,
created_at: core::time::Duration, expanded_key: &ExpandedKey, secp_ctx: &Secp256k1<T>
@ -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<T: secp256k1::Signing>(
&self, key: &ExpandedKey, secp_ctx: &Secp256k1<T>
) -> Result<Option<KeyPair>, ()> {
@ -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));
}

19
lightning/src/offers/offer.rs
View File

@ -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<T>
@ -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

32
lightning/src/offers/refund.rs
View File

@ -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<ES: Deref>(
&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<ES: Deref>(
&self, payment_paths: Vec<(BlindedPayInfo, BlindedPath)>, payment_hash: PaymentHash,
created_at: core::time::Duration, expanded_key: &ExpandedKey, entropy_source: ES

14
lightning/src/onion_message/offers.rs
View File

@ -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<OffersMessage>;
}
@ -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<u8>) -> Result<Self, ParseError> {
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)),
}
}

6
lightning/src/routing/router.rs
View File

@ -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.