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

@@ -685,6 +685,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 {
@@ -696,6 +710,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,
 		}
 	}
 }
@@ -5451,10 +5466,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 amount (which can be fetched with
+	/// [`Bolt11Invoice::amount_milli_satoshis`]) while others allow you to pay amount 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

@@ -691,6 +691,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,11 @@ 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 user-provided amount is less than an amount specified in the
+	/// [`Bolt11Invoice`] 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
@@ -1031,9 +1035,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),
 		};
@@ -1043,6 +1049,18 @@ 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 let Some(invoice_amount) = invoice.amount_milli_satoshis() {
+				if mpp_amt < invoice_amount {
+					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);
 

lightning/src/ln/payment_tests.rs

@@ -5423,3 +5423,160 @@ fn max_out_mpp_path() {
 	check_added_monitors(&nodes[0], 2); // one monitor update per MPP part
 	nodes[0].node.get_and_clear_pending_msg_events();
 }
+
+#[test]
+fn bolt11_multi_node_mpp() {
+	// Test that multiple nodes can collaborate to pay a single BOLT 11 invoice, with each node
+	// paying a portion of the total invoice amount. This is useful for scenarios like:
+	// - Paying from multiple wallets (e.g., ecash wallets with funds in multiple mints)
+	// - Graduated wallets (funds split between trusted and self-custodial wallets)
+
+	let chanmon_cfgs = create_chanmon_cfgs(3);
+	let node_cfgs = create_node_cfgs(3, &chanmon_cfgs);
+	let node_chanmgrs = create_node_chanmgrs(3, &node_cfgs, &[None, None, None]);
+	let nodes = create_network(3, &node_cfgs, &node_chanmgrs);
+
+	// Create channels: A<>C and B<>C
+	create_announced_chan_between_nodes(&nodes, 0, 2);
+	create_announced_chan_between_nodes(&nodes, 1, 2);
+
+	// Node C creates a BOLT 11 invoice for 100_000 msat
+	let invoice_amt_msat = 100_000;
+	let invoice_params = crate::ln::channelmanager::Bolt11InvoiceParameters {
+		amount_msats: Some(invoice_amt_msat),
+		..Default::default()
+	};
+	let invoice = nodes[2].node.create_bolt11_invoice(invoice_params).unwrap();
+
+	// Node A pays 60_000 msat (part of the total)
+	let node_a_payment_amt = 60_000;
+	let payment_id_a = PaymentId([1; 32]);
+	let optional_params_a = crate::ln::channelmanager::OptionalBolt11PaymentParams {
+		declared_total_mpp_value_override: Some(invoice_amt_msat),
+		..Default::default()
+	};
+	nodes[0]
+		.node
+		.pay_for_bolt11_invoice(&invoice, payment_id_a, Some(node_a_payment_amt), optional_params_a)
+		.unwrap();
+	check_added_monitors(&nodes[0], 1);
+
+	// Node B pays 40_000 msat (the remaining part)
+	let node_b_payment_amt = 40_000;
+	let payment_id_b = PaymentId([2; 32]);
+	let optional_params_b = crate::ln::channelmanager::OptionalBolt11PaymentParams {
+		declared_total_mpp_value_override: Some(invoice_amt_msat),
+		..Default::default()
+	};
+	nodes[1]
+		.node
+		.pay_for_bolt11_invoice(&invoice, payment_id_b, Some(node_b_payment_amt), optional_params_b)
+		.unwrap();
+	check_added_monitors(&nodes[1], 1);
+
+	let payment_event_a = SendEvent::from_node(&nodes[0]);
+	nodes[2].node.handle_update_add_htlc(nodes[0].node.get_our_node_id(), &payment_event_a.msgs[0]);
+	do_commitment_signed_dance(&nodes[2], &nodes[0], &payment_event_a.commitment_msg, false, false);
+
+	let payment_event_b = SendEvent::from_node(&nodes[1]);
+	nodes[2].node.handle_update_add_htlc(nodes[1].node.get_our_node_id(), &payment_event_b.msgs[0]);
+	do_commitment_signed_dance(&nodes[2], &nodes[1], &payment_event_b.commitment_msg, false, false);
+
+	// Process the pending HTLCs on node C and generate the PaymentClaimable event
+	assert!(nodes[2].node.get_and_clear_pending_events().is_empty());
+	expect_and_process_pending_htlcs(&nodes[2], false);
+	let events = nodes[2].node.get_and_clear_pending_events();
+	assert_eq!(events.len(), 1);
+	let payment_preimage = match &events[0] {
+		Event::PaymentClaimable {
+			payment_hash,
+			amount_msat,
+			purpose: PaymentPurpose::Bolt11InvoicePayment { payment_preimage, .. },
+			..
+		} => {
+			assert_eq!(*payment_hash, invoice.payment_hash());
+			assert_eq!(*amount_msat, invoice_amt_msat);
+			payment_preimage.unwrap()
+		},
+		_ => panic!("Unexpected event: {:?}", events[0]),
+	};
+
+	nodes[2].node.claim_funds(payment_preimage);
+
+	expect_payment_claimed!(nodes[2], invoice.payment_hash(), invoice_amt_msat);
+	check_added_monitors(&nodes[2], 2);
+
+	// Get the fulfill messages from C to both A and B
+	let mut events_c = nodes[2].node.get_and_clear_pending_msg_events();
+	assert_eq!(events_c.len(), 2);
+
+	// Handle fulfill message from C to A
+	let fulfill_idx_a = events_c
+		.iter()
+		.position(|ev| {
+			if let MessageSendEvent::UpdateHTLCs { node_id, .. } = ev {
+				*node_id == nodes[0].node.get_our_node_id()
+			} else {
+				false
+			}
+		})
+		.unwrap();
+	let fulfill_idx_b = 1 - fulfill_idx_a;
+
+	if let MessageSendEvent::UpdateHTLCs { ref updates, .. } = events_c[fulfill_idx_a] {
+		nodes[0].node.handle_update_fulfill_htlc(
+			nodes[2].node.get_our_node_id(),
+			updates.update_fulfill_htlcs[0].clone(),
+		);
+		do_commitment_signed_dance(&nodes[0], &nodes[2], &updates.commitment_signed, false, false);
+	}
+
+	let payment_sent = nodes[0].node.get_and_clear_pending_events();
+	check_added_monitors(&nodes[0], 1);
+
+	assert_eq!(payment_sent.len(), 2, "{payment_sent:?}");
+	if let Event::PaymentSent { payment_id, payment_hash, amount_msat, fee_paid_msat, .. } =
+		&payment_sent[0]
+	{
+		assert_eq!(*payment_id, Some(payment_id_a));
+		assert_eq!(*payment_hash, invoice.payment_hash());
+		assert_eq!(*amount_msat, Some(node_a_payment_amt));
+		assert_eq!(*fee_paid_msat, Some(0));
+	} else {
+		panic!("{payment_sent:?}");
+	}
+	if let Event::PaymentPathSuccessful { payment_id, .. } = &payment_sent[1] {
+		assert_eq!(*payment_id, payment_id_a);
+	} else {
+		panic!("{payment_sent:?}");
+	}
+
+	// Handle fulfill message from C to B
+	if let MessageSendEvent::UpdateHTLCs { ref updates, .. } = events_c[fulfill_idx_b] {
+		nodes[1].node.handle_update_fulfill_htlc(
+			nodes[2].node.get_our_node_id(),
+			updates.update_fulfill_htlcs[0].clone(),
+		);
+		do_commitment_signed_dance(&nodes[1], &nodes[2], &updates.commitment_signed, false, false);
+	}
+
+	let payment_sent = nodes[1].node.get_and_clear_pending_events();
+	check_added_monitors(&nodes[1], 1);
+
+	assert_eq!(payment_sent.len(), 2, "{payment_sent:?}");
+	if let Event::PaymentSent { payment_id, payment_hash, amount_msat, fee_paid_msat, .. } =
+		&payment_sent[0]
+	{
+		assert_eq!(*payment_id, Some(payment_id_b));
+		assert_eq!(*payment_hash, invoice.payment_hash());
+		assert_eq!(*amount_msat, Some(node_b_payment_amt));
+		assert_eq!(*fee_paid_msat, Some(0));
+	} else {
+		panic!("{payment_sent:?}");
+	}
+	if let Event::PaymentPathSuccessful { payment_id, .. } = &payment_sent[1] {
+		assert_eq!(*payment_id, payment_id_b);
+	} else {
+		panic!("{payment_sent:?}");
+	}
+}