//!
//! 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
+
+// Prefix these with `rustdoc::` when we update our MSRV to be >= 1.52 to remove warnings.
+#![deny(broken_intra_doc_links)]
+#![deny(private_intra_doc_links)]
+
+#![deny(missing_docs)]
+#![deny(unsafe_code)]
+
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
#[cfg(any(feature = "rest-client", feature = "rpc-client"))]
pub mod http;
+pub mod init;
pub mod poll;
#[cfg(feature = "rest-client")]
use bitcoin::hash_types::BlockHash;
use bitcoin::util::uint::Uint256;
+use lightning::chain;
+use lightning::chain::Listen;
+
use std::future::Future;
+use std::ops::Deref;
use std::pin::Pin;
/// Abstract type for retrieving block headers and data.
///
/// Implementations that cannot find headers based on the hash should return a `Transient` error
/// when `height_hint` is `None`.
- fn get_header<'a>(&'a mut self, header_hash: &'a BlockHash, height_hint: Option<u32>) -> AsyncBlockSourceResult<'a, BlockHeaderData>;
+ fn get_header<'a>(&'a self, header_hash: &'a BlockHash, height_hint: Option<u32>) -> AsyncBlockSourceResult<'a, BlockHeaderData>;
/// Returns the block for a given hash. A headers-only block source should return a `Transient`
/// error.
- fn get_block<'a>(&'a mut self, header_hash: &'a BlockHash) -> AsyncBlockSourceResult<'a, Block>;
+ fn get_block<'a>(&'a self, header_hash: &'a BlockHash) -> AsyncBlockSourceResult<'a, BlockData>;
/// 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>)>;
+ /// [`get_header`]: Self::get_header
+ fn get_best_block<'a>(&'a self) -> AsyncBlockSourceResult<(BlockHash, Option<u32>)>;
}
/// Result type for `BlockSource` requests.
-type BlockSourceResult<T> = Result<T, BlockSourceError>;
+pub type BlockSourceResult<T> = Result<T, BlockSourceError>;
// TODO: Replace with BlockSourceResult once `async` trait functions are supported. For details,
// see: https://areweasyncyet.rs.
/// Result type for asynchronous `BlockSource` requests.
-type AsyncBlockSourceResult<'a, T> = Pin<Box<dyn Future<Output = BlockSourceResult<T>> + 'a + Send>>;
+pub type AsyncBlockSourceResult<'a, T> = Pin<Box<dyn Future<Output = BlockSourceResult<T>> + 'a + Send>>;
/// Error type for `BlockSource` requests.
///
}
/// The kind of `BlockSourceError`, either persistent or transient.
-#[derive(Clone, Copy, Debug, PartialEq)]
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum BlockSourceErrorKind {
/// Indicates an error that won't resolve when retrying a request (e.g., invalid data).
Persistent,
/// A block header and some associated data. This information should be available from most block
/// sources (and, notably, is available in Bitcoin Core's RPC and REST interfaces).
-#[derive(Clone, Copy, Debug, PartialEq)]
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct BlockHeaderData {
/// The block header itself.
pub header: BlockHeader,
pub chainwork: Uint256,
}
+/// A block including either all its transactions or only the block header.
+///
+/// [`BlockSource`] may be implemented to either always return full blocks or, in the case of
+/// compact block filters (BIP 157/158), return header-only blocks when no pertinent transactions
+/// match. See [`chain::Filter`] for details on how to notify a source of such transactions.
+pub enum BlockData {
+ /// A block containing all its transactions.
+ FullBlock(Block),
+ /// A block header for when the block does not contain any pertinent transactions.
+ HeaderOnly(BlockHeader),
+}
+
/// A lightweight client for keeping a listener in sync with the chain, allowing for Simplified
/// Payment Verification (SPV).
///
/// 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> {
+pub struct SpvClient<'a, P: Poll, C: Cache, L: Deref>
+where L::Target: chain::Listen {
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);
+ chain_notifier: ChainNotifier<'a, C, L>,
}
/// The `Cache` trait defines behavior for managing a block header cache, where block headers are
/// 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>;
}
}
-impl<P: Poll, C: Cache, L: ChainListener> SpvClient<P, C, L> {
+impl<'a, P: Poll, C: Cache, L: Deref> SpvClient<'a, P, C, L> where L::Target: chain::Listen {
/// 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
/// * `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
+ /// [`poll_best_tip`]: SpvClient::poll_best_tip
pub fn new(
chain_tip: ValidatedBlockHeader,
chain_poller: P,
- header_cache: C,
+ header_cache: &'a mut C,
chain_listener: L,
) -> Self {
- let chain_notifier = ChainNotifier { header_cache };
- Self { chain_tip, chain_poller, chain_notifier, chain_listener }
+ let chain_notifier = ChainNotifier { header_cache, chain_listener };
+ Self { chain_tip, chain_poller, chain_notifier }
}
/// Polls for the best tip and updates 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
+ best_chain_tip, &self.chain_tip, &mut self.chain_poller).await
{
Ok(_) => {
self.chain_tip = best_chain_tip;
/// Notifies [listeners] of blocks that have been connected or disconnected from the chain.
///
-/// [listeners]: trait.ChainListener.html
-struct ChainNotifier<C: Cache> {
+/// [listeners]: lightning::chain::Listen
+pub struct ChainNotifier<'a, C: Cache, L: Deref> where L::Target: chain::Listen {
/// Cache for looking up headers before fetching from a block source.
- header_cache: C,
+ header_cache: &'a mut C,
+
+ /// Listener that will be notified of connected or disconnected blocks.
+ chain_listener: L,
}
/// Changes made to the chain between subsequent polls that transformed it from having one chain tip
/// Blocks are given in height-descending order. Therefore, blocks are first disconnected in order
/// before new blocks are connected in reverse order.
struct ChainDifference {
+ /// The most recent ancestor common between the chain tips.
+ ///
+ /// If there are any disconnected blocks, this is where the chain forked.
+ common_ancestor: ValidatedBlockHeader,
+
/// Blocks that were disconnected from the chain since the last poll.
disconnected_blocks: Vec<ValidatedBlockHeader>,
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`.
+impl<'a, C: Cache, L: Deref> ChainNotifier<'a, C, L> where L::Target: chain::Listen {
+ /// Finds the first common ancestor 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>(
+ async fn synchronize_listener<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
+ let 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(())
+ self.disconnect_blocks(difference.disconnected_blocks);
+ self.connect_blocks(
+ difference.common_ancestor,
+ difference.connected_blocks,
+ chain_poller,
+ ).await
}
/// Returns the changes needed to produce the chain with `current_header` as its tip from the
}
}
- Ok(ChainDifference { disconnected_blocks, connected_blocks })
+ let common_ancestor = current;
+ Ok(ChainDifference { common_ancestor, disconnected_blocks, connected_blocks })
}
/// Returns the previous header for the given header, either by looking it up in the cache or
None => chain_poller.look_up_previous_header(header).await,
}
}
+
+ /// Notifies the chain listeners of disconnected blocks.
+ fn disconnect_blocks(&mut self, mut disconnected_blocks: Vec<ValidatedBlockHeader>) {
+ for header in disconnected_blocks.drain(..) {
+ if let Some(cached_header) = self.header_cache.block_disconnected(&header.block_hash) {
+ assert_eq!(cached_header, header);
+ }
+ self.chain_listener.block_disconnected(&header.header, header.height);
+ }
+ }
+
+ /// Notifies the chain listeners of connected blocks.
+ async fn connect_blocks<P: Poll>(
+ &mut self,
+ mut new_tip: ValidatedBlockHeader,
+ mut connected_blocks: Vec<ValidatedBlockHeader>,
+ chain_poller: &mut P,
+ ) -> Result<(), (BlockSourceError, Option<ValidatedBlockHeader>)> {
+ for header in connected_blocks.drain(..).rev() {
+ let height = header.height;
+ let block_data = chain_poller
+ .fetch_block(&header).await
+ .or_else(|e| Err((e, Some(new_tip))))?;
+ debug_assert_eq!(block_data.block_hash, header.block_hash);
+
+ match block_data.deref() {
+ BlockData::FullBlock(block) => {
+ self.chain_listener.block_connected(&block, height);
+ },
+ BlockData::HeaderOnly(header) => {
+ self.chain_listener.filtered_block_connected(&header, &[], height);
+ },
+ }
+
+ self.header_cache.block_connected(header.block_hash, header);
+ new_tip = header;
+ }
+
+ Ok(())
+ }
}
#[cfg(test)]
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 {});
+ let mut cache = UnboundedCache::new();
+ let mut listener = NullChainListener {};
+ let mut client = SpvClient::new(best_tip, poller, &mut cache, &mut listener);
match client.poll_best_tip().await {
Err(e) => {
assert_eq!(e.kind(), BlockSourceErrorKind::Persistent);
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 {});
+ let mut cache = UnboundedCache::new();
+ let mut listener = NullChainListener {};
+ let mut client = SpvClient::new(common_tip, poller, &mut cache, &mut listener);
match client.poll_best_tip().await {
Err(e) => panic!("Unexpected error: {:?}", e),
Ok((chain_tip, blocks_connected)) => {
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 {});
+ let mut cache = UnboundedCache::new();
+ let mut listener = NullChainListener {};
+ let mut client = SpvClient::new(old_tip, poller, &mut cache, &mut listener);
match client.poll_best_tip().await {
Err(e) => panic!("Unexpected error: {:?}", e),
Ok((chain_tip, blocks_connected)) => {
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 {});
+ let mut cache = UnboundedCache::new();
+ let mut listener = NullChainListener {};
+ let mut client = SpvClient::new(old_tip, poller, &mut cache, &mut listener);
match client.poll_best_tip().await {
Err(e) => panic!("Unexpected error: {:?}", e),
Ok((chain_tip, blocks_connected)) => {
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 {});
+ let mut cache = UnboundedCache::new();
+ let mut listener = NullChainListener {};
+ let mut client = SpvClient::new(old_tip, poller, &mut cache, &mut listener);
match client.poll_best_tip().await {
Err(e) => panic!("Unexpected error: {:?}", e),
Ok((chain_tip, blocks_connected)) => {
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 {});
+ let mut cache = UnboundedCache::new();
+ let mut listener = NullChainListener {};
+ let mut client = SpvClient::new(best_tip, poller, &mut cache, &mut listener);
match client.poll_best_tip().await {
Err(e) => panic!("Unexpected error: {:?}", e),
Ok((chain_tip, blocks_connected)) => {
let new_tip = chain.tip();
let old_tip = chain.at_height(1);
- let mut listener = MockChainListener::new()
+ let chain_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 notifier = ChainNotifier {
+ header_cache: &mut chain.header_cache(0..=1),
+ chain_listener,
+ };
let mut poller = poll::ChainPoller::new(&mut chain, Network::Testnet);
- match notifier.synchronize_listener(new_tip, &old_tip, &mut poller, &mut listener).await {
+ match notifier.synchronize_listener(new_tip, &old_tip, &mut poller).await {
Err((e, _)) => panic!("Unexpected error: {:?}", e),
Ok(_) => {},
}
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 chain_listener = &MockChainListener::new();
+ let mut notifier = ChainNotifier {
+ header_cache: &mut main_chain.header_cache(0..=1),
+ chain_listener,
+ };
let mut poller = poll::ChainPoller::new(&mut test_chain, Network::Testnet);
- match notifier.synchronize_listener(new_tip, &old_tip, &mut poller, &mut listener).await {
+ match notifier.synchronize_listener(new_tip, &old_tip, &mut poller).await {
Err((e, _)) => {
assert_eq!(e.kind(), BlockSourceErrorKind::Persistent);
assert_eq!(e.into_inner().as_ref().to_string(), "genesis block reached");
let new_tip = fork_chain.tip();
let old_tip = main_chain.tip();
- let mut listener = MockChainListener::new()
+ let chain_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 notifier = ChainNotifier {
+ header_cache: &mut main_chain.header_cache(0..=2),
+ chain_listener,
+ };
let mut poller = poll::ChainPoller::new(&mut fork_chain, Network::Testnet);
- match notifier.synchronize_listener(new_tip, &old_tip, &mut poller, &mut listener).await {
+ match notifier.synchronize_listener(new_tip, &old_tip, &mut poller).await {
Err((e, _)) => panic!("Unexpected error: {:?}", e),
Ok(_) => {},
}
let new_tip = fork_chain.tip();
let old_tip = main_chain.tip();
- let mut listener = MockChainListener::new()
+ let chain_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 notifier = ChainNotifier {
+ header_cache: &mut main_chain.header_cache(0..=3),
+ chain_listener,
+ };
let mut poller = poll::ChainPoller::new(&mut fork_chain, Network::Testnet);
- match notifier.synchronize_listener(new_tip, &old_tip, &mut poller, &mut listener).await {
+ match notifier.synchronize_listener(new_tip, &old_tip, &mut poller).await {
Err((e, _)) => panic!("Unexpected error: {:?}", e),
Ok(_) => {},
}
let new_tip = fork_chain.tip();
let old_tip = main_chain.tip();
- let mut listener = MockChainListener::new()
+ let chain_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 notifier = ChainNotifier {
+ header_cache: &mut main_chain.header_cache(0..=2),
+ chain_listener,
+ };
let mut poller = poll::ChainPoller::new(&mut fork_chain, Network::Testnet);
- match notifier.synchronize_listener(new_tip, &old_tip, &mut poller, &mut listener).await {
+ match notifier.synchronize_listener(new_tip, &old_tip, &mut poller).await {
Err((e, _)) => panic!("Unexpected error: {:?}", e),
Ok(_) => {},
}
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 chain_listener = &MockChainListener::new();
+ let mut notifier = ChainNotifier {
+ header_cache: &mut chain.header_cache(0..=1),
+ chain_listener,
+ };
let mut poller = poll::ChainPoller::new(&mut chain, Network::Testnet);
- match notifier.synchronize_listener(new_tip, &old_tip, &mut poller, &mut listener).await {
+ match notifier.synchronize_listener(new_tip, &old_tip, &mut poller).await {
Err((_, tip)) => assert_eq!(tip, None),
Ok(_) => panic!("Expected error"),
}
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 chain_listener = &MockChainListener::new();
+ let mut notifier = ChainNotifier {
+ header_cache: &mut chain.header_cache(0..=3),
+ chain_listener,
+ };
let mut poller = poll::ChainPoller::new(&mut chain, Network::Testnet);
- match notifier.synchronize_listener(new_tip, &old_tip, &mut poller, &mut listener).await {
+ match notifier.synchronize_listener(new_tip, &old_tip, &mut poller).await {
Err((_, tip)) => assert_eq!(tip, Some(old_tip)),
Ok(_) => panic!("Expected error"),
}
let new_tip = chain.tip();
let old_tip = chain.at_height(1);
- let mut listener = MockChainListener::new()
+ let chain_listener = &MockChainListener::new()
.expect_block_connected(*chain.at_height(2));
- let mut notifier = ChainNotifier { header_cache: chain.header_cache(0..=3) };
+ let mut notifier = ChainNotifier {
+ header_cache: &mut chain.header_cache(0..=3),
+ chain_listener,
+ };
let mut poller = poll::ChainPoller::new(&mut chain, Network::Testnet);
- match notifier.synchronize_listener(new_tip, &old_tip, &mut poller, &mut listener).await {
+ match notifier.synchronize_listener(new_tip, &old_tip, &mut poller).await {
Err((_, tip)) => assert_eq!(tip, Some(chain.at_height(2))),
Ok(_) => panic!("Expected error"),
}
}
+
+ #[tokio::test]
+ async fn sync_from_chain_with_filtered_blocks() {
+ let mut chain = Blockchain::default().with_height(3).filtered_blocks();
+
+ let new_tip = chain.tip();
+ let old_tip = chain.at_height(1);
+ let chain_listener = &MockChainListener::new()
+ .expect_filtered_block_connected(*chain.at_height(2))
+ .expect_filtered_block_connected(*new_tip);
+ let mut notifier = ChainNotifier {
+ header_cache: &mut chain.header_cache(0..=1),
+ chain_listener,
+ };
+ let mut poller = poll::ChainPoller::new(&mut chain, Network::Testnet);
+ match notifier.synchronize_listener(new_tip, &old_tip, &mut poller).await {
+ Err((e, _)) => panic!("Unexpected error: {:?}", e),
+ Ok(_) => {},
+ }
+ }
+
}