Merge pull request #249 from stevenroose/bitcoin-0.15

[rust-lightning] / src / chain / chaininterface.rs

diff --git a/src/chain/chaininterface.rs b/src/chain/chaininterface.rs
index c6b3b1b629d0cd11051215c27c01a2f66237205d..7b5e0d0749832a7cf2ffcfcd560156d085fd53f7 100644 (file)
--- a/src/chain/chaininterface.rs
+++ b/src/chain/chaininterface.rs
@@ -1,14 +1,15 @@
 //! Traits and utility impls which allow other parts of rust-lightning to interact with the
-//! blockchain - receiving notifications of new blocks and block disconnections and allowing
-//! rust-lightning to request that you monitor the chain for certain outpoints/transactions.
+//! blockchain.
+//!
+//! Includes traits for monitoring and receiving notifications of new blocks and block
+//! disconnections, transactio broadcasting, and feerate information requests.
 
 use bitcoin::blockdata::block::{Block, BlockHeader};
 use bitcoin::blockdata::transaction::Transaction;
 use bitcoin::blockdata::script::Script;
 use bitcoin::blockdata::constants::genesis_block;
-use bitcoin::util::hash::Sha256dHash;
+use bitcoin::util::hash::{BitcoinHash, Sha256dHash};
 use bitcoin::network::constants::Network;
-use bitcoin::network::serialize::BitcoinHash;
 
 use util::logger::Logger;
 
@@ -28,6 +29,7 @@ pub enum ChainError {
 
 /// An interface to request notification of certain scripts as they appear the
 /// chain.
+///
 /// Note that all of the functions implemented here *must* be reentrant-safe (obviously - they're
 /// called from inside the library in response to ChainListener events, P2P events, or timer
 /// events).
@@ -66,8 +68,10 @@ pub trait ChainListener: Sync + Send {
        /// Note that if a new transaction/outpoint is watched during a block_connected call, the block
        /// *must* be re-scanned with the new transaction/outpoints and block_connected should be
        /// called again with the same header and (at least) the new transactions.
+       ///
        /// Note that if non-new transaction/outpoints may be registered during a call, a second call
        /// *must not* happen.
+       ///
        /// This also means those counting confirmations using block_connected callbacks should watch
        /// for duplicate headers and not count them towards confirmations!
        fn block_connected(&self, header: &BlockHeader, height: u32, txn_matched: &[&Transaction], indexes_of_txn_matched: &[u32]);
@@ -89,15 +93,19 @@ pub enum ConfirmationTarget {
 
 /// A trait which should be implemented to provide feerate information on a number of time
 /// horizons.
+///
 /// Note that all of the functions implemented here *must* be reentrant-safe (obviously - they're
 /// called from inside the library in response to ChainListener events, P2P events, or timer
 /// events).
 pub trait FeeEstimator: Sync + Send {
-       /// Gets estimated satoshis of fee required per 1000 Weight-Units. This translates to:
-       ///  * satoshis-per-byte * 250
-       ///  * ceil(satoshis-per-kbyte / 4)
+       /// Gets estimated satoshis of fee required per 1000 Weight-Units.
+       ///
        /// Must be no smaller than 253 (ie 1 satoshi-per-byte rounded up to ensure later round-downs
        /// don't put us below 1 satoshi-per-byte).
+       ///
+       /// This translates to:
+       ///  * satoshis-per-byte * 250
+       ///  * ceil(satoshis-per-kbyte / 4)
        fn get_est_sat_per_1000_weight(&self, confirmation_target: ConfirmationTarget) -> u64;
 }
 
@@ -189,6 +197,7 @@ impl ChainWatchedUtil {
 }
 
 /// Utility to capture some common parts of ChainWatchInterface implementors.
+///
 /// Keeping a local copy of this in a ChainWatchInterface implementor is likely useful.
 pub struct ChainWatchInterfaceUtil {
        network: Network,
@@ -247,6 +256,7 @@ impl ChainWatchInterfaceUtil {
        }
 
        /// Notify listeners that a block was connected given a full, unfiltered block.
+       ///
        /// Handles re-scanning the block and calling block_connected again if listeners register new
        /// watch data during the callbacks for you (see ChainListener::block_connected for more info).
        pub fn block_connected_with_filtering(&self, block: &Block, height: u32) {
@@ -280,6 +290,7 @@ impl ChainWatchInterfaceUtil {
 
        /// Notify listeners that a block was connected, given pre-filtered list of transactions in the
        /// block which matched the filter (probably using does_match_tx).
+       ///
        /// Returns true if notified listeners registered additional watch data (implying that the
        /// block must be re-scanned and this function called again prior to further block_connected
        /// calls, see ChainListener::block_connected for more info).