Stateless offer and refund builder utilities

Add utility functions to ChannelManager for creating OfferBuilder,
InvoiceRequestBuilder, and RefundBuilder such that derived keys are used
for the signing pubkey and payer id, respectively. This allows for
stateless verification of any InvoiceRequest and Invoice messages.

Later, blinded paths can be included in the returned builders.

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

Author: jkczyz

lightning/src/ln/channelmanager.rs

@@ -57,8 +57,11 @@ use crate::ln::outbound_payment::{Bolt12PaymentError, OutboundPayments, PaymentA
 use crate::ln::wire::Encode;
 use crate::offers::invoice::{Bolt12Invoice, DEFAULT_RELATIVE_EXPIRY, DerivedSigningPubkey, InvoiceBuilder};
 use crate::offers::invoice_error::InvoiceError;
+use crate::offers::invoice_request::{DerivedPayerId, InvoiceRequestBuilder};
 use crate::offers::merkle::SignError;
+use crate::offers::offer::{DerivedMetadata, Offer, OfferBuilder};
 use crate::offers::parse::Bolt12SemanticError;
+use crate::offers::refund::RefundBuilder;
 use crate::onion_message::{OffersMessage, OffersMessageHandler};
 use crate::sign::{EntropySource, KeysManager, NodeSigner, Recipient, SignerProvider, WriteableEcdsaChannelSigner};
 use crate::util::config::{UserConfig, ChannelConfig, ChannelConfigUpdate};
@@ -6585,6 +6588,74 @@ where
 		}
 	}
 
+	/// Creates an [`OfferBuilder`] such that the [`Offer`] it builds is recognized by the
+	/// [`ChannelManager`] when handling [`InvoiceRequest`] messages for the offer.
+	///
+	/// [`Offer`]: crate::offers::offer::Offer
+	/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
+	pub fn create_offer_builder(
+		&self, description: String
+	) -> OfferBuilder<DerivedMetadata, secp256k1::All> {
+		let node_id = self.get_our_node_id();
+		let expanded_key = &self.inbound_payment_key;
+		let entropy = &*self.entropy_source;
+		let secp_ctx = &self.secp_ctx;
+
+		// TODO: Set blinded paths
+		OfferBuilder::deriving_signing_pubkey(description, node_id, expanded_key, entropy, secp_ctx)
+	}
+
+	/// Creates a [`RefundBuilder`] such that the [`Refund`] it builds is recognized by the
+	/// [`ChannelManager`] when handling [`Bolt12Invoice`] messages for the refund.
+	///
+	/// The provided `payment_id` is used to ensure that only one invoice is paid for the refund.
+	///
+	/// [`Refund`]: crate::offers::refund::Refund
+	/// [`Bolt12Invoice`]: crate::offers::invoice::Bolt12Invoice
+	pub fn create_refund_builder(
+		&self, description: String, amount_msats: u64, payment_id: PaymentId, retry_strategy: Retry
+	) -> Result<RefundBuilder<secp256k1::All>, Bolt12SemanticError> {
+		let node_id = self.get_our_node_id();
+		let expanded_key = &self.inbound_payment_key;
+		let entropy = &*self.entropy_source;
+		let secp_ctx = &self.secp_ctx;
+
+		// TODO: Set blinded paths
+		let builder = RefundBuilder::deriving_payer_id(
+			description, node_id, expanded_key, entropy, secp_ctx, amount_msats, payment_id
+		)?;
+		self.pending_outbound_payments
+			.add_new_awaiting_invoice(payment_id, retry_strategy)
+			.map_err(|_| Bolt12SemanticError::DuplicatePaymentId)?;
+
+		Ok(builder)
+	}
+
+	/// Creates an [`InvoiceRequestBuilder`] such that the [`InvoiceRequest`] it builds is
+	/// recognized by the [`ChannelManager`] when handling [`Bolt12Invoice`] messages for the
+	/// request.
+	///
+	/// The provided `payment_id` is used to ensure that only one invoice is paid for the request.
+	///
+	/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
+	/// [`Bolt12Invoice`]: crate::offers::invoice::Bolt12Invoice
+	pub fn create_invoice_request_builder<'a, 'b>(
+		&'b self, offer: &'a Offer, payment_id: PaymentId, retry_strategy: Retry
+	) -> Result<InvoiceRequestBuilder<'a, 'b, DerivedPayerId, secp256k1::All>, 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
+		)?;
+		self.pending_outbound_payments
+			.add_new_awaiting_invoice(payment_id, retry_strategy)
+			.map_err(|_| Bolt12SemanticError::DuplicatePaymentId)?;
+
+		Ok(builder)
+	}
+
 	/// Gets a payment secret and payment hash for use in an invoice given to a third party wishing
 	/// to pay us.
 	///

lightning/src/offers/offer.rs

@@ -13,6 +13,8 @@
 //! published as a QR code to be scanned by a customer. The customer uses the offer to request an
 //! invoice from the merchant to be paid.
 //!
+//! # Example
+//!
 //! ```
 //! extern crate bitcoin;
 //! extern crate core;
@@ -65,6 +67,14 @@
 //! # Ok(())
 //! # }
 //! ```
+//!
+//! # Note
+//!
+//! If constructing an [`Offer`] for use with a [`ChannelManager`], use
+//! [`ChannelManager::create_offer_builder`] instead of [`OfferBuilder::new`].
+//!
+//! [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
+//! [`ChannelManager::create_offer_builder`]: crate::ln::channelmanager::ChannelManager::create_offer_builder
 
 use bitcoin::blockdata::constants::ChainHash;
 use bitcoin::network::constants::Network;
@@ -132,6 +142,14 @@ impl<'a> OfferBuilder<'a, ExplicitMetadata, secp256k1::SignOnly> {
 	/// while the offer is valid.
 	///
 	/// Use a different pubkey per offer to avoid correlating offers.
+	///
+	/// # Note
+	///
+	/// If constructing an [`Offer`] for use with a [`ChannelManager`], use
+	/// [`ChannelManager::create_offer_builder`] instead of [`OfferBuilder::new`].
+	///
+	/// [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
+	/// [`ChannelManager::create_offer_builder`]: crate::ln::channelmanager::ChannelManager::create_offer_builder
 	pub fn new(description: String, signing_pubkey: PublicKey) -> Self {
 		OfferBuilder {
 			offer: OfferContents {

lightning/src/offers/parse.rs

@@ -179,6 +179,8 @@ pub enum Bolt12SemanticError {
 	MissingPayerMetadata,
 	/// A payer id was expected but was missing.
 	MissingPayerId,
+	/// The payment id for a refund or request is already in use.
+	DuplicatePaymentId,
 	/// Blinded paths were expected but were missing.
 	MissingPaths,
 	/// The blinded payinfo given does not match the number of blinded path hops.

lightning/src/offers/refund.rs

@@ -18,6 +18,8 @@
 //! [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
 //! [`Offer`]: crate::offers::offer::Offer
 //!
+//! # Example
+//!
 //! ```
 //! extern crate bitcoin;
 //! extern crate core;
@@ -70,6 +72,14 @@
 //! # Ok(())
 //! # }
 //! ```
+//!
+//! # Note
+//!
+//! If constructing a [`Refund`] for use with a [`ChannelManager`], use
+//! [`ChannelManager::create_refund_builder`] instead of [`RefundBuilder::new`].
+//!
+//! [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
+//! [`ChannelManager::create_refund_builder`]: crate::ln::channelmanager::ChannelManager::create_refund_builder
 
 use bitcoin::blockdata::constants::ChainHash;
 use bitcoin::network::constants::Network;
@@ -120,6 +130,14 @@ impl<'a> RefundBuilder<'a, secp256k1::SignOnly> {
 	///
 	/// Additionally, sets the required [`Refund::description`], [`Refund::payer_metadata`], and
 	/// [`Refund::amount_msats`].
+	///
+	/// # Note
+	///
+	/// If constructing a [`Refund`] for use with a [`ChannelManager`], use
+	/// [`ChannelManager::create_refund_builder`] instead of [`RefundBuilder::new`].
+	///
+	/// [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
+	/// [`ChannelManager::create_refund_builder`]: crate::ln::channelmanager::ChannelManager::create_refund_builder
 	pub fn new(
 		description: String, metadata: Vec<u8>, payer_id: PublicKey, amount_msats: u64
 	) -> Result<Self, Bolt12SemanticError> {