add lsps4 bolt12 receive

Author: martinsaposnic

LSPS4_BOLT12_IMPLEMENTATION_PLAN.md

@@ -0,0 +1,162 @@
+# LSPS4 + BOLT12 JIT Channel Implementation Plan
+
+## Problem Statement
+Enable BOLT12 offers to work with LSPS4 JIT channels for nodes that have no existing channels.
+
+## Background
+
+### How BOLT12 Works
+1. Recipient creates an **Offer** (contains blinded MESSAGE paths for receiving invoice requests)
+2. Payer sends **InvoiceRequest** via onion message to recipient
+3. Recipient responds with **Bolt12Invoice** (contains blinded PAYMENT paths)
+4. Payer pays the invoice using the blinded payment paths
+
+### How LSPS4 Works
+1. Client registers with LSP, receives `intercept_scid` and `cltv_expiry_delta`
+2. Client creates invoices with route hint pointing to LSP via `intercept_scid`
+3. When payment arrives at `intercept_scid`, LSP intercepts HTLC and opens JIT channel
+4. LSP forwards payment to client
+
+### The Gap
+- **Message paths**: Work fine - LSP is a connected peer, can forward onion messages
+- **Payment paths**: Fail - `Router::create_blinded_payment_paths` requires usable channels
+
+## Solution
+
+### Architecture
+Create a wrapper router (`LSPS4Router`) that:
+1. Delegates to `DefaultRouter` for normal operations
+2. Falls back to LSPS4 blinded payment paths when no channels exist
+
+### Shared State
+```rust
+pub struct LSPS4BlindedPathConfig {
+    pub lsp_node_id: PublicKey,
+    pub intercept_scid: u64,
+    pub cltv_expiry_delta: u32,
+}
+```
+
+This state is:
+- Written by: LiquiditySource after LSPS4 registration
+- Read by: LSPS4Router when creating blinded payment paths
+
+### LSPS4Router Implementation
+```rust
+pub struct LSPS4Router<G, L, ES, S, SP, Sc> {
+    inner: DefaultRouter<G, L, ES, S, SP, Sc>,
+    lsps4_config: Arc<RwLock<Option<LSPS4BlindedPathConfig>>>,
+    entropy_source: ES,
+}
+
+impl Router for LSPS4Router {
+    fn create_blinded_payment_paths(...) -> Result<Vec<BlindedPaymentPath>, ()> {
+        // 1. Try normal path creation
+        if let Ok(paths) = self.inner.create_blinded_payment_paths(...) {
+            if !paths.is_empty() {
+                return Ok(paths);
+            }
+        }
+
+        // 2. Fall back to LSPS4 if configured
+        if let Some(config) = self.lsps4_config.read().unwrap().as_ref() {
+            return self.create_lsps4_blinded_path(config, recipient, tlvs, ...);
+        }
+
+        Err(())
+    }
+}
+```
+
+### LSPS4 Blinded Path Creation
+```rust
+fn create_lsps4_blinded_path(&self, config: &LSPS4BlindedPathConfig, ...) {
+    let forward_node = PaymentForwardNode {
+        node_id: config.lsp_node_id,
+        tlvs: ForwardTlvs {
+            short_channel_id: config.intercept_scid,
+            payment_relay: PaymentRelay {
+                cltv_expiry_delta: config.cltv_expiry_delta as u16,
+                fee_base_msat: 0,  // LSPS4 charges via channel opening
+                fee_proportional_millionths: 0,
+            },
+            payment_constraints: PaymentConstraints {
+                max_cltv_expiry: tlvs.tlvs().payment_constraints.max_cltv_expiry + config.cltv_expiry_delta,
+                htlc_minimum_msat: 0,
+            },
+            next_blinding_override: None,
+            features: BlindedHopFeatures::empty(),
+        },
+        htlc_maximum_msat: u64::MAX,
+    };
+
+    BlindedPaymentPath::new(
+        &[forward_node],
+        recipient,
+        tlvs,
+        u64::MAX,
+        MIN_FINAL_CLTV_EXPIRY_DELTA,
+        &self.entropy_source,
+        secp_ctx,
+    ).map(|path| vec![path])
+}
+```
+
+## Implementation Steps
+
+### Step 1: Create router module (src/router.rs) - DONE
+- [x] Define `LSPS4BlindedPathConfig` struct
+- [x] Create `LSPS4Router` struct wrapping `DefaultRouter`
+- [x] Implement `Router` trait for `LSPS4Router`
+- [x] Add LSPS4 blinded path fallback logic
+
+### Step 2: Update types.rs - DONE
+- [x] Change `Router` type alias to use `LSPS4Router`
+- [x] Export `LSPS4BlindedPathConfig`
+
+### Step 3: Update builder.rs - DONE
+- [x] Create `LSPS4BlindedPathConfig` shared state
+- [x] Create `LSPS4Router` instead of `DefaultRouter`
+- [x] Pass shared state to both router and liquidity source
+
+### Step 4: Update liquidity.rs - DONE
+- [x] Add method to set LSPS4 config after registration
+- [x] Store reference to shared config
+- [x] Update config when LSPS4 registration succeeds
+- [x] Add `lsps4_register_for_bolt12()` method for BOLT12 use case
+
+### Step 5: Add receive_via_lsps4_jit_channel to Bolt12Payment - DONE
+- [x] Add required fields to Bolt12Payment (runtime, connection_manager, liquidity_source, peer_store)
+- [x] Update constructor and call sites in lib.rs
+- [x] Add `receive_via_lsps4_jit_channel` method
+- [x] Add `receive_variable_amount_via_lsps4_jit_channel` method
+
+### Step 6: Testing - DONE
+- [ ] Unit test for LSPS4Router fallback (optional)
+- [x] Integration test for full BOLT12 + LSPS4 flow (`lsps4_bolt12_jit_channel` in integration_tests_rust.rs)
+
+## Files Modified
+
+1. **NEW: src/router.rs** - LSPS4Router implementation
+2. **src/types.rs** - Update Router type alias
+3. **src/builder.rs** - Wire up LSPS4Router and shared state
+4. **src/liquidity.rs** - Populate LSPS4 config after registration, add lsps4_register_for_bolt12()
+5. **src/payment/bolt12.rs** - Add receive_via_lsps4_jit_channel methods
+6. **src/lib.rs** - Add router module, update Bolt12Payment construction
+
+## Dependencies
+
+From rust-lightning:
+- `lightning::blinded_path::payment::{BlindedPaymentPath, PaymentForwardNode, ForwardTlvs, PaymentRelay, PaymentConstraints}`
+- `lightning::routing::router::Router`
+- `lightning::types::features::BlindedHopFeatures`
+- `lightning::ln::channelmanager::MIN_FINAL_CLTV_EXPIRY_DELTA`
+
+## Notes
+
+### Normal BOLT12 still works
+The `LSPS4Router` first tries normal path creation via `DefaultRouter`. LSPS4 fallback only triggers when:
+1. Normal path creation fails or returns empty, AND
+2. LSPS4 config is populated
+
+So existing BOLT12 functionality is completely preserved for nodes with channels.

