+//! 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;
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).
/// If you're using this for local monitoring of your own channels, you probably want to use
/// `OutPoint` as the key, which will give you a ManyChannelMonitor implementation.
pub struct SimpleManyChannelMonitor<Key> {
+ #[cfg(test)] // Used in ChannelManager tests to manipulate channels directly
+ pub monitors: Mutex<HashMap<Key, ChannelMonitor>>,
+ #[cfg(not(test))]
monitors: Mutex<HashMap<Key, ChannelMonitor>>,
chain_monitor: Arc<ChainWatchInterface>,
broadcaster: Arc<BroadcasterInterface>
}
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()),
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) {
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,
}
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,
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
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),
//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))
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() {
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 {