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 /// 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.
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
17 /// Useful during startup to bring the [`ChannelManager`] and each [`ChannelMonitor`] in sync before
18 /// switching to [`SpvClient`]. For example:
21 /// use bitcoin::hash_types::BlockHash;
22 /// use bitcoin::network::constants::Network;
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;
39 /// use lightning_block_sync::*;
41 /// use std::cell::RefCell;
42 /// use std::io::Cursor;
44 /// async fn init_sync<
46 /// K: KeysInterface<Signer = S>,
47 /// S: keysinterface::Sign,
48 /// T: BroadcasterInterface,
52 /// P: channelmonitor::Persist<S>,
54 /// block_source: &mut B,
55 /// chain_monitor: &ChainMonitor<S, &C, &T, &F, &L, &P>,
56 /// config: UserConfig,
58 /// tx_broadcaster: &T,
59 /// fee_estimator: &F,
63 /// let serialized_monitor = "...";
64 /// let (monitor_block_hash, mut monitor) = <(BlockHash, ChannelMonitor<S>)>::read(
65 /// &mut Cursor::new(&serialized_monitor), keys_manager).unwrap();
67 /// let serialized_manager = "...";
68 /// let (manager_block_hash, mut manager) = {
69 /// let read_args = ChannelManagerReadArgs::new(
76 /// vec![&mut monitor],
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()
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
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),
92 /// init::sync_listeners(block_source, Network::Bitcoin, &mut cache, listeners).await.unwrap();
94 /// chain_monitor.watch_channel(monitor.get_funding_txo().0, monitor);
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);
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,
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)?;
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,
122 .get_header(&old_block, None).await?
123 .validate(old_block)?
125 chain_listeners_with_old_headers.push((old_header, chain_listener))
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 };
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)
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;
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))?;
164 /// A wrapper to make a cache read-only.
166 /// Used to prevent losing headers that may be needed to disconnect blocks common to more than one
168 struct ReadOnlyCache<'a, C: Cache>(&'a mut C);
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)
175 fn block_connected(&mut self, _block_hash: BlockHash, _block_header: ValidatedBlockHeader) {
179 fn block_disconnected(&mut self, _block_hash: &BlockHash) -> Option<ValidatedBlockHeader> {
184 /// Wrapper for supporting dynamically sized chain listeners.
185 struct DynamicChainListener<'a>(&'a mut dyn chain::Listen);
187 impl<'a> chain::Listen for DynamicChainListener<'a> {
188 fn block_connected(&mut self, _block: &Block, _height: u32) {
192 fn block_disconnected(&mut self, header: &BlockHeader, height: u32) {
193 self.0.block_disconnected(header, height)
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)>);
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);
209 fn block_disconnected(&mut self, _header: &BlockHeader, _height: u32) {
216 use crate::test_utils::{Blockchain, MockChainListener};
219 use bitcoin::network::constants::Network;
222 async fn sync_from_same_chain() {
223 let mut chain = Blockchain::default().with_height(4);
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));
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),
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),
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);
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));
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),
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),
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);
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));
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),
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),
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();
334 let mut listener = MockChainListener::new()
335 .expect_block_disconnected(*old_tip)
336 .expect_block_connected(*new_tip);
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 {
342 assert!(cache.contains_key(&new_tip.block_hash));
343 assert!(cache.contains_key(&old_tip.block_hash));
345 Err(e) => panic!("Unexpected error: {:?}", e),