From 7ab1216bb5d120be4c3a425c10ce611e3b751b53 Mon Sep 17 00:00:00 2001
From: Jeffrey Czyz <jkczyz@gmail.com>
Date: Fri, 17 Nov 2023 17:58:56 -0600
Subject: [PATCH] WIP: ChannelManager initialization docs with example

---
 lightning/src/ln/channelmanager.rs | 62 +++++++++++++++++++++++++++++-
 1 file changed, 61 insertions(+), 1 deletion(-)

diff --git a/lightning/src/ln/channelmanager.rs b/lightning/src/ln/channelmanager.rs
index fefcca93a0b..7cf5b9ee46c 100644
--- a/lightning/src/ln/channelmanager.rs
+++ b/lightning/src/ln/channelmanager.rs
@@ -991,7 +991,67 @@ where
 ///
 /// # Initialization
 ///
-///	TODO
+/// Use [`ChannelManager::new`] with the most recent [`BlockHash`] when creating a fresh instance.
+/// Otherwise, if restarting, construct [`ChannelManagerReadArgs`] with the necessary parameters and
+/// references to any deserialized [`ChannelMonitor`]s that were previously persisted. Use this to
+/// deserialize the [`ChannelManager`] and feed it any new chain data since it was last online, as
+/// detailed in the [`ChannelManagerReadArgs`] documentation.
+///
+///	```
+///	use bitcoin::BlockHash;
+///	use bitcoin::network::constants::Network;
+///	use lightning::chain::BestBlock;
+///	# use lightning::chain::channelmonitor::ChannelMonitor;
+///	use lightning::ln::channelmanager::{ChainParameters, ChannelManager, ChannelManagerReadArgs};
+///	use lightning::util::config::UserConfig;
+///	use lightning::util::ser::ReadableArgs;
+///
+/// # fn read_channel_monitors() -> Vec<ChannelMonitor<lightning::sign::InMemorySigner>> { vec![] }
+///	# fn example<R: lightning::io::Read>(
+///	#     fee_estimator: &dyn lightning::chain::chaininterface::FeeEstimator,
+///	#     chain_monitor: &dyn lightning::chain::Watch<lightning::sign::InMemorySigner>,
+///	#     tx_broadcaster: &dyn lightning::chain::chaininterface::BroadcasterInterface,
+///	#     router: &dyn lightning::routing::router::Router,
+///	#     logger: &dyn lightning::util::logger::Logger,
+///	#     entropy_source: &dyn lightning::sign::EntropySource,
+///	#     node_signer: &dyn lightning::sign::NodeSigner,
+///	#     signer_provider: &dyn lightning::sign::SignerProvider<Signer = lightning::sign::InMemorySigner>,
+///	#     best_block: lightning::chain::BestBlock,
+///	#     current_timestamp: u32,
+///	#     mut reader: R,
+///	# ) -> Result<(), lightning::ln::msgs::DecodeError> {
+///	// Fresh start with no channels
+/// let params = ChainParameters {
+///     network: Network::Bitcoin,
+///     best_block,
+/// };
+/// let default_config = UserConfig::default();
+/// let channel_manager = ChannelManager::new(
+///     fee_estimator, chain_monitor, tx_broadcaster, router, logger, entropy_source, node_signer,
+///     signer_provider, default_config, params, current_timestamp
+/// );
+///
+/// // Restart from deserialized data
+/// let mut channel_monitors = read_channel_monitors();
+/// let args = ChannelManagerReadArgs::new(
+///     entropy_source, node_signer, signer_provider, fee_estimator, chain_monitor, tx_broadcaster,
+///     router, logger, default_config, channel_monitors.iter_mut().collect()
+/// );
+/// let (block_hash, channel_manager) =
+///     <(BlockHash, ChannelManager<_, _, _, _, _, _, _, _>)>::read(&mut reader, args)?;
+///
+/// // Update the ChannelManager and ChannelMonitors with the latest chain data
+/// // ...
+///
+/// // Move the monitors to the ChannelManager's chain::Watch parameter
+/// for monitor in channel_monitors {
+/// 	chain_monitor.watch_channel(monitor.get_funding_txo().0, monitor);
+/// }
+/// # Ok(())
+/// # }
+///	```
+///
+/// TODO: Consider re-writing ChannelManagerReadArgs docs and moving here.
 ///
 /// # Operation
 ///