Add persistent closed channel history and list_closed_channels()

Introduce `ClosedChannelDetails`, a new record type persisted to the KV
store under the `"closed_channels"` namespace whenever a channel closes.
Records are written in the `ChannelClosed` event handler and loaded back
at startup in parallel with other stores via `tokio::join!`.

Add `Node::list_closed_channels()` to expose the full history of closed
channels across restarts.

 Track outbound channel direction via an in-memory `outbound_channel_ids`
set seeded from `channel_manager.list_channels()` at startup and updated
on `ChannelPending` events, since `ChannelClosed` does not carry that
information directly.

Author: f3r10

bindings/ldk_node.udl

@@ -137,6 +137,7 @@ interface Node {
 	sequence<PaymentDetails> list_payments();
 	sequence<PeerDetails> list_peers();
 	sequence<ChannelDetails> list_channels();
+	sequence<ClosedChannelDetails> list_closed_channels();
 	NetworkGraph network_graph();
 	string sign_message([ByRef]sequence<u8> msg);
 	boolean verify_signature([ByRef]sequence<u8> msg, [ByRef]string sig, [ByRef]PublicKey pkey);
@@ -319,6 +320,8 @@ dictionary OutPoint {
 
 typedef dictionary ChannelDetails;
 
+typedef dictionary ClosedChannelDetails;
+
 typedef dictionary PeerDetails;
 
 [Remote]

src/builder.rs

@@ -64,7 +64,9 @@ use crate::io::utils::{
 };
 use crate::io::vss_store::VssStoreBuilder;
 use crate::io::{
-	self, PAYMENT_INFO_PERSISTENCE_PRIMARY_NAMESPACE, PAYMENT_INFO_PERSISTENCE_SECONDARY_NAMESPACE,
+	self, CLOSED_CHANNEL_INFO_PERSISTENCE_PRIMARY_NAMESPACE,
+	CLOSED_CHANNEL_INFO_PERSISTENCE_SECONDARY_NAMESPACE,
+	PAYMENT_INFO_PERSISTENCE_PRIMARY_NAMESPACE, PAYMENT_INFO_PERSISTENCE_SECONDARY_NAMESPACE,
 	PENDING_PAYMENT_INFO_PERSISTENCE_PRIMARY_NAMESPACE,
 	PENDING_PAYMENT_INFO_PERSISTENCE_SECONDARY_NAMESPACE,
 };
@@ -79,9 +81,9 @@ use crate::peer_store::PeerStore;
 use crate::runtime::{Runtime, RuntimeSpawner};
 use crate::tx_broadcaster::TransactionBroadcaster;
 use crate::types::{
-	AsyncPersister, ChainMonitor, ChannelManager, DynStore, DynStoreRef, DynStoreWrapper,
-	GossipSync, Graph, HRNResolver, KeysManager, MessageRouter, OnionMessenger, PaymentStore,
-	PeerManager, PendingPaymentStore, SyncAndAsyncKVStore,
+	AsyncPersister, ChainMonitor, ChannelManager, ClosedChannelStore, DynStore, DynStoreRef,
+	DynStoreWrapper, GossipSync, Graph, HRNResolver, KeysManager, MessageRouter, OnionMessenger,
+	PaymentStore, PeerManager, PendingPaymentStore, SyncAndAsyncKVStore,
 };
 use crate::wallet::persist::KVStoreWalletPersister;
 use crate::wallet::Wallet;
@@ -1288,7 +1290,7 @@ fn build_with_store_internal(
 
 	let kv_store_ref = Arc::clone(&kv_store);
 	let logger_ref = Arc::clone(&logger);
-	let (payment_store_res, node_metris_res, pending_payment_store_res) =
+	let (payment_store_res, node_metris_res, pending_payment_store_res, closed_channel_store_res) =
 		runtime.block_on(async move {
 			tokio::join!(
 				read_all_objects(
@@ -1303,6 +1305,12 @@ fn build_with_store_internal(
 					PENDING_PAYMENT_INFO_PERSISTENCE_PRIMARY_NAMESPACE,
 					PENDING_PAYMENT_INFO_PERSISTENCE_SECONDARY_NAMESPACE,
 					Arc::clone(&logger_ref),
+				),
+				read_all_objects(
+					&*kv_store_ref,
+					CLOSED_CHANNEL_INFO_PERSISTENCE_PRIMARY_NAMESPACE,
+					CLOSED_CHANNEL_INFO_PERSISTENCE_SECONDARY_NAMESPACE,
+					Arc::clone(&logger_ref),
 				)
 			)
 		});
@@ -1334,6 +1342,20 @@ fn build_with_store_internal(
 		},
 	};
 
+	let closed_channel_store = match closed_channel_store_res {
+		Ok(channels) => Arc::new(ClosedChannelStore::new(
+			channels,
+			CLOSED_CHANNEL_INFO_PERSISTENCE_PRIMARY_NAMESPACE.to_string(),
+			CLOSED_CHANNEL_INFO_PERSISTENCE_SECONDARY_NAMESPACE.to_string(),
+			Arc::clone(&kv_store),
+			Arc::clone(&logger),
+		)),
+		Err(e) => {
+			log_error!(logger, "Failed to read closed channel data from store: {}", e);
+			return Err(BuildError::ReadFailed);
+		},
+	};
+
 	let (chain_source, chain_tip_opt) = match chain_data_source_config {
 		Some(ChainDataSourceConfig::Esplora { server_url, headers, sync_config }) => {
 			let sync_config = sync_config.unwrap_or(EsploraSyncConfig::default());
@@ -2063,6 +2085,7 @@ fn build_with_store_internal(
 		scorer,
 		peer_store,
 		payment_store,
+		closed_channel_store,
 		lnurl_auth,
 		is_running,
 		node_metrics,

src/closed_channel.rs

@@ -0,0 +1,98 @@
+// This file is Copyright its original authors, visible in version control history.
+//
+// This file is licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license <LICENSE-MIT or
+// 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 std::time::{Duration, SystemTime, UNIX_EPOCH};
+
+use bitcoin::secp256k1::PublicKey;
+use bitcoin::OutPoint;
+use lightning::events::ClosureReason;
+use lightning::impl_writeable_tlv_based;
+use lightning::ln::types::ChannelId;
+
+use crate::data_store::{StorableObject, StorableObjectId, StorableObjectUpdate};
+use crate::hex_utils;
+use crate::types::UserChannelId;
+
+/// Details of a closed channel.
+///
+/// Returned by [`Node::list_closed_channels`].
+///
+/// [`Node::list_closed_channels`]: crate::Node::list_closed_channels
+#[derive(Clone, Debug, PartialEq, Eq)]
+#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
+pub struct ClosedChannelDetails {
+	/// The channel's ID at the time it was closed.
+	pub channel_id: ChannelId,
+	/// The local identifier of the channel.
+	pub user_channel_id: UserChannelId,
+	/// The node ID of the channel's counterparty.
+	pub counterparty_node_id: Option<PublicKey>,
+	/// The channel's funding transaction outpoint.
+	pub funding_txo: Option<OutPoint>,
+	/// The channel's capacity in satoshis.
+	pub channel_capacity_sats: Option<u64>,
+	/// Our local balance in millisatoshis at the time of channel closure.
+	pub last_local_balance_msat: Option<u64>,
+	/// Indicates whether we initiated the channel opening.
+	///
+	/// `true` if the channel was opened by us (outbound), `false` if opened by the counterparty
+	/// (inbound). This will be `false` for channels opened prior to this field being tracked.
+	pub is_outbound: bool,
+	/// Indicates whether the channel was publicly announced.
+	///
+	/// This will be `false` for channels opened prior to this field being tracked.
+	pub is_announced: bool,
+	/// The reason for the channel closure.
+	pub closure_reason: Option<ClosureReason>,
+	/// The timestamp, in seconds since start of the UNIX epoch, when the channel was closed.
+	pub closed_at: u64,
+}
+
+impl_writeable_tlv_based!(ClosedChannelDetails, {
+	(0, channel_id, required),
+	(2, user_channel_id, required),
+	(4, counterparty_node_id, option),
+	(6, funding_txo, option),
+	(8, channel_capacity_sats, option),
+	(10, last_local_balance_msat, option),
+	(12, is_outbound, required),
+	(14, closure_reason, upgradable_option),
+	(16, closed_at, (default_value, SystemTime::now().duration_since(UNIX_EPOCH).unwrap_or(Duration::from_secs(0)).as_secs())),
+	(18, is_announced, required),
+});
+
+pub(crate) struct ClosedChannelDetailsUpdate(pub UserChannelId);
+
+impl StorableObjectUpdate<ClosedChannelDetails> for ClosedChannelDetailsUpdate {
+	fn id(&self) -> UserChannelId {
+		self.0
+	}
+}
+
+impl StorableObject for ClosedChannelDetails {
+	type Id = UserChannelId;
+	type Update = ClosedChannelDetailsUpdate;
+
+	fn id(&self) -> UserChannelId {
+		self.user_channel_id
+	}
+
+	fn update(&mut self, _update: Self::Update) -> bool {
+		// Closed channel records are immutable once written.
+		false
+	}
+
+	fn to_update(&self) -> Self::Update {
+		ClosedChannelDetailsUpdate(self.user_channel_id)
+	}
+}
+
+impl StorableObjectId for UserChannelId {
+	fn encode_to_hex_str(&self) -> String {
+		hex_utils::to_string(&self.0.to_be_bytes())
+	}
+}

src/event.rs

@@ -7,9 +7,10 @@
 
 use core::future::Future;
 use core::task::{Poll, Waker};
-use std::collections::VecDeque;
+use std::collections::{HashSet, VecDeque};
 use std::ops::Deref;
 use std::sync::{Arc, Mutex};
+use std::time::{Duration, SystemTime, UNIX_EPOCH};
 
 use bitcoin::blockdata::locktime::absolute::LockTime;
 use bitcoin::secp256k1::PublicKey;
@@ -33,6 +34,7 @@ use lightning::{impl_writeable_tlv_based, impl_writeable_tlv_based_enum};
 use lightning_liquidity::lsps2::utils::compute_opening_fee;
 use lightning_types::payment::{PaymentHash, PaymentPreimage};
 
+use crate::closed_channel::ClosedChannelDetails;
 use crate::config::{may_announce_channel, Config};
 use crate::connection::ConnectionManager;
 use crate::data_store::DataStoreUpdateResult;
@@ -52,7 +54,8 @@ use crate::payment::store::{
 };
 use crate::runtime::Runtime;
 use crate::types::{
-	CustomTlvRecord, DynStore, KeysManager, OnionMessenger, PaymentStore, Sweeper, Wallet,
+	ClosedChannelStore, CustomTlvRecord, DynStore, KeysManager, OnionMessenger, PaymentStore,
+	Sweeper, Wallet,
 };
 use crate::{
 	hex_utils, BumpTransactionEventHandler, ChannelManager, Error, Graph, PeerInfo, PeerStore,
@@ -269,6 +272,18 @@ pub enum Event {
 		counterparty_node_id: Option<PublicKey>,
 		/// This will be `None` for events serialized by LDK Node v0.2.1 and prior.
 		reason: Option<ClosureReason>,
+		/// The channel's capacity in satoshis.
+		///
+		/// This will be `None` for events serialized by LDK Node v0.8.0 and prior.
+		channel_capacity_sats: Option<u64>,
+		/// The channel's funding transaction outpoint.
+		///
+		/// This will be `None` for events serialized by LDK Node v0.8.0 and prior.
+		channel_funding_txo: Option<OutPoint>,
+		/// Our local balance in millisatoshis at the time of channel closure.
+		///
+		/// This will be `None` for events serialized by LDK Node v0.8.0 and prior.
+		last_local_balance_msat: Option<u64>,
 	},
 	/// A channel splice is pending confirmation on-chain.
 	SplicePending {
@@ -331,6 +346,9 @@ impl_writeable_tlv_based_enum!(Event,
 		(1, counterparty_node_id, option),
 		(2, user_channel_id, required),
 		(3, reason, upgradable_option),
+		(5, channel_capacity_sats, option),
+		(7, channel_funding_txo, option),
+		(9, last_local_balance_msat, option),
 	},
 	(6, PaymentClaimable) => {
 		(0, payment_hash, required),
@@ -536,6 +554,13 @@ where
 	liquidity_source: Option<Arc<LiquiditySource<Arc<Logger>>>>,
 	payment_store: Arc<PaymentStore>,
 	peer_store: Arc<PeerStore<L>>,
+	closed_channel_store: Arc<ClosedChannelStore>,
+	// Tracks which user_channel_ids correspond to outbound channels. Populated at startup from
+	// list_channels() and updated on ChannelPending events. Consumed on ChannelClosed events.
+	outbound_channel_ids: Mutex<HashSet<UserChannelId>>,
+	// Tracks which user_channel_ids correspond to announced channels. Populated at startup from
+	// list_channels() and updated on ChannelPending events. Consumed on ChannelClosed events.
+	announced_channel_ids: Mutex<HashSet<UserChannelId>>,
 	keys_manager: Arc<KeysManager>,
 	runtime: Arc<Runtime>,
 	logger: L,
@@ -556,10 +581,27 @@ where
 		output_sweeper: Arc<Sweeper>, network_graph: Arc<Graph>,
 		liquidity_source: Option<Arc<LiquiditySource<Arc<Logger>>>>,
 		payment_store: Arc<PaymentStore>, peer_store: Arc<PeerStore<L>>,
-		keys_manager: Arc<KeysManager>, static_invoice_store: Option<StaticInvoiceStore>,
-		onion_messenger: Arc<OnionMessenger>, om_mailbox: Option<Arc<OnionMessageMailbox>>,
-		runtime: Arc<Runtime>, logger: L, config: Arc<Config>,
+		closed_channel_store: Arc<ClosedChannelStore>, keys_manager: Arc<KeysManager>,
+		static_invoice_store: Option<StaticInvoiceStore>, onion_messenger: Arc<OnionMessenger>,
+		om_mailbox: Option<Arc<OnionMessageMailbox>>, runtime: Arc<Runtime>, logger: L,
+		config: Arc<Config>,
 	) -> Self {
+		// Seed outbound_channel_ids and announced_channel_ids from currently open channels so we
+		// correctly classify channels that were already open when this node started.
+		let (outbound_channel_ids, announced_channel_ids) = {
+			let mut outbound = HashSet::new();
+			let mut announced = HashSet::new();
+			for chan in channel_manager.list_channels() {
+				if chan.is_outbound {
+					outbound.insert(UserChannelId(chan.user_channel_id));
+				}
+				if chan.is_announced {
+					announced.insert(UserChannelId(chan.user_channel_id));
+				}
+			}
+			(Mutex::new(outbound), Mutex::new(announced))
+		};
+
 		Self {
 			event_queue,
 			wallet,
@@ -571,6 +613,9 @@ where
 			liquidity_source,
 			payment_store,
 			peer_store,
+			closed_channel_store,
+			outbound_channel_ids,
+			announced_channel_ids,
 			keys_manager,
 			logger,
 			runtime,
@@ -1506,6 +1551,20 @@ where
 				if let Some(pending_channel) =
 					channels.into_iter().find(|c| c.channel_id == channel_id)
 				{
+					if pending_channel.is_outbound {
+						self.outbound_channel_ids
+							.lock()
+							.expect("Lock poisoned")
+							.insert(UserChannelId(user_channel_id));
+					}
+
+					if pending_channel.is_announced {
+						self.announced_channel_ids
+							.lock()
+							.expect("Lock poisoned")
+							.insert(UserChannelId(user_channel_id));
+					}
+
 					if !pending_channel.is_outbound
 						&& self.peer_store.get_peer(&counterparty_node_id).is_none()
 					{
@@ -1581,15 +1640,62 @@ where
 				reason,
 				user_channel_id,
 				counterparty_node_id,
-				..
+				channel_capacity_sats,
+				channel_funding_txo,
+				last_local_balance_msat,
 			} => {
 				log_info!(self.logger, "Channel {} closed due to: {}", channel_id, reason);
 
+				let user_channel_id = UserChannelId(user_channel_id);
+				let is_outbound = self
+					.outbound_channel_ids
+					.lock()
+					.expect("Lock poisoned")
+					.remove(&user_channel_id);
+				let is_announced = self
+					.announced_channel_ids
+					.lock()
+					.expect("Lock poisoned")
+					.remove(&user_channel_id);
+
+				let closed_at = SystemTime::now()
+					.duration_since(UNIX_EPOCH)
+					.unwrap_or(Duration::ZERO)
+					.as_secs();
+
+				let funding_txo =
+					channel_funding_txo.map(|op| OutPoint { txid: op.txid, vout: op.index as u32 });
+
+				let record = ClosedChannelDetails {
+					channel_id,
+					user_channel_id,
+					counterparty_node_id,
+					funding_txo,
+					channel_capacity_sats,
+					last_local_balance_msat,
+					is_outbound,
+					is_announced,
+					closure_reason: Some(reason.clone()),
+					closed_at,
+				};
+
+				if let Err(e) = self.closed_channel_store.insert(record) {
+					log_error!(
+						self.logger,
+						"Failed to persist closed channel {}: {}",
+						channel_id,
+						e
+					);
+				}
+
 				let event = Event::ChannelClosed {
 					channel_id,
-					user_channel_id: UserChannelId(user_channel_id),
+					user_channel_id,
 					counterparty_node_id,
 					reason: Some(reason),
+					channel_capacity_sats,
+					channel_funding_txo: funding_txo,
+					last_local_balance_msat,
 				};
 
 				match self.event_queue.add_event(event).await {