1 //! Utilities to assist in the initial sync required to initialize or reload Rust-Lightning objects
4 use crate::{BlockSource, BlockSourceResult, Cache, ChainNotifier};
5 use crate::poll::{ChainPoller, Validate, ValidatedBlockHeader};
7 use bitcoin::blockdata::block::Header;
8 use bitcoin::hash_types::BlockHash;
9 use bitcoin::network::Network;
15 /// Returns a validated block header of the source's best chain tip.
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.
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?;
25 .get_header(&best_block_hash, best_block_height).await?
26 .validate(best_block_hash)
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.
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
36 /// Useful during startup to bring the [`ChannelManager`] and each [`ChannelMonitor`] in sync before
37 /// switching to [`SpvClient`]. For example:
40 /// use bitcoin::hash_types::BlockHash;
41 /// use bitcoin::network::Network;
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;
58 /// use lightning_block_sync::*;
60 /// use std::io::Cursor;
62 /// async fn init_sync<
64 /// ES: EntropySource,
66 /// SP: SignerProvider,
67 /// T: BroadcasterInterface,
72 /// P: chainmonitor::Persist<SP::EcdsaSigner>,
75 /// chain_monitor: &ChainMonitor<SP::EcdsaSigner, &C, &T, &F, &L, &P>,
76 /// config: UserConfig,
77 /// entropy_source: &ES,
79 /// signer_provider: &SP,
80 /// tx_broadcaster: &T,
81 /// fee_estimator: &F,
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::EcdsaSigner>)>::read(
89 /// &mut Cursor::new(&serialized_monitor), (entropy_source, signer_provider)).unwrap();
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(
104 /// vec![&mut monitor],
106 /// <(BlockHash, ChannelManager<&ChainMonitor<SP::EcdsaSigner, &C, &T, &F, &L, &P>, &T, &ES, &NS, &SP, &F, &R, &L>)>::read(
107 /// &mut Cursor::new(&serialized_manager), read_args).unwrap()
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),
117 /// let chain_tip = init::synchronize_listeners(
118 /// block_source, Network::Bitcoin, &mut cache, listeners).await.unwrap();
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);
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);
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>(
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?;
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,
148 .get_header(&old_block_hash, None).await?
149 .validate(old_block_hash)?
151 chain_listeners_with_old_headers.push((old_header, chain_listener))
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 };
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)
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;
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)?;
190 /// A wrapper to make a cache read-only.
192 /// Used to prevent losing headers that may be needed to disconnect blocks common to more than one
194 struct ReadOnlyCache<'a, C: Cache>(&'a mut C);
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)
201 fn block_connected(&mut self, _block_hash: BlockHash, _block_header: ValidatedBlockHeader) {
205 fn block_disconnected(&mut self, _block_hash: &BlockHash) -> Option<ValidatedBlockHeader> {
210 /// Wrapper for supporting dynamically sized chain listeners.
211 struct DynamicChainListener<'a, L: chain::Listen + ?Sized>(&'a L);
213 impl<'a, L: chain::Listen + ?Sized> chain::Listen for DynamicChainListener<'a, L> {
214 fn filtered_block_connected(&self, _header: &Header, _txdata: &chain::transaction::TransactionData, _height: u32) {
218 fn block_disconnected(&self, header: &Header, height: u32) {
219 self.0.block_disconnected(header, height)
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)>);
226 impl<'a, L: chain::Listen + ?Sized> chain::Listen for ChainListenerSet<'a, L> {
227 // Needed to differentiate test expectations.
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);
237 fn filtered_block_connected(&self, header: &Header, 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);
245 fn block_disconnected(&self, _header: &Header, _height: u32) {
252 use crate::test_utils::{Blockchain, MockChainListener};
256 async fn sync_from_same_chain() {
257 let chain = Blockchain::default().with_height(4);
259 let listener_1 = MockChainListener::new()
260 .expect_block_connected(*chain.at_height(2))
261 .expect_block_connected(*chain.at_height(3))
262 .expect_block_connected(*chain.at_height(4));
263 let listener_2 = MockChainListener::new()
264 .expect_block_connected(*chain.at_height(3))
265 .expect_block_connected(*chain.at_height(4));
266 let listener_3 = MockChainListener::new()
267 .expect_block_connected(*chain.at_height(4));
269 let listeners = vec![
270 (chain.at_height(1).block_hash, &listener_1 as &dyn chain::Listen),
271 (chain.at_height(2).block_hash, &listener_2 as &dyn chain::Listen),
272 (chain.at_height(3).block_hash, &listener_3 as &dyn chain::Listen),
274 let mut cache = chain.header_cache(0..=4);
275 match synchronize_listeners(&chain, Network::Bitcoin, &mut cache, listeners).await {
276 Ok(header) => assert_eq!(header, chain.tip()),
277 Err(e) => panic!("Unexpected error: {:?}", e),
282 async fn sync_from_different_chains() {
283 let main_chain = Blockchain::default().with_height(4);
284 let fork_chain_1 = main_chain.fork_at_height(1);
285 let fork_chain_2 = main_chain.fork_at_height(2);
286 let fork_chain_3 = main_chain.fork_at_height(3);
288 let listener_1 = MockChainListener::new()
289 .expect_block_disconnected(*fork_chain_1.at_height(4))
290 .expect_block_disconnected(*fork_chain_1.at_height(3))
291 .expect_block_disconnected(*fork_chain_1.at_height(2))
292 .expect_block_connected(*main_chain.at_height(2))
293 .expect_block_connected(*main_chain.at_height(3))
294 .expect_block_connected(*main_chain.at_height(4));
295 let listener_2 = MockChainListener::new()
296 .expect_block_disconnected(*fork_chain_2.at_height(4))
297 .expect_block_disconnected(*fork_chain_2.at_height(3))
298 .expect_block_connected(*main_chain.at_height(3))
299 .expect_block_connected(*main_chain.at_height(4));
300 let listener_3 = MockChainListener::new()
301 .expect_block_disconnected(*fork_chain_3.at_height(4))
302 .expect_block_connected(*main_chain.at_height(4));
304 let listeners = vec![
305 (fork_chain_1.tip().block_hash, &listener_1 as &dyn chain::Listen),
306 (fork_chain_2.tip().block_hash, &listener_2 as &dyn chain::Listen),
307 (fork_chain_3.tip().block_hash, &listener_3 as &dyn chain::Listen),
309 let mut cache = fork_chain_1.header_cache(2..=4);
310 cache.extend(fork_chain_2.header_cache(3..=4));
311 cache.extend(fork_chain_3.header_cache(4..=4));
312 match synchronize_listeners(&main_chain, Network::Bitcoin, &mut cache, listeners).await {
313 Ok(header) => assert_eq!(header, main_chain.tip()),
314 Err(e) => panic!("Unexpected error: {:?}", e),
319 async fn sync_from_overlapping_chains() {
320 let main_chain = Blockchain::default().with_height(4);
321 let fork_chain_1 = main_chain.fork_at_height(1);
322 let fork_chain_2 = fork_chain_1.fork_at_height(2);
323 let fork_chain_3 = fork_chain_2.fork_at_height(3);
325 let listener_1 = MockChainListener::new()
326 .expect_block_disconnected(*fork_chain_1.at_height(4))
327 .expect_block_disconnected(*fork_chain_1.at_height(3))
328 .expect_block_disconnected(*fork_chain_1.at_height(2))
329 .expect_block_connected(*main_chain.at_height(2))
330 .expect_block_connected(*main_chain.at_height(3))
331 .expect_block_connected(*main_chain.at_height(4));
332 let listener_2 = MockChainListener::new()
333 .expect_block_disconnected(*fork_chain_2.at_height(4))
334 .expect_block_disconnected(*fork_chain_2.at_height(3))
335 .expect_block_disconnected(*fork_chain_2.at_height(2))
336 .expect_block_connected(*main_chain.at_height(2))
337 .expect_block_connected(*main_chain.at_height(3))
338 .expect_block_connected(*main_chain.at_height(4));
339 let listener_3 = MockChainListener::new()
340 .expect_block_disconnected(*fork_chain_3.at_height(4))
341 .expect_block_disconnected(*fork_chain_3.at_height(3))
342 .expect_block_disconnected(*fork_chain_3.at_height(2))
343 .expect_block_connected(*main_chain.at_height(2))
344 .expect_block_connected(*main_chain.at_height(3))
345 .expect_block_connected(*main_chain.at_height(4));
347 let listeners = vec![
348 (fork_chain_1.tip().block_hash, &listener_1 as &dyn chain::Listen),
349 (fork_chain_2.tip().block_hash, &listener_2 as &dyn chain::Listen),
350 (fork_chain_3.tip().block_hash, &listener_3 as &dyn chain::Listen),
352 let mut cache = fork_chain_1.header_cache(2..=4);
353 cache.extend(fork_chain_2.header_cache(3..=4));
354 cache.extend(fork_chain_3.header_cache(4..=4));
355 match synchronize_listeners(&main_chain, Network::Bitcoin, &mut cache, listeners).await {
356 Ok(header) => assert_eq!(header, main_chain.tip()),
357 Err(e) => panic!("Unexpected error: {:?}", e),
362 async fn cache_connected_and_keep_disconnected_blocks() {
363 let main_chain = Blockchain::default().with_height(2);
364 let fork_chain = main_chain.fork_at_height(1);
365 let new_tip = main_chain.tip();
366 let old_tip = fork_chain.tip();
368 let listener = MockChainListener::new()
369 .expect_block_disconnected(*old_tip)
370 .expect_block_connected(*new_tip);
372 let listeners = vec![(old_tip.block_hash, &listener as &dyn chain::Listen)];
373 let mut cache = fork_chain.header_cache(2..=2);
374 match synchronize_listeners(&main_chain, Network::Bitcoin, &mut cache, listeners).await {
376 assert!(cache.contains_key(&new_tip.block_hash));
377 assert!(cache.contains_key(&old_tip.block_hash));
379 Err(e) => panic!("Unexpected error: {:?}", e),