Introduce pay_for_bolt11_invoice

Previously, paying a Bolt11 invoice required manually extracting the
`payment_id`, `payment_hash`, and other parameters before passing them to
`send_payment`.

This commit introduces `pay_for_bolt11_invoice`, bringing the same simplicity
already available for Bolt12 invoices. It allows users to pass the entire
Bolt11 invoice directly while also supporting custom routing parameters
via `RouteParametersConfig`.

Author: shaavan

lightning/src/events/mod.rs

@@ -598,9 +598,12 @@ pub enum PaymentFailureReason {
 	///
 	/// [`HeldHtlcAvailable`]: crate::onion_message::async_payments::HeldHtlcAvailable
 	BlindedPathCreationFailed,
-	/// Incorrect amount was provided to ChannelManager::pay_for_bolt11_invoice.
-	/// This happens when an amount is specified when Bolt11Invoice already contains
+	/// Incorrect amount was provided to [`ChannelManager::pay_for_bolt11_invoice`].
+	/// This happens when an amount is specified when [`Bolt11Invoice`] already contains
 	/// an amount, or vice versa.
+	///
+	/// [`Bolt11Invoice`]: lightning_invoice::Bolt11Invoice
+	/// [`ChannelManager::pay_for_bolt11_invoice`]: crate::ln::channelmanager::ChannelManager::pay_for_bolt11_invoice
 	InvalidAmount,
 }
 

lightning/src/ln/channelmanager.rs

@@ -2045,21 +2045,22 @@ where
 /// [`send_payment`].
 ///
 /// ```
+/// # use bitcoin::hashes::Hash;
 /// # use lightning::events::{Event, EventsProvider};
 /// # use lightning::types::payment::PaymentHash;
-/// # use lightning::ln::channelmanager::{AChannelManager, PaymentId, RecentPaymentDetails, RecipientOnionFields, Retry};
-/// # use lightning::routing::router::RouteParameters;
+/// # use lightning::ln::channelmanager::{AChannelManager, PaymentId, RecentPaymentDetails, Retry};
+/// # use lightning::routing::router::RouteParametersConfig;
+/// # use lightning_invoice::Bolt11Invoice;
 /// #
 /// # fn example<T: AChannelManager>(
-/// #     channel_manager: T, payment_hash: PaymentHash, recipient_onion: RecipientOnionFields,
-/// #     route_params: RouteParameters, retry: Retry
+/// #     channel_manager: T, invoice: &Bolt11Invoice, route_params_config: RouteParametersConfig,
+/// #     retry: Retry
 /// # ) {
 /// # let channel_manager = channel_manager.get_cm();
-/// // let (payment_hash, recipient_onion, route_params) =
-/// //     payment::payment_parameters_from_invoice(&invoice);
-/// let payment_id = PaymentId([42; 32]);
-/// match channel_manager.send_payment(
-///     payment_hash, recipient_onion, payment_id, route_params, retry
+/// # let payment_id = PaymentId([42; 32]);
+/// # let payment_hash = PaymentHash((*invoice.payment_hash()).to_byte_array());
+/// match channel_manager.pay_for_bolt11_invoice(
+///     invoice, payment_id, None, route_params_config, retry
 /// ) {
 ///     Ok(()) => println!("Sending payment with hash {}", payment_hash),
 ///     Err(e) => println!("Failed sending payment with hash {}: {:?}", payment_hash, e),
@@ -4771,6 +4772,34 @@ where
 		self.pending_outbound_payments.test_set_payment_metadata(payment_id, new_payment_metadata);
 	}
 
+	/// Pays a [`Bolt11Invoice`] associated with the `payment_id`. See [`Self::send_payment`] for more info.
+	///
+	/// # Payment Id
+	/// The invoice's `payment_hash().0` serves as a reliable choice for the `payment_id`.
+	///
+	/// # Handling Invoice Amounts
+	/// Some invoices include a specific amount, while others require you to specify one.
+	/// - If the invoice **includes** an amount, user must not provide `amount_msats`.
+	/// - If the invoice **doesn't include** an amount, you'll need to specify `amount_msats`.
+	///
+	/// If these conditions aren’t met, the function will return [`RetryableSendFailure::InvalidAmount`].
+	///
+	/// # Custom Routing Parameters
+	/// Users can customize routing parameters via [`RouteParametersConfig`].
+	/// To use default settings, call the function with `RouteParametersConfig::default()`.
+	pub fn pay_for_bolt11_invoice(
+		&self, invoice: &Bolt11Invoice, payment_id: PaymentId, amount_msats: Option<u64>,
+		route_params_config: RouteParametersConfig, retry_strategy: Retry
+	) -> Result<(), RetryableSendFailure> {
+		let best_block_height = self.best_block.read().unwrap().height;
+		let _persistence_guard = PersistenceNotifierGuard::notify_on_drop(self);
+		self.pending_outbound_payments
+			.pay_for_bolt11_invoice(invoice, payment_id, amount_msats, route_params_config, retry_strategy,
+				&self.router, self.list_usable_channels(), || self.compute_inflight_htlcs(),
+				&self.entropy_source, &self.node_signer, best_block_height, &self.logger,
+				&self.pending_events, |args| self.send_payment_along_path(args))
+	}
+
 	/// Pays the [`Bolt12Invoice`] associated with the `payment_id` encoded in its `payer_metadata`.
 	///
 	/// The invoice's `payer_metadata` is used to authenticate that the invoice was indeed requested

lightning/src/ln/outbound_payment.rs

