1 //! A lightweight client for keeping in sync with chain activity.
3 //! Defines a [`BlockSource`] trait, which is an asynchronous interface for retrieving block headers
6 //! Enabling feature `rest-client` or `rpc-client` allows configuring the client to fetch blocks
7 //! using Bitcoin Core's REST or RPC interface, respectively.
9 //! Both features support either blocking I/O using `std::net::TcpStream` or, with feature `tokio`,
10 //! non-blocking I/O using `tokio::net::TcpStream` from inside a Tokio runtime.
12 //! [`BlockSource`]: trait.BlockSource.html
14 #[cfg(any(feature = "rest-client", feature = "rpc-client"))]
19 #[cfg(feature = "rest-client")]
22 #[cfg(feature = "rpc-client")]
25 #[cfg(any(feature = "rest-client", feature = "rpc-client"))]
31 #[cfg(any(feature = "rest-client", feature = "rpc-client"))]
34 use crate::poll::{Poll, ValidatedBlockHeader};
36 use bitcoin::blockdata::block::{Block, BlockHeader};
37 use bitcoin::hash_types::BlockHash;
38 use bitcoin::util::uint::Uint256;
40 use std::future::Future;
43 /// Abstract type for retrieving block headers and data.
44 pub trait BlockSource : Sync + Send {
45 /// Returns the header for a given hash. A height hint may be provided in case a block source
46 /// cannot easily find headers based on a hash. This is merely a hint and thus the returned
47 /// header must have the same hash as was requested. Otherwise, an error must be returned.
49 /// Implementations that cannot find headers based on the hash should return a `Transient` error
50 /// when `height_hint` is `None`.
51 fn get_header<'a>(&'a mut self, header_hash: &'a BlockHash, height_hint: Option<u32>) -> AsyncBlockSourceResult<'a, BlockHeaderData>;
53 /// Returns the block for a given hash. A headers-only block source should return a `Transient`
55 fn get_block<'a>(&'a mut self, header_hash: &'a BlockHash) -> AsyncBlockSourceResult<'a, Block>;
57 // TODO: Phrase in terms of `Poll` once added.
58 /// Returns the hash of the best block and, optionally, its height. When polling a block source,
59 /// the height is passed to `get_header` to allow for a more efficient lookup.
60 fn get_best_block<'a>(&'a mut self) -> AsyncBlockSourceResult<(BlockHash, Option<u32>)>;
63 /// Result type for `BlockSource` requests.
64 type BlockSourceResult<T> = Result<T, BlockSourceError>;
66 // TODO: Replace with BlockSourceResult once `async` trait functions are supported. For details,
67 // see: https://areweasyncyet.rs.
68 /// Result type for asynchronous `BlockSource` requests.
69 type AsyncBlockSourceResult<'a, T> = Pin<Box<dyn Future<Output = BlockSourceResult<T>> + 'a + Send>>;
71 /// Error type for `BlockSource` requests.
73 /// Transient errors may be resolved when re-polling, but no attempt will be made to re-poll on
74 /// persistent errors.
76 pub struct BlockSourceError {
77 kind: BlockSourceErrorKind,
78 error: Box<dyn std::error::Error + Send + Sync>,
81 /// The kind of `BlockSourceError`, either persistent or transient.
82 #[derive(Clone, Copy, Debug, PartialEq)]
83 pub enum BlockSourceErrorKind {
84 /// Indicates an error that won't resolve when retrying a request (e.g., invalid data).
87 /// Indicates an error that may resolve when retrying a request (e.g., unresponsive).
91 impl BlockSourceError {
92 /// Creates a new persistent error originated from the given error.
93 pub fn persistent<E>(error: E) -> Self
94 where E: Into<Box<dyn std::error::Error + Send + Sync>> {
96 kind: BlockSourceErrorKind::Persistent,
101 /// Creates a new transient error originated from the given error.
102 pub fn transient<E>(error: E) -> Self
103 where E: Into<Box<dyn std::error::Error + Send + Sync>> {
105 kind: BlockSourceErrorKind::Transient,
110 /// Returns the kind of error.
111 pub fn kind(&self) -> BlockSourceErrorKind {
115 /// Converts the error into the underlying error.
116 pub fn into_inner(self) -> Box<dyn std::error::Error + Send + Sync> {
121 /// A block header and some associated data. This information should be available from most block
122 /// sources (and, notably, is available in Bitcoin Core's RPC and REST interfaces).
123 #[derive(Clone, Copy, Debug, PartialEq)]
124 pub struct BlockHeaderData {
125 /// The block header itself.
126 pub header: BlockHeader,
128 /// The block height where the genesis block has height 0.
131 /// The total chain work in expected number of double-SHA256 hashes required to build a chain
132 /// of equivalent weight.
133 pub chainwork: Uint256,
136 /// Adaptor used for notifying when blocks have been connected or disconnected from the chain.
138 /// Used when needing to replay chain data upon startup or as new chain events occur.
139 pub trait ChainListener {
140 /// Notifies the listener that a block was added at the given height.
141 fn block_connected(&mut self, block: &Block, height: u32);
143 /// Notifies the listener that a block was removed at the given height.
144 fn block_disconnected(&mut self, header: &BlockHeader, height: u32);
147 /// The `Cache` trait defines behavior for managing a block header cache, where block headers are
148 /// keyed by block hash.
150 /// Used by [`ChainNotifier`] to store headers along the best chain, which is important for ensuring
151 /// that blocks can be disconnected if they are no longer accessible from a block source (e.g., if
152 /// the block source does not store stale forks indefinitely).
154 /// Implementations may define how long to retain headers such that it's unlikely they will ever be
155 /// needed to disconnect a block. In cases where block sources provide access to headers on stale
156 /// forks reliably, caches may be entirely unnecessary.
158 /// [`ChainNotifier`]: struct.ChainNotifier.html
160 /// Retrieves the block header keyed by the given block hash.
161 fn look_up(&self, block_hash: &BlockHash) -> Option<&ValidatedBlockHeader>;
163 /// Called when a block has been connected to the best chain to ensure it is available to be
164 /// disconnected later if needed.
165 fn block_connected(&mut self, block_hash: BlockHash, block_header: ValidatedBlockHeader);
167 /// Called when a block has been disconnected from the best chain. Once disconnected, a block's
168 /// header is no longer needed and thus can be removed.
169 fn block_disconnected(&mut self, block_hash: &BlockHash) -> Option<ValidatedBlockHeader>;
172 /// Unbounded cache of block headers keyed by block hash.
173 pub type UnboundedCache = std::collections::HashMap<BlockHash, ValidatedBlockHeader>;
175 impl Cache for UnboundedCache {
176 fn look_up(&self, block_hash: &BlockHash) -> Option<&ValidatedBlockHeader> {
180 fn block_connected(&mut self, block_hash: BlockHash, block_header: ValidatedBlockHeader) {
181 self.insert(block_hash, block_header);
184 fn block_disconnected(&mut self, block_hash: &BlockHash) -> Option<ValidatedBlockHeader> {
185 self.remove(block_hash)
189 /// Notifies [listeners] of blocks that have been connected or disconnected from the chain.
191 /// [listeners]: trait.ChainListener.html
192 struct ChainNotifier<C: Cache> {
193 /// Cache for looking up headers before fetching from a block source.
197 /// Changes made to the chain between subsequent polls that transformed it from having one chain tip
200 /// Blocks are given in height-descending order. Therefore, blocks are first disconnected in order
201 /// before new blocks are connected in reverse order.
202 struct ChainDifference {
203 /// Blocks that were disconnected from the chain since the last poll.
204 disconnected_blocks: Vec<ValidatedBlockHeader>,
206 /// Blocks that were connected to the chain since the last poll.
207 connected_blocks: Vec<ValidatedBlockHeader>,
210 impl<C: Cache> ChainNotifier<C> {
211 /// Finds the fork point between `new_header` and `old_header`, disconnecting blocks from
212 /// `old_header` to get to that point and then connecting blocks until `new_header`.
214 /// Validates headers along the transition path, but doesn't fetch blocks until the chain is
215 /// disconnected to the fork point. Thus, this may return an `Err` that includes where the tip
216 /// ended up which may not be `new_header`. Note that iff the returned `Err` contains `Some`
217 /// header then the transition from `old_header` to `new_header` is valid.
218 async fn sync_listener<L: ChainListener, P: Poll>(
220 new_header: ValidatedBlockHeader,
221 old_header: &ValidatedBlockHeader,
222 chain_poller: &mut P,
223 chain_listener: &mut L,
224 ) -> Result<(), (BlockSourceError, Option<ValidatedBlockHeader>)> {
225 let mut difference = self.find_difference(new_header, old_header, chain_poller).await
226 .map_err(|e| (e, None))?;
228 let mut new_tip = *old_header;
229 for header in difference.disconnected_blocks.drain(..) {
230 println!("Disconnecting block {}", header.block_hash);
231 if let Some(cached_header) = self.header_cache.block_disconnected(&header.block_hash) {
232 assert_eq!(cached_header, header);
234 chain_listener.block_disconnected(&header.header, header.height);
238 for header in difference.connected_blocks.drain(..).rev() {
239 let block = chain_poller
240 .fetch_block(&header).await
241 .or_else(|e| Err((e, Some(new_tip))))?;
242 debug_assert_eq!(block.block_hash, header.block_hash);
244 println!("Connecting block {}", header.block_hash);
245 self.header_cache.block_connected(header.block_hash, header);
246 chain_listener.block_connected(&block, header.height);
253 /// Returns the changes needed to produce the chain with `current_header` as its tip from the
254 /// chain with `prev_header` as its tip.
256 /// Walks backwards from `current_header` and `prev_header`, finding the common ancestor.
257 async fn find_difference<P: Poll>(
259 current_header: ValidatedBlockHeader,
260 prev_header: &ValidatedBlockHeader,
261 chain_poller: &mut P,
262 ) -> BlockSourceResult<ChainDifference> {
263 let mut disconnected_blocks = Vec::new();
264 let mut connected_blocks = Vec::new();
265 let mut current = current_header;
266 let mut previous = *prev_header;
268 // Found the common ancestor.
269 if current.block_hash == previous.block_hash {
273 // Walk back the chain, finding blocks needed to connect and disconnect. Only walk back
274 // the header with the greater height, or both if equal heights.
275 let current_height = current.height;
276 let previous_height = previous.height;
277 if current_height <= previous_height {
278 disconnected_blocks.push(previous);
279 previous = self.look_up_previous_header(chain_poller, &previous).await?;
281 if current_height >= previous_height {
282 connected_blocks.push(current);
283 current = self.look_up_previous_header(chain_poller, ¤t).await?;
287 Ok(ChainDifference { disconnected_blocks, connected_blocks })
290 /// Returns the previous header for the given header, either by looking it up in the cache or
291 /// fetching it if not found.
292 async fn look_up_previous_header<P: Poll>(
294 chain_poller: &mut P,
295 header: &ValidatedBlockHeader,
296 ) -> BlockSourceResult<ValidatedBlockHeader> {
297 match self.header_cache.look_up(&header.header.prev_blockhash) {
298 Some(prev_header) => Ok(*prev_header),
299 None => chain_poller.look_up_previous_header(header).await,
305 mod chain_notifier_tests {
306 use crate::test_utils::{Blockchain, MockChainListener};
309 use bitcoin::network::constants::Network;
312 async fn sync_from_same_chain() {
313 let mut chain = Blockchain::default().with_height(3);
315 let new_tip = chain.tip();
316 let old_tip = chain.at_height(1);
317 let mut listener = MockChainListener::new()
318 .expect_block_connected(*chain.at_height(2))
319 .expect_block_connected(*new_tip);
320 let mut notifier = ChainNotifier { header_cache: chain.header_cache(0..=1) };
321 let mut poller = poll::ChainPoller::new(&mut chain, Network::Testnet);
322 match notifier.sync_listener(new_tip, &old_tip, &mut poller, &mut listener).await {
323 Err((e, _)) => panic!("Unexpected error: {:?}", e),
329 async fn sync_from_different_chains() {
330 let mut test_chain = Blockchain::with_network(Network::Testnet).with_height(1);
331 let main_chain = Blockchain::with_network(Network::Bitcoin).with_height(1);
333 let new_tip = test_chain.tip();
334 let old_tip = main_chain.tip();
335 let mut listener = MockChainListener::new();
336 let mut notifier = ChainNotifier { header_cache: main_chain.header_cache(0..=1) };
337 let mut poller = poll::ChainPoller::new(&mut test_chain, Network::Testnet);
338 match notifier.sync_listener(new_tip, &old_tip, &mut poller, &mut listener).await {
340 assert_eq!(e.kind(), BlockSourceErrorKind::Persistent);
341 assert_eq!(e.into_inner().as_ref().to_string(), "genesis block reached");
343 Ok(_) => panic!("Expected error"),
348 async fn sync_from_equal_length_fork() {
349 let main_chain = Blockchain::default().with_height(2);
350 let mut fork_chain = main_chain.fork_at_height(1);
352 let new_tip = fork_chain.tip();
353 let old_tip = main_chain.tip();
354 let mut listener = MockChainListener::new()
355 .expect_block_disconnected(*old_tip)
356 .expect_block_connected(*new_tip);
357 let mut notifier = ChainNotifier { header_cache: main_chain.header_cache(0..=2) };
358 let mut poller = poll::ChainPoller::new(&mut fork_chain, Network::Testnet);
359 match notifier.sync_listener(new_tip, &old_tip, &mut poller, &mut listener).await {
360 Err((e, _)) => panic!("Unexpected error: {:?}", e),
366 async fn sync_from_shorter_fork() {
367 let main_chain = Blockchain::default().with_height(3);
368 let mut fork_chain = main_chain.fork_at_height(1);
369 fork_chain.disconnect_tip();
371 let new_tip = fork_chain.tip();
372 let old_tip = main_chain.tip();
373 let mut listener = MockChainListener::new()
374 .expect_block_disconnected(*old_tip)
375 .expect_block_disconnected(*main_chain.at_height(2))
376 .expect_block_connected(*new_tip);
377 let mut notifier = ChainNotifier { header_cache: main_chain.header_cache(0..=3) };
378 let mut poller = poll::ChainPoller::new(&mut fork_chain, Network::Testnet);
379 match notifier.sync_listener(new_tip, &old_tip, &mut poller, &mut listener).await {
380 Err((e, _)) => panic!("Unexpected error: {:?}", e),
386 async fn sync_from_longer_fork() {
387 let mut main_chain = Blockchain::default().with_height(3);
388 let mut fork_chain = main_chain.fork_at_height(1);
389 main_chain.disconnect_tip();
391 let new_tip = fork_chain.tip();
392 let old_tip = main_chain.tip();
393 let mut listener = MockChainListener::new()
394 .expect_block_disconnected(*old_tip)
395 .expect_block_connected(*fork_chain.at_height(2))
396 .expect_block_connected(*new_tip);
397 let mut notifier = ChainNotifier { header_cache: main_chain.header_cache(0..=2) };
398 let mut poller = poll::ChainPoller::new(&mut fork_chain, Network::Testnet);
399 match notifier.sync_listener(new_tip, &old_tip, &mut poller, &mut listener).await {
400 Err((e, _)) => panic!("Unexpected error: {:?}", e),
406 async fn sync_from_chain_without_headers() {
407 let mut chain = Blockchain::default().with_height(3).without_headers();
409 let new_tip = chain.tip();
410 let old_tip = chain.at_height(1);
411 let mut listener = MockChainListener::new();
412 let mut notifier = ChainNotifier { header_cache: chain.header_cache(0..=1) };
413 let mut poller = poll::ChainPoller::new(&mut chain, Network::Testnet);
414 match notifier.sync_listener(new_tip, &old_tip, &mut poller, &mut listener).await {
415 Err((_, tip)) => assert_eq!(tip, None),
416 Ok(_) => panic!("Expected error"),
421 async fn sync_from_chain_without_any_new_blocks() {
422 let mut chain = Blockchain::default().with_height(3).without_blocks(2..);
424 let new_tip = chain.tip();
425 let old_tip = chain.at_height(1);
426 let mut listener = MockChainListener::new();
427 let mut notifier = ChainNotifier { header_cache: chain.header_cache(0..=3) };
428 let mut poller = poll::ChainPoller::new(&mut chain, Network::Testnet);
429 match notifier.sync_listener(new_tip, &old_tip, &mut poller, &mut listener).await {
430 Err((_, tip)) => assert_eq!(tip, Some(old_tip)),
431 Ok(_) => panic!("Expected error"),
436 async fn sync_from_chain_without_some_new_blocks() {
437 let mut chain = Blockchain::default().with_height(3).without_blocks(3..);
439 let new_tip = chain.tip();
440 let old_tip = chain.at_height(1);
441 let mut listener = MockChainListener::new()
442 .expect_block_connected(*chain.at_height(2));
443 let mut notifier = ChainNotifier { header_cache: chain.header_cache(0..=3) };
444 let mut poller = poll::ChainPoller::new(&mut chain, Network::Testnet);
445 match notifier.sync_listener(new_tip, &old_tip, &mut poller, &mut listener).await {
446 Err((_, tip)) => assert_eq!(tip, Some(chain.at_height(2))),
447 Ok(_) => panic!("Expected error"),