X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;ds=sidebyside;f=src%2Fln%2Fchannelmonitor.rs;h=f3eed0fe16ac0ed9d7e4a59d67f8e82bf5330e8f;hb=3aeec96470cc681bf6bf50baa5ce1b533762c479;hp=cd38c9c1a79b10dde58d07d5b878280d167cb23d;hpb=9373c5993fcc4943f31e20fb0e0367d2bddec596;p=rust-lightning

diff --git a/src/ln/channelmonitor.rs b/src/ln/channelmonitor.rs
index cd38c9c1..f3eed0fe 100644
--- a/src/ln/channelmonitor.rs
+++ b/src/ln/channelmonitor.rs
@@ -1,3 +1,14 @@
+//! The logic to monitor for on-chain transactions and create the relevant claim responses lives
+//! here.
+//! ChannelMonitor objects are generated by ChannelManager in response to relevant
+//! messages/actions, and MUST be persisted to disk (and, preferably, remotely) before progress can
+//! be made in responding to certain messages, see ManyChannelMonitor for more.
+//! Note that ChannelMonitors are an important part of the lightning trust model and a copy of the
+//! latest ChannelMonitor must always be actively monitoring for chain updates (and no out-of-date
+//! ChannelMonitors should do so). Thus, if you're building rust-lightning into an HSM or other
+//! security-domain-separated system design, you should consider having multiple paths for
+//! ChannelMonitors to get out of the HSM and onto monitoring devices.
+
 use bitcoin::blockdata::block::BlockHeader;
 use bitcoin::blockdata::transaction::{TxIn,TxOut,SigHashType,Transaction};
 use bitcoin::blockdata::transaction::OutPoint as BitcoinOutPoint;
@@ -24,6 +35,7 @@ use std::collections::HashMap;
 use std::sync::{Arc,Mutex};
 use std::{hash,cmp};
 
+/// An error enum representing a failure to persist a channel monitor update.
 pub enum ChannelMonitorUpdateErr {
 	/// Used to indicate a temporary failure (eg connection to a watchtower failed, but is expected
 	/// to succeed at some point in the future).
@@ -88,6 +100,8 @@ impl<Key : Send + cmp::Eq + hash::Hash> ChainListener for SimpleManyChannelMonit
 }
 
 impl<Key : Send + cmp::Eq + hash::Hash + 'static> SimpleManyChannelMonitor<Key> {
+	/// Creates a new object which can be used to monitor several channels given the chain
+	/// interface with which to register to receive notifications.
 	pub fn new(chain_monitor: Arc<ChainWatchInterface>, broadcaster: Arc<BroadcasterInterface>) -> Arc<SimpleManyChannelMonitor<Key>> {
 		let res = Arc::new(SimpleManyChannelMonitor {
 			monitors: Mutex::new(HashMap::new()),
@@ -99,6 +113,7 @@ impl<Key : Send + cmp::Eq + hash::Hash + 'static> SimpleManyChannelMonitor<Key>
 		res
 	}
 
+	/// Adds or udpates the monitor which monitors the channel referred to by the given key.
 	pub fn add_update_monitor_by_key(&self, key: Key, monitor: ChannelMonitor) -> Result<(), HandleError> {
 		let mut monitors = self.monitors.lock().unwrap();
 		match monitors.get_mut(&key) {
@@ -162,6 +177,10 @@ struct LocalSignedTx {
 const SERIALIZATION_VERSION: u8 = 1;
 const MIN_SERIALIZATION_VERSION: u8 = 1;
 
+/// A ChannelMonitor handles chain events (blocks connected and disconnected) and generates
+/// on-chain transactions to ensure no loss of funds occurs.
+/// You MUST ensure that no ChannelMonitors for a given channel anywhere contain out-of-date
+/// information and are actively monitoring the chain.
 pub struct ChannelMonitor {
 	funding_txo: Option<(OutPoint, Script)>,
 	commitment_transaction_number_obscure_factor: u64,
@@ -438,6 +457,9 @@ impl ChannelMonitor {
 		self.payment_preimages.insert(payment_hash.clone(), payment_preimage.clone());
 	}
 
+	/// Combines this ChannelMonitor with the information contained in the other ChannelMonitor.
+	/// After a successful call this ChannelMonitor is up-to-date and is safe to use to monitor the
+	/// chain for new blocks/transactions.
 	pub fn insert_combine(&mut self, mut other: ChannelMonitor) -> Result<(), HandleError> {
 		if self.funding_txo.is_some() {
 			// We should be able to compare the entire funding_txo, but in fuzztarget its trivially
@@ -499,6 +521,7 @@ impl ChannelMonitor {
 		self.funding_txo = None;
 	}
 
+	/// Gets the funding transaction outpoint of the channel this ChannelMonitor is monitoring for.
 	pub fn get_funding_txo(&self) -> Option<OutPoint> {
 		match self.funding_txo {
 			Some((outpoint, _)) => Some(outpoint),