1 use crate::{BlockSource, BlockSourceResult, Cache, ChainNotifier};
2 use crate::poll::{ChainPoller, Validate, ValidatedBlockHeader};
4 use bitcoin::blockdata::block::{Block, BlockHeader};
5 use bitcoin::hash_types::BlockHash;
6 use bitcoin::network::constants::Network;
10 /// Returns a validated block header of the source's best chain tip.
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?;
18 .get_header(&best_block_hash, best_block_height).await?
19 .validate(best_block_hash)
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.
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
29 /// Useful during startup to bring the [`ChannelManager`] and each [`ChannelMonitor`] in sync before
30 /// switching to [`SpvClient`]. For example:
33 /// use bitcoin::hash_types::BlockHash;
34 /// use bitcoin::network::constants::Network;
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;
51 /// use lightning_block_sync::*;
53 /// use std::io::Cursor;
55 /// async fn init_sync<
57 /// K: KeysInterface<Signer = S>,
58 /// S: keysinterface::Sign,
59 /// T: BroadcasterInterface,
63 /// P: channelmonitor::Persist<S>,
65 /// block_source: &mut B,
66 /// chain_monitor: &ChainMonitor<S, &C, &T, &F, &L, &P>,
67 /// config: UserConfig,
69 /// tx_broadcaster: &T,
70 /// fee_estimator: &F,
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();
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(
89 /// vec![&mut monitor],
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()
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))
102 /// if let Some(manager_block_hash) = manager_block_hash_option {
103 /// listeners.push((manager_block_hash, &mut manager as &mut dyn chain::Listen))
105 /// let chain_tip = init::synchronize_listeners(
106 /// block_source, Network::Bitcoin, &mut cache, listeners).await.unwrap();
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);
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);
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,
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?;
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,
136 .get_header(&old_block_hash, None).await?
137 .validate(old_block_hash)?
139 chain_listeners_with_old_headers.push((old_header, chain_listener))
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 };
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)
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;
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))?;
178 /// A wrapper to make a cache read-only.
180 /// Used to prevent losing headers that may be needed to disconnect blocks common to more than one
182 struct ReadOnlyCache<'a, C: Cache>(&'a mut C);
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)
189 fn block_connected(&mut self, _block_hash: BlockHash, _block_header: ValidatedBlockHeader) {
193 fn block_disconnected(&mut self, _block_hash: &BlockHash) -> Option<ValidatedBlockHeader> {
198 /// Wrapper for supporting dynamically sized chain listeners.
199 struct DynamicChainListener<'a>(&'a mut dyn chain::Listen);
201 impl<'a> chain::Listen for DynamicChainListener<'a> {
202 fn block_connected(&self, _block: &Block, _height: u32) {
206 fn block_disconnected(&self, header: &BlockHeader, height: u32) {
207 self.0.block_disconnected(header, height)
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)>);
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);
223 fn block_disconnected(&self, _header: &BlockHeader, _height: u32) {
230 use crate::test_utils::{Blockchain, MockChainListener};
233 use bitcoin::network::constants::Network;
236 async fn sync_from_same_chain() {
237 let mut chain = Blockchain::default().with_height(4);
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));
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),
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),
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);
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));
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),
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),
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);
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));
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),
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),
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();
348 let mut listener = MockChainListener::new()
349 .expect_block_disconnected(*old_tip)
350 .expect_block_connected(*new_tip);
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 {
356 assert!(cache.contains_key(&new_tip.block_hash));
357 assert!(cache.contains_key(&old_tip.block_hash));
359 Err(e) => panic!("Unexpected error: {:?}", e),