1 use crate::{AsyncBlockSourceResult, BlockHeaderData, BlockSource, BlockSourceError, BlockSourceResult};
3 use bitcoin::blockdata::block::Block;
4 use bitcoin::hash_types::BlockHash;
5 use bitcoin::network::constants::Network;
7 use std::ops::DerefMut;
9 /// The `Poll` trait defines behavior for polling block sources for a chain tip and retrieving
10 /// related chain data. It serves as an adapter for `BlockSource`.
12 /// [`ChainPoller`] adapts a single `BlockSource`, while any other implementations of `Poll` are
13 /// required to be built in terms of it to ensure chain data validity.
15 /// [`ChainPoller`]: ../struct.ChainPoller.html
17 /// Returns a chain tip in terms of its relationship to the provided chain tip.
18 fn poll_chain_tip<'a>(&'a mut self, best_known_chain_tip: ValidatedBlockHeader) ->
19 AsyncBlockSourceResult<'a, ChainTip>;
21 /// Returns the header that preceded the given header in the chain.
22 fn look_up_previous_header<'a>(&'a mut self, header: &'a ValidatedBlockHeader) ->
23 AsyncBlockSourceResult<'a, ValidatedBlockHeader>;
25 /// Returns the block associated with the given header.
26 fn fetch_block<'a>(&'a mut self, header: &'a ValidatedBlockHeader) ->
27 AsyncBlockSourceResult<'a, ValidatedBlock>;
30 /// A chain tip relative to another chain tip in terms of block hash and chainwork.
31 #[derive(Clone, Debug, PartialEq)]
33 /// A chain tip with the same hash as another chain's tip.
36 /// A chain tip with more chainwork than another chain's tip.
37 Better(ValidatedBlockHeader),
39 /// A chain tip with less or equal chainwork than another chain's tip. In either case, the
40 /// hashes of each tip will be different.
41 Worse(ValidatedBlockHeader),
44 /// The `Validate` trait defines behavior for validating chain data.
45 pub(crate) trait Validate {
46 /// The validated data wrapper which can be dereferenced to obtain the validated data.
47 type T: std::ops::Deref<Target = Self>;
49 /// Validates the chain data against the given block hash and any criteria needed to ensure that
50 /// it is internally consistent.
51 fn validate(self, block_hash: BlockHash) -> BlockSourceResult<Self::T>;
54 impl Validate for BlockHeaderData {
55 type T = ValidatedBlockHeader;
57 fn validate(self, block_hash: BlockHash) -> BlockSourceResult<Self::T> {
59 .validate_pow(&self.header.target())
60 .or_else(|e| Err(BlockSourceError::persistent(e)))?;
62 // TODO: Use the result of validate_pow instead of recomputing the block hash once upstream.
63 if self.header.block_hash() != block_hash {
64 return Err(BlockSourceError::persistent("invalid block hash"));
67 Ok(ValidatedBlockHeader { block_hash, inner: self })
71 impl Validate for Block {
72 type T = ValidatedBlock;
74 fn validate(self, block_hash: BlockHash) -> BlockSourceResult<Self::T> {
76 .validate_pow(&self.header.target())
77 .or_else(|e| Err(BlockSourceError::persistent(e)))?;
79 // TODO: Use the result of validate_pow instead of recomputing the block hash once upstream.
80 if self.block_hash() != block_hash {
81 return Err(BlockSourceError::persistent("invalid block hash"));
84 if !self.check_merkle_root() {
85 return Err(BlockSourceError::persistent("invalid merkle root"));
88 if !self.check_witness_commitment() {
89 return Err(BlockSourceError::persistent("invalid witness commitment"));
92 Ok(ValidatedBlock { block_hash, inner: self })
96 /// A block header with validated proof of work and corresponding block hash.
97 #[derive(Clone, Copy, Debug, PartialEq)]
98 pub struct ValidatedBlockHeader {
99 pub(crate) block_hash: BlockHash,
100 inner: BlockHeaderData,
103 impl std::ops::Deref for ValidatedBlockHeader {
104 type Target = BlockHeaderData;
106 fn deref(&self) -> &Self::Target {
111 impl ValidatedBlockHeader {
112 /// Checks that the header correctly builds on previous_header: the claimed work differential
113 /// matches the actual PoW and the difficulty transition is possible, i.e., within 4x.
114 fn check_builds_on(&self, previous_header: &ValidatedBlockHeader, network: Network) -> BlockSourceResult<()> {
115 if self.header.prev_blockhash != previous_header.block_hash {
116 return Err(BlockSourceError::persistent("invalid previous block hash"));
119 if self.height != previous_header.height + 1 {
120 return Err(BlockSourceError::persistent("invalid block height"));
123 let work = self.header.work();
124 if self.chainwork != previous_header.chainwork + work {
125 return Err(BlockSourceError::persistent("invalid chainwork"));
128 if let Network::Bitcoin = network {
129 if self.height % 2016 == 0 {
130 let previous_work = previous_header.header.work();
131 if work > (previous_work << 2) || work < (previous_work >> 2) {
132 return Err(BlockSourceError::persistent("invalid difficulty transition"))
134 } else if self.header.bits != previous_header.header.bits {
135 return Err(BlockSourceError::persistent("invalid difficulty"))
143 /// A block with validated data against its transaction list and corresponding block hash.
144 pub struct ValidatedBlock {
145 pub(crate) block_hash: BlockHash,
149 impl std::ops::Deref for ValidatedBlock {
152 fn deref(&self) -> &Self::Target {
157 /// The canonical `Poll` implementation used for a single `BlockSource`.
159 /// Other `Poll` implementations must be built using `ChainPoller` as it provides the only means of
160 /// validating chain data.
161 pub struct ChainPoller<B: DerefMut<Target=T> + Sized + Sync + Send, T: BlockSource> {
166 impl<B: DerefMut<Target=T> + Sized + Sync + Send, T: BlockSource> ChainPoller<B, T> {
167 /// Creates a new poller for the given block source.
169 /// If the `network` parameter is mainnet, then the difficulty between blocks is checked for
171 pub fn new(block_source: B, network: Network) -> Self {
172 Self { block_source, network }
176 impl<B: DerefMut<Target=T> + Sized + Sync + Send, T: BlockSource> Poll for ChainPoller<B, T> {
177 fn poll_chain_tip<'a>(&'a mut self, best_known_chain_tip: ValidatedBlockHeader) ->
178 AsyncBlockSourceResult<'a, ChainTip>
180 Box::pin(async move {
181 let (block_hash, height) = self.block_source.get_best_block().await?;
182 if block_hash == best_known_chain_tip.header.block_hash() {
183 return Ok(ChainTip::Common);
186 let chain_tip = self.block_source
187 .get_header(&block_hash, height).await?
188 .validate(block_hash)?;
189 if chain_tip.chainwork > best_known_chain_tip.chainwork {
190 Ok(ChainTip::Better(chain_tip))
192 Ok(ChainTip::Worse(chain_tip))
197 fn look_up_previous_header<'a>(&'a mut self, header: &'a ValidatedBlockHeader) ->
198 AsyncBlockSourceResult<'a, ValidatedBlockHeader>
200 Box::pin(async move {
201 if header.height == 0 {
202 return Err(BlockSourceError::persistent("genesis block reached"));
205 let previous_hash = &header.header.prev_blockhash;
206 let height = header.height - 1;
207 let previous_header = self.block_source
208 .get_header(previous_hash, Some(height)).await?
209 .validate(*previous_hash)?;
210 header.check_builds_on(&previous_header, self.network)?;
216 fn fetch_block<'a>(&'a mut self, header: &'a ValidatedBlockHeader) ->
217 AsyncBlockSourceResult<'a, ValidatedBlock>
219 Box::pin(async move {
221 .get_block(&header.block_hash).await?
222 .validate(header.block_hash)
230 use crate::test_utils::Blockchain;
232 use bitcoin::util::uint::Uint256;
235 async fn poll_empty_chain() {
236 let mut chain = Blockchain::default().with_height(0);
237 let best_known_chain_tip = chain.tip();
238 chain.disconnect_tip();
240 let mut poller = ChainPoller::new(&mut chain, Network::Bitcoin);
241 match poller.poll_chain_tip(best_known_chain_tip).await {
243 assert_eq!(e.kind(), BlockSourceErrorKind::Transient);
244 assert_eq!(e.into_inner().as_ref().to_string(), "empty chain");
246 Ok(_) => panic!("Expected error"),
251 async fn poll_chain_without_headers() {
252 let mut chain = Blockchain::default().with_height(1).without_headers();
253 let best_known_chain_tip = chain.at_height(0);
255 let mut poller = ChainPoller::new(&mut chain, Network::Bitcoin);
256 match poller.poll_chain_tip(best_known_chain_tip).await {
258 assert_eq!(e.kind(), BlockSourceErrorKind::Persistent);
259 assert_eq!(e.into_inner().as_ref().to_string(), "header not found");
261 Ok(_) => panic!("Expected error"),
266 async fn poll_chain_with_invalid_pow() {
267 let mut chain = Blockchain::default().with_height(1);
268 let best_known_chain_tip = chain.at_height(0);
270 // Invalidate the tip by changing its target.
271 chain.blocks.last_mut().unwrap().header.bits =
272 BlockHeader::compact_target_from_u256(&Uint256::from_be_bytes([0; 32]));
274 let mut poller = ChainPoller::new(&mut chain, Network::Bitcoin);
275 match poller.poll_chain_tip(best_known_chain_tip).await {
277 assert_eq!(e.kind(), BlockSourceErrorKind::Persistent);
278 assert_eq!(e.into_inner().as_ref().to_string(), "block target correct but not attained");
280 Ok(_) => panic!("Expected error"),
285 async fn poll_chain_with_malformed_headers() {
286 let mut chain = Blockchain::default().with_height(1).malformed_headers();
287 let best_known_chain_tip = chain.at_height(0);
289 let mut poller = ChainPoller::new(&mut chain, Network::Bitcoin);
290 match poller.poll_chain_tip(best_known_chain_tip).await {
292 assert_eq!(e.kind(), BlockSourceErrorKind::Persistent);
293 assert_eq!(e.into_inner().as_ref().to_string(), "invalid block hash");
295 Ok(_) => panic!("Expected error"),
300 async fn poll_chain_with_common_tip() {
301 let mut chain = Blockchain::default().with_height(0);
302 let best_known_chain_tip = chain.tip();
304 let mut poller = ChainPoller::new(&mut chain, Network::Bitcoin);
305 match poller.poll_chain_tip(best_known_chain_tip).await {
306 Err(e) => panic!("Unexpected error: {:?}", e),
307 Ok(tip) => assert_eq!(tip, ChainTip::Common),
312 async fn poll_chain_with_uncommon_tip_but_equal_chainwork() {
313 let mut chain = Blockchain::default().with_height(1);
314 let best_known_chain_tip = chain.tip();
316 // Change the nonce to get a different block hash with the same chainwork.
317 chain.blocks.last_mut().unwrap().header.nonce += 1;
318 let worse_chain_tip = chain.tip();
319 assert_eq!(best_known_chain_tip.chainwork, worse_chain_tip.chainwork);
321 let mut poller = ChainPoller::new(&mut chain, Network::Bitcoin);
322 match poller.poll_chain_tip(best_known_chain_tip).await {
323 Err(e) => panic!("Unexpected error: {:?}", e),
324 Ok(tip) => assert_eq!(tip, ChainTip::Worse(worse_chain_tip)),
329 async fn poll_chain_with_worse_tip() {
330 let mut chain = Blockchain::default().with_height(1);
331 let best_known_chain_tip = chain.tip();
333 chain.disconnect_tip();
334 let worse_chain_tip = chain.tip();
336 let mut poller = ChainPoller::new(&mut chain, Network::Bitcoin);
337 match poller.poll_chain_tip(best_known_chain_tip).await {
338 Err(e) => panic!("Unexpected error: {:?}", e),
339 Ok(tip) => assert_eq!(tip, ChainTip::Worse(worse_chain_tip)),
344 async fn poll_chain_with_better_tip() {
345 let mut chain = Blockchain::default().with_height(1);
346 let best_known_chain_tip = chain.at_height(0);
348 let better_chain_tip = chain.tip();
350 let mut poller = ChainPoller::new(&mut chain, Network::Bitcoin);
351 match poller.poll_chain_tip(best_known_chain_tip).await {
352 Err(e) => panic!("Unexpected error: {:?}", e),
353 Ok(tip) => assert_eq!(tip, ChainTip::Better(better_chain_tip)),