Add end-to-end SIP integration test on regtest

Exercise the full swap-in-potentiam lifecycle through the public Node
API on regtest: configure SIP via the Builder, generate a deposit
address, fund it via bitcoind, register and confirm the UTXO, advance
past the CSV expiry, build and broadcast the refund transaction, and
verify Bitcoin Core accepts it. This proves the P2WSH scripts and
refund spending path are cryptographically correct end-to-end.

Co-Authored-By: HAL 9000

Author: tnull

src/builder.rs

@@ -512,15 +512,19 @@ impl NodeBuilder {
 	/// Configures the [`Node`] instance to use swap-in-potentiam with the given LSP.
 	///
 	/// SIP allows the node to receive on-chain funds at a shared address and instantly swap them
-	/// into a Lightning channel. The LSP at `node_id` must support the SIP protocol.
+	/// into a Lightning channel. The LSP's node ID is used as the server public key for SIP
+	/// address construction, following the original protocol design.
+	///
+	/// The `csv_delay` is the relative timelock (in blocks) for the refund spending path.
 	pub fn set_sip_lsp(
-		&mut self, node_id: PublicKey, address: SocketAddress,
+		&mut self, node_id: PublicKey, address: SocketAddress, csv_delay: u16,
 	) -> &mut Self {
 		self.config.trusted_peers_0conf.push(node_id.clone());
 
 		let liquidity_source_config =
 			self.liquidity_source_config.get_or_insert(LiquiditySourceConfig::default());
-		liquidity_source_config.sip_client = Some(SIPClientConfig { node_id, address });
+		liquidity_source_config.sip_client =
+			Some(SIPClientConfig { node_id, address, csv_delay });
 		self
 	}
 
@@ -1868,7 +1872,7 @@ fn build_with_store_internal(
 			});
 
 			lsc.sip_client.as_ref().map(|config| {
-				liquidity_source_builder.sip_client(config.node_id, config.address.clone())
+				liquidity_source_builder.sip_client(config.node_id, config.address.clone(), config.csv_delay)
 			});
 
 			lsc.sip_service.as_ref().map(|config| {
@@ -2016,6 +2020,19 @@ fn build_with_store_internal(
 		_leak_checker.0.push(Arc::downgrade(&wallet) as Weak<dyn Any + Send + Sync>);
 	}
 
+	let sip_manager = liquidity_source_config
+		.as_ref()
+		.and_then(|lsc| lsc.sip_client.as_ref())
+		.map(|sip_config| {
+			Arc::new(crate::sip::SipManager::new(
+				xprv,
+				sip_config.node_id,
+				sip_config.csv_delay,
+				config.network,
+				Arc::clone(&logger),
+			))
+		});
+
 	Ok(Node {
 		runtime,
 		stop_sender,
@@ -2037,7 +2054,7 @@ fn build_with_store_internal(
 		gossip_source,
 		pathfinding_scores_sync_url,
 		liquidity_source,
-		sip_manager: None,
+		sip_manager,
 		kv_store,
 		logger,
 		_router: router,

src/lib.rs

@@ -122,7 +122,7 @@ use bitcoin::secp256k1::PublicKey;
 pub use bitcoin::FeeRate;
 #[cfg(not(feature = "uniffi"))]
 use bitcoin::FeeRate;
-use bitcoin::{Address, Amount};
+use bitcoin::{Address, Amount, OutPoint, ScriptBuf, Transaction, Txid};
 #[cfg(feature = "uniffi")]
 pub use builder::ArcedNodeBuilder as Builder;
 pub use builder::BuildError;
@@ -1959,6 +1959,57 @@ impl Node {
 		Ok(sip.list_utxos())
 	}
 
+	/// Registers a newly discovered SIP UTXO.
+	///
+	/// Call this when a deposit to a SIP address is detected on-chain. In production this
+	/// would be driven by chain sync; for testing it can be called manually.
+	pub fn register_sip_utxo(
+		&self, outpoint: OutPoint, value: Amount, address_index: u32,
+		prevtx: Transaction,
+	) -> Result<(), Error> {
+		let sip = self.sip_manager.as_ref().ok_or(Error::LiquiditySourceUnavailable)?;
+		sip.wallet().register_utxo(outpoint, value, address_index, prevtx);
+		Ok(())
+	}
+
+	/// Marks a SIP UTXO as confirmed at the given block height.
+	pub fn confirm_sip_utxo(
+		&self, outpoint: &OutPoint, confirmed_at_height: u32,
+	) -> Result<(), Error> {
+		let sip = self.sip_manager.as_ref().ok_or(Error::LiquiditySourceUnavailable)?;
+		sip.wallet().confirm_utxo(outpoint, confirmed_at_height);
+		Ok(())
+	}
+
+	/// Updates SIP UTXO states based on the current chain tip, transitioning confirmed UTXOs
+	/// to expired once their CSV timelock has elapsed.
+	pub fn update_sip_on_new_block(&self, current_height: u32) -> Result<(), Error> {
+		let sip = self.sip_manager.as_ref().ok_or(Error::LiquiditySourceUnavailable)?;
+		sip.update_on_new_block(current_height);
+		Ok(())
+	}
+
+	/// Builds a signed refund transaction sweeping all CSV-expired SIP UTXOs to the given
+	/// destination.
+	///
+	/// Returns the signed transaction and the swept outpoints, or `None` if no UTXOs are
+	/// eligible for refund. The caller is responsible for broadcasting the transaction.
+	pub fn build_sip_refund_transaction(
+		&self, destination: ScriptBuf, fee_rate: FeeRate,
+	) -> Result<Option<(Transaction, Vec<OutPoint>)>, Error> {
+		let sip = self.sip_manager.as_ref().ok_or(Error::LiquiditySourceUnavailable)?;
+		Ok(sip.wallet().build_refund_transaction(destination, fee_rate))
+	}
+
+	/// Marks a SIP UTXO as refunded after the refund transaction has been broadcast.
+	pub fn mark_sip_refunded(
+		&self, outpoint: &OutPoint, spending_txid: Txid,
+	) -> Result<(), Error> {
+		let sip = self.sip_manager.as_ref().ok_or(Error::LiquiditySourceUnavailable)?;
+		sip.wallet().mark_refunded(outpoint, spending_txid);
+		Ok(())
+	}
+
 	/// Retrieves all payments that match the given predicate.
 	///
 	/// For example, you could retrieve all stored outbound payments as follows:

src/liquidity.rs

@@ -152,10 +152,13 @@ pub struct LSPS2ServiceConfig {
 }
 
 /// Client-side configuration for connecting to an LSP's SIP service.
+///
+/// The LSP's `node_id` doubles as the server public key for SIP address construction.
 #[derive(Debug, Clone)]
 pub(crate) struct SIPClientConfig {
 	pub node_id: PublicKey,
 	pub address: SocketAddress,
+	pub csv_delay: u16,
 }
 
 /// Service-side configuration for offering a SIP service.
@@ -261,9 +264,10 @@ where
 	}
 
 	pub(crate) fn sip_client(
-		&mut self, lsp_node_id: PublicKey, lsp_address: SocketAddress,
+		&mut self, lsp_node_id: PublicKey, lsp_address: SocketAddress, csv_delay: u16,
 	) -> &mut Self {
-		self.sip_client = Some(SIPClientConfig { node_id: lsp_node_id, address: lsp_address });
+		self.sip_client =
+			Some(SIPClientConfig { node_id: lsp_node_id, address: lsp_address, csv_delay });
 		self
 	}
 

src/sip/wallet.rs

@@ -31,7 +31,7 @@ const SIP_HARDENED_CHILD_INDEX: u32 = 787;
 
 /// Information about a generated SIP address.
 #[derive(Debug, Clone)]
-pub(crate) struct SipAddressInfo {
+pub struct SipAddressInfo {
 	/// The BIP32 derivation index.
 	pub index: u32,
 	/// The derived user public key.
@@ -45,7 +45,7 @@ pub(crate) struct SipAddressInfo {
 /// Key derivation uses BIP32: user keys are derived at `m/787'/<index>` from the node's
 /// master key. The server (LSP) public key and CSV delay are obtained during the initial
 /// SIP protocol exchange and remain fixed for the lifetime of the wallet.
-pub(crate) struct SipWallet {
+pub struct SipWallet {
 	/// BIP32 extended private key for deriving user keys.
 	user_xpriv: Xpriv,
 	/// The server (LSP) public key used in all SIP addresses.
@@ -68,7 +68,7 @@ impl SipWallet {
 	///
 	/// The `master_xpriv` should be the node's master extended private key. SIP user keys are
 	/// derived from it at `m/787'/<index>`.
-	pub(crate) fn new(
+	pub fn new(
 		master_xpriv: Xpriv, server_pubkey: PublicKey, csv_delay: u16, network: Network,
 		logger: Arc<Logger>,
 	) -> Self {
@@ -103,25 +103,25 @@ impl SipWallet {
 	}
 
 	/// Derives the user public key for the given address index.
-	pub(crate) fn derive_user_pubkey(&self, index: u32) -> PublicKey {
+	pub fn derive_user_pubkey(&self, index: u32) -> PublicKey {
 		let secp = Secp256k1::new();
 		PublicKey::from_secret_key(&secp, &self.derive_user_secret_key(index))
 	}
 
 	/// Returns the server (LSP) public key.
-	pub(crate) fn server_pubkey(&self) -> PublicKey {
+	pub fn server_pubkey(&self) -> PublicKey {
 		self.server_pubkey
 	}
 
 	/// Returns the CSV delay in blocks.
-	pub(crate) fn csv_delay(&self) -> u16 {
+	pub fn csv_delay(&self) -> u16 {
 		self.csv_delay
 	}
 
 	/// Generates a new SIP deposit address.
 	///
 	/// Each call increments the internal derivation index, producing a unique address.
-	pub(crate) fn new_address(&self) -> SipAddressInfo {
+	pub fn new_address(&self) -> SipAddressInfo {
 		let index = self.next_index.fetch_add(1, Ordering::Relaxed);
 		let user_pk = self.derive_user_pubkey(index);
 		let witness_script =
@@ -138,7 +138,7 @@ impl SipWallet {
 
 	/// Returns the satisfaction weight for cooperative spends from SIP addresses managed by this
 	/// wallet. This is constant for all addresses since they share the same script structure.
-	pub(crate) fn cooperative_satisfaction_weight(&self) -> bitcoin::Weight {
+	pub fn cooperative_satisfaction_weight(&self) -> bitcoin::Weight {
 		// Use index 0 as representative -- all SIP addresses have the same script structure
 		// and thus the same satisfaction weight.
 		let user_pk = self.derive_user_pubkey(0);
@@ -151,7 +151,7 @@ impl SipWallet {
 	///
 	/// The chain source should watch these for incoming transactions. This returns the
 	/// P2WSH scriptPubKey for each generated SIP address.
-	pub(crate) fn script_pubkeys_to_watch(&self) -> Vec<bitcoin::ScriptBuf> {
+	pub fn script_pubkeys_to_watch(&self) -> Vec<bitcoin::ScriptBuf> {
 		let addresses = self.addresses.lock().unwrap();
 		addresses
 			.values()
@@ -169,7 +169,7 @@ impl SipWallet {
 	/// Registers a newly discovered UTXO at a SIP address.
 	///
 	/// Called when the chain source discovers a deposit to one of our SIP addresses.
-	pub(crate) fn register_utxo(
+	pub fn register_utxo(
 		&self, outpoint: OutPoint, value: Amount, address_index: u32, prevtx: Transaction,
 	) {
 		let user_pk = self.derive_user_pubkey(address_index);
@@ -197,7 +197,7 @@ impl SipWallet {
 	}
 
 	/// Updates a UTXO's state to confirmed.
-	pub(crate) fn confirm_utxo(&self, outpoint: &OutPoint, confirmed_at_height: u32) {
+	pub fn confirm_utxo(&self, outpoint: &OutPoint, confirmed_at_height: u32) {
 		let mut utxos = self.utxos.lock().unwrap();
 		if let Some(utxo) = utxos.get_mut(outpoint) {
 			if matches!(utxo.state, SipUtxoState::Unconfirmed) {
@@ -215,7 +215,7 @@ impl SipWallet {
 	/// Updates UTXO states based on the current chain tip height.
 	///
 	/// Transitions confirmed UTXOs to `CsvExpired` when the relative timelock has elapsed.
-	pub(crate) fn update_csv_expiry(&self, current_height: u32) {
+	pub fn update_csv_expiry(&self, current_height: u32) {
 		let mut utxos = self.utxos.lock().unwrap();
 		for utxo in utxos.values_mut() {
 			if utxo.csv_expired(current_height)
@@ -233,32 +233,32 @@ impl SipWallet {
 	}
 
 	/// Returns all tracked SIP UTXOs that are confirmed and eligible for swapping.
-	pub(crate) fn swappable_utxos(&self) -> Vec<SipUtxo> {
+	pub fn swappable_utxos(&self) -> Vec<SipUtxo> {
 		self.utxos.lock().unwrap().values().filter(|u| u.is_swappable()).cloned().collect()
 	}
 
 	/// Returns all tracked SIP UTXOs whose CSV has expired and are eligible for refund.
-	pub(crate) fn refundable_utxos(&self) -> Vec<SipUtxo> {
+	pub fn refundable_utxos(&self) -> Vec<SipUtxo> {
 		self.utxos.lock().unwrap().values().filter(|u| u.is_refundable()).cloned().collect()
 	}
 
 	/// Returns information about all tracked SIP UTXOs for the public API.
-	pub(crate) fn list_utxos(&self) -> Vec<SipUtxoInfo> {
+	pub fn list_utxos(&self) -> Vec<SipUtxoInfo> {
 		self.utxos.lock().unwrap().values().map(SipUtxoInfo::from).collect()
 	}
 
 	/// Returns the total balance across all non-terminal SIP UTXOs.
-	pub(crate) fn total_balance(&self) -> Amount {
+	pub fn total_balance(&self) -> Amount {
 		self.utxos.lock().unwrap().values().filter(|u| !u.is_terminal()).map(|u| u.value).sum()
 	}
 
 	/// Returns the balance of confirmed, swappable SIP UTXOs.
-	pub(crate) fn spendable_balance(&self) -> Amount {
+	pub fn spendable_balance(&self) -> Amount {
 		self.utxos.lock().unwrap().values().filter(|u| u.is_swappable()).map(|u| u.value).sum()
 	}
 
 	/// Returns the balance of unconfirmed SIP UTXOs.
-	pub(crate) fn pending_balance(&self) -> Amount {
+	pub fn pending_balance(&self) -> Amount {
 		self.utxos
 			.lock()
 			.unwrap()
@@ -271,18 +271,18 @@ impl SipWallet {
 	/// Returns the user secret key for signing a cooperative or refund spend.
 	///
 	/// This is used by the SIP protocol handlers when constructing spending transactions.
-	pub(crate) fn signing_key(&self, address_index: u32) -> SecretKey {
+	pub fn signing_key(&self, address_index: u32) -> SecretKey {
 		self.derive_user_secret_key(address_index)
 	}
 
 	/// Looks up the address index for a given SIP address, if it was generated by this wallet.
-	pub(crate) fn address_index_for(&self, address: &Address) -> Option<u32> {
+	pub fn address_index_for(&self, address: &Address) -> Option<u32> {
 		let addresses = self.addresses.lock().unwrap();
 		addresses.iter().find(|(_, info)| &info.address == address).map(|(index, _)| *index)
 	}
 
 	/// Marks a UTXO as swap-initiated.
-	pub(crate) fn mark_swap_initiated(
+	pub fn mark_swap_initiated(
 		&self, outpoint: &OutPoint, channel_id: lightning::ln::types::ChannelId,
 	) {
 		let mut utxos = self.utxos.lock().unwrap();
@@ -301,7 +301,7 @@ impl SipWallet {
 	}
 
 	/// Marks a UTXO as swapped (terminal state).
-	pub(crate) fn mark_swapped(
+	pub fn mark_swapped(
 		&self, outpoint: &OutPoint, channel_id: lightning::ln::types::ChannelId,
 	) {
 		let mut utxos = self.utxos.lock().unwrap();
@@ -312,7 +312,7 @@ impl SipWallet {
 	}
 
 	/// Marks a UTXO as refunded (terminal state).
-	pub(crate) fn mark_refunded(&self, outpoint: &OutPoint, spending_txid: Txid) {
+	pub fn mark_refunded(&self, outpoint: &OutPoint, spending_txid: Txid) {
 		let mut utxos = self.utxos.lock().unwrap();
 		if let Some(utxo) = utxos.get_mut(outpoint) {
 			log_info!(self.logger, "SIP UTXO {} refunded via {}", outpoint, spending_txid);
@@ -324,7 +324,7 @@ impl SipWallet {
 	///
 	/// Returns the signed transaction and the outpoints being swept, or `None` if no UTXOs are
 	/// eligible for refund.
-	pub(crate) fn build_refund_transaction(
+	pub fn build_refund_transaction(
 		&self, destination: bitcoin::ScriptBuf, fee_rate: FeeRate,
 	) -> Option<(Transaction, Vec<OutPoint>)> {
 		let secp = Secp256k1::new();