Replace ManyChannelMonitor with chain::Watch

Rename ManyChannelMonitor to chain::Watch and move to chain/mod.rs,
where chain-related interfaces live. Update the documentation for
clarity and to conform to rustdoc formatting.

Author: jkczyz

ARCH.md

@@ -6,7 +6,7 @@ need to use are `ChannelManager` and `ChannelMonitor`. `ChannelManager` holds mu
 channels, routes payments between them, and exposes a simple API to make and receive
 payments. Individual `ChannelMonitor`s monitor the on-chain state of a channel, punish
 counterparties if they misbehave, and force-close channels if they contain unresolved
-HTLCs which are near expiration. The `ManyChannelMonitor` API provides a way for you to
+HTLCs which are near expiration. The `chain::Watch` interface provides a way for you to
 receive `ChannelMonitorUpdate`s from `ChannelManager` and persist them to disk before the
 channel steps forward.
 
@@ -45,9 +45,9 @@ At a high level, some of the common interfaces fit together as follows:
  |                          \       |   |   /      ---------> | BroadcasterInterface |
  |                           \      |   |  /      /     |     ------------------------
  |                            \     v   v v      /      v        ^
- |    (as                      ------------------       ----------------------
- |    ChannelMessageHandler)-> | ChannelManager | ----> | ManyChannelMonitor |
- v               /             ------------------       ----------------------
+ |    (as                      ------------------       ----------------
+ |    ChannelMessageHandler)-> | ChannelManager | ----> | chain::Watch |
+ v               /             ------------------       ----------------
 --------------- /                          (as EventsProvider)
 | PeerManager |-                                \     /
 ---------------                                  \   /

fuzz/src/chanmon_consistency.rs

@@ -20,6 +20,7 @@ use bitcoin::hashes::Hash as TraitImport;
 use bitcoin::hashes::sha256::Hash as Sha256;
 use bitcoin::hash_types::{BlockHash, WPubkeyHash};
 
+use lightning::chain;
 use lightning::chain::transaction::OutPoint;
 use lightning::chain::chaininterface::{BroadcasterInterface, ChainListener, ConfirmationTarget, FeeEstimator};
 use lightning::chain::keysinterface::{KeysInterface, InMemoryChannelKeys};
@@ -95,21 +96,21 @@ impl TestChannelMonitor {
 		}
 	}
 }
-impl channelmonitor::ManyChannelMonitor for TestChannelMonitor {
+impl chain::Watch for TestChannelMonitor {
 	type Keys = EnforcingChannelKeys;
 
-	fn add_monitor(&self, funding_txo: OutPoint, monitor: channelmonitor::ChannelMonitor<EnforcingChannelKeys>) -> Result<(), channelmonitor::ChannelMonitorUpdateErr> {
+	fn watch_channel(&self, funding_txo: OutPoint, monitor: channelmonitor::ChannelMonitor<EnforcingChannelKeys>) -> Result<(), channelmonitor::ChannelMonitorUpdateErr> {
 		let mut ser = VecWriter(Vec::new());
 		monitor.write_for_disk(&mut ser).unwrap();
 		if let Some(_) = self.latest_monitors.lock().unwrap().insert(funding_txo, (monitor.get_latest_update_id(), ser.0)) {
-			panic!("Already had monitor pre-add_monitor");
+			panic!("Already had monitor pre-watch_channel");
 		}
 		self.should_update_manager.store(true, atomic::Ordering::Relaxed);
-		assert!(self.simple_monitor.add_monitor(funding_txo, monitor).is_ok());
+		assert!(self.simple_monitor.watch_channel(funding_txo, monitor).is_ok());
 		self.update_ret.lock().unwrap().clone()
 	}
 
-	fn update_monitor(&self, funding_txo: OutPoint, update: channelmonitor::ChannelMonitorUpdate) -> Result<(), channelmonitor::ChannelMonitorUpdateErr> {
+	fn update_channel(&self, funding_txo: OutPoint, update: channelmonitor::ChannelMonitorUpdate) -> Result<(), channelmonitor::ChannelMonitorUpdateErr> {
 		let mut map_lock = self.latest_monitors.lock().unwrap();
 		let mut map_entry = match map_lock.entry(funding_txo) {
 			hash_map::Entry::Occupied(entry) => entry,
@@ -125,8 +126,8 @@ impl channelmonitor::ManyChannelMonitor for TestChannelMonitor {
 		self.update_ret.lock().unwrap().clone()
 	}
 
-	fn get_and_clear_pending_htlcs_updated(&self) -> Vec<HTLCUpdate> {
-		return self.simple_monitor.get_and_clear_pending_htlcs_updated();
+	fn release_pending_htlc_updates(&self) -> Vec<HTLCUpdate> {
+		return self.simple_monitor.release_pending_htlc_updates();
 	}
 }
 
@@ -204,7 +205,7 @@ pub fn do_test<Out: test_logger::Output>(data: &[u8], out: Out) {
 	macro_rules! reload_node {
 		($ser: expr, $node_id: expr, $old_monitors: expr) => { {
 			let logger: Arc<dyn Logger> = Arc::new(test_logger::TestLogger::new($node_id.to_string(), out.clone()));
-			let monitor = Arc::new(TestChannelMonitor::new(broadcast.clone(), logger.clone(), fee_est.clone()));
+			let chain_monitor = Arc::new(TestChannelMonitor::new(broadcast.clone(), logger.clone(), fee_est.clone()));
 
 			let keys_manager = Arc::new(KeyProvider { node_id: $node_id, session_id: atomic::AtomicU8::new(0), channel_id: atomic::AtomicU8::new(0) });
 			let mut config = UserConfig::default();
@@ -216,7 +217,7 @@ pub fn do_test<Out: test_logger::Output>(data: &[u8], out: Out) {
 			let mut old_monitors = $old_monitors.latest_monitors.lock().unwrap();
 			for (outpoint, (update_id, monitor_ser)) in old_monitors.drain() {
 				monitors.insert(outpoint, <(BlockHash, ChannelMonitor<EnforcingChannelKeys>)>::read(&mut Cursor::new(&monitor_ser)).expect("Failed to read monitor").1);
-				monitor.latest_monitors.lock().unwrap().insert(outpoint, (update_id, monitor_ser));
+				chain_monitor.latest_monitors.lock().unwrap().insert(outpoint, (update_id, monitor_ser));
 			}
 			let mut monitor_refs = HashMap::new();
 			for (outpoint, monitor) in monitors.iter_mut() {
@@ -226,14 +227,14 @@ pub fn do_test<Out: test_logger::Output>(data: &[u8], out: Out) {
 			let read_args = ChannelManagerReadArgs {
 				keys_manager,
 				fee_estimator: fee_est.clone(),
-				monitor: monitor.clone(),
+				chain_monitor: chain_monitor.clone(),
 				tx_broadcaster: broadcast.clone(),
 				logger,
 				default_config: config,
 				channel_monitors: &mut monitor_refs,
 			};
 
-			(<(BlockHash, ChannelManager<EnforcingChannelKeys, Arc<TestChannelMonitor>, Arc<TestBroadcaster>, Arc<KeyProvider>, Arc<FuzzEstimator>, Arc<dyn Logger>>)>::read(&mut Cursor::new(&$ser.0), read_args).expect("Failed to read manager").1, monitor)
+			(<(BlockHash, ChannelManager<EnforcingChannelKeys, Arc<TestChannelMonitor>, Arc<TestBroadcaster>, Arc<KeyProvider>, Arc<FuzzEstimator>, Arc<dyn Logger>>)>::read(&mut Cursor::new(&$ser.0), read_args).expect("Failed to read manager").1, chain_monitor)
 		} }
 	}
 

lightning/src/chain/mod.rs

@@ -4,7 +4,9 @@ use bitcoin::blockdata::script::Script;
 use bitcoin::blockdata::transaction::TxOut;
 use bitcoin::hash_types::{BlockHash, Txid};
 
+use chain::keysinterface::ChannelKeys;
 use chain::transaction::OutPoint;
+use ln::channelmonitor::{ChannelMonitor, ChannelMonitorUpdate, ChannelMonitorUpdateErr, HTLCUpdate};
 
 pub mod chaininterface;
 pub mod transaction;
@@ -32,6 +34,51 @@ pub enum AccessError {
 	UnknownTx,
 }
 
+/// The `Watch` trait defines behavior for watching on-chain activity pertaining to channels as
+/// blocks are connected and disconnected.
+///
+/// Each channel is associated with a [`ChannelMonitor`]. Implementations are responsible for
+/// maintaining a set of monitors and updating them accordingly as channel state changes and HTLCs
+/// are resolved on chain. See method documentation for specific requirements.
+///
+/// TODO: Add documentation about persisting monitors.
+///
+/// If an implementation maintains multiple instances of a channel's monitor (e.g., by using a
+/// watchtower), then it must ensure that updates are applied across all instances. Otherwise, it
+/// could result in a revoked transaction being broadcast, allowing the counterparty to claim all
+/// funds in the channel.
+///
+/// [`ChannelMonitor`]: ../ln/channelmonitor/struct.ChannelMonitor.html
+pub trait Watch: Send + Sync {
+	/// Keys needed by monitors for creating and signing transactions.
+	type Keys: ChannelKeys;
+
+	/// Watches a channel identified by `funding_txo` using `monitor`.
+	///
+	/// Implementations are responsible for watching the chain for the funding transaction along
+	/// with spends of its output and any outputs returned by [`get_outputs_to_watch`]. In practice,
+	/// this means calling [`block_connected`] and [`block_disconnected`] on the monitor and
+	/// including all such transactions that meet this criteria.
+	///
+	/// [`get_outputs_to_watch`]: ../ln/channelmonitor/struct.ChannelMonitor.html#method.get_outputs_to_watch
+	/// [`block_connected`]: ../ln/channelmonitor/struct.ChannelMonitor.html#method.block_connected
+	/// [`block_disconnected`]: ../ln/channelmonitor/struct.ChannelMonitor.html#method.block_disconnected
+	fn watch_channel(&self, funding_txo: OutPoint, monitor: ChannelMonitor<Self::Keys>) -> Result<(), ChannelMonitorUpdateErr>;
+
+	/// Updates a channel identified by `funding_txo` by applying `update` to its monitor.
+	///
+	/// Implementations must call [`update_monitor`] with the given update. See
+	/// [`ChannelMonitorUpdateErr`] for invariants around returning an error.
+	///
+	/// [`update_monitor`]: ../ln/channelmonitor/struct.ChannelMonitor.html#method.update_monitor
+	/// [`ChannelMonitorUpdateErr`]: ../ln/channelmonitor/enum.ChannelMonitorUpdateErr.html
+	fn update_channel(&self, funding_txo: OutPoint, update: ChannelMonitorUpdate) -> Result<(), ChannelMonitorUpdateErr>;
+
+	/// Returns any HTLCs resolved on chain since the last call. Subsequent calls must only return
+	/// newly resolved HTLCs.
+	fn release_pending_htlc_updates(&self) -> Vec<HTLCUpdate>;
+}
+
 /// An interface for providing [`WatchEvent`]s.
 ///
 /// [`WatchEvent`]: enum.WatchEvent.html