Allow BOLT 11 payments to be a part of a larger MPP payment

In some uses of LDK we need the ability to send HTLCs for only a
portion of some larger MPP payment. This allows payers to make
single payments which spend funds from multiple wallets, which may
be important for ecash wallets holding funds in multiple mints or
graduated wallets which hold funds across a trusted wallet and a
self-custodial wallet.

In the previous few commits we added support for making these
kinds of payments when using the payment methods which explicitly
accepted a `RecipientOnionFields`. Here we also add support for
such payments made via the `pay_for_bolt11_invoice` method,
utilizing the new `OptionalBolt11PaymentParams` to hide the
parameter from most calls.

Test mostly by Claude

Author: TheBlueMatt

lightning/src/ln/channelmanager.rs

@@ -686,6 +686,20 @@ pub struct OptionalBolt11PaymentParams {
 	/// will ultimately fail once all pending paths have failed (generating an
 	/// [`Event::PaymentFailed`]).
 	pub retry_strategy: Retry,
+	/// If the payment being made from this node is part of a larger MPP payment from multiple
+	/// nodes (i.e. because a single payment is being made from multiple wallets), you can specify
+	/// the total amount being paid here.
+	///
+	/// If this is set, it must be at least the [`Bolt11Invoice::amount_milli_satoshis`] for the
+	/// invoice provided to [`ChannelManager::pay_for_bolt11_invoice`]. Further, if this is set,
+	/// the `amount_msats` provided to [`ChannelManager::pay_for_bolt11_invoice`] is allowed to be
+	/// lower than [`Bolt11Invoice::amount_milli_satoshis`] (as the payment we're making may be a
+	/// small part of the amount needed to meet the invoice's minimum).
+	///
+	/// If this is lower than the `amount_msats` passed to
+	/// [`ChannelManager::pay_for_bolt11_invoice`] the call will fail with
+	/// [`Bolt11PaymentError::InvalidAmount`].
+	pub declared_total_mpp_value_override: Option<u64>,
 }
 
 impl Default for OptionalBolt11PaymentParams {
@@ -697,6 +711,7 @@ impl Default for OptionalBolt11PaymentParams {
 			retry_strategy: Retry::Timeout(core::time::Duration::from_secs(2)),
 			#[cfg(not(feature = "std"))]
 			retry_strategy: Retry::Attempts(3),
+			declared_total_mpp_value_override: None,
 		}
 	}
 }
@@ -5441,10 +5456,18 @@ impl<
 	/// 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 may provide an amount greater or equal to it
-	/// to allow for overpayments.
-	/// - If the invoice **doesn't include** an amount, you'll need to specify `amount_msats`.
+	/// Some invoices require a specific minimum amount (which can be fetched with
+	/// [`Bolt11Invoice::amount_milli_satoshis`]) while others allow you to pay amount.
+	///
+	/// - If the invoice **includes** an amount, `amount_msats` may be `None` to pay exactly
+	///   [`Bolt11Invoice::amount_milli_satoshis`] or may be `Some` with a value greater than or
+	///   equal to the [`Bolt11Invoice::amount_milli_satoshis`] to allow for deliberate overpayment
+	///   (e.g. for "tips").
+	/// - If the invoice **doesn't include** an amount, `amount_msats` must be `Some`.
+	///
+	/// In the special case that [`OptionalBolt11PaymentParams::declared_total_mpp_value_override`]
+	/// is set, `amount_msats` may be `Some` and lower than
+	/// [`Bolt11Invoice::amount_milli_satoshis`]. See the parameter for more details.
 	///
 	/// If these conditions aren’t met, the function will return [`Bolt11PaymentError::InvalidAmount`].
 	///

lightning/src/ln/invoice_utils.rs

@@ -690,6 +690,7 @@ mod test {
 			custom_tlvs: custom_tlvs.clone(),
 			route_params_config: RouteParametersConfig::default(),
 			retry_strategy: Retry::Attempts(0),
+			declared_total_mpp_value_override: None,
 		};
 
 		nodes[0]

lightning/src/ln/outbound_payment.rs

@@ -627,7 +627,12 @@ pub(crate) enum PaymentSendFailure {
 #[derive(Debug)]
 pub enum Bolt11PaymentError {
 	/// Incorrect amount was provided to [`ChannelManager::pay_for_bolt11_invoice`].
-	/// This happens when the user-provided amount is less than an amount specified in the [`Bolt11Invoice`].
+	///
+	/// This happens when the payment amount (either the [`ChannelManager::pay_for_bolt11_invoice`]
+	/// `amount` or [`OptionalBolt11PaymentParams::declared_total_mpp_value_override`]) is less than
+	/// [`Bolt11Invoice::amount_milli_satoshis`] or the amount set at
+	/// [`OptionalBolt11PaymentParams::declared_total_mpp_value_override`] was lower than the
+	/// explicit amount provided to [`ChannelManager::pay_for_bolt11_invoice`].
 	///
 	/// [`Bolt11Invoice`]: lightning_invoice::Bolt11Invoice
 	/// [`ChannelManager::pay_for_bolt11_invoice`]: crate::ln::channelmanager::ChannelManager::pay_for_bolt11_invoice
@@ -1037,9 +1042,11 @@ impl OutboundPayments {
 	{
 		let payment_hash = invoice.payment_hash();
 
+		let partial_payment = optional_params.declared_total_mpp_value_override.is_some();
 		let amount = match (invoice.amount_milli_satoshis(), amount_msats) {
 			(Some(amt), None) | (None, Some(amt)) => amt,
-			(Some(inv_amt), Some(user_amt)) if user_amt < inv_amt => return Err(Bolt11PaymentError::InvalidAmount),
+			(Some(inv_amt), Some(user_amt)) if user_amt < inv_amt && !partial_payment =>
+				return Err(Bolt11PaymentError::InvalidAmount),
 			(Some(_), Some(user_amt)) => user_amt,
 			(None, None) => return Err(Bolt11PaymentError::InvalidAmount),
 		};
@@ -1049,6 +1056,16 @@ impl OutboundPayments {
 				.with_custom_tlvs(optional_params.custom_tlvs);
 		recipient_onion.payment_metadata = invoice.payment_metadata().map(|v| v.clone());
 
+		if let Some(mpp_amt) = optional_params.declared_total_mpp_value_override {
+			if mpp_amt < amount {
+				return Err(Bolt11PaymentError::InvalidAmount);
+			}
+			if invoice.amount_milli_satoshis().is_some_and(|invoice_amt| mpp_amt < invoice_amt) {
+				return Err(Bolt11PaymentError::InvalidAmount);
+			}
+			recipient_onion.total_mpp_amount_msat = mpp_amt;
+		}
+
 		let payment_params = PaymentParameters::from_bolt11_invoice(invoice)
 			.with_user_config_ignoring_fee_limit(optional_params.route_params_config);