tests: Add interoperability tests for BOLT12 (Offers) with CLN

Activates scenarios for BOLT12 offer payments between
ldk-node and Core Lightning (CLN) inside integration tests

Fix #856

Author: alexgrad42

tests/common/cln.rs

@@ -181,6 +181,41 @@ impl ExternalNode for TestClnNode {
 		Ok(invoice.bolt11)
 	}
 
+	async fn create_offer(
+		&self, amount_msat: u64, description: &str,
+	) -> Result<String, TestFailure> {
+		let desc = description.to_string();
+		let label = format!(
+			"{}-{}",
+			desc,
+			std::time::SystemTime::now()
+				.duration_since(std::time::UNIX_EPOCH)
+				.unwrap_or_default()
+				.as_nanos()
+		);
+
+		let params = serde_json::json!({
+			"amount": format!("{}msat", amount_msat),
+			"description": desc,
+			"label": label,
+			"single_use": true,
+		});
+
+		let response: serde_json::Value = self
+			.rpc(move |c| c.call("offer", params))
+			.await
+			.map_err(|e| self.make_error(format!("offer RPC call failed: {}", e)))?;
+
+		let offer_str = response["bolt12"]
+			.as_str()
+			.ok_or_else(|| {
+				self.make_error("Failed to parse 'bolt12' from CLN response".to_string())
+			})?
+			.to_string();
+
+		Ok(offer_str)
+	}
+
 	async fn pay_invoice(&self, invoice: &str) -> Result<String, TestFailure> {
 		let inv = invoice.to_string();
 		let result = self
@@ -190,6 +225,40 @@ impl ExternalNode for TestClnNode {
 		Ok(result.payment_preimage)
 	}
 
+	async fn pay_offer(
+		&self, offer_str: &str, amount_msat: Option<u64>,
+	) -> Result<String, TestFailure> {
+		let offer = offer_str.to_string();
+
+		let mut fetch_params = serde_json::json!({
+			"offer": offer,
+			"quantity": 1,
+		});
+
+		if let Some(msat) = amount_msat {
+			fetch_params["amount_msat"] = serde_json::json!(format!("{}msat", msat));
+		}
+
+		let fetch_response: serde_json::Value =
+			self.rpc(move |c| c.call("fetchinvoice", fetch_params)).await.map_err(|e| {
+				self.make_error(format!("fetchinvoice RPC call failed for BOLT12: {}", e))
+			})?;
+
+		let inv = fetch_response["invoice"]
+			.as_str()
+			.ok_or_else(|| {
+				self.make_error("Failed to parse 'invoice' from fetchinvoice response".to_string())
+			})?
+			.to_string();
+
+		let result = self
+			.rpc(move |c| c.pay(&inv, PayOptions::default()))
+			.await
+			.map_err(|e| self.make_error(format!("pay: {}", e)))?;
+
+		Ok(result.payment_preimage)
+	}
+
 	async fn send_keysend(
 		&self, peer_id: PublicKey, amount_msat: u64,
 	) -> Result<String, TestFailure> {

tests/common/eclair.rs

@@ -211,6 +211,12 @@ impl ExternalNode for TestEclairNode {
 		Ok(invoice.to_string())
 	}
 
+	async fn create_offer(
+		&self, amount_msat: u64, description: &str,
+	) -> Result<String, TestFailure> {
+		Err(self.make_error("create_offer is not supported on Eclair".to_string()))
+	}
+
 	async fn pay_invoice(&self, invoice: &str) -> Result<String, TestFailure> {
 		let result = self.post("/payinvoice", &[("invoice", invoice)]).await?;
 		let payment_id = result
@@ -220,6 +226,12 @@ impl ExternalNode for TestEclairNode {
 		self.poll_payment_settlement(&payment_id, "payment").await
 	}
 
+	async fn pay_offer(
+		&self, _offer_str: &str, _amount_msat: Option<u64>,
+	) -> Result<String, TestFailure> {
+		Err(self.make_error("pay_offer is not supported on Eclair".to_string()))
+	}
+
 	async fn send_keysend(
 		&self, peer_id: PublicKey, amount_msat: u64,
 	) -> Result<String, TestFailure> {

tests/common/external_node.rs

@@ -87,9 +87,19 @@ pub(crate) trait ExternalNode: Send + Sync {
 		&self, amount_msat: u64, description: &str,
 	) -> Result<String, TestFailure>;
 
+	/// Create a BOLT12 offer for the given amount
+	async fn create_offer(
+		&self, amount_msat: u64, description: &str,
+	) -> Result<String, TestFailure>;
+
 	/// Pay a BOLT11 invoice; returns an implementation-specific payment identifier on success.
 	async fn pay_invoice(&self, invoice: &str) -> Result<String, TestFailure>;
 
+	/// Pay a BOLT12 offer; returns an implementation-specific payment identifier on success.
+	async fn pay_offer(
+		&self, offer_str: &str, amount_msat: Option<u64>,
+	) -> Result<String, TestFailure>;
+
 	/// Send a keysend payment to a peer.
 	async fn send_keysend(
 		&self, peer_id: PublicKey, amount_msat: u64,

tests/common/lnd.rs

@@ -243,6 +243,14 @@ impl ExternalNode for TestLndNode {
 		Ok(response.payment_request)
 	}
 
+	async fn create_offer(
+		&self, amount_msat: u64, description: &str,
+	) -> Result<String, TestFailure> {
+		Err(self.make_error(
+			"create_offer is not supported on LND without LNDK integration".to_string(),
+		))
+	}
+
 	async fn pay_invoice(&self, invoice: &str) -> Result<String, TestFailure> {
 		let mut client = self.client.lock().await;
 		let request = SendPaymentRequest {
@@ -280,6 +288,13 @@ impl ExternalNode for TestLndNode {
 		Err(self.make_error("payment stream ended without terminal status"))
 	}
 
+	async fn pay_offer(
+		&self, _offer_str: &str, _amount_msat: Option<u64>,
+	) -> Result<String, TestFailure> {
+		Err(self
+			.make_error("pay_offer is not supported on LND without LNDK integration".to_string()))
+	}
+
 	async fn send_keysend(
 		&self, peer_id: PublicKey, amount_msat: u64,
 	) -> Result<String, TestFailure> {

tests/common/mod.rs

@@ -216,10 +216,30 @@ macro_rules! expect_payment_received_event {
 			panic!("{} timed out waiting for PaymentReceived event after 60s", $node.node_id())
 		});
 		match event {
-			ref e @ Event::PaymentReceived { payment_id, amount_msat, .. } => {
+			ref e @ Event::PaymentReceived { payment_id, amount_msat: rec_msat, .. } => {
 				println!("{} got event {:?}", $node.node_id(), e);
-				assert_eq!(amount_msat, $amount_msat);
+
 				let payment = $node.payment(&payment_id.unwrap()).unwrap();
+
+				match payment.kind {
+					ldk_node::payment::PaymentKind::Bolt12Offer { .. } => {
+						// BOLT12: Blinded paths can lead to minor overpayments (e.g., routing path fees)
+						assert!(
+							rec_msat >= $amount_msat,
+							"BOLT12: Received amount ({}) is less than expected ({})",
+							rec_msat,
+							$amount_msat
+						);
+					},
+					_ => {
+						assert_eq!(
+							rec_msat, $amount_msat,
+							"BOLT11/Keysend: Received amount ({}) does not match expected ({})",
+							rec_msat, $amount_msat
+						);
+					},
+				}
+
 				if !matches!(payment.kind, ldk_node::payment::PaymentKind::Onchain { .. }) {
 					assert_eq!(payment.fee_paid_msat, None);
 				}

tests/common/scenarios/mod.rs

@@ -151,7 +151,7 @@ pub(crate) async fn run_interop_scenario<N, E, F>(
 }
 
 /// Open a channel, send a BOLT11 payment in each direction, then cooperatively close.
-pub(crate) async fn basic_channel_cycle_scenario<E: ElectrumApi>(
+pub(crate) async fn basic_channel_cycle_bolt11_scenario<E: ElectrumApi>(
 	node: &Node, peer: &(impl ExternalNode + ?Sized), bitcoind: &BitcoindClient, electrs: &E,
 ) {
 	let (user_ch, ext_ch) = channel::open_channel_to_external(
@@ -164,12 +164,32 @@ pub(crate) async fn basic_channel_cycle_scenario<E: ElectrumApi>(
 	)
 	.await;
 
-	payment::send_bolt11_to_peer(node, peer, 10_000_000, "basic-send").await;
+	payment::send_bolt11_to_peer(node, peer, 10_000_000, "basic-send-bolt11").await;
 	payment::receive_bolt11_payment(node, peer, 10_000_000).await;
 
 	channel::cooperative_close(node, peer, bitcoind, electrs, &user_ch, &ext_ch, Side::Ldk).await;
 }
 
+/// Open a channel, send a BOLT12 payment in each direction, then cooperatively close.
+pub(crate) async fn basic_channel_cycle_bolt12_scenario<E: ElectrumApi>(
+	node: &Node, peer: &(impl ExternalNode + ?Sized), bitcoind: &BitcoindClient, electrs: &E,
+) {
+	let (user_ch, ext_ch) = channel::open_channel_to_external(
+		node,
+		peer,
+		bitcoind,
+		electrs,
+		1_000_000,
+		Some(500_000_000),
+	)
+	.await;
+
+	payment::send_bolt12_to_peer(node, peer, 10_000_000, "basic-send-bolt12").await;
+	payment::receive_bolt12_payment(node, peer, 10_000_000).await;
+
+	channel::cooperative_close(node, peer, bitcoind, electrs, &user_ch, &ext_ch, Side::Ldk).await;
+}
+
 /// Open a channel, send keysend in both directions, then cooperatively close.
 pub(crate) async fn keysend_scenario<E: ElectrumApi>(
 	node: &Node, peer: &(impl ExternalNode + ?Sized), bitcoind: &BitcoindClient, electrs: &E,
@@ -188,8 +208,8 @@ pub(crate) async fn keysend_scenario<E: ElectrumApi>(
 	channel::cooperative_close(node, peer, bitcoind, electrs, &user_ch, &ext_ch, Side::Ldk).await;
 }
 
-/// Open a channel, send a payment, then force-close from the LDK side.
-pub(crate) async fn force_close_after_payment_scenario<E: ElectrumApi>(
+/// Open a channel, send a BOLT11 payment, then force-close from the LDK side.
+pub(crate) async fn force_close_after_payment_bolt11_scenario<E: ElectrumApi>(
 	node: &Node, peer: &(impl ExternalNode + ?Sized), bitcoind: &BitcoindClient, electrs: &E,
 ) {
 	let (user_ch, ext_ch) = channel::open_channel_to_external(
@@ -201,7 +221,25 @@ pub(crate) async fn force_close_after_payment_scenario<E: ElectrumApi>(
 		Some(500_000_000),
 	)
 	.await;
-	payment::send_bolt11_to_peer(node, peer, 5_000_000, "force-close").await;
+	payment::send_bolt11_to_peer(node, peer, 5_000_000, "force-close-bolt11").await;
+	wait_for_htlcs_settled(peer, &ext_ch).await;
+	channel::force_close(node, peer, bitcoind, electrs, &user_ch, &ext_ch, Side::Ldk).await;
+}
+
+/// Open a channel, send a BOLT12 payment, then force-close from the LDK side.
+pub(crate) async fn force_close_after_payment_bolt12_scenario<E: ElectrumApi>(
+	node: &Node, peer: &(impl ExternalNode + ?Sized), bitcoind: &BitcoindClient, electrs: &E,
+) {
+	let (user_ch, ext_ch) = channel::open_channel_to_external(
+		node,
+		peer,
+		bitcoind,
+		electrs,
+		1_000_000,
+		Some(500_000_000),
+	)
+	.await;
+	payment::send_bolt12_to_peer(node, peer, 5_000_000, "force-close-bolt12").await;
 	wait_for_htlcs_settled(peer, &ext_ch).await;
 	channel::force_close(node, peer, bitcoind, electrs, &user_ch, &ext_ch, Side::Ldk).await;
 }
@@ -225,8 +263,33 @@ pub(crate) async fn disconnect_during_payment_scenario<E: ElectrumApi>(
 	channel::cooperative_close(node, peer, bitcoind, electrs, &user_ch, &ext_ch, Side::Ldk).await;
 }
 
-/// Open a channel, splice-in additional funds, send a post-splice payment, then close.
-pub(crate) async fn splice_in_scenario<E: ElectrumApi>(
+/// Open a channel, splice-in additional funds, send a post-splice BOLT11 payment, then close.
+pub(crate) async fn splice_in_bolt11_scenario<E: ElectrumApi>(
+	node: &Node, peer: &(impl ExternalNode + ?Sized), bitcoind: &BitcoindClient, electrs: &E,
+) {
+	let (user_ch, ext_ch) = channel::open_channel_to_external(
+		node,
+		peer,
+		bitcoind,
+		electrs,
+		1_000_000,
+		Some(500_000_000),
+	)
+	.await;
+	let ext_node_id = peer.get_node_id().await.unwrap();
+	node.splice_in(&user_ch, ext_node_id, 500_000).unwrap();
+	expect_splice_pending_event!(node, ext_node_id);
+	generate_blocks_and_wait(bitcoind, electrs, 6).await;
+	sync_wallets_with_retry(node).await;
+	expect_channel_ready_event!(node, ext_node_id);
+
+	payment::send_bolt11_to_peer(node, peer, 5_000_000, "post-splice-bolt11").await;
+
+	channel::cooperative_close(node, peer, bitcoind, electrs, &user_ch, &ext_ch, Side::Ldk).await;
+}
+
+/// Open a channel, splice-in additional funds, send a post-splice BOLT12 payment, then close.
+pub(crate) async fn splice_in_bolt12_scenario<E: ElectrumApi>(
 	node: &Node, peer: &(impl ExternalNode + ?Sized), bitcoind: &BitcoindClient, electrs: &E,
 ) {
 	let (user_ch, ext_ch) = channel::open_channel_to_external(
@@ -245,7 +308,7 @@ pub(crate) async fn splice_in_scenario<E: ElectrumApi>(
 	sync_wallets_with_retry(node).await;
 	expect_channel_ready_event!(node, ext_node_id);
 
-	payment::send_bolt11_to_peer(node, peer, 5_000_000, "post-splice").await;
+	payment::send_bolt12_to_peer(node, peer, 5_000_000, "post-splice-bolt12").await;
 
 	channel::cooperative_close(node, peer, bitcoind, electrs, &user_ch, &ext_ch, Side::Ldk).await;
 }

tests/common/scenarios/payment.rs

@@ -7,11 +7,11 @@
 
 use std::str::FromStr;
 
-use ldk_node::{Event, Node};
-use lightning_invoice::{Bolt11Invoice, Bolt11InvoiceDescription, Description};
-
 use super::super::external_node::ExternalNode;
 use super::retry_until_ok;
+use ldk_node::{Event, Node};
+use lightning::offers::offer::Offer;
+use lightning_invoice::{Bolt11Invoice, Bolt11InvoiceDescription, Description};
 
 /// LDK pays the peer via a fresh BOLT11 invoice; asserts `PaymentSuccessful`.
 pub(crate) async fn send_bolt11_to_peer(
@@ -23,6 +23,16 @@ pub(crate) async fn send_bolt11_to_peer(
 	expect_event!(node, PaymentSuccessful);
 }
 
+/// LDK pays the peer via a fresh BOLT12 offer; asserts `PaymentSuccessful`.
+pub(crate) async fn send_bolt12_to_peer(
+	node: &Node, peer: &(impl ExternalNode + ?Sized), amount_msat: u64, label: &str,
+) {
+	let offer_str = peer.create_offer(amount_msat, label).await.unwrap();
+	let parsed_offer = Offer::from_str(&offer_str).unwrap();
+	node.bolt12_payment().send(&parsed_offer, None, None, None).unwrap();
+	expect_event!(node, PaymentSuccessful);
+}
+
 /// External node pays LDK via BOLT11 invoice. Retries to absorb gossip-propagation
 /// delay (peer may not yet know a route to LDK right after channel confirmation).
 pub(crate) async fn receive_bolt11_payment(
@@ -33,7 +43,7 @@ pub(crate) async fn receive_bolt11_payment(
 		.receive(
 			amount_msat,
 			&Bolt11InvoiceDescription::Direct(
-				Description::new("interop-receive-test".to_string()).unwrap(),
+				Description::new("interop-receive-test-bolt11".to_string()).unwrap(),
 			),
 			3600,
 		)
@@ -43,6 +53,21 @@ pub(crate) async fn receive_bolt11_payment(
 	expect_payment_received_event!(node, amount_msat);
 }
 
+/// External node pays LDK via BOLT12 offer. Retries to absorb gossip-propagation
+/// delay (peer may not yet know a route to LDK right after channel confirmation).
+pub(crate) async fn receive_bolt12_payment(
+	node: &Node, peer: &(impl ExternalNode + ?Sized), amount_msat: u64,
+) {
+	let offer = node
+		.bolt12_payment()
+		.receive(amount_msat, "interop-receive-test-bolt12", Some(3600), Some(1))
+		.unwrap();
+	let offer_str = offer.to_string();
+	retry_until_ok(10, "receive_bolt12_payment", || peer.pay_offer(&offer_str, Some(amount_msat)))
+		.await;
+	expect_payment_received_event!(node, amount_msat);
+}
+
 /// LDK keysends to peer; asserts `PaymentSuccessful`.
 pub(crate) async fn send_keysend_to_peer(
 	node: &Node, peer: &(impl ExternalNode + ?Sized), amount_msat: u64,