Tie funding payment status transitions to Lightning lifecycle events

Channel-opening and splice transactions transition to Succeeded when
ChannelReady fires, not after ANTI_REORG_DELAY confirmations. This
matches the point at which the Lightning layer considers the channel
usable: a zero-conf channel graduates as soon as its counterparty
signals, and a high-conf channel waits however many confirmations the
peer requires, rather than always stopping at six.

For splice RBF, the payment records whichever candidate actually
confirmed, with that candidate's amount and this node's share of the fee
— not the fee-estimate used for weight at coin-selection time, and not
the whole-tx fee for a multi-contributor splice.

A channel closure whose funding or splice never confirmed discards its
payment record instead of leaving it pending forever.

Generated with assistance from Claude Code.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: jkczyz

Cargo.toml

@@ -40,18 +40,18 @@ default = []
 #lightning-macros = { version = "0.2.0" }
 #lightning-dns-resolver = { version = "0.3.0" }
 
-lightning = { git = "https://github.com/lightningdevkit/rust-lightning", rev = "369a2cf9c8ef810deea0cd2b4cf6ed0691b78144", features = ["std"] }
-lightning-types = { git = "https://github.com/lightningdevkit/rust-lightning", rev = "369a2cf9c8ef810deea0cd2b4cf6ed0691b78144" }
-lightning-invoice = { git = "https://github.com/lightningdevkit/rust-lightning", rev = "369a2cf9c8ef810deea0cd2b4cf6ed0691b78144", features = ["std"] }
-lightning-net-tokio = { git = "https://github.com/lightningdevkit/rust-lightning", rev = "369a2cf9c8ef810deea0cd2b4cf6ed0691b78144" }
-lightning-persister = { git = "https://github.com/lightningdevkit/rust-lightning", rev = "369a2cf9c8ef810deea0cd2b4cf6ed0691b78144", features = ["tokio"] }
-lightning-background-processor = { git = "https://github.com/lightningdevkit/rust-lightning", rev = "369a2cf9c8ef810deea0cd2b4cf6ed0691b78144" }
-lightning-rapid-gossip-sync = { git = "https://github.com/lightningdevkit/rust-lightning", rev = "369a2cf9c8ef810deea0cd2b4cf6ed0691b78144" }
-lightning-block-sync = { git = "https://github.com/lightningdevkit/rust-lightning", rev = "369a2cf9c8ef810deea0cd2b4cf6ed0691b78144", features = ["rest-client", "rpc-client", "tokio"] }
-lightning-transaction-sync = { git = "https://github.com/lightningdevkit/rust-lightning", rev = "369a2cf9c8ef810deea0cd2b4cf6ed0691b78144", features = ["esplora-async-https", "time", "electrum-rustls-ring"] }
-lightning-liquidity = { git = "https://github.com/lightningdevkit/rust-lightning", rev = "369a2cf9c8ef810deea0cd2b4cf6ed0691b78144", features = ["std"] }
-lightning-macros = { git = "https://github.com/lightningdevkit/rust-lightning", rev = "369a2cf9c8ef810deea0cd2b4cf6ed0691b78144" }
-lightning-dns-resolver = { git = "https://github.com/lightningdevkit/rust-lightning", rev = "369a2cf9c8ef810deea0cd2b4cf6ed0691b78144" }
+lightning = { git = "https://github.com/jkczyz/rust-lightning", rev = "86dcedebe380737cbed0dd1d4230b4bc1e90dd05", features = ["std"] }
+lightning-types = { git = "https://github.com/jkczyz/rust-lightning", rev = "86dcedebe380737cbed0dd1d4230b4bc1e90dd05" }
+lightning-invoice = { git = "https://github.com/jkczyz/rust-lightning", rev = "86dcedebe380737cbed0dd1d4230b4bc1e90dd05", features = ["std"] }
+lightning-net-tokio = { git = "https://github.com/jkczyz/rust-lightning", rev = "86dcedebe380737cbed0dd1d4230b4bc1e90dd05" }
+lightning-persister = { git = "https://github.com/jkczyz/rust-lightning", rev = "86dcedebe380737cbed0dd1d4230b4bc1e90dd05", features = ["tokio"] }
+lightning-background-processor = { git = "https://github.com/jkczyz/rust-lightning", rev = "86dcedebe380737cbed0dd1d4230b4bc1e90dd05" }
+lightning-rapid-gossip-sync = { git = "https://github.com/jkczyz/rust-lightning", rev = "86dcedebe380737cbed0dd1d4230b4bc1e90dd05" }
+lightning-block-sync = { git = "https://github.com/jkczyz/rust-lightning", rev = "86dcedebe380737cbed0dd1d4230b4bc1e90dd05", features = ["rest-client", "rpc-client", "tokio"] }
+lightning-transaction-sync = { git = "https://github.com/jkczyz/rust-lightning", rev = "86dcedebe380737cbed0dd1d4230b4bc1e90dd05", features = ["esplora-async-https", "time", "electrum-rustls-ring"] }
+lightning-liquidity = { git = "https://github.com/jkczyz/rust-lightning", rev = "86dcedebe380737cbed0dd1d4230b4bc1e90dd05", features = ["std"] }
+lightning-macros = { git = "https://github.com/jkczyz/rust-lightning", rev = "86dcedebe380737cbed0dd1d4230b4bc1e90dd05" }
+lightning-dns-resolver = { git = "https://github.com/jkczyz/rust-lightning", rev = "86dcedebe380737cbed0dd1d4230b4bc1e90dd05" }
 
 bdk_chain = { version = "0.23.0", default-features = false, features = ["std"] }
 bdk_esplora = { version = "0.22.0", default-features = false, features = ["async-https-rustls", "tokio"]}
