_ Git - rust-lightning/blob - lightning-block-sync/src/init.rs

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