@@ -12,6 +12,7 @@
 use bitcoin::hashes::Hash;
 use bitcoin::hashes::sha256::Hash as Sha256;
 use bitcoin::secp256k1::{self, Secp256k1, SecretKey};
+use lightning_invoice::Bolt11Invoice;
 
 use crate::blinded_path::{IntroductionNode, NodeIdLookUp};
 use crate::events::{self, PaymentFailureReason};
@@ -500,9 +501,11 @@ pub enum RetryableSendFailure {
 	///
 	/// [`BlindedPaymentPath`]: crate::blinded_path::payment::BlindedPaymentPath
 	OnionPacketSizeExceeded,
-	/// Incorrect amount was provided to ChannelManager::pay_for_bolt11_invoice.
-	/// This happens when an amount is specified when Bolt11Invoice already contains
+	/// Incorrect amount was provided to [`ChannelManager::pay_for_bolt11_invoice`].
+	/// This happens when an amount is specified when [`Bolt11Invoice`] already contains
 	/// an amount, or vice versa.
+	///
+	/// [`ChannelManager::pay_for_bolt11_invoice`]: crate::ln::channelmanager::ChannelManager::pay_for_bolt11_invoice
 	InvalidAmount,
 }
 
@@ -847,6 +850,49 @@ impl OutboundPayments {
 			.map(|()| payment_hash)
 	}
 
+	pub(super) fn pay_for_bolt11_invoice<R: Deref, ES: Deref, NS: Deref, IH, SP, L: Deref>(
+		&self, invoice: &Bolt11Invoice, payment_id: PaymentId,
+		amount_msats: Option<u64>,
+		route_params_config: RouteParametersConfig,
+		retry_strategy: Retry,
+		router: &R,
+		first_hops: Vec<ChannelDetails>, compute_inflight_htlcs: IH, entropy_source: &ES,
+		node_signer: &NS, best_block_height: u32, logger: &L,
+		pending_events: &Mutex<VecDeque<(events::Event, Option<EventCompletionAction>)>>, send_payment_along_path: SP,
+	) -> Result<(), RetryableSendFailure>
+	where
+		R::Target: Router,
+		ES::Target: EntropySource,
+		NS::Target: NodeSigner,
+		L::Target: Logger,
+		IH: Fn() -> InFlightHtlcs,
+		SP: Fn(SendAlongPathArgs) -> Result<(), APIError>,
+	{
+		let payment_hash = PaymentHash((*invoice.payment_hash()).to_byte_array());
+
+		let amount = match (invoice.amount_milli_satoshis(), amount_msats) {
+			(Some(amt), None) | (None, Some(amt)) => amt,
+			(None, None) | (Some(_), Some(_)) => return Err(RetryableSendFailure::InvalidAmount),
+		};
+
+		let mut recipient_onion = RecipientOnionFields::secret_only(*invoice.payment_secret());
+		recipient_onion.payment_metadata = invoice.payment_metadata().map(|v| v.clone());
+
+		let payment_params = PaymentParameters::from_bolt11_invoice(invoice)
+			.with_user_config_ignoring_fee_limit(route_params_config);
+
+		let mut route_params = RouteParameters::from_payment_params_and_value(payment_params, amount);
+
+		if let Some(max_fee_msat) = route_params_config.max_total_routing_fee_msat {
+			route_params.max_total_routing_fee_msat = Some(max_fee_msat);
+		}
+
+		self.send_payment_internal(payment_id, payment_hash, recipient_onion, None, retry_strategy, route_params,
+			router, first_hops, compute_inflight_htlcs,
+			entropy_source, node_signer, best_block_height, logger,
+			pending_events, send_payment_along_path)
+	}
+
 	pub(super) fn send_payment_for_bolt12_invoice<
 		R: Deref, ES: Deref, NS: Deref, NL: Deref, IH, SP, L: Deref
 	>(

lightning/src/routing/router.rs

@@ -10,6 +10,7 @@
 //! The router finds paths within a [`NetworkGraph`] for a payment.
 
 use bitcoin::secp256k1::{PublicKey, Secp256k1, self};
+use lightning_invoice::Bolt11Invoice;
 
 use crate::blinded_path::{BlindedHop, Direction, IntroductionNode};
 use crate::blinded_path::payment::{BlindedPaymentPath, ForwardTlvs, PaymentConstraints, PaymentForwardNode, PaymentRelay, ReceiveTlvs};
@@ -910,6 +911,27 @@ impl PaymentParameters {
 			.expect("PaymentParameters::from_node_id should always initialize the payee as unblinded")
 	}
 
+	/// Creates parameters for paying to a blinded payee from the provided invoice. Sets
+	/// [`Payee::Blinded::route_hints`], [`Payee::Blinded::features`], and
+	/// [`PaymentParameters::expiry_time`].
+	pub fn from_bolt11_invoice(invoice: &Bolt11Invoice) -> Self {
+		let mut payment_params = Self::from_node_id(
+			invoice.recover_payee_pub_key(),
+			invoice.min_final_cltv_expiry_delta() as u32,
+		)
+		.with_route_hints(invoice.route_hints())
+		.unwrap();
+
+		if let Some(expiry) = invoice.expires_at() {
+			payment_params = payment_params.with_expiry_time(expiry.as_secs());
+		}
+		if let Some(features) = invoice.features() {
+			payment_params = payment_params.with_bolt11_features(features.clone()).unwrap();
+		}
+
+		payment_params
+	}
+
 	/// Creates parameters for paying to a blinded payee from the provided invoice. Sets
 	/// [`Payee::Blinded::route_hints`], [`Payee::Blinded::features`], and
 	/// [`PaymentParameters::expiry_time`].