Invoice request message interface and data format

Define an interface for BOLT 12 `invoice_request` messages. The
underlying format consists of the original bytes and the parsed
contents.

The bytes are later needed when constructing an `invoice` message. This
is because it must mirror all the `offer` and `invoice_request` TLV
records, including unknown ones, which aren't represented in the
contents.

The contents will be used in `invoice` messages to avoid duplication.
Some fields while required in a typical user-pays-merchant flow may not
be necessary in the merchant-pays-user flow (e.g., refund, ATM).

Author: jkczyz

lightning/src/offers/invoice_request.rs

@@ -0,0 +1,100 @@
+// This file is Copyright its original authors, visible in version control
+// history.
+//
+// This file is licensed under the Apache License, Version 2.0 <LICENSE-APACHE
+// or http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your option.
+// You may not use this file except in accordance with one or both of these
+// licenses.
+
+//! Data structures and encoding for `invoice_request` messages.
+
+use bitcoin::blockdata::constants::ChainHash;
+use bitcoin::secp256k1::PublicKey;
+use bitcoin::secp256k1::schnorr::Signature;
+use crate::ln::features::OfferFeatures;
+use crate::offers::offer::OfferContents;
+use crate::offers::payer::PayerContents;
+
+use crate::prelude::*;
+
+/// An `InvoiceRequest` is a request for an `Invoice` formulated from an [`Offer`].
+///
+/// An offer may provided choices such as quantity, amount, chain, features, etc. An invoice request
+/// specifies these such that the recipient can send an invoice for payment.
+///
+/// [`Offer`]: crate::offers::offer::Offer
+#[derive(Clone, Debug)]
+pub struct InvoiceRequest {
+	bytes: Vec<u8>,
+	contents: InvoiceRequestContents,
+	signature: Option<Signature>,
+}
+
+/// The contents of an [`InvoiceRequest`], which may be shared with an `Invoice`.
+#[derive(Clone, Debug)]
+pub(crate) struct InvoiceRequestContents {
+	payer: PayerContents,
+	offer: OfferContents,
+	chain: Option<ChainHash>,
+	amount_msats: Option<u64>,
+	features: Option<OfferFeatures>,
+	quantity: Option<u64>,
+	payer_id: PublicKey,
+	payer_note: Option<String>,
+}
+
+impl InvoiceRequest {
+	/// An unpredictable series of bytes, typically containing information about the derivation of
+	/// [`payer_id`].
+	///
+	/// [`payer_id`]: Self::payer_id
+	pub fn metadata(&self) -> Option<&Vec<u8>> {
+		self.contents.payer.0.as_ref()
+	}
+
+	/// A chain from [`Offer::chains`] that the offer is valid for.
+	///
+	/// [`Offer::chains`]: crate::offers::offer::Offer::chains
+	pub fn chain(&self) -> ChainHash {
+		self.contents.chain.unwrap_or_else(|| self.contents.offer.implied_chain())
+	}
+
+	/// The amount to pay in msats (i.e., the minimum lightning-payable unit for [`chain`]), which
+	/// must be greater than or equal to [`Offer::amount`], converted if necessary.
+	///
+	/// [`chain`]: Self::chain
+	/// [`Offer::amount`]: crate::offers::offer::Offer::amount
+	pub fn amount_msats(&self) -> Option<u64> {
+		self.contents.amount_msats
+	}
+
+	/// Features for paying the invoice.
+	pub fn features(&self) -> Option<&OfferFeatures> {
+		self.contents.features.as_ref()
+	}
+
+	/// The quantity of the offer's item conforming to [`Offer::supported_quantity`].
+	///
+	/// [`Offer::supported_quantity`]: crate::offers::offer::Offer::supported_quantity
+	pub fn quantity(&self) -> Option<u64> {
+		self.contents.quantity
+	}
+
+	/// A transient pubkey used to sign the invoice request.
+	pub fn payer_id(&self) -> PublicKey {
+		self.contents.payer_id
+	}
+
+	/// Payer provided note to include in the invoice.
+	pub fn payer_note(&self) -> Option<&String> {
+		self.contents.payer_note.as_ref()
+	}
+
+	/// Signature of the invoice request using [`payer_id`].
+	///
+	/// [`payer_id`]: Self::payer_id
+	pub fn signature(&self) -> Option<Signature> {
+		self.signature
+	}
+}

lightning/src/offers/mod.rs

@@ -12,5 +12,7 @@
 //!
 //! Offers are a flexible protocol for Lightning payments.
 
+pub mod invoice_request;
 pub mod offer;
 pub mod parse;
+mod payer;

lightning/src/offers/offer.rs

@@ -223,14 +223,16 @@ impl OfferBuilder {
 
 /// 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
+/// 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`].
 ///
 /// Offers may be denominated in currency other than bitcoin but are ultimately paid using the
 /// latter.
 ///
 /// Through the use of [`BlindedPath`]s, offers provide recipient privacy.
+///
+/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
 #[derive(Clone, Debug)]
 pub struct Offer {
 	// The serialized offer. Needed when creating an `InvoiceRequest` if the offer contains unknown
@@ -239,7 +241,9 @@ pub struct Offer {
 	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 an `Invoice`.
+///
+/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
 #[derive(Clone, Debug)]
 pub(crate) struct OfferContents {
 	chains: Option<Vec<ChainHash>>,
@@ -262,10 +266,7 @@ impl Offer {
 	/// Payments must be denominated in units of the minimal lightning-payable unit (e.g., msats)
 	/// for the selected chain.
 	pub fn chains(&self) -> Vec<ChainHash> {
-		self.contents.chains
-			.as_ref()
-			.cloned()
-			.unwrap_or_else(|| vec![self.contents.implied_chain()])
+		self.contents.chains()
 	}
 
 	// TODO: Link to corresponding method in `InvoiceRequest`.
@@ -345,6 +346,10 @@ impl AsRef<[u8]> for Offer {
 }
 
 impl OfferContents {
+	pub fn chains(&self) -> Vec<ChainHash> {
+		self.chains.as_ref().cloned().unwrap_or_else(|| vec![self.implied_chain()])
+	}
+
 	pub fn implied_chain(&self) -> ChainHash {
 		ChainHash::using_genesis_block(Network::Bitcoin)
 	}

lightning/src/offers/payer.rs

@@ -0,0 +1,19 @@
+// This file is Copyright its original authors, visible in version control
+// history.
+//
+// This file is licensed under the Apache License, Version 2.0 <LICENSE-APACHE
+// or http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your option.
+// You may not use this file except in accordance with one or both of these
+// licenses.
+
+//! Data structures and encoding for `invoice_request_metadata` records.
+
+use crate::prelude::*;
+
+/// An unpredictable sequence of bytes typically containing information needed to derive
+/// [`InvoiceRequestContents::payer_id`].
+///
+/// [`InvoiceRequestContents::payer_id`]: invoice_request::InvoiceRequestContents::payer_id
+#[derive(Clone, Debug)]
+pub(crate) struct PayerContents(pub Option<Vec<u8>>);