_ Git - rust-lightning/blob - lightning-block-sync/src/poll.rs

   1 //! Adapters that make one or more [`BlockSource`]s simpler to poll for new chain tip transitions.
   2
   3 use crate::{AsyncBlockSourceResult, BlockHeaderData, BlockSource, BlockSourceError, BlockSourceResult};
   4
   5 use bitcoin::blockdata::block::Block;
   6 use bitcoin::hash_types::BlockHash;
   7 use bitcoin::network::constants::Network;
   8
   9 use std::ops::DerefMut;
  10
  11 /// The `Poll` trait defines behavior for polling block sources for a chain tip and retrieving
  12 /// related chain data. It serves as an adapter for `BlockSource`.
  13 ///
  14 /// [`ChainPoller`] adapts a single `BlockSource`, while any other implementations of `Poll` are
  15 /// required to be built in terms of it to ensure chain data validity.
  16 ///
  17 /// [`ChainPoller`]: ../struct.ChainPoller.html
  18 pub trait Poll {
  19         /// Returns a chain tip in terms of its relationship to the provided chain tip.
  20         fn poll_chain_tip<'a>(&'a mut self, best_known_chain_tip: ValidatedBlockHeader) ->
  21                 AsyncBlockSourceResult<'a, ChainTip>;
  22
  23         /// Returns the header that preceded the given header in the chain.
  24         fn look_up_previous_header<'a>(&'a mut self, header: &'a ValidatedBlockHeader) ->
  25                 AsyncBlockSourceResult<'a, ValidatedBlockHeader>;
  26
  27         /// Returns the block associated with the given header.
  28         fn fetch_block<'a>(&'a mut self, header: &'a ValidatedBlockHeader) ->
  29                 AsyncBlockSourceResult<'a, ValidatedBlock>;
  30 }
  31
  32 /// A chain tip relative to another chain tip in terms of block hash and chainwork.
  33 #[derive(Clone, Debug, PartialEq)]
  34 pub enum ChainTip {
  35         /// A chain tip with the same hash as another chain's tip.
  36         Common,
  37
  38         /// A chain tip with more chainwork than another chain's tip.
  39         Better(ValidatedBlockHeader),
  40
  41         /// A chain tip with less or equal chainwork than another chain's tip. In either case, the
  42         /// hashes of each tip will be different.
  43         Worse(ValidatedBlockHeader),
  44 }
  45
  46 /// The `Validate` trait defines behavior for validating chain data.
  47 pub(crate) trait Validate {
  48         /// The validated data wrapper which can be dereferenced to obtain the validated data.
  49         type T: std::ops::Deref<Target = Self>;
  50
  51         /// Validates the chain data against the given block hash and any criteria needed to ensure that
  52         /// it is internally consistent.
  53         fn validate(self, block_hash: BlockHash) -> BlockSourceResult<Self::T>;
  54 }
  55
  56 impl Validate for BlockHeaderData {
  57         type T = ValidatedBlockHeader;
  58
  59         fn validate(self, block_hash: BlockHash) -> BlockSourceResult<Self::T> {
  60                 self.header
  61                         .validate_pow(&self.header.target())
  62                         .or_else(|e| Err(BlockSourceError::persistent(e)))?;
  63
  64                 // TODO: Use the result of validate_pow instead of recomputing the block hash once upstream.
  65                 if self.header.block_hash() != block_hash {
  66                         return Err(BlockSourceError::persistent("invalid block hash"));
  67                 }
  68
  69                 Ok(ValidatedBlockHeader { block_hash, inner: self })
  70         }
  71 }
  72
  73 impl Validate for Block {
  74         type T = ValidatedBlock;
  75
  76         fn validate(self, block_hash: BlockHash) -> BlockSourceResult<Self::T> {
  77                 self.header
  78                         .validate_pow(&self.header.target())
  79                         .or_else(|e| Err(BlockSourceError::persistent(e)))?;
  80
  81                 // TODO: Use the result of validate_pow instead of recomputing the block hash once upstream.
  82                 if self.block_hash() != block_hash {
  83                         return Err(BlockSourceError::persistent("invalid block hash"));
  84                 }
  85
  86                 if !self.check_merkle_root() {
  87                         return Err(BlockSourceError::persistent("invalid merkle root"));
  88                 }
  89
  90                 if !self.check_witness_commitment() {
  91                         return Err(BlockSourceError::persistent("invalid witness commitment"));
  92                 }
  93
  94                 Ok(ValidatedBlock { block_hash, inner: self })
  95         }
  96 }
  97
  98 /// A block header with validated proof of work and corresponding block hash.
  99 #[derive(Clone, Copy, Debug, PartialEq)]
 100 pub struct ValidatedBlockHeader {
 101         pub(crate) block_hash: BlockHash,
 102         inner: BlockHeaderData,
 103 }
 104
 105 impl std::ops::Deref for ValidatedBlockHeader {
 106         type Target = BlockHeaderData;
 107
 108         fn deref(&self) -> &Self::Target {
 109                 &self.inner
 110         }
 111 }
 112
 113 impl ValidatedBlockHeader {
 114         /// Checks that the header correctly builds on previous_header: the claimed work differential
 115         /// matches the actual PoW and the difficulty transition is possible, i.e., within 4x.
 116         fn check_builds_on(&self, previous_header: &ValidatedBlockHeader, network: Network) -> BlockSourceResult<()> {
 117                 if self.header.prev_blockhash != previous_header.block_hash {
 118                         return Err(BlockSourceError::persistent("invalid previous block hash"));
 119                 }
 120
 121                 if self.height != previous_header.height + 1 {
 122                         return Err(BlockSourceError::persistent("invalid block height"));
 123                 }
 124
 125                 let work = self.header.work();
 126                 if self.chainwork != previous_header.chainwork + work {
 127                         return Err(BlockSourceError::persistent("invalid chainwork"));
 128                 }
 129
 130                 if let Network::Bitcoin = network {
 131                         if self.height % 2016 == 0 {
 132                                 let previous_work = previous_header.header.work();
 133                                 if work > (previous_work << 2) || work < (previous_work >> 2) {
 134                                         return Err(BlockSourceError::persistent("invalid difficulty transition"))
 135                                 }
 136                         } else if self.header.bits != previous_header.header.bits {
 137                                 return Err(BlockSourceError::persistent("invalid difficulty"))
 138                         }
 139                 }
 140
 141                 Ok(())
 142         }
 143 }
 144
 145 /// A block with validated data against its transaction list and corresponding block hash.
 146 pub struct ValidatedBlock {
 147         pub(crate) block_hash: BlockHash,
 148         inner: Block,
 149 }
 150
 151 impl std::ops::Deref for ValidatedBlock {
 152         type Target = Block;
 153
 154         fn deref(&self) -> &Self::Target {
 155                 &self.inner
 156         }
 157 }
 158
 159 /// The canonical `Poll` implementation used for a single `BlockSource`.
 160 ///
 161 /// Other `Poll` implementations must be built using `ChainPoller` as it provides the only means of
 162 /// validating chain data.
 163 pub struct ChainPoller<B: DerefMut<Target=T> + Sized , T: BlockSource> {
 164         block_source: B,
 165         network: Network,
 166 }
 167
 168 impl<B: DerefMut<Target=T> + Sized , T: BlockSource> ChainPoller<B, T> {
 169         /// Creates a new poller for the given block source.
 170         ///
 171         /// If the `network` parameter is mainnet, then the difficulty between blocks is checked for
 172         /// validity.
 173         pub fn new(block_source: B, network: Network) -> Self {
 174                 Self { block_source, network }
 175         }
 176 }
 177
 178 impl<B: DerefMut<Target=T> + Sized + Send + Sync, T: BlockSource> Poll for ChainPoller<B, T> {
 179         fn poll_chain_tip<'a>(&'a mut self, best_known_chain_tip: ValidatedBlockHeader) ->
 180                 AsyncBlockSourceResult<'a, ChainTip>
 181         {
 182                 Box::pin(async move {
 183                         let (block_hash, height) = self.block_source.get_best_block().await?;
 184                         if block_hash == best_known_chain_tip.header.block_hash() {
 185                                 return Ok(ChainTip::Common);
 186                         }
 187
 188                         let chain_tip = self.block_source
 189                                 .get_header(&block_hash, height).await?
 190                                 .validate(block_hash)?;
 191                         if chain_tip.chainwork > best_known_chain_tip.chainwork {
 192                                 Ok(ChainTip::Better(chain_tip))
 193                         } else {
 194                                 Ok(ChainTip::Worse(chain_tip))
 195                         }
 196                 })
 197         }
 198
 199         fn look_up_previous_header<'a>(&'a mut self, header: &'a ValidatedBlockHeader) ->
 200                 AsyncBlockSourceResult<'a, ValidatedBlockHeader>
 201         {
 202                 Box::pin(async move {
 203                         if header.height == 0 {
 204                                 return Err(BlockSourceError::persistent("genesis block reached"));
 205                         }
 206
 207                         let previous_hash = &header.header.prev_blockhash;
 208                         let height = header.height - 1;
 209                         let previous_header = self.block_source
 210                                 .get_header(previous_hash, Some(height)).await?
 211                                 .validate(*previous_hash)?;
 212                         header.check_builds_on(&previous_header, self.network)?;
 213
 214                         Ok(previous_header)
 215                 })
 216         }
 217
 218         fn fetch_block<'a>(&'a mut self, header: &'a ValidatedBlockHeader) ->
 219                 AsyncBlockSourceResult<'a, ValidatedBlock>
 220         {
 221                 Box::pin(async move {
 222                         self.block_source
 223                                 .get_block(&header.block_hash).await?
 224                                 .validate(header.block_hash)
 225                 })
 226         }
 227 }
 228
 229 #[cfg(test)]
 230 mod tests {
 231         use crate::*;
 232         use crate::test_utils::Blockchain;
 233         use super::*;
 234         use bitcoin::util::uint::Uint256;
 235
 236         #[tokio::test]
 237         async fn poll_empty_chain() {
 238                 let mut chain = Blockchain::default().with_height(0);
 239                 let best_known_chain_tip = chain.tip();
 240                 chain.disconnect_tip();
 241
 242                 let mut poller = ChainPoller::new(&mut chain, Network::Bitcoin);
 243                 match poller.poll_chain_tip(best_known_chain_tip).await {
 244                         Err(e) => {
 245                                 assert_eq!(e.kind(), BlockSourceErrorKind::Transient);
 246                                 assert_eq!(e.into_inner().as_ref().to_string(), "empty chain");
 247                         },
 248                         Ok(_) => panic!("Expected error"),
 249                 }
 250         }
 251
 252         #[tokio::test]
 253         async fn poll_chain_without_headers() {
 254                 let mut chain = Blockchain::default().with_height(1).without_headers();
 255                 let best_known_chain_tip = chain.at_height(0);
 256
 257                 let mut poller = ChainPoller::new(&mut chain, Network::Bitcoin);
 258                 match poller.poll_chain_tip(best_known_chain_tip).await {
 259                         Err(e) => {
 260                                 assert_eq!(e.kind(), BlockSourceErrorKind::Persistent);
 261                                 assert_eq!(e.into_inner().as_ref().to_string(), "header not found");
 262                         },
 263                         Ok(_) => panic!("Expected error"),
 264                 }
 265         }
 266
 267         #[tokio::test]
 268         async fn poll_chain_with_invalid_pow() {
 269                 let mut chain = Blockchain::default().with_height(1);
 270                 let best_known_chain_tip = chain.at_height(0);
 271
 272                 // Invalidate the tip by changing its target.
 273                 chain.blocks.last_mut().unwrap().header.bits =
 274                         BlockHeader::compact_target_from_u256(&Uint256::from_be_bytes([0; 32]));
 275
 276                 let mut poller = ChainPoller::new(&mut chain, Network::Bitcoin);
 277                 match poller.poll_chain_tip(best_known_chain_tip).await {
 278                         Err(e) => {
 279                                 assert_eq!(e.kind(), BlockSourceErrorKind::Persistent);
 280                                 assert_eq!(e.into_inner().as_ref().to_string(), "block target correct but not attained");
 281                         },
 282                         Ok(_) => panic!("Expected error"),
 283                 }
 284         }
 285
 286         #[tokio::test]
 287         async fn poll_chain_with_malformed_headers() {
 288                 let mut chain = Blockchain::default().with_height(1).malformed_headers();
 289                 let best_known_chain_tip = chain.at_height(0);
 290
 291                 let mut poller = ChainPoller::new(&mut chain, Network::Bitcoin);
 292                 match poller.poll_chain_tip(best_known_chain_tip).await {
 293                         Err(e) => {
 294                                 assert_eq!(e.kind(), BlockSourceErrorKind::Persistent);
 295                                 assert_eq!(e.into_inner().as_ref().to_string(), "invalid block hash");
 296                         },
 297                         Ok(_) => panic!("Expected error"),
 298                 }
 299         }
 300
 301         #[tokio::test]
 302         async fn poll_chain_with_common_tip() {
 303                 let mut chain = Blockchain::default().with_height(0);
 304                 let best_known_chain_tip = chain.tip();
 305
 306                 let mut poller = ChainPoller::new(&mut chain, Network::Bitcoin);
 307                 match poller.poll_chain_tip(best_known_chain_tip).await {
 308                         Err(e) => panic!("Unexpected error: {:?}", e),
 309                         Ok(tip) => assert_eq!(tip, ChainTip::Common),
 310                 }
 311         }
 312
 313         #[tokio::test]
 314         async fn poll_chain_with_uncommon_tip_but_equal_chainwork() {
 315                 let mut chain = Blockchain::default().with_height(1);
 316                 let best_known_chain_tip = chain.tip();
 317
 318                 // Change the nonce to get a different block hash with the same chainwork.
 319                 chain.blocks.last_mut().unwrap().header.nonce += 1;
 320                 let worse_chain_tip = chain.tip();
 321                 assert_eq!(best_known_chain_tip.chainwork, worse_chain_tip.chainwork);
 322
 323                 let mut poller = ChainPoller::new(&mut chain, Network::Bitcoin);
 324                 match poller.poll_chain_tip(best_known_chain_tip).await {
 325                         Err(e) => panic!("Unexpected error: {:?}", e),
 326                         Ok(tip) => assert_eq!(tip, ChainTip::Worse(worse_chain_tip)),
 327                 }
 328         }
 329
 330         #[tokio::test]
 331         async fn poll_chain_with_worse_tip() {
 332                 let mut chain = Blockchain::default().with_height(1);
 333                 let best_known_chain_tip = chain.tip();
 334
 335                 chain.disconnect_tip();
 336                 let worse_chain_tip = chain.tip();
 337
 338                 let mut poller = ChainPoller::new(&mut chain, Network::Bitcoin);
 339                 match poller.poll_chain_tip(best_known_chain_tip).await {
 340                         Err(e) => panic!("Unexpected error: {:?}", e),
 341                         Ok(tip) => assert_eq!(tip, ChainTip::Worse(worse_chain_tip)),
 342                 }
 343         }
 344
 345         #[tokio::test]
 346         async fn poll_chain_with_better_tip() {
 347                 let mut chain = Blockchain::default().with_height(1);
 348                 let best_known_chain_tip = chain.at_height(0);
 349
 350                 let better_chain_tip = chain.tip();
 351
 352                 let mut poller = ChainPoller::new(&mut chain, Network::Bitcoin);
 353                 match poller.poll_chain_tip(best_known_chain_tip).await {
 354                         Err(e) => panic!("Unexpected error: {:?}", e),
 355                         Ok(tip) => assert_eq!(tip, ChainTip::Better(better_chain_tip)),
 356                 }
 357         }
 358 }