@@ -81,13 +81,13 @@ async-trait = { version = "0.1", default-features = false }
 vss-client = { package = "vss-client-ng", version = "0.5" }
 prost = { version = "0.11.6", default-features = false}
 #bitcoin-payment-instructions = { version = "0.6" }
-bitcoin-payment-instructions = { git = "https://github.com/jkczyz/bitcoin-payment-instructions", rev = "679dac50cc0d81ec4d31da94b93d467e5308f16a" }
+bitcoin-payment-instructions = { git = "https://github.com/jkczyz/bitcoin-payment-instructions", rev = "91b60116d87e19b42c06bcdf1cbf1affb566ffc2" }
 
 [target.'cfg(windows)'.dependencies]
 winapi = { version = "0.3", features = ["winbase"] }
 
 [dev-dependencies]
-lightning = { git = "https://github.com/lightningdevkit/rust-lightning", rev = "369a2cf9c8ef810deea0cd2b4cf6ed0691b78144", features = ["std", "_test_utils"] }
+lightning = { git = "https://github.com/jkczyz/rust-lightning", rev = "86dcedebe380737cbed0dd1d4230b4bc1e90dd05", features = ["std", "_test_utils"] }
 rand = { version = "0.9.2", default-features = false, features = ["std", "thread_rng", "os_rng"] }
 proptest = "1.0.0"
 regex = "1.5.6"

src/builder.rs

@@ -1496,6 +1496,8 @@ fn build_with_store_internal(
 		Arc::clone(&pending_payment_store),
 	));
 
+	tx_broadcaster.set_wallet(Arc::downgrade(&wallet));
+
 	// Initialize the KeysManager
 	let cur_time = SystemTime::now().duration_since(SystemTime::UNIX_EPOCH).map_err(|e| {
 		log_error!(logger, "Failed to get current time: {}", e);

src/event.rs

@@ -1518,6 +1518,18 @@ where
 					);
 				}
 
