git.bitcoin.ninja Git - rust-lightning/blob - lightning-block-sync/src/init.rs

   1 //! Utilities to assist in the initial sync required to initialize or reload Rust-Lightning objects
   2 //! from disk.
   3
   4 use crate::{BlockSource, BlockSourceResult, Cache, ChainNotifier};
   5 use crate::poll::{ChainPoller, Validate, ValidatedBlockHeader};
   6
   7 use bitcoin::blockdata::block::BlockHeader;
   8 use bitcoin::hash_types::BlockHash;
   9 use bitcoin::network::constants::Network;
  10
  11 use lightning::chain;
  12
  13 use std::ops::Deref;
  14
  15 /// Returns a validated block header of the source's best chain tip.
  16 ///
  17 /// Upon success, the returned header can be used to initialize [`SpvClient`]. Useful during a fresh
  18 /// start when there are no chain listeners to sync yet.
  19 ///
  20 /// [`SpvClient`]: crate::SpvClient
  21 pub async fn validate_best_block_header<B: Deref>(block_source: B) ->
  22 BlockSourceResult<ValidatedBlockHeader> where B::Target: BlockSource {
  23         let (best_block_hash, best_block_height) = block_source.get_best_block().await?;
  24         block_source
  25                 .get_header(&best_block_hash, best_block_height).await?
  26                 .validate(best_block_hash)
  27 }
  28
  29 /// Performs a one-time sync of chain listeners using a single *trusted* block source, bringing each
  30 /// listener's view of the chain from its paired block hash to `block_source`'s best chain tip.
  31 ///
  32 /// Upon success, the returned header can be used to initialize [`SpvClient`]. In the case of
  33 /// failure, each listener may be left at a different block hash than the one it was originally
  34 /// paired with.
  35 ///
  36 /// Useful during startup to bring the [`ChannelManager`] and each [`ChannelMonitor`] in sync before
  37 /// switching to [`SpvClient`]. For example:
  38 ///
  39 /// ```
  40 /// use bitcoin::hash_types::BlockHash;
  41 /// use bitcoin::network::constants::Network;
  42 ///
  43 /// use lightning::chain;
  44 /// use lightning::chain::Watch;
  45 /// use lightning::chain::chainmonitor;
  46 /// use lightning::chain::chainmonitor::ChainMonitor;
  47 /// use lightning::chain::channelmonitor::ChannelMonitor;
  48 /// use lightning::chain::chaininterface::BroadcasterInterface;
  49 /// use lightning::chain::chaininterface::FeeEstimator;
  50 /// use lightning::sign;
  51 /// use lightning::sign::{EntropySource, NodeSigner, SignerProvider};
  52 /// use lightning::ln::channelmanager::{ChannelManager, ChannelManagerReadArgs};
  53 /// use lightning::routing::router::Router;
  54 /// use lightning::util::config::UserConfig;
  55 /// use lightning::util::logger::Logger;
  56 /// use lightning::util::ser::ReadableArgs;
  57 ///
  58 /// use lightning_block_sync::*;
  59 ///
  60 /// use std::io::Cursor;
  61 ///
  62 /// async fn init_sync<
  63 ///     B: BlockSource,
  64 ///     ES: EntropySource,
  65 ///     NS: NodeSigner,
  66 ///     SP: SignerProvider,
  67 ///     T: BroadcasterInterface,
  68 ///     F: FeeEstimator,
  69 ///     R: Router,
  70 ///     L: Logger,
  71 ///     C: chain::Filter,
  72 ///     P: chainmonitor::Persist<SP::Signer>,
  73 /// >(
  74 ///     block_source: &B,
  75 ///     chain_monitor: &ChainMonitor<SP::Signer, &C, &T, &F, &L, &P>,
  76 ///     config: UserConfig,
  77 ///     entropy_source: &ES,
  78 ///     node_signer: &NS,
  79 ///     signer_provider: &SP,
  80 ///     tx_broadcaster: &T,
  81 ///     fee_estimator: &F,
  82 ///     router: &R,
  83 ///     logger: &L,
  84 ///     persister: &P,
  85 /// ) {
  86 ///     // Read a serialized channel monitor paired with the block hash when it was persisted.
  87 ///     let serialized_monitor = "...";
  88 ///     let (monitor_block_hash, mut monitor) = <(BlockHash, ChannelMonitor<SP::Signer>)>::read(
  89 ///             &mut Cursor::new(&serialized_monitor), (entropy_source, signer_provider)).unwrap();
  90 ///
  91 ///     // Read the channel manager paired with the block hash when it was persisted.
  92 ///     let serialized_manager = "...";
  93 ///     let (manager_block_hash, mut manager) = {
  94 ///             let read_args = ChannelManagerReadArgs::new(
  95 ///                     entropy_source,
  96 ///                     node_signer,
  97 ///                     signer_provider,
  98 ///                     fee_estimator,
  99 ///                     chain_monitor,
 100 ///                     tx_broadcaster,
 101 ///                     router,
 102 ///                     logger,
 103 ///                     config,
 104 ///                     vec![&mut monitor],
 105 ///             );
 106 ///             <(BlockHash, ChannelManager<&ChainMonitor<SP::Signer, &C, &T, &F, &L, &P>, &T, &ES, &NS, &SP, &F, &R, &L>)>::read(
 107 ///                     &mut Cursor::new(&serialized_manager), read_args).unwrap()
 108 ///     };
 109 ///
 110 ///     // Synchronize any channel monitors and the channel manager to be on the best block.
 111 ///     let mut cache = UnboundedCache::new();
 112 ///     let mut monitor_listener = (monitor, &*tx_broadcaster, &*fee_estimator, &*logger);
 113 ///     let listeners = vec![
 114 ///             (monitor_block_hash, &monitor_listener as &dyn chain::Listen),
 115 ///             (manager_block_hash, &manager as &dyn chain::Listen),
 116 ///     ];
 117 ///     let chain_tip = init::synchronize_listeners(
 118 ///             block_source, Network::Bitcoin, &mut cache, listeners).await.unwrap();
 119 ///
 120 ///     // Allow the chain monitor to watch any channels.
 121 ///     let monitor = monitor_listener.0;
 122 ///     chain_monitor.watch_channel(monitor.get_funding_txo().0, monitor);
 123 ///
 124 ///     // Create an SPV client to notify the chain monitor and channel manager of block events.
 125 ///     let chain_poller = poll::ChainPoller::new(block_source, Network::Bitcoin);
 126 ///     let mut chain_listener = (chain_monitor, &manager);
 127 ///     let spv_client = SpvClient::new(chain_tip, chain_poller, &mut cache, &chain_listener);
 128 /// }
 129 /// ```
 130 ///
 131 /// [`SpvClient`]: crate::SpvClient
 132 /// [`ChannelManager`]: lightning::ln::channelmanager::ChannelManager
 133 /// [`ChannelMonitor`]: lightning::chain::channelmonitor::ChannelMonitor
 134 pub async fn synchronize_listeners<B: Deref + Sized + Send + Sync, C: Cache, L: chain::Listen + ?Sized>(
 135         block_source: B,
 136         network: Network,
 137         header_cache: &mut C,
 138         mut chain_listeners: Vec<(BlockHash, &L)>,
 139 ) -> BlockSourceResult<ValidatedBlockHeader> where B::Target: BlockSource {
 140         let best_header = validate_best_block_header(&*block_source).await?;
 141
 142         // Fetch the header for the block hash paired with each listener.
 143         let mut chain_listeners_with_old_headers = Vec::new();
 144         for (old_block_hash, chain_listener) in chain_listeners.drain(..) {
 145                 let old_header = match header_cache.look_up(&old_block_hash) {
 146                         Some(header) => *header,
 147                         None => block_source
 148                                 .get_header(&old_block_hash, None).await?
 149                                 .validate(old_block_hash)?
 150                 };
 151                 chain_listeners_with_old_headers.push((old_header, chain_listener))
 152         }
 153
 154         // Find differences and disconnect blocks for each listener individually.
 155         let mut chain_poller = ChainPoller::new(block_source, network);
 156         let mut chain_listeners_at_height = Vec::new();
 157         let mut most_common_ancestor = None;
 158         let mut most_connected_blocks = Vec::new();
 159         for (old_header, chain_listener) in chain_listeners_with_old_headers.drain(..) {
 160                 // Disconnect any stale blocks, but keep them in the cache for the next iteration.
 161                 let header_cache = &mut ReadOnlyCache(header_cache);
 162                 let (common_ancestor, connected_blocks) = {
 163                         let chain_listener = &DynamicChainListener(chain_listener);
 164                         let mut chain_notifier = ChainNotifier { header_cache, chain_listener };
 165                         let difference =
 166                                 chain_notifier.find_difference(best_header, &old_header, &mut chain_poller).await?;
 167                         chain_notifier.disconnect_blocks(difference.disconnected_blocks);
 168                         (difference.common_ancestor, difference.connected_blocks)
 169                 };
 170
 171                 // Keep track of the most common ancestor and all blocks connected across all listeners.
 172                 chain_listeners_at_height.push((common_ancestor.height, chain_listener));
 173                 if connected_blocks.len() > most_connected_blocks.len() {
 174                         most_common_ancestor = Some(common_ancestor);
 175                         most_connected_blocks = connected_blocks;
 176                 }
 177         }
 178
 179         // Connect new blocks for all listeners at once to avoid re-fetching blocks.
 180         if let Some(common_ancestor) = most_common_ancestor {
 181                 let chain_listener = &ChainListenerSet(chain_listeners_at_height);
 182                 let mut chain_notifier = ChainNotifier { header_cache, chain_listener };
 183                 chain_notifier.connect_blocks(common_ancestor, most_connected_blocks, &mut chain_poller)
 184                         .await.map_err(|(e, _)| e)?;
 185         }
 186
 187         Ok(best_header)
 188 }
 189
 190 /// A wrapper to make a cache read-only.
 191 ///
 192 /// Used to prevent losing headers that may be needed to disconnect blocks common to more than one
 193 /// listener.
 194 struct ReadOnlyCache<'a, C: Cache>(&'a mut C);
 195
 196 impl<'a, C: Cache> Cache for ReadOnlyCache<'a, C> {
 197         fn look_up(&self, block_hash: &BlockHash) -> Option<&ValidatedBlockHeader> {
 198                 self.0.look_up(block_hash)
 199         }
 200
 201         fn block_connected(&mut self, _block_hash: BlockHash, _block_header: ValidatedBlockHeader) {
 202                 unreachable!()
 203         }
 204
 205         fn block_disconnected(&mut self, _block_hash: &BlockHash) -> Option<ValidatedBlockHeader> {
 206                 None
 207         }
 208 }
 209
 210 /// Wrapper for supporting dynamically sized chain listeners.
 211 struct DynamicChainListener<'a, L: chain::Listen + ?Sized>(&'a L);
 212
 213 impl<'a, L: chain::Listen + ?Sized> chain::Listen for DynamicChainListener<'a, L> {
 214         fn filtered_block_connected(&self, _header: &BlockHeader, _txdata: &chain::transaction::TransactionData, _height: u32) {
 215                 unreachable!()
 216         }
 217
 218         fn block_disconnected(&self, header: &BlockHeader, height: u32) {
 219                 self.0.block_disconnected(header, height)
 220         }
 221 }
 222
 223 /// A set of dynamically sized chain listeners, each paired with a starting block height.
 224 struct ChainListenerSet<'a, L: chain::Listen + ?Sized>(Vec<(u32, &'a L)>);
 225
 226 impl<'a, L: chain::Listen + ?Sized> chain::Listen for ChainListenerSet<'a, L> {
 227         // Needed to differentiate test expectations.
 228         #[cfg(test)]
 229         fn block_connected(&self, block: &bitcoin::Block, height: u32) {
 230                 for (starting_height, chain_listener) in self.0.iter() {
 231                         if height > *starting_height {
 232                                 chain_listener.block_connected(block, height);
 233                         }
 234                 }
 235         }
 236
 237         fn filtered_block_connected(&self, header: &BlockHeader, txdata: &chain::transaction::TransactionData, height: u32) {
 238                 for (starting_height, chain_listener) in self.0.iter() {
 239                         if height > *starting_height {
 240                                 chain_listener.filtered_block_connected(header, txdata, height);
 241                         }
 242                 }
 243         }
 244
 245         fn block_disconnected(&self, _header: &BlockHeader, _height: u32) {
 246                 unreachable!()
 247         }
 248 }
 249
 250 #[cfg(test)]
 251 mod tests {
 252         use crate::test_utils::{Blockchain, MockChainListener};
 253         use super::*;
 254
 255         use bitcoin::network::constants::Network;
 256
 257         #[tokio::test]
 258         async fn sync_from_same_chain() {
 259                 let chain = Blockchain::default().with_height(4);
 260
 261                 let listener_1 = MockChainListener::new()
 262                         .expect_block_connected(*chain.at_height(2))
 263                         .expect_block_connected(*chain.at_height(3))
 264                         .expect_block_connected(*chain.at_height(4));
 265                 let listener_2 = MockChainListener::new()
 266                         .expect_block_connected(*chain.at_height(3))
 267                         .expect_block_connected(*chain.at_height(4));
 268                 let listener_3 = MockChainListener::new()
 269                         .expect_block_connected(*chain.at_height(4));
 270
 271                 let listeners = vec![
 272                         (chain.at_height(1).block_hash, &listener_1 as &dyn chain::Listen),
 273                         (chain.at_height(2).block_hash, &listener_2 as &dyn chain::Listen),
 274                         (chain.at_height(3).block_hash, &listener_3 as &dyn chain::Listen),
 275                 ];
 276                 let mut cache = chain.header_cache(0..=4);
 277                 match synchronize_listeners(&chain, Network::Bitcoin, &mut cache, listeners).await {
 278                         Ok(header) => assert_eq!(header, chain.tip()),
 279                         Err(e) => panic!("Unexpected error: {:?}", e),
 280                 }
 281         }
 282
 283         #[tokio::test]
 284         async fn sync_from_different_chains() {
 285                 let main_chain = Blockchain::default().with_height(4);
 286                 let fork_chain_1 = main_chain.fork_at_height(1);
 287                 let fork_chain_2 = main_chain.fork_at_height(2);
 288                 let fork_chain_3 = main_chain.fork_at_height(3);
 289
 290                 let listener_1 = MockChainListener::new()
 291                         .expect_block_disconnected(*fork_chain_1.at_height(4))
 292                         .expect_block_disconnected(*fork_chain_1.at_height(3))
 293                         .expect_block_disconnected(*fork_chain_1.at_height(2))
 294                         .expect_block_connected(*main_chain.at_height(2))
 295                         .expect_block_connected(*main_chain.at_height(3))
 296                         .expect_block_connected(*main_chain.at_height(4));
 297                 let listener_2 = MockChainListener::new()
 298                         .expect_block_disconnected(*fork_chain_2.at_height(4))
 299                         .expect_block_disconnected(*fork_chain_2.at_height(3))
 300                         .expect_block_connected(*main_chain.at_height(3))
 301                         .expect_block_connected(*main_chain.at_height(4));
 302                 let listener_3 = MockChainListener::new()
 303                         .expect_block_disconnected(*fork_chain_3.at_height(4))
 304                         .expect_block_connected(*main_chain.at_height(4));
 305
 306                 let listeners = vec![
 307                         (fork_chain_1.tip().block_hash, &listener_1 as &dyn chain::Listen),
 308                         (fork_chain_2.tip().block_hash, &listener_2 as &dyn chain::Listen),
 309                         (fork_chain_3.tip().block_hash, &listener_3 as &dyn chain::Listen),
 310                 ];
 311                 let mut cache = fork_chain_1.header_cache(2..=4);
 312                 cache.extend(fork_chain_2.header_cache(3..=4));
 313                 cache.extend(fork_chain_3.header_cache(4..=4));
 314                 match synchronize_listeners(&main_chain, Network::Bitcoin, &mut cache, listeners).await {
 315                         Ok(header) => assert_eq!(header, main_chain.tip()),
 316                         Err(e) => panic!("Unexpected error: {:?}", e),
 317                 }
 318         }
 319
 320         #[tokio::test]
 321         async fn sync_from_overlapping_chains() {
 322                 let main_chain = Blockchain::default().with_height(4);
 323                 let fork_chain_1 = main_chain.fork_at_height(1);
 324                 let fork_chain_2 = fork_chain_1.fork_at_height(2);
 325                 let fork_chain_3 = fork_chain_2.fork_at_height(3);
 326
 327                 let listener_1 = MockChainListener::new()
 328                         .expect_block_disconnected(*fork_chain_1.at_height(4))
 329                         .expect_block_disconnected(*fork_chain_1.at_height(3))
 330                         .expect_block_disconnected(*fork_chain_1.at_height(2))
 331                         .expect_block_connected(*main_chain.at_height(2))
 332                         .expect_block_connected(*main_chain.at_height(3))
 333                         .expect_block_connected(*main_chain.at_height(4));
 334                 let listener_2 = MockChainListener::new()
 335                         .expect_block_disconnected(*fork_chain_2.at_height(4))
 336                         .expect_block_disconnected(*fork_chain_2.at_height(3))
 337                         .expect_block_disconnected(*fork_chain_2.at_height(2))
 338                         .expect_block_connected(*main_chain.at_height(2))
 339                         .expect_block_connected(*main_chain.at_height(3))
 340                         .expect_block_connected(*main_chain.at_height(4));
 341                 let listener_3 = MockChainListener::new()
 342                         .expect_block_disconnected(*fork_chain_3.at_height(4))
 343                         .expect_block_disconnected(*fork_chain_3.at_height(3))
 344                         .expect_block_disconnected(*fork_chain_3.at_height(2))
 345                         .expect_block_connected(*main_chain.at_height(2))
 346                         .expect_block_connected(*main_chain.at_height(3))
 347                         .expect_block_connected(*main_chain.at_height(4));
 348
 349                 let listeners = vec![
 350                         (fork_chain_1.tip().block_hash, &listener_1 as &dyn chain::Listen),
 351                         (fork_chain_2.tip().block_hash, &listener_2 as &dyn chain::Listen),
 352                         (fork_chain_3.tip().block_hash, &listener_3 as &dyn chain::Listen),
 353                 ];
 354                 let mut cache = fork_chain_1.header_cache(2..=4);
 355                 cache.extend(fork_chain_2.header_cache(3..=4));
 356                 cache.extend(fork_chain_3.header_cache(4..=4));
 357                 match synchronize_listeners(&main_chain, Network::Bitcoin, &mut cache, listeners).await {
 358                         Ok(header) => assert_eq!(header, main_chain.tip()),
 359                         Err(e) => panic!("Unexpected error: {:?}", e),
 360                 }
 361         }
 362
 363         #[tokio::test]
 364         async fn cache_connected_and_keep_disconnected_blocks() {
 365                 let main_chain = Blockchain::default().with_height(2);
 366                 let fork_chain = main_chain.fork_at_height(1);
 367                 let new_tip = main_chain.tip();
 368                 let old_tip = fork_chain.tip();
 369
 370                 let listener = MockChainListener::new()
 371                         .expect_block_disconnected(*old_tip)
 372                         .expect_block_connected(*new_tip);
 373
 374                 let listeners = vec![(old_tip.block_hash, &listener as &dyn chain::Listen)];
 375                 let mut cache = fork_chain.header_cache(2..=2);
 376                 match synchronize_listeners(&main_chain, Network::Bitcoin, &mut cache, listeners).await {
 377                         Ok(_) => {
 378                                 assert!(cache.contains_key(&new_tip.block_hash));
 379                                 assert!(cache.contains_key(&old_tip.block_hash));
 380                         },
 381                         Err(e) => panic!("Unexpected error: {:?}", e),
 382                 }
 383         }
 384 }