Add pay_for_bolt12_invoice for externally-sourced BOLT 12 invoices

lightning/src/ln/channelmanager.rs

@@ -758,6 +758,33 @@ impl Default for OptionalBolt11PaymentParams {
 	}
 }
 
+/// Optional arguments to [`ChannelManager::pay_for_bolt12_invoice`].
+///
+/// These fields will often not need to be set, and the provided [`Self::default`] can be used.
+pub struct OptionalBolt12PaymentParams {
+	/// Pathfinding options which tweak how the path is constructed to the recipient.
+	pub route_params_config: RouteParametersConfig,
+	/// The number of tries or time during which we'll retry this payment if some paths to the
+	/// recipient fail.
+	///
+	/// Once the retry limit is reached, further path failures will not be retried and the payment
+	/// will ultimately fail once all pending paths have failed (generating an
+	/// [`Event::PaymentFailed`]).
+	pub retry_strategy: Retry,
+}
+
+impl Default for OptionalBolt12PaymentParams {
+	fn default() -> Self {
+		Self {
+			route_params_config: Default::default(),
+			#[cfg(feature = "std")]
+			retry_strategy: Retry::Timeout(core::time::Duration::from_secs(2)),
+			#[cfg(not(feature = "std"))]
+			retry_strategy: Retry::Attempts(3),
+		}
+	}
+}
+
 /// Optional arguments to [`ChannelManager::pay_for_offer`].
 ///
 /// These fields will often not need to be set, and the provided [`Self::default`] can be used.
@@ -5857,6 +5884,50 @@ impl<
 		)
 	}
 
+	/// Pays a [`Bolt12Invoice`] without requiring it to have been requested through LDK.
+	///
+	/// Unlike [`ChannelManager::send_payment_for_bolt12_invoice`], this method does not verify
+	/// that the invoice was previously requested. The caller is responsible for invoice
+	/// verification and for providing a unique `payment_id`.
+	///
+	/// `amount_msats` controls how much this node contributes to the payment. Set to `None` to pay
+	/// the full invoice amount. For payments split across multiple senders, provide a partial
+	/// `amount_msats` here — the onion total is always set to the full invoice amount so that the
+	/// recipient can correctly validate the payment.
+	///
+	/// Returns [`Bolt12PaymentError::DuplicateInvoice`] if a payment with the given `payment_id`
+	/// is already pending, or [`Bolt12PaymentError::InvalidAmount`] if `amount_msats` exceeds the
+	/// invoice amount.
+	///
+	/// Either [`Event::PaymentSent`] or [`Event::PaymentFailed`] will be generated once the
+	/// payment completes.
+	pub fn pay_for_bolt12_invoice(
+		&self, invoice: &Bolt12Invoice, payment_id: PaymentId, amount_msats: Option<u64>,
+		optional_params: OptionalBolt12PaymentParams,
+	) -> Result<(), Bolt12PaymentError> {
+		let best_block_height = self.best_block.read().unwrap().height;
+		let _persistence_guard = PersistenceNotifierGuard::notify_on_drop(self);
+		let features = self.bolt12_invoice_features();
+		self.pending_outbound_payments.pay_for_bolt12_invoice(
+			invoice,
+			payment_id,
+			amount_msats,
+			optional_params,
+			&self.router,
+			self.list_usable_channels(),
+			features,
+			|| self.compute_inflight_htlcs(),
+			&self.entropy_source,
+			&self.node_signer,
+			&self,
+			&self.secp_ctx,
+			best_block_height,
+			&self.pending_events,
+			|args| self.send_payment_along_path(args),
+			&WithContext::for_payment(&self.logger, None, None, None, payment_id),
+		)
+	}
+
 	fn check_refresh_async_receive_offer_cache(&self, timer_tick_occurred: bool) {
 		let peers = self.get_peers_for_blinded_path();
 		let channels = self.list_usable_channels();
@@ -17059,6 +17130,11 @@ impl<
 						log_trace!($logger, "{}", err_msg);
 						InvoiceError::from_string(err_msg.to_string())
 					},
+					Err(Bolt12PaymentError::InvalidAmount) => {
+						debug_assert!(false, "Got InvalidAmount paying internally-sourced invoice; this shouldn't happen");
+						log_error!($logger, "Got InvalidAmount paying internally-sourced invoice; this shouldn't happen");
+						return None
+					},
 					Err(Bolt12PaymentError::UnexpectedInvoice)
 						| Err(Bolt12PaymentError::DuplicateInvoice)
 						| Ok(()) => return None,

lightning/src/ln/offers_tests.rs

@@ -2667,3 +2667,229 @@ fn creates_and_pays_for_phantom_offer() {
 		assert!(nodes[0].onion_messenger.next_onion_message_for_peer(node_c_id).is_none());
 	}
 }
+
+/// Checks that a BOLT 12 invoice can be paid via [`ChannelManager::pay_for_bolt12_invoice`]
+/// without requiring a prior LDK-managed payment request.
+#[test]
+fn pay_for_bolt12_invoice_with_fresh_payment_id() {
+	let mut manually_pay_cfg = test_default_channel_config();
+	manually_pay_cfg.manually_handle_bolt12_invoices = true;
+
+	let chanmon_cfgs = create_chanmon_cfgs(2);
+	let node_cfgs = create_node_cfgs(2, &chanmon_cfgs);
+	let node_chanmgrs = create_node_chanmgrs(2, &node_cfgs, &[None, Some(manually_pay_cfg)]);
+	let nodes = create_network(2, &node_cfgs, &node_chanmgrs);
+
+	create_announced_chan_between_nodes_with_value(&nodes, 0, 1, 10_000_000, 1_000_000_000);
+
+	let alice = &nodes[0];
+	let alice_id = alice.node.get_our_node_id();
+	let bob = &nodes[1];
+	let bob_id = bob.node.get_our_node_id();
+
+	let offer = alice.node
+		.create_offer_builder().unwrap()
+		.amount_msats(10_000_000)
+		.build().unwrap();
+
+	// Use the standard offer flow to obtain an invoice, but pay it via the new API with a
+	// fresh payment_id rather than the one from the original request.
+	let orig_payment_id = PaymentId([1; 32]);
+	bob.node.pay_for_offer(&offer, None, orig_payment_id, Default::default()).unwrap();
+
+	let onion_message = bob.onion_messenger.next_onion_message_for_peer(alice_id).unwrap();
+	alice.onion_messenger.handle_onion_message(bob_id, &onion_message);
+
+	let (invoice_request, _) = extract_invoice_request(alice, &onion_message);
+	let payment_context = PaymentContext::Bolt12Offer(Bolt12OfferContext {
+		offer_id: offer.id(),
+		invoice_request: InvoiceRequestFields {
+			payer_signing_pubkey: invoice_request.payer_signing_pubkey(),
+			quantity: None,
+			payer_note_truncated: None,
+			human_readable_name: None,
+		},
+	});
+
+	let onion_message = alice.onion_messenger.next_onion_message_for_peer(bob_id).unwrap();
+	bob.onion_messenger.handle_onion_message(alice_id, &onion_message);
+
+	let invoice = match get_event!(bob, Event::InvoiceReceived) {
+		Event::InvoiceReceived { invoice, .. } => invoice,
+		_ => panic!("Expected InvoiceReceived"),
+	};
+
+	// Abandon the original payment since we're paying via a fresh payment_id below.
+	bob.node.abandon_payment(orig_payment_id);
+	get_event!(bob, Event::PaymentFailed);
+
+	let payment_id = PaymentId([2; 32]);
+	bob.node.pay_for_bolt12_invoice(&invoice, payment_id, None, Default::default()).unwrap();
+	expect_recent_payment!(bob, RecentPaymentDetails::Pending, payment_id);
+
+	route_bolt12_payment(bob, &[alice], &invoice);
+	claim_bolt12_payment(bob, &[alice], payment_context, &invoice);
+	expect_recent_payment!(bob, RecentPaymentDetails::Fulfilled, payment_id);
+}
+
+/// Checks error cases for [`ChannelManager::pay_for_bolt12_invoice`]:
+/// zero amount and overpaying return [`Bolt12PaymentError::InvalidAmount`], re-using a
+/// payment_id returns [`Bolt12PaymentError::DuplicateInvoice`].
+#[test]
+fn pay_for_bolt12_invoice_error_cases() {
+	let mut manually_pay_cfg = test_default_channel_config();
+	manually_pay_cfg.manually_handle_bolt12_invoices = true;
+
+	let chanmon_cfgs = create_chanmon_cfgs(2);
+	let node_cfgs = create_node_cfgs(2, &chanmon_cfgs);
+	let node_chanmgrs = create_node_chanmgrs(2, &node_cfgs, &[None, Some(manually_pay_cfg)]);
+	let nodes = create_network(2, &node_cfgs, &node_chanmgrs);
+
+	create_announced_chan_between_nodes_with_value(&nodes, 0, 1, 10_000_000, 1_000_000_000);
+
+	let alice = &nodes[0];
+	let alice_id = alice.node.get_our_node_id();
+	let bob = &nodes[1];
+	let bob_id = bob.node.get_our_node_id();
+
+	let offer = alice.node
+		.create_offer_builder().unwrap()
+		.amount_msats(10_000_000)
+		.build().unwrap();
+
+	let orig_payment_id = PaymentId([1; 32]);
+	bob.node.pay_for_offer(&offer, None, orig_payment_id, Default::default()).unwrap();
+
+	let onion_message = bob.onion_messenger.next_onion_message_for_peer(alice_id).unwrap();
+	alice.onion_messenger.handle_onion_message(bob_id, &onion_message);
+
+	let (invoice_request, _) = extract_invoice_request(alice, &onion_message);
+	let payment_context = PaymentContext::Bolt12Offer(Bolt12OfferContext {
+		offer_id: offer.id(),
+		invoice_request: InvoiceRequestFields {
+			payer_signing_pubkey: invoice_request.payer_signing_pubkey(),
+			quantity: None,
+			payer_note_truncated: None,
+			human_readable_name: None,
+		},
+	});
+
+	let onion_message = alice.onion_messenger.next_onion_message_for_peer(bob_id).unwrap();
+	bob.onion_messenger.handle_onion_message(alice_id, &onion_message);
+
+	let invoice = match get_event!(bob, Event::InvoiceReceived) {
+		Event::InvoiceReceived { invoice, .. } => invoice,
+		_ => panic!("Expected InvoiceReceived"),
+	};
+
+	bob.node.abandon_payment(orig_payment_id);
+	get_event!(bob, Event::PaymentFailed);
+
+	let payment_id = PaymentId([2; 32]);
+
+	// Zero amount is rejected.
+	assert_eq!(
+		bob.node.pay_for_bolt12_invoice(&invoice, payment_id, Some(0), Default::default()),
+		Err(Bolt12PaymentError::InvalidAmount),
+	);
+
+	// Overpaying is rejected before any state is inserted.
+	assert_eq!(
+		bob.node.pay_for_bolt12_invoice(
+			&invoice, payment_id, Some(invoice.amount_msats() + 1), Default::default()
+		),
+		Err(Bolt12PaymentError::InvalidAmount),
+	);
+
+	// First call succeeds and starts the payment.
+	bob.node.pay_for_bolt12_invoice(&invoice, payment_id, None, Default::default()).unwrap();
+
+	// Re-using the same payment_id is rejected.
+	assert_eq!(
+		bob.node.pay_for_bolt12_invoice(&invoice, payment_id, None, Default::default()),
+		Err(Bolt12PaymentError::DuplicateInvoice),
+	);
+
+	route_bolt12_payment(bob, &[alice], &invoice);
+	claim_bolt12_payment(bob, &[alice], payment_context, &invoice);
+	expect_recent_payment!(bob, RecentPaymentDetails::Fulfilled, payment_id);
+}
+
+/// Checks that pay_for_bolt12_invoice with a partial amount routes an HTLC for the partial
+/// amount while setting total_mpp_amount_msat to the full invoice amount in the onion, so the
+/// recipient holds the HTLC awaiting additional parts until the full amount arrives.
+#[test]
+fn pay_for_bolt12_invoice_partial_amount() {
+	let mut manually_pay_cfg = test_default_channel_config();
+	manually_pay_cfg.manually_handle_bolt12_invoices = true;
+
+	let chanmon_cfgs = create_chanmon_cfgs(2);
+	let node_cfgs = create_node_cfgs(2, &chanmon_cfgs);
+	let node_chanmgrs = create_node_chanmgrs(2, &node_cfgs, &[None, Some(manually_pay_cfg)]);
+	let nodes = create_network(2, &node_cfgs, &node_chanmgrs);
+
+	create_announced_chan_between_nodes_with_value(&nodes, 0, 1, 10_000_000, 1_000_000_000);
+
+	let alice = &nodes[0];
+	let alice_id = alice.node.get_our_node_id();
+	let bob = &nodes[1];
+	let bob_id = bob.node.get_our_node_id();
+
+	let invoice_amount = 10_000_000u64;
+	let partial_amount = 5_000_000u64;
+
+	let offer = alice.node
+		.create_offer_builder().unwrap()
+		.amount_msats(invoice_amount)
+		.build().unwrap();
+
+	let orig_payment_id = PaymentId([1; 32]);
+	bob.node.pay_for_offer(&offer, None, orig_payment_id, Default::default()).unwrap();
+
+	let onion_message = bob.onion_messenger.next_onion_message_for_peer(alice_id).unwrap();
+	alice.onion_messenger.handle_onion_message(bob_id, &onion_message);
+
+	let onion_message = alice.onion_messenger.next_onion_message_for_peer(bob_id).unwrap();
+	bob.onion_messenger.handle_onion_message(alice_id, &onion_message);
+
+	let invoice = match get_event!(bob, Event::InvoiceReceived) {
+		Event::InvoiceReceived { invoice, .. } => invoice,
+		_ => panic!("Expected InvoiceReceived"),
+	};
+
+	bob.node.abandon_payment(orig_payment_id);
+	get_event!(bob, Event::PaymentFailed);
+
+	let payment_hash = invoice.payment_hash();
+	let payment_id = PaymentId([2; 32]);
+
+	let params = channelmanager::OptionalBolt12PaymentParams {
+		retry_strategy: Retry::Attempts(0),
+		..Default::default()
+	};
+	bob.node.pay_for_bolt12_invoice(&invoice, payment_id, Some(partial_amount), params).unwrap();
+	expect_recent_payment!(bob, RecentPaymentDetails::Pending, payment_id);
+
+	check_added_monitors(bob, 1);
+	let mut events = bob.node.get_and_clear_pending_msg_events();
+	assert_eq!(events.len(), 1);
+	let ev = remove_first_msg_event_to_node(&alice_id, &mut events);
+
+	// The HTLC carries the partial amount, not the full invoice amount.
+	if let crate::ln::msgs::MessageSendEvent::UpdateHTLCs { ref updates, .. } = ev {
+		assert_eq!(updates.update_add_htlcs[0].amount_msat, partial_amount);
+	} else {
+		panic!("Expected UpdateHTLCs");
+	}
+
+	do_pass_along_path(
+		PassAlongPathArgs::new(bob, &[alice], partial_amount, payment_hash, ev)
+			.without_clearing_recipient_events()
+			.without_claimable_event()
+			.with_dummy_tlvs(&[DummyTlvs::default(); DEFAULT_PAYMENT_DUMMY_HOPS])
+	);
+
+	// Alice has not emitted PaymentClaimable: total_mpp_amount_msat in the onion equals the
+	// full invoice amount (10M), so she waits for the remaining 5M before settling.
+	assert!(alice.node.get_and_clear_pending_events().is_empty());
+}