X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=src%2Fln%2Fchannelmonitor.rs;h=f3eed0fe16ac0ed9d7e4a59d67f8e82bf5330e8f;hb=3aeec96470cc681bf6bf50baa5ce1b533762c479;hp=ded2a99dc37cf2933150d8537ec31ecfaddc073e;hpb=68be3c03531667a1ecae7c67664e0ef71ea98a61;p=rust-lightning diff --git a/src/ln/channelmonitor.rs b/src/ln/channelmonitor.rs index ded2a99d..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 ChainListener for SimpleManyChannelMonit } impl SimpleManyChannelMonitor { + /// 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, broadcaster: Arc) -> Arc> { let res = Arc::new(SimpleManyChannelMonitor { monitors: Mutex::new(HashMap::new()), @@ -99,6 +113,7 @@ impl SimpleManyChannelMonitor 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, @@ -269,7 +288,7 @@ impl PartialEq for ChannelMonitor { } impl ChannelMonitor { - pub fn new(revocation_base_key: &SecretKey, delayed_payment_base_key: &PublicKey, htlc_base_key: &SecretKey, our_to_self_delay: u16, destination_script: Script) -> ChannelMonitor { + pub(super) fn new(revocation_base_key: &SecretKey, delayed_payment_base_key: &PublicKey, htlc_base_key: &SecretKey, our_to_self_delay: u16, destination_script: Script) -> ChannelMonitor { ChannelMonitor { funding_txo: None, commitment_transaction_number_obscure_factor: 0, @@ -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 { match self.funding_txo { Some((outpoint, _)) => Some(outpoint), @@ -903,7 +926,7 @@ impl ChannelMonitor { //we want to leave out (eg funding_txo, etc). /// Can only fail if idx is < get_min_seen_secret - pub fn get_secret(&self, idx: u64) -> Result<[u8; 32], HandleError> { + pub(super) fn get_secret(&self, idx: u64) -> Result<[u8; 32], HandleError> { for i in 0..self.old_secrets.len() { if (idx & (!((1 << i) - 1))) == self.old_secrets[i].1 { return Ok(ChannelMonitor::derive_secret(self.old_secrets[i].0, i as u8, idx)) @@ -913,7 +936,7 @@ impl ChannelMonitor { Err(HandleError{err: "idx too low", action: None}) } - pub fn get_min_seen_secret(&self) -> u64 { + pub(super) fn get_min_seen_secret(&self) -> u64 { //TODO This can be optimized? let mut min = 1 << 48; for &(_, idx) in self.old_secrets.iter() { @@ -1403,7 +1426,7 @@ impl ChannelMonitor { watch_outputs } - pub fn would_broadcast_at_height(&self, height: u32) -> bool { + pub(super) fn would_broadcast_at_height(&self, height: u32) -> bool { if let Some(ref cur_local_tx) = self.current_local_signed_commitment_tx { for &(ref htlc, _, _) in cur_local_tx.htlc_outputs.iter() { if htlc.cltv_expiry <= height + CLTV_CLAIM_BUFFER {