+				if let Err(e) =
+					self.wallet.handle_channel_ready(channel_id, funding_txo.map(|txo| txo.txid))
+				{
+					log_error!(
+						self.logger,
+						"Failed to graduate funding payment on ChannelReady for channel {}: {:?}",
+						channel_id,
+						e,
+					);
+					return Err(ReplayEvent());
+				}
+
 				if let Some(liquidity_source) = self.liquidity_source.as_ref() {
 					liquidity_source
 						.handle_channel_ready(user_channel_id, &channel_id, &counterparty_node_id)
@@ -1547,6 +1559,16 @@ where
 			} => {
 				log_info!(self.logger, "Channel {} closed due to: {}", channel_id, reason);
 
+				if let Err(e) = self.wallet.handle_channel_closed(channel_id) {
+					log_error!(
+						self.logger,
+						"Failed to handle ChannelClosed for channel {}: {:?}",
+						channel_id,
+						e,
+					);
+					return Err(ReplayEvent());
+				}
+
 				let event = Event::ChannelClosed {
 					channel_id,
 					user_channel_id: UserChannelId(user_channel_id),

src/payment/pending_payment_store.rs

@@ -5,26 +5,107 @@
 // http://opensource.org/licenses/MIT>, at your option. You may not use this file except in
 // accordance with one or both of these licenses.
 
+use bitcoin::secp256k1::PublicKey;
 use bitcoin::Txid;
 use lightning::impl_writeable_tlv_based;
+use lightning::impl_writeable_tlv_based_enum;
 use lightning::ln::channelmanager::PaymentId;
+use lightning::ln::funding::FundingContribution;
+use lightning::ln::types::ChannelId;
 
 use crate::data_store::{StorableObject, StorableObjectUpdate};
 use crate::payment::store::PaymentDetailsUpdate;
 use crate::payment::PaymentDetails;
 
+/// Identifies which channel lifecycle event a [`FundingDetails`] record tracks.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum FundingPurpose {
+	/// The funding transaction opens a channel.
+	Establishment,
+	/// The funding transaction splices an already-open channel.
+	Splice,
+}
+
+impl_writeable_tlv_based_enum!(FundingPurpose,
+	(0, Establishment) => {},
+	(2, Splice) => {}
+);
+
+/// One broadcast of a funding transaction (channel open or splice) in which this node
+/// had a stake.
+///
+/// When an RBF produces multiple candidates for the same [`FundingDetails`], each
+/// broadcast is recorded as its own [`FundingCandidate`] so that whichever candidate
+/// actually confirms can be identified and its contribution values restored onto the
+/// outer [`PaymentDetails`].
+///
+/// `contribution` is set for dual-funded opens and splices, where the local node submits
+/// a [`FundingContribution`] describing its inputs, outputs, and fee share. It is `None`
+/// for single-funded opens, which have exactly one candidate and no alternative to swap
+/// to.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct FundingCandidate {
+	/// Transaction ID of this broadcast.
+	pub txid: Txid,
+	/// The contribution used to build this candidate, if any.
+	pub contribution: Option<FundingContribution>,
+}
+
+impl_writeable_tlv_based!(FundingCandidate, {
+	(0, txid, required),
+	(2, contribution, option),
+});
+
+/// Marks an on-chain payment as belonging to a channel's funding lifecycle (open or
+/// splice), and carries the per-candidate state needed to react to RBF replacements.
+///
+/// The candidate whose `txid` matches the outer [`PaymentDetails`]`::kind.txid` is the
+/// one currently reflected by the payment's `amount_msat` and `fee_paid_msat`. On RBF, a
+/// new candidate is appended and becomes active.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct FundingDetails {
+	/// The channel whose funding is being tracked.
+	pub channel_id: ChannelId,
+	/// The channel's counterparty.
+	pub counterparty_node_id: PublicKey,
+	/// Whether this funding is for a channel open or a splice.
+	pub purpose: FundingPurpose,
+	/// Broadcast candidates, in the order they were observed.
+	pub candidates: Vec<FundingCandidate>,
+}
+
+impl_writeable_tlv_based!(FundingDetails, {
+	(0, channel_id, required),
+	(2, counterparty_node_id, required),
+	(4, purpose, required),
+	(6, candidates, optional_vec),
+});
+
 /// Represents a pending payment
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct PendingPaymentDetails {
 	/// The full payment details
 	pub details: PaymentDetails,
 	/// Transaction IDs that have replaced or conflict with this payment.
 	pub conflicting_txids: Vec<Txid>,
+	/// Set when the payment's transaction is a channel funding (open or splice). The
+	/// record transitions to [`PaymentStatus::Succeeded`] on `ChannelReady` instead of
+	/// after [`ANTI_REORG_DELAY`] confirmations.
+	///
+	/// [`PaymentStatus::Succeeded`]: crate::payment::store::PaymentStatus::Succeeded
+	/// [`ANTI_REORG_DELAY`]: lightning::chain::channelmonitor::ANTI_REORG_DELAY
+	pub funding_details: Option<FundingDetails>,
 }
 
 impl PendingPaymentDetails {
 	pub(crate) fn new(details: PaymentDetails, conflicting_txids: Vec<Txid>) -> Self {
-		Self { details, conflicting_txids }
+		Self { details, conflicting_txids, funding_details: None }
+	}
+
+	pub(crate) fn with_funding_details(
+		details: PaymentDetails, conflicting_txids: Vec<Txid>, funding_details: FundingDetails,
+	) -> Self {
+		Self { details, conflicting_txids, funding_details: Some(funding_details) }
 	}
 
 	/// Convert to finalized payment for the main payment store
@@ -36,13 +117,15 @@ impl PendingPaymentDetails {
 impl_writeable_tlv_based!(PendingPaymentDetails, {
 	(0, details, required),
 	(2, conflicting_txids, optional_vec),
+	(4, funding_details, option),
 });
 
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub(crate) struct PendingPaymentDetailsUpdate {
 	pub id: PaymentId,
 	pub payment_update: Option<PaymentDetailsUpdate>,
 	pub conflicting_txids: Option<Vec<Txid>>,
+	pub funding_details: Option<Option<FundingDetails>>,
 }
 
 impl StorableObject for PendingPaymentDetails {
@@ -68,6 +151,13 @@ impl StorableObject for PendingPaymentDetails {
 			}
 		}
 
+		if let Some(new_funding_details) = update.funding_details {
+			if self.funding_details != new_funding_details {
+				self.funding_details = new_funding_details;
+				updated = true;
+			}
+		}
+
 		updated
 	}
 
@@ -89,6 +179,11 @@ impl From<&PendingPaymentDetails> for PendingPaymentDetailsUpdate {
 		} else {
 			Some(value.conflicting_txids.clone())
 		};
-		Self { id: value.id(), payment_update: Some(value.details.to_update()), conflicting_txids }
+		Self {
+			id: value.id(),
+			payment_update: Some(value.details.to_update()),
+			conflicting_txids,
+			funding_details: Some(value.funding_details.clone()),
+		}
 	}
 }

src/tx_broadcaster.rs

@@ -6,12 +6,14 @@
 // accordance with one or both of these licenses.
 
 use std::ops::Deref;
+use std::sync::{Mutex as StdMutex, Weak};
 
 use bitcoin::Transaction;
 use lightning::chain::chaininterface::{BroadcasterInterface, TransactionType};
 use tokio::sync::{mpsc, Mutex, MutexGuard};
 
 use crate::logger::{log_error, LdkLogger};
+use crate::types::Wallet;
 
 const BCAST_PACKAGE_QUEUE_SIZE: usize = 50;
 
@@ -21,6 +23,12 @@ where
 {
 	queue_sender: mpsc::Sender<Vec<Transaction>>,
 	queue_receiver: Mutex<mpsc::Receiver<Vec<Transaction>>>,
+	/// Weak handle to the [`Wallet`] that performs classification of funding broadcasts
+	/// (channel opens and splices) into payment records. Remains `None` while the
+	/// builder is wiring the node up, during which broadcasts are still forwarded to
+	/// the queue but no payment record is written. [`Self::set_wallet`] installs the
+	/// handle once the [`Wallet`] exists.
+	wallet: StdMutex<Option<Weak<Wallet>>>,
 	logger: L,
 }
 
@@ -30,7 +38,19 @@ where
 {
 	pub(crate) fn new(logger: L) -> Self {
 		let (queue_sender, queue_receiver) = mpsc::channel(BCAST_PACKAGE_QUEUE_SIZE);
-		Self { queue_sender, queue_receiver: Mutex::new(queue_receiver), logger }
+		Self {
+			queue_sender,
+			queue_receiver: Mutex::new(queue_receiver),
+			wallet: StdMutex::new(None),
+			logger,
+		}
+	}
+
+	/// Installs the [`Wallet`] handle used to classify funding broadcasts (channel
+	/// opens and splices) into payment records. Called once the builder has constructed
+	/// both the broadcaster and the wallet.
+	pub(crate) fn set_wallet(&self, wallet: Weak<Wallet>) {
+		*self.wallet.lock().expect("lock") = Some(wallet);
 	}
 
 	pub(crate) async fn get_broadcast_queue(
@@ -45,6 +65,19 @@ where
 	L::Target: LdkLogger,
 {
 	fn broadcast_transactions(&self, txs: &[(&Transaction, TransactionType)]) {
+		let wallet = self.wallet.lock().expect("lock").as_ref().and_then(Weak::upgrade);
+		if let Some(wallet) = wallet {
+			for (tx, tx_type) in txs {
+				if let Err(e) = wallet.classify_broadcast(tx, tx_type) {
+					log_error!(
+						self.logger,
+						"Failed to classify broadcast tx {}: {:?}",
+						tx.compute_txid(),
+						e,
+					);
+				}
+			}
+		}
 		let package = txs.iter().map(|(t, _)| (*t).clone()).collect::<Vec<Transaction>>();
 		self.queue_sender.try_send(package).unwrap_or_else(|e| {
 			log_error!(self.logger, "Failed to broadcast transactions: {}", e);