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