src/builder.rs

@@ -71,6 +71,7 @@ use crate::logger::{log_error, LdkLogger, LogLevel, LogWriter, Logger};
 use crate::message_handler::NodeCustomMessageHandler;
 use crate::payment::asynchronous::om_mailbox::OnionMessageMailbox;
 use crate::peer_store::PeerStore;
+use crate::router::{LSPS4BlindedPathConfig, LSPS4Router};
 use crate::runtime::Runtime;
 use crate::tx_broadcaster::TransactionBroadcaster;
 use crate::types::{
@@ -1594,12 +1595,22 @@ fn build_with_store_internal(
 	}
 
 	let scoring_fee_params = ProbabilisticScoringFeeParameters::default();
-	let router = Arc::new(DefaultRouter::new(
+	let inner_router = DefaultRouter::new(
 		Arc::clone(&network_graph),
 		Arc::clone(&logger),
 		Arc::clone(&keys_manager),
 		Arc::clone(&scorer),
 		scoring_fee_params,
+	);
+
+	// Create shared LSPS4 config state for the router
+	let lsps4_blinded_path_config: Arc<RwLock<Option<LSPS4BlindedPathConfig>>> =
+		Arc::new(RwLock::new(None));
+
+	let router = Arc::new(LSPS4Router::new(
+		inner_router,
+		Arc::clone(&lsps4_blinded_path_config),
+		Arc::clone(&keys_manager),
 	));
 
 	let mut user_config = default_user_config(&config);
@@ -1801,6 +1812,7 @@ fn build_with_store_internal(
 				Arc::clone(&config),
 				Arc::clone(&logger),
 				Arc::clone(&event_queue),
+				Arc::clone(&lsps4_blinded_path_config),
 			);
 
 			lsc.lsps1_client.as_ref().map(|config| {

src/lib.rs

@@ -96,6 +96,7 @@ pub mod logger;
 mod message_handler;
 pub mod payment;
 mod peer_store;
+mod router;
 mod runtime;
 mod scoring;
 mod tx_broadcaster;
@@ -880,8 +881,12 @@ impl Node {
 	#[cfg(not(feature = "uniffi"))]
 	pub fn bolt12_payment(&self) -> Bolt12Payment {
 		Bolt12Payment::new(
+			Arc::clone(&self.runtime),
 			Arc::clone(&self.channel_manager),
+			Arc::clone(&self.connection_manager),
+			self.liquidity_source.clone(),
 			Arc::clone(&self.payment_store),
+			Arc::clone(&self.peer_store),
 			Arc::clone(&self.config),
 			Arc::clone(&self.is_running),
 			Arc::clone(&self.logger),
@@ -895,8 +900,12 @@ impl Node {
 	#[cfg(feature = "uniffi")]
 	pub fn bolt12_payment(&self) -> Arc<Bolt12Payment> {
 		Arc::new(Bolt12Payment::new(
+			Arc::clone(&self.runtime),
 			Arc::clone(&self.channel_manager),
+			Arc::clone(&self.connection_manager),
+			self.liquidity_source.clone(),
 			Arc::clone(&self.payment_store),
+			Arc::clone(&self.peer_store),
 			Arc::clone(&self.config),
 			Arc::clone(&self.is_running),
 			Arc::clone(&self.logger),

src/liquidity.rs

@@ -46,6 +46,7 @@ use tokio::sync::oneshot;
 use crate::builder::BuildError;
 use crate::chain::ChainSource;
 use crate::connection::ConnectionManager;
+use crate::router::LSPS4BlindedPathConfig;
 use crate::event::EventQueue;
 use crate::logger::{log_debug, log_error, log_info, Logger};
 use crate::runtime::Runtime;
@@ -199,6 +200,7 @@ where
 	lsps2_service: Option<LSPS2Service>,
 	lsps4_client: Option<LSPS4Client>,
 	lsps4_service: Option<LSPS4Service>,
+	lsps4_blinded_path_config: Arc<RwLock<Option<LSPS4BlindedPathConfig>>>,
 	wallet: Arc<Wallet>,
 	channel_manager: Arc<ChannelManager>,
 	keys_manager: Arc<KeysManager>,
@@ -218,6 +220,7 @@ where
 		wallet: Arc<Wallet>, channel_manager: Arc<ChannelManager>, keys_manager: Arc<KeysManager>,
 		chain_source: Arc<ChainSource>, tx_broadcaster: Arc<Broadcaster>, kv_store: Arc<DynStore>,
 		config: Arc<Config>, logger: L, event_queue: Arc<EventQueue<L>>,
+		lsps4_blinded_path_config: Arc<RwLock<Option<LSPS4BlindedPathConfig>>>,
 	) -> Self {
 		let lsps1_client = None;
 		let lsps2_client = None;
@@ -230,6 +233,7 @@ where
 			lsps2_service,
 			lsps4_client,
 			lsps4_service,
+			lsps4_blinded_path_config,
 			wallet,
 			channel_manager,
 			keys_manager,
@@ -358,6 +362,7 @@ where
 			lsps2_service: self.lsps2_service,
 			lsps4_client: self.lsps4_client,
 			lsps4_service: self.lsps4_service,
+			lsps4_blinded_path_config: self.lsps4_blinded_path_config,
 			wallet: self.wallet,
 			channel_manager: self.channel_manager,
 			peer_manager: RwLock::new(None),
@@ -379,6 +384,7 @@ where
 	lsps2_service: Option<LSPS2Service>,
 	lsps4_client: Option<LSPS4Client>,
 	lsps4_service: Option<LSPS4Service>,
+	lsps4_blinded_path_config: Arc<RwLock<Option<LSPS4BlindedPathConfig>>>,
 	wallet: Arc<Wallet>,
 	channel_manager: Arc<ChannelManager>,
 	peer_manager: RwLock<Option<Arc<PeerManager>>>,
@@ -397,6 +403,33 @@ where
 		*self.peer_manager.write().unwrap() = Some(peer_manager);
 	}
 
+	/// Updates the LSPS4 blinded path config used by the router for BOLT12 offers.
+	///
+	/// This is called after successful LSPS4 registration to enable BOLT12 offers
+	/// to create blinded payment paths through the LSP.
+	pub(crate) fn set_lsps4_blinded_path_config(
+		&self, lsp_node_id: PublicKey, intercept_scid: u64, cltv_expiry_delta: u32,
+	) {
+		let config = LSPS4BlindedPathConfig { lsp_node_id, intercept_scid, cltv_expiry_delta };
+		*self.lsps4_blinded_path_config.write().unwrap() = Some(config);
+		log_info!(
+			self.logger,
+			"LSPS4 blinded path config set: lsp_node_id={}, intercept_scid={}, cltv_expiry_delta={}",
+			lsp_node_id,
+			intercept_scid,
+			cltv_expiry_delta
+		);
+	}
+
+	/// Clears the LSPS4 blinded path config.
+	///
+	/// Call this after a JIT channel has been opened so that subsequent BOLT12 offers
+	/// use normal blinded paths through the existing channel instead of LSPS4.
+	pub(crate) fn clear_lsps4_blinded_path_config(&self) {
+		*self.lsps4_blinded_path_config.write().unwrap() = None;
+		log_info!(self.logger, "LSPS4 blinded path config cleared");
+	}
+
 	pub(crate) fn liquidity_manager(&self) -> Arc<LiquidityManager<L>> {
 		Arc::clone(&self.liquidity_manager)
 	}
@@ -1656,7 +1689,7 @@ where
 		}
 		log_info!(self.logger, "TIMING: lsps4_register_node() sent request, waiting for response...");
 
-		let result = tokio::time::timeout(
+		let response = tokio::time::timeout(
 			Duration::from_secs(LIQUIDITY_REQUEST_TIMEOUT_SECS),
 			register_node_receiver,
 		)
@@ -1668,10 +1701,26 @@ where
 		.map_err(|e| {
 			log_error!(self.logger, "Failed to handle response from liquidity service: {}", e);
 			Error::LiquidityRequestFailed
-		});
+		})?;
+
+		// Update the LSPS4 blinded path config for BOLT12 offers
+		self.set_lsps4_blinded_path_config(
+			lsps4_client.lsp_node_id,
+			response.intercept_scid,
+			response.cltv_expiry_delta,
+		);
 
 		log_info!(self.logger, "TIMING: lsps4_register_node() TOTAL took {}ms", fn_start.elapsed().as_millis());
-		result
+		Ok(response)
+	}
+
+	/// Registers with LSPS4 for BOLT12 offer creation.
+	///
+	/// This populates the LSPS4 blinded path config used by the router when creating
+	/// blinded payment paths for BOLT12 offers.
+	pub(crate) async fn lsps4_register_for_bolt12(&self) -> Result<(), Error> {
+		self.lsps4_register_node().await?;
+		Ok(())
 	}
 
 	pub(crate) async fn lsps4_receive_to_jit_channel(