//! A lightweight client for keeping in sync with chain activity.
//!
+//! Defines an [`SpvClient`] utility for polling one or more block sources for the best chain tip.
+//! It is used to notify listeners of blocks connected or disconnected since the last poll. Useful
+//! for keeping a Lightning node in sync with the chain.
+//!
//! Defines a [`BlockSource`] trait, which is an asynchronous interface for retrieving block headers
//! and data.
//!
//! Both features support either blocking I/O using `std::net::TcpStream` or, with feature `tokio`,
//! non-blocking I/O using `tokio::net::TcpStream` from inside a Tokio runtime.
//!
+//! [`SpvClient`]: struct.SpvClient.html
//! [`BlockSource`]: trait.BlockSource.html
#[cfg(any(feature = "rest-client", feature = "rpc-client"))]
#[cfg(any(feature = "rest-client", feature = "rpc-client"))]
mod utils;
+use crate::poll::{ChainTip, Poll, ValidatedBlockHeader};
+
use bitcoin::blockdata::block::{Block, BlockHeader};
use bitcoin::hash_types::BlockHash;
use bitcoin::util::uint::Uint256;
/// error.
fn get_block<'a>(&'a mut self, header_hash: &'a BlockHash) -> AsyncBlockSourceResult<'a, Block>;
- // TODO: Phrase in terms of `Poll` once added.
- /// Returns the hash of the best block and, optionally, its height. When polling a block source,
- /// the height is passed to `get_header` to allow for a more efficient lookup.
+ /// Returns the hash of the best block and, optionally, its height.
+ ///
+ /// When polling a block source, [`Poll`] implementations may pass the height to [`get_header`]
+ /// to allow for a more efficient lookup.
+ ///
+ /// [`Poll`]: poll/trait.Poll.html
+ /// [`get_header`]: #tymethod.get_header
fn get_best_block<'a>(&'a mut self) -> AsyncBlockSourceResult<(BlockHash, Option<u32>)>;
}
/// of equivalent weight.
pub chainwork: Uint256,
}
+
+/// A lightweight client for keeping a listener in sync with the chain, allowing for Simplified
+/// Payment Verification (SPV).
+///
+/// The client is parameterized by a chain poller which is responsible for polling one or more block
+/// sources for the best chain tip. During this process it detects any chain forks, determines which
+/// constitutes the best chain, and updates the listener accordingly with any blocks that were
+/// connected or disconnected since the last poll.
+///
+/// Block headers for the best chain are maintained in the parameterized cache, allowing for a
+/// custom cache eviction policy. This offers flexibility to those sensitive to resource usage.
+/// Hence, there is a trade-off between a lower memory footprint and potentially increased network
+/// I/O as headers are re-fetched during fork detection.
+pub struct SpvClient<P: Poll, C: Cache, L: ChainListener> {
+ chain_tip: ValidatedBlockHeader,
+ chain_poller: P,
+ chain_notifier: ChainNotifier<C>,
+ chain_listener: L,
+}
+
+/// Adaptor used for notifying when blocks have been connected or disconnected from the chain.
+///
+/// Used when needing to replay chain data upon startup or as new chain events occur.
+pub trait ChainListener {
+ /// Notifies the listener that a block was added at the given height.
+ fn block_connected(&mut self, block: &Block, height: u32);
+
+ /// Notifies the listener that a block was removed at the given height.
+ fn block_disconnected(&mut self, header: &BlockHeader, height: u32);
+}
+
+/// The `Cache` trait defines behavior for managing a block header cache, where block headers are
+/// keyed by block hash.
+///
+/// Used by [`ChainNotifier`] to store headers along the best chain, which is important for ensuring
+/// that blocks can be disconnected if they are no longer accessible from a block source (e.g., if
+/// the block source does not store stale forks indefinitely).
+///
+/// Implementations may define how long to retain headers such that it's unlikely they will ever be
+/// needed to disconnect a block. In cases where block sources provide access to headers on stale
+/// forks reliably, caches may be entirely unnecessary.
+///
+/// [`ChainNotifier`]: struct.ChainNotifier.html
+pub trait Cache {
+ /// Retrieves the block header keyed by the given block hash.
+ fn look_up(&self, block_hash: &BlockHash) -> Option<&ValidatedBlockHeader>;
+
+ /// Called when a block has been connected to the best chain to ensure it is available to be
+ /// disconnected later if needed.
+ fn block_connected(&mut self, block_hash: BlockHash, block_header: ValidatedBlockHeader);
+
+ /// Called when a block has been disconnected from the best chain. Once disconnected, a block's
+ /// header is no longer needed and thus can be removed.
+ fn block_disconnected(&mut self, block_hash: &BlockHash) -> Option<ValidatedBlockHeader>;
+}
+
+/// Unbounded cache of block headers keyed by block hash.
+pub type UnboundedCache = std::collections::HashMap<BlockHash, ValidatedBlockHeader>;
+
+impl Cache for UnboundedCache {
+ fn look_up(&self, block_hash: &BlockHash) -> Option<&ValidatedBlockHeader> {
+ self.get(block_hash)
+ }
+
+ fn block_connected(&mut self, block_hash: BlockHash, block_header: ValidatedBlockHeader) {
+ self.insert(block_hash, block_header);
+ }
+
+ fn block_disconnected(&mut self, block_hash: &BlockHash) -> Option<ValidatedBlockHeader> {
+ self.remove(block_hash)
+ }
+}
+
+impl<P: Poll, C: Cache, L: ChainListener> SpvClient<P, C, L> {
+ /// Creates a new SPV client using `chain_tip` as the best known chain tip.
+ ///
+ /// Subsequent calls to [`poll_best_tip`] will poll for the best chain tip using the given chain
+ /// poller, which may be configured with one or more block sources to query. At least one block
+ /// source must provide headers back from the best chain tip to its common ancestor with
+ /// `chain_tip`.
+ /// * `header_cache` is used to look up and store headers on the best chain
+ /// * `chain_listener` is notified of any blocks connected or disconnected
+ ///
+ /// [`poll_best_tip`]: struct.SpvClient.html#method.poll_best_tip
+ pub fn new(
+ chain_tip: ValidatedBlockHeader,
+ chain_poller: P,
+ header_cache: C,
+ chain_listener: L,
+ ) -> Self {
+ let chain_notifier = ChainNotifier { header_cache };
+ Self { chain_tip, chain_poller, chain_notifier, chain_listener }
+ }
+
+ /// Polls for the best tip and updates the chain listener with any connected or disconnected
+ /// blocks accordingly.
+ ///
+ /// Returns the best polled chain tip relative to the previous best known tip and whether any
+ /// blocks were indeed connected or disconnected.
+ pub async fn poll_best_tip(&mut self) -> BlockSourceResult<(ChainTip, bool)> {
+ let chain_tip = self.chain_poller.poll_chain_tip(self.chain_tip).await?;
+ let blocks_connected = match chain_tip {
+ ChainTip::Common => false,
+ ChainTip::Better(chain_tip) => {
+ debug_assert_ne!(chain_tip.block_hash, self.chain_tip.block_hash);
+ debug_assert!(chain_tip.chainwork > self.chain_tip.chainwork);
+ self.update_chain_tip(chain_tip).await
+ },
+ ChainTip::Worse(chain_tip) => {
+ debug_assert_ne!(chain_tip.block_hash, self.chain_tip.block_hash);
+ debug_assert!(chain_tip.chainwork <= self.chain_tip.chainwork);
+ false
+ },
+ };
+ Ok((chain_tip, blocks_connected))
+ }
+
+ /// Updates the chain tip, syncing the chain listener with any connected or disconnected
+ /// blocks. Returns whether there were any such blocks.
+ async fn update_chain_tip(&mut self, best_chain_tip: ValidatedBlockHeader) -> bool {
+ match self.chain_notifier.synchronize_listener(
+ best_chain_tip, &self.chain_tip, &mut self.chain_poller, &mut self.chain_listener).await
+ {
+ Ok(_) => {
+ self.chain_tip = best_chain_tip;
+ true
+ },
+ Err((_, Some(chain_tip))) if chain_tip.block_hash != self.chain_tip.block_hash => {
+ self.chain_tip = chain_tip;
+ true
+ },
+ Err(_) => false,
+ }
+ }
+}
+
+/// Notifies [listeners] of blocks that have been connected or disconnected from the chain.
+///
+/// [listeners]: trait.ChainListener.html
+struct ChainNotifier<C: Cache> {
+ /// Cache for looking up headers before fetching from a block source.
+ header_cache: C,
+}
+
+/// Changes made to the chain between subsequent polls that transformed it from having one chain tip
+/// to another.
+///
+/// Blocks are given in height-descending order. Therefore, blocks are first disconnected in order
+/// before new blocks are connected in reverse order.
+struct ChainDifference {
+ /// Blocks that were disconnected from the chain since the last poll.
+ disconnected_blocks: Vec<ValidatedBlockHeader>,
+
+ /// Blocks that were connected to the chain since the last poll.
+ connected_blocks: Vec<ValidatedBlockHeader>,
+}
+
+impl<C: Cache> ChainNotifier<C> {
+ /// Finds the fork point between `new_header` and `old_header`, disconnecting blocks from
+ /// `old_header` to get to that point and then connecting blocks until `new_header`.
+ ///
+ /// Validates headers along the transition path, but doesn't fetch blocks until the chain is
+ /// disconnected to the fork point. Thus, this may return an `Err` that includes where the tip
+ /// ended up which may not be `new_header`. Note that the returned `Err` contains `Some` header
+ /// if and only if the transition from `old_header` to `new_header` is valid.
+ async fn synchronize_listener<L: ChainListener, P: Poll>(
+ &mut self,
+ new_header: ValidatedBlockHeader,
+ old_header: &ValidatedBlockHeader,
+ chain_poller: &mut P,
+ chain_listener: &mut L,
+ ) -> Result<(), (BlockSourceError, Option<ValidatedBlockHeader>)> {
+ let mut difference = self.find_difference(new_header, old_header, chain_poller).await
+ .map_err(|e| (e, None))?;
+
+ let mut new_tip = *old_header;
+ for header in difference.disconnected_blocks.drain(..) {
+ if let Some(cached_header) = self.header_cache.block_disconnected(&header.block_hash) {
+ assert_eq!(cached_header, header);
+ }
+ chain_listener.block_disconnected(&header.header, header.height);
+ new_tip = header;
+ }
+
+ for header in difference.connected_blocks.drain(..).rev() {
+ let block = chain_poller
+ .fetch_block(&header).await
+ .or_else(|e| Err((e, Some(new_tip))))?;
+ debug_assert_eq!(block.block_hash, header.block_hash);
+
+ self.header_cache.block_connected(header.block_hash, header);
+ chain_listener.block_connected(&block, header.height);
+ new_tip = header;
+ }
+
+ Ok(())
+ }
+
+ /// Returns the changes needed to produce the chain with `current_header` as its tip from the
+ /// chain with `prev_header` as its tip.
+ ///
+ /// Walks backwards from `current_header` and `prev_header`, finding the common ancestor.
+ async fn find_difference<P: Poll>(
+ &self,
+ current_header: ValidatedBlockHeader,
+ prev_header: &ValidatedBlockHeader,
+ chain_poller: &mut P,
+ ) -> BlockSourceResult<ChainDifference> {
+ let mut disconnected_blocks = Vec::new();
+ let mut connected_blocks = Vec::new();
+ let mut current = current_header;
+ let mut previous = *prev_header;
+ loop {
+ // Found the common ancestor.
+ if current.block_hash == previous.block_hash {
+ break;
+ }
+
+ // Walk back the chain, finding blocks needed to connect and disconnect. Only walk back
+ // the header with the greater height, or both if equal heights.
+ let current_height = current.height;
+ let previous_height = previous.height;
+ if current_height <= previous_height {
+ disconnected_blocks.push(previous);
+ previous = self.look_up_previous_header(chain_poller, &previous).await?;
+ }
+ if current_height >= previous_height {
+ connected_blocks.push(current);
+ current = self.look_up_previous_header(chain_poller, ¤t).await?;
+ }
+ }
+
+ Ok(ChainDifference { disconnected_blocks, connected_blocks })
+ }
+
+ /// Returns the previous header for the given header, either by looking it up in the cache or
+ /// fetching it if not found.
+ async fn look_up_previous_header<P: Poll>(
+ &self,
+ chain_poller: &mut P,
+ header: &ValidatedBlockHeader,
+ ) -> BlockSourceResult<ValidatedBlockHeader> {
+ match self.header_cache.look_up(&header.header.prev_blockhash) {
+ Some(prev_header) => Ok(*prev_header),
+ None => chain_poller.look_up_previous_header(header).await,
+ }
+ }
+}
+
+#[cfg(test)]
+mod spv_client_tests {
+ use crate::test_utils::{Blockchain, NullChainListener};
+ use super::*;
+
+ use bitcoin::network::constants::Network;
+
+ #[tokio::test]
+ async fn poll_from_chain_without_headers() {
+ let mut chain = Blockchain::default().with_height(3).without_headers();
+ let best_tip = chain.at_height(1);
+
+ let poller = poll::ChainPoller::new(&mut chain, Network::Testnet);
+ let cache = UnboundedCache::new();
+ let mut client = SpvClient::new(best_tip, poller, cache, NullChainListener {});
+ match client.poll_best_tip().await {
+ Err(e) => {
+ assert_eq!(e.kind(), BlockSourceErrorKind::Persistent);
+ assert_eq!(e.into_inner().as_ref().to_string(), "header not found");
+ },
+ Ok(_) => panic!("Expected error"),
+ }
+ assert_eq!(client.chain_tip, best_tip);
+ }
+
+ #[tokio::test]
+ async fn poll_from_chain_with_common_tip() {
+ let mut chain = Blockchain::default().with_height(3);
+ let common_tip = chain.tip();
+
+ let poller = poll::ChainPoller::new(&mut chain, Network::Testnet);
+ let cache = UnboundedCache::new();
+ let mut client = SpvClient::new(common_tip, poller, cache, NullChainListener {});
+ match client.poll_best_tip().await {
+ Err(e) => panic!("Unexpected error: {:?}", e),
+ Ok((chain_tip, blocks_connected)) => {
+ assert_eq!(chain_tip, ChainTip::Common);
+ assert!(!blocks_connected);
+ },
+ }
+ assert_eq!(client.chain_tip, common_tip);
+ }
+
+ #[tokio::test]
+ async fn poll_from_chain_with_better_tip() {
+ let mut chain = Blockchain::default().with_height(3);
+ let new_tip = chain.tip();
+ let old_tip = chain.at_height(1);
+
+ let poller = poll::ChainPoller::new(&mut chain, Network::Testnet);
+ let cache = UnboundedCache::new();
+ let mut client = SpvClient::new(old_tip, poller, cache, NullChainListener {});
+ match client.poll_best_tip().await {
+ Err(e) => panic!("Unexpected error: {:?}", e),
+ Ok((chain_tip, blocks_connected)) => {
+ assert_eq!(chain_tip, ChainTip::Better(new_tip));
+ assert!(blocks_connected);
+ },
+ }
+ assert_eq!(client.chain_tip, new_tip);
+ }
+
+ #[tokio::test]
+ async fn poll_from_chain_with_better_tip_and_without_any_new_blocks() {
+ let mut chain = Blockchain::default().with_height(3).without_blocks(2..);
+ let new_tip = chain.tip();
+ let old_tip = chain.at_height(1);
+
+ let poller = poll::ChainPoller::new(&mut chain, Network::Testnet);
+ let cache = UnboundedCache::new();
+ let mut client = SpvClient::new(old_tip, poller, cache, NullChainListener {});
+ match client.poll_best_tip().await {
+ Err(e) => panic!("Unexpected error: {:?}", e),
+ Ok((chain_tip, blocks_connected)) => {
+ assert_eq!(chain_tip, ChainTip::Better(new_tip));
+ assert!(!blocks_connected);
+ },
+ }
+ assert_eq!(client.chain_tip, old_tip);
+ }
+
+ #[tokio::test]
+ async fn poll_from_chain_with_better_tip_and_without_some_new_blocks() {
+ let mut chain = Blockchain::default().with_height(3).without_blocks(3..);
+ let new_tip = chain.tip();
+ let old_tip = chain.at_height(1);
+
+ let poller = poll::ChainPoller::new(&mut chain, Network::Testnet);
+ let cache = UnboundedCache::new();
+ let mut client = SpvClient::new(old_tip, poller, cache, NullChainListener {});
+ match client.poll_best_tip().await {
+ Err(e) => panic!("Unexpected error: {:?}", e),
+ Ok((chain_tip, blocks_connected)) => {
+ assert_eq!(chain_tip, ChainTip::Better(new_tip));
+ assert!(blocks_connected);
+ },
+ }
+ assert_eq!(client.chain_tip, chain.at_height(2));
+ }
+
+ #[tokio::test]
+ async fn poll_from_chain_with_worse_tip() {
+ let mut chain = Blockchain::default().with_height(3);
+ let best_tip = chain.tip();
+ chain.disconnect_tip();
+ let worse_tip = chain.tip();
+
+ let poller = poll::ChainPoller::new(&mut chain, Network::Testnet);
+ let cache = UnboundedCache::new();
+ let mut client = SpvClient::new(best_tip, poller, cache, NullChainListener {});
+ match client.poll_best_tip().await {
+ Err(e) => panic!("Unexpected error: {:?}", e),
+ Ok((chain_tip, blocks_connected)) => {
+ assert_eq!(chain_tip, ChainTip::Worse(worse_tip));
+ assert!(!blocks_connected);
+ },
+ }
+ assert_eq!(client.chain_tip, best_tip);
+ }
+}
+
+#[cfg(test)]
+mod chain_notifier_tests {
+ use crate::test_utils::{Blockchain, MockChainListener};
+ use super::*;
+
+ use bitcoin::network::constants::Network;
+
+ #[tokio::test]
+ async fn sync_from_same_chain() {
+ let mut chain = Blockchain::default().with_height(3);
+
+ let new_tip = chain.tip();
+ let old_tip = chain.at_height(1);
+ let mut listener = MockChainListener::new()
+ .expect_block_connected(*chain.at_height(2))
+ .expect_block_connected(*new_tip);
+ let mut notifier = ChainNotifier { header_cache: chain.header_cache(0..=1) };
+ let mut poller = poll::ChainPoller::new(&mut chain, Network::Testnet);
+ match notifier.synchronize_listener(new_tip, &old_tip, &mut poller, &mut listener).await {
+ Err((e, _)) => panic!("Unexpected error: {:?}", e),
+ Ok(_) => {},
+ }
+ }
+
+ #[tokio::test]
+ async fn sync_from_different_chains() {
+ let mut test_chain = Blockchain::with_network(Network::Testnet).with_height(1);
+ let main_chain = Blockchain::with_network(Network::Bitcoin).with_height(1);
+
+ let new_tip = test_chain.tip();
+ let old_tip = main_chain.tip();
+ let mut listener = MockChainListener::new();
+ let mut notifier = ChainNotifier { header_cache: main_chain.header_cache(0..=1) };
+ let mut poller = poll::ChainPoller::new(&mut test_chain, Network::Testnet);
+ match notifier.synchronize_listener(new_tip, &old_tip, &mut poller, &mut listener).await {
+ Err((e, _)) => {
+ assert_eq!(e.kind(), BlockSourceErrorKind::Persistent);
+ assert_eq!(e.into_inner().as_ref().to_string(), "genesis block reached");
+ },
+ Ok(_) => panic!("Expected error"),
+ }
+ }
+
+ #[tokio::test]
+ async fn sync_from_equal_length_fork() {
+ let main_chain = Blockchain::default().with_height(2);
+ let mut fork_chain = main_chain.fork_at_height(1);
+
+ let new_tip = fork_chain.tip();
+ let old_tip = main_chain.tip();
+ let mut listener = MockChainListener::new()
+ .expect_block_disconnected(*old_tip)
+ .expect_block_connected(*new_tip);
+ let mut notifier = ChainNotifier { header_cache: main_chain.header_cache(0..=2) };
+ let mut poller = poll::ChainPoller::new(&mut fork_chain, Network::Testnet);
+ match notifier.synchronize_listener(new_tip, &old_tip, &mut poller, &mut listener).await {
+ Err((e, _)) => panic!("Unexpected error: {:?}", e),
+ Ok(_) => {},
+ }
+ }
+
+ #[tokio::test]
+ async fn sync_from_shorter_fork() {
+ let main_chain = Blockchain::default().with_height(3);
+ let mut fork_chain = main_chain.fork_at_height(1);
+ fork_chain.disconnect_tip();
+
+ let new_tip = fork_chain.tip();
+ let old_tip = main_chain.tip();
+ let mut listener = MockChainListener::new()
+ .expect_block_disconnected(*old_tip)
+ .expect_block_disconnected(*main_chain.at_height(2))
+ .expect_block_connected(*new_tip);
+ let mut notifier = ChainNotifier { header_cache: main_chain.header_cache(0..=3) };
+ let mut poller = poll::ChainPoller::new(&mut fork_chain, Network::Testnet);
+ match notifier.synchronize_listener(new_tip, &old_tip, &mut poller, &mut listener).await {
+ Err((e, _)) => panic!("Unexpected error: {:?}", e),
+ Ok(_) => {},
+ }
+ }
+
+ #[tokio::test]
+ async fn sync_from_longer_fork() {
+ let mut main_chain = Blockchain::default().with_height(3);
+ let mut fork_chain = main_chain.fork_at_height(1);
+ main_chain.disconnect_tip();
+
+ let new_tip = fork_chain.tip();
+ let old_tip = main_chain.tip();
+ let mut listener = MockChainListener::new()
+ .expect_block_disconnected(*old_tip)
+ .expect_block_connected(*fork_chain.at_height(2))
+ .expect_block_connected(*new_tip);
+ let mut notifier = ChainNotifier { header_cache: main_chain.header_cache(0..=2) };
+ let mut poller = poll::ChainPoller::new(&mut fork_chain, Network::Testnet);
+ match notifier.synchronize_listener(new_tip, &old_tip, &mut poller, &mut listener).await {
+ Err((e, _)) => panic!("Unexpected error: {:?}", e),
+ Ok(_) => {},
+ }
+ }
+
+ #[tokio::test]
+ async fn sync_from_chain_without_headers() {
+ let mut chain = Blockchain::default().with_height(3).without_headers();
+
+ let new_tip = chain.tip();
+ let old_tip = chain.at_height(1);
+ let mut listener = MockChainListener::new();
+ let mut notifier = ChainNotifier { header_cache: chain.header_cache(0..=1) };
+ let mut poller = poll::ChainPoller::new(&mut chain, Network::Testnet);
+ match notifier.synchronize_listener(new_tip, &old_tip, &mut poller, &mut listener).await {
+ Err((_, tip)) => assert_eq!(tip, None),
+ Ok(_) => panic!("Expected error"),
+ }
+ }
+
+ #[tokio::test]
+ async fn sync_from_chain_without_any_new_blocks() {
+ let mut chain = Blockchain::default().with_height(3).without_blocks(2..);
+
+ let new_tip = chain.tip();
+ let old_tip = chain.at_height(1);
+ let mut listener = MockChainListener::new();
+ let mut notifier = ChainNotifier { header_cache: chain.header_cache(0..=3) };
+ let mut poller = poll::ChainPoller::new(&mut chain, Network::Testnet);
+ match notifier.synchronize_listener(new_tip, &old_tip, &mut poller, &mut listener).await {
+ Err((_, tip)) => assert_eq!(tip, Some(old_tip)),
+ Ok(_) => panic!("Expected error"),
+ }
+ }
+
+ #[tokio::test]
+ async fn sync_from_chain_without_some_new_blocks() {
+ let mut chain = Blockchain::default().with_height(3).without_blocks(3..);
+
+ let new_tip = chain.tip();
+ let old_tip = chain.at_height(1);
+ let mut listener = MockChainListener::new()
+ .expect_block_connected(*chain.at_height(2));
+ let mut notifier = ChainNotifier { header_cache: chain.header_cache(0..=3) };
+ let mut poller = poll::ChainPoller::new(&mut chain, Network::Testnet);
+ match notifier.synchronize_listener(new_tip, &old_tip, &mut poller, &mut listener).await {
+ Err((_, tip)) => assert_eq!(tip, Some(chain.at_height(2))),
+ Ok(_) => panic!("Expected error"),
+ }
+ }
+}
projects / rust-lightning / blobdiff