Utility for paying for an Offer

Add a utility to ChannelManager for sending an InvoiceRequest for an
Offer such that derived keys are used for the payer id. This allows for
stateless verification of any Invoice messages before it is paid.

Also tracks future payments using the given PaymentId such that the
corresponding Invoice is paid only once.

diff --git a/lightning/src/ln/channelmanager.rs b/lightning/src/ln/channelmanager.rs
index 74fef11e9132c65e05818d07874baa33952d7f53..3e7bac3d43b2d140cffaef960673b425420b74b5 100644 (file)
--- a/lightning/src/ln/channelmanager.rs
+++ b/lightning/src/ln/channelmanager.rs
@@ -56,10 +56,10 @@ use crate::ln::msgs::{ChannelMessageHandler, DecodeError, LightningError};
 use crate::ln::outbound_payment;
 use crate::ln::outbound_payment::{OutboundPayments, PaymentAttempts, PendingOutboundPayment, SendAlongPathArgs, StaleExpiration};
 use crate::ln::wire::Encode;
-use crate::offers::offer::{DerivedMetadata, OfferBuilder};
+use crate::offers::offer::{DerivedMetadata, Offer, OfferBuilder};
 use crate::offers::parse::Bolt12SemanticError;
 use crate::offers::refund::RefundBuilder;
-use crate::onion_message::{OffersMessage, PendingOnionMessage};
+use crate::onion_message::{Destination, OffersMessage, PendingOnionMessage};
 use crate::sign::{EntropySource, KeysManager, NodeSigner, Recipient, SignerProvider, WriteableEcdsaChannelSigner};
 use crate::util::config::{UserConfig, ChannelConfig, ChannelConfigUpdate};
 use crate::util::wakers::{Future, Notifier};
@@ -7359,6 +7359,92 @@ where
                Ok(builder)
        }
 
+       /// Pays for an [`Offer`] using the given parameters by creating an [`InvoiceRequest`] and
+       /// enqueuing it to be sent via an onion message. [`ChannelManager`] will pay the actual
+       /// [`Bolt12Invoice`] once it is received.
+       ///
+       /// Uses [`InvoiceRequestBuilder`] such that the [`InvoiceRequest`] it builds is recognized by
+       /// the [`ChannelManager`] when handling a [`Bolt12Invoice`] message in response to the request.
+       /// The optional parameters are used in the builder, if `Some`:
+       /// - `quantity` for [`InvoiceRequest::quantity`] which must be set if
+       ///   [`Offer::expects_quantity`] is `true`.
+       /// - `amount_msats` if overpaying what is required for the given `quantity` is desired, and
+       /// - `payer_note` for [`InvoiceRequest::payer_note`].
+       ///
+       /// The provided `payment_id` is used to ensure that only one invoice is paid for the request
+       /// when received. See [Avoiding Duplicate Payments] for other requirements once the payment has
+       /// been sent. To revoke the request, use [`ChannelManager::abandon_payment`] prior to receiving
+       /// the invoice.
+       ///
+       /// Errors if a duplicate `payment_id` is provided given the caveats in the aforementioned link.
+       ///
+       /// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
+       /// [`InvoiceRequest::quantity`]: crate::offers::invoice_request::InvoiceRequest::quantity
+       /// [`InvoiceRequest::payer_note`]: crate::offers::invoice_request::InvoiceRequest::payer_note
+       /// [`InvoiceRequestBuilder`]: crate::offers::invoice_request::InvoiceRequestBuilder
+       /// [`Bolt12Invoice`]: crate::offers::invoice::Bolt12Invoice
+       /// [Avoiding Duplicate Payments]: #avoiding-duplicate-payments
+       pub fn pay_for_offer(
+               &self, offer: &Offer, quantity: Option<u64>, amount_msats: Option<u64>,
+               payer_note: Option<String>, payment_id: PaymentId, retry_strategy: Retry,
+               max_total_routing_fee_msat: Option<u64>
+       ) -> Result<(), Bolt12SemanticError> {
+               let expanded_key = &self.inbound_payment_key;
+               let entropy = &*self.entropy_source;
+               let secp_ctx = &self.secp_ctx;
+
+               let builder = offer
+                       .request_invoice_deriving_payer_id(expanded_key, entropy, secp_ctx, payment_id)?
+                       .chain_hash(self.chain_hash)?;
+               let builder = match quantity {
+                       None => builder,
+                       Some(quantity) => builder.quantity(quantity)?,
+               };
+               let builder = match amount_msats {
+                       None => builder,
+                       Some(amount_msats) => builder.amount_msats(amount_msats)?,
+               };
+               let builder = match payer_note {
+                       None => builder,
+                       Some(payer_note) => builder.payer_note(payer_note),
+               };
+
+               let invoice_request = builder.build_and_sign()?;
+               let reply_path = self.create_one_hop_blinded_path();
+
+               let expiration = StaleExpiration::TimerTicks(1);
+               self.pending_outbound_payments
+                       .add_new_awaiting_invoice(
+                               payment_id, expiration, retry_strategy, max_total_routing_fee_msat
+                       )
+                       .map_err(|_| Bolt12SemanticError::DuplicatePaymentId)?;
+
+               let mut pending_offers_messages = self.pending_offers_messages.lock().unwrap();
+               if offer.paths().is_empty() {
+                       let message = PendingOnionMessage {
+                               contents: OffersMessage::InvoiceRequest(invoice_request),
+                               destination: Destination::Node(offer.signing_pubkey()),
+                               reply_path: Some(reply_path),
+                       };
+                       pending_offers_messages.push(message);
+               } else {
+                       // Send as many invoice requests as there are paths in the offer (with an upper bound).
+                       // Using only one path could result in a failure if the path no longer exists. But only
+                       // one invoice for a given payment id will be paid, even if more than one is received.
+                       const REQUEST_LIMIT: usize = 10;
+                       for path in offer.paths().into_iter().take(REQUEST_LIMIT) {
+                               let message = PendingOnionMessage {
+                                       contents: OffersMessage::InvoiceRequest(invoice_request.clone()),
+                                       destination: Destination::BlindedPath(path.clone()),
+                                       reply_path: Some(reply_path.clone()),
+                               };
+                               pending_offers_messages.push(message);
+                       }
+               }
+
+               Ok(())
+       }
+
        /// Gets a payment secret and payment hash for use in an invoice given to a third party wishing
        /// to pay us.
        ///

diff --git a/lightning/src/offers/invoice_request.rs b/lightning/src/offers/invoice_request.rs
index fb0b0205bd689e1356b65ae5f7c79690479a55f5..bd6d58371a9f316cccf6b362cc4825f27171f177 100644 (file)
--- a/lightning/src/offers/invoice_request.rs
+++ b/lightning/src/offers/invoice_request.rs
@@ -179,8 +179,16 @@ impl<'a, 'b, P: PayerIdStrategy, T: secp256k1::Signing> InvoiceRequestBuilder<'a
        /// by the offer.
        ///
        /// Successive calls to this method will override the previous setting.
-       pub fn chain(mut self, network: Network) -> Result<Self, Bolt12SemanticError> {
-               let chain = ChainHash::using_genesis_block(network);
+       pub fn chain(self, network: Network) -> Result<Self, Bolt12SemanticError> {
+               self.chain_hash(ChainHash::using_genesis_block(network))
+       }
+
+       /// Sets the [`InvoiceRequest::chain`] for paying an invoice. If not called, the chain hash of
+       /// [`Network::Bitcoin`] is assumed. Errors if the chain for `network` is not supported by the
+       /// offer.
+       ///
+       /// Successive calls to this method will override the previous setting.
+       pub(crate) fn chain_hash(mut self, chain: ChainHash) -> Result<Self, Bolt12SemanticError> {
                if !self.offer.supports_chain(chain) {
                        return Err(Bolt12SemanticError::UnsupportedChain);
                }