Move pay_for_offer to flow.rs

Move pay_for_offer documentation to flow.rs

Author: shaavan

lightning/src/ln/channelmanager.rs

@@ -48,6 +48,7 @@ use crate::events::{Event, EventHandler, EventsProvider, MessageSendEvent, Messa
 // construct one themselves.
 use crate::ln::inbound_payment;
 use crate::ln::types::ChannelId;
+use crate::offers::offer::Offer;
 use crate::types::payment::{PaymentHash, PaymentPreimage, PaymentSecret};
 use crate::ln::channel::{self, Channel, ChannelPhase, ChannelError, ChannelUpdateStatus, ShutdownResult, UpdateFulfillCommitFetch, OutboundV1Channel, InboundV1Channel, WithChannelContext};
 use crate::ln::channel_state::ChannelDetails;
@@ -67,7 +68,6 @@ use crate::ln::wire::Encode;
 use crate::offers::invoice::{Bolt12Invoice, DEFAULT_RELATIVE_EXPIRY, DerivedSigningPubkey, InvoiceBuilder};
 use crate::offers::invoice_request::{InvoiceRequest, InvoiceRequestBuilder};
 use crate::offers::nonce::Nonce;
-use crate::offers::offer::Offer;
 use crate::offers::parse::Bolt12SemanticError;
 use crate::offers::refund::Refund;
 use crate::offers::signer;
@@ -1996,57 +1996,6 @@ where
 ///
 /// ## BOLT 12 Offers
 ///
-/// Use [`pay_for_offer`] to initiated payment, which sends an [`InvoiceRequest`] for an [`Offer`]
-/// and pays the [`Bolt12Invoice`] response.
-///
-/// ```
-/// # use lightning::events::{Event, EventsProvider};
-/// # use lightning::ln::channelmanager::{AChannelManager, OffersMessageCommons, PaymentId, RecentPaymentDetails, Retry};
-/// # use lightning::offers::offer::Offer;
-/// #
-/// # fn example<T: AChannelManager>(
-/// #     channel_manager: T, offer: &Offer, quantity: Option<u64>, amount_msats: Option<u64>,
-/// #     payer_note: Option<String>, retry: Retry, max_total_routing_fee_msat: Option<u64>
-/// # ) {
-/// # let channel_manager = channel_manager.get_cm();
-/// let payment_id = PaymentId([42; 32]);
-/// match channel_manager.pay_for_offer(
-///     offer, quantity, amount_msats, payer_note, payment_id, retry, max_total_routing_fee_msat
-/// ) {
-///     Ok(()) => println!("Requesting invoice for offer"),
-///     Err(e) => println!("Unable to request invoice for offer: {:?}", e),
-/// }
-///
-/// // First the payment will be waiting on an invoice
-/// let expected_payment_id = payment_id;
-/// assert!(
-///     channel_manager.list_recent_payments().iter().find(|details| matches!(
-///         details,
-///         RecentPaymentDetails::AwaitingInvoice { payment_id: expected_payment_id }
-///     )).is_some()
-/// );
-///
-/// // Once the invoice is received, a payment will be sent
-/// assert!(
-///     channel_manager.list_recent_payments().iter().find(|details| matches!(
-///         details,
-///         RecentPaymentDetails::Pending { payment_id: expected_payment_id, ..  }
-///     )).is_some()
-/// );
-///
-/// // On the event processing thread
-/// channel_manager.process_pending_events(&|event| {
-///     match event {
-///         Event::PaymentSent { payment_id: Some(payment_id), .. } => println!("Paid {}", payment_id),
-///         Event::PaymentFailed { payment_id, .. } => println!("Failed paying {}", payment_id),
-///         // ...
-///     #     _ => {},
-///     }
-///     Ok(())
-/// });
-/// # }
-/// ```
-///
 /// ## BOLT 12 Refunds
 ///
 /// Use [`request_refund_payment`] to send a [`Bolt12Invoice`] for receiving the refund. Similar to
@@ -2173,7 +2122,7 @@ where
 /// [`claim_funds`]: Self::claim_funds
 /// [`send_payment`]: Self::send_payment
 /// [`offers`]: crate::offers
-/// [`pay_for_offer`]: Self::pay_for_offer
+/// [`Offer`]: crate::offers::offer
 /// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
 /// [`request_refund_payment`]: Self::request_refund_payment
 /// [`peer_disconnected`]: msgs::ChannelMessageHandler::peer_disconnected
@@ -2685,6 +2634,8 @@ const MAX_NO_CHANNEL_PEERS: usize = 250;
 /// Using compact [`BlindedMessagePath`]s may provide better privacy as the [`MessageRouter`] could select
 /// more hops. However, since they use short channel ids instead of pubkeys, they are more likely to
 /// become invalid over time as channels are closed. Thus, they are only suitable for short-term use.
+///
+/// [`Offer`]: crate::offers::offer
 pub const MAX_SHORT_LIVED_RELATIVE_EXPIRY: Duration = Duration::from_secs(60 * 60 * 24);
 
 /// Used by [`ChannelManager::list_recent_payments`] to express the status of recent payments.
@@ -2693,8 +2644,10 @@ pub const MAX_SHORT_LIVED_RELATIVE_EXPIRY: Duration = Duration::from_secs(60 * 6
 pub enum RecentPaymentDetails {
 	/// When an invoice was requested and thus a payment has not yet been sent.
 	AwaitingInvoice {
-		/// A user-provided identifier in [`ChannelManager::pay_for_offer`] used to uniquely identify a
+		/// A user-provided identifier in [`OffersMessageFlow::pay_for_offer`] used to uniquely identify a
 		/// payment and ensure idempotency in LDK.
+		/// 
+		/// [`OffersMessageFlow::pay_for_offer`]: crate::offers::flow::OffersMessageFlow::pay_for_offer
 		payment_id: PaymentId,
 	},
 	/// When a payment is still being sent and awaiting successful delivery.
@@ -2703,7 +2656,7 @@ pub enum RecentPaymentDetails {
 		/// identify a payment and ensure idempotency in LDK.
 		///
 		/// [`send_payment`]: crate::ln::channelmanager::ChannelManager::send_payment
-		/// [`pay_for_offer`]: crate::ln::channelmanager::ChannelManager::pay_for_offer
+		/// [`pay_for_offer`]: crate::offers::flow::OffersMessageFlow::pay_for_offer
 		payment_id: PaymentId,
 		/// Hash of the payment that is currently being sent but has yet to be fulfilled or
 		/// abandoned.
@@ -2720,7 +2673,7 @@ pub enum RecentPaymentDetails {
 		/// identify a payment and ensure idempotency in LDK.
 		///
 		/// [`send_payment`]: crate::ln::channelmanager::ChannelManager::send_payment
-		/// [`pay_for_offer`]: crate::ln::channelmanager::ChannelManager::pay_for_offer
+		/// [`pay_for_offer`]: crate::offers::flow::OffersMessageFlow::pay_for_offer
 		payment_id: PaymentId,
 		/// Hash of the payment that was claimed. `None` for serializations of [`ChannelManager`]
 		/// made before LDK version 0.0.104.
@@ -2734,7 +2687,7 @@ pub enum RecentPaymentDetails {
 		/// identify a payment and ensure idempotency in LDK.
 		///
 		/// [`send_payment`]: crate::ln::channelmanager::ChannelManager::send_payment
-		/// [`pay_for_offer`]: crate::ln::channelmanager::ChannelManager::pay_for_offer
+		/// [`pay_for_offer`]: crate::offers::flow::OffersMessageFlow::pay_for_offer
 		payment_id: PaymentId,
 		/// Hash of the payment that we have given up trying to send.
 		payment_hash: PaymentHash,
@@ -4608,7 +4561,7 @@ where
 	///
 	/// # Requested Invoices
 	///
-	/// In the case of paying a [`Bolt12Invoice`] via [`ChannelManager::pay_for_offer`], abandoning
+	/// In the case of paying a [`Bolt12Invoice`] via [`OffersMessageFlow::pay_for_offer`], abandoning
 	/// the payment prior to receiving the invoice will result in an [`Event::PaymentFailed`] and
 	/// prevent any attempts at paying it once received.
 	///
@@ -4618,6 +4571,7 @@ where
 	/// [`ChannelManager`], another [`Event::PaymentFailed`] may be generated.
 	///
 	/// [`Bolt12Invoice`]: crate::offers::invoice::Bolt12Invoice
+	/// [`OffersMessageFlow::pay_for_offer`]: crate::offers::flow::OffersMessageFlow::pay_for_offer
 	pub fn abandon_payment(&self, payment_id: PaymentId) {
 		self.abandon_payment_with_reason(payment_id, PaymentFailureReason::UserAbandoned)
 	}
@@ -9346,6 +9300,13 @@ pub trait OffersMessageCommons {
 	///
 	/// [`Event::PaymentSent`]: events::Event::PaymentSent
 	fn list_recent_payments(&self) -> Vec<RecentPaymentDetails>;
+
+	/// Internal pay_for_offer
+	fn pay_for_offer_intern<CPP: FnOnce(&InvoiceRequest, Nonce) -> Result<(), Bolt12SemanticError>> (
+		&self, offer: &Offer, quantity: Option<u64>, amount_msats: Option<u64>,
+		payer_note: Option<String>, payment_id: PaymentId,
+		human_readable_name: Option<HumanReadableName>, create_pending_payment: CPP,
+	) -> Result<(), Bolt12SemanticError>;
 }
 
 impl<M: Deref, T: Deref, ES: Deref, NS: Deref, SP: Deref, F: Deref, R: Deref, MR: Deref, L: Deref> OffersMessageCommons for ChannelManager<M, T, ES, NS, SP, F, R, MR, L>
@@ -9519,7 +9480,6 @@ where
 	}
 
 	fn add_new_awaiting_invoice(&self, payment_id: PaymentId, expiration: StaleExpiration, retry_strategy: Retry, max_total_routing_fee_msat: Option<u64>, retryable_invoice_request: Option<RetryableInvoiceRequest>) -> Result<(), ()> {
-		let _persistence_guard = PersistenceNotifierGuard::notify_on_drop(self);
 		self.pending_outbound_payments.add_new_awaiting_invoice (
 			payment_id, expiration, retry_strategy, max_total_routing_fee_msat, retryable_invoice_request,
 		)
@@ -9555,6 +9515,53 @@ where
 			})
 			.collect()
 	}
+
+	fn pay_for_offer_intern<CPP: FnOnce(&InvoiceRequest, Nonce) -> Result<(), Bolt12SemanticError>>(
+		&self, offer: &Offer, quantity: Option<u64>, amount_msats: Option<u64>,
+		payer_note: Option<String>, payment_id: PaymentId,
+		human_readable_name: Option<HumanReadableName>, create_pending_payment: CPP,
+	) -> Result<(), Bolt12SemanticError> {
+		let expanded_key = &self.inbound_payment_key;
+		let entropy = &*self.entropy_source;
+		let secp_ctx = &self.secp_ctx;
+
+		let nonce = Nonce::from_entropy_source(entropy);
+		let builder: InvoiceRequestBuilder<secp256k1::All> = offer
+			.request_invoice(expanded_key, nonce, secp_ctx, payment_id)?
+			.into();
+		let builder = builder.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 builder = match human_readable_name {
+			None => builder,
+			Some(hrn) => builder.sourced_from_human_readable_name(hrn),
+		};
+		let invoice_request = builder.build_and_sign()?;
+
+		let hmac = payment_id.hmac_for_offer_payment(nonce, expanded_key);
+		let context = MessageContext::Offers(
+			OffersContext::OutboundPayment { payment_id, nonce, hmac: Some(hmac) }
+		);
+		let reply_paths = self.create_blinded_paths(context)
+			.map_err(|_| Bolt12SemanticError::MissingPaths)?;
+
+		let _persistence_guard = PersistenceNotifierGuard::notify_on_drop(self);
+
+		create_pending_payment(&invoice_request, nonce)?;
+
+		self.enqueue_invoice_request(invoice_request, reply_paths)
+	}
 }
 
 /// Defines the maximum number of [`OffersMessage`] including different reply paths to be sent
@@ -9649,53 +9656,6 @@ where
 		})
 	}
 
-	fn pay_for_offer_intern<CPP: FnOnce(&InvoiceRequest, Nonce) -> Result<(), Bolt12SemanticError>>(
-		&self, offer: &Offer, quantity: Option<u64>, amount_msats: Option<u64>,
-		payer_note: Option<String>, payment_id: PaymentId,
-		human_readable_name: Option<HumanReadableName>, create_pending_payment: CPP,
-	) -> Result<(), Bolt12SemanticError> {
-		let expanded_key = &self.inbound_payment_key;
-		let entropy = &*self.entropy_source;
-		let secp_ctx = &self.secp_ctx;
-
-		let nonce = Nonce::from_entropy_source(entropy);
-		let builder: InvoiceRequestBuilder<secp256k1::All> = offer
-			.request_invoice(expanded_key, nonce, secp_ctx, payment_id)?
-			.into();
-		let builder = builder.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 builder = match human_readable_name {
-			None => builder,
-			Some(hrn) => builder.sourced_from_human_readable_name(hrn),
-		};
-		let invoice_request = builder.build_and_sign()?;
-
-		let hmac = payment_id.hmac_for_offer_payment(nonce, expanded_key);
-		let context = MessageContext::Offers(
-			OffersContext::OutboundPayment { payment_id, nonce, hmac: Some(hmac) }
-		);
-		let reply_paths = self.create_blinded_paths(context)
-			.map_err(|_| Bolt12SemanticError::MissingPaths)?;
-
-		let _persistence_guard = PersistenceNotifierGuard::notify_on_drop(self);
-
-		create_pending_payment(&invoice_request, nonce)?;
-
-		self.enqueue_invoice_request(invoice_request, reply_paths)
-	}
-
 	/// Creates a [`Bolt12Invoice`] for a [`Refund`] and enqueues it to be sent via an onion
 	/// message.
 	///
@@ -12240,6 +12200,8 @@ where
 	pub router: R,
 	/// The [`MessageRouter`] used for constructing [`BlindedMessagePath`]s for [`Offer`]s,
 	/// [`Refund`]s, and any reply paths.
+	///
+	/// [`Offer`]: crate::offers::offer
 	pub message_router: MR,
 	/// The Logger for use in the ChannelManager and which may be used to log information during
 	/// deserialization.

lightning/src/ln/max_payment_path_len_tests.rs

@@ -387,7 +387,7 @@ fn bolt12_invoice_too_large_blinded_paths() {
 
 	let offer = nodes[1].offers_handler.create_offer_builder(None).unwrap().build().unwrap();
 	let payment_id = PaymentId([1; 32]);
-	nodes[0].node.pay_for_offer(&offer, None, Some(5000), None, payment_id, Retry::Attempts(0), None).unwrap();
+	nodes[0].offers_handler.pay_for_offer(&offer, None, Some(5000), None, payment_id, Retry::Attempts(0), None).unwrap();
 	let invreq_om = nodes[0].onion_messenger.next_onion_message_for_peer(nodes[1].node.get_our_node_id()).unwrap();
 	nodes[1].onion_messenger.handle_onion_message(nodes[0].node.get_our_node_id(), &invreq_om);