_ 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, BlockData, BlockHeaderData, BlockSource, BlockSourceError, BlockSourceResult};
   4
   5 use bitcoin::hash_types::BlockHash;
   6 use bitcoin::network::constants::Network;
   7 use lightning::chain::BestBlock;
   8
   9 use std::ops::Deref;
  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 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 self, header: &'a ValidatedBlockHeader) ->
  25                 AsyncBlockSourceResult<'a, ValidatedBlockHeader>;
  26
  27         /// Returns the block associated with the given header.
  28         fn fetch_block<'a>(&'a 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, Eq)]
  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 ///
  48 /// This trait is sealed and not meant to be implemented outside of this crate.
  49 pub trait Validate: sealed::Validate {
  50         /// The validated data wrapper which can be dereferenced to obtain the validated data.
  51         type T: std::ops::Deref<Target = Self>;
  52
  53         /// Validates the chain data against the given block hash and any criteria needed to ensure that
  54         /// it is internally consistent.
  55         fn validate(self, block_hash: BlockHash) -> BlockSourceResult<Self::T>;
  56 }
  57
  58 impl Validate for BlockHeaderData {
  59         type T = ValidatedBlockHeader;
  60
  61         fn validate(self, block_hash: BlockHash) -> BlockSourceResult<Self::T> {
  62                 let pow_valid_block_hash = self.header
  63                         .validate_pow(&self.header.target())
  64                         .or_else(|e| Err(BlockSourceError::persistent(e)))?;
  65
  66                 if pow_valid_block_hash != block_hash {
  67                         return Err(BlockSourceError::persistent("invalid block hash"));
  68                 }
  69
  70                 Ok(ValidatedBlockHeader { block_hash, inner: self })
  71         }
  72 }
  73
  74 impl Validate for BlockData {
  75         type T = ValidatedBlock;
  76
  77         fn validate(self, block_hash: BlockHash) -> BlockSourceResult<Self::T> {
  78                 let header = match &self {
  79                         BlockData::FullBlock(block) => &block.header,
  80                         BlockData::HeaderOnly(header) => header,
  81                 };
  82
  83                 let pow_valid_block_hash = header
  84                         .validate_pow(&header.target())
  85                         .or_else(|e| Err(BlockSourceError::persistent(e)))?;
  86
  87                 if pow_valid_block_hash != block_hash {
  88                         return Err(BlockSourceError::persistent("invalid block hash"));
  89                 }
  90
  91                 if let BlockData::FullBlock(block) = &self {
  92                         if !block.check_merkle_root() {
  93                                 return Err(BlockSourceError::persistent("invalid merkle root"));
  94                         }
  95
  96                         if !block.check_witness_commitment() {
  97                                 return Err(BlockSourceError::persistent("invalid witness commitment"));
  98                         }
  99                 }
 100
 101                 Ok(ValidatedBlock { block_hash, inner: self })
 102         }
 103 }
 104
 105 /// A block header with validated proof of work and corresponding block hash.
 106 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 107 pub struct ValidatedBlockHeader {
 108         pub(crate) block_hash: BlockHash,
 109         inner: BlockHeaderData,
 110 }
 111
 112 impl std::ops::Deref for ValidatedBlockHeader {
 113         type Target = BlockHeaderData;
 114
 115         fn deref(&self) -> &Self::Target {
 116                 &self.inner
 117         }
 118 }
 119
 120 impl ValidatedBlockHeader {
 121         /// Checks that the header correctly builds on previous_header: the claimed work differential
 122         /// matches the actual PoW and the difficulty transition is possible, i.e., within 4x.
 123         fn check_builds_on(&self, previous_header: &ValidatedBlockHeader, network: Network) -> BlockSourceResult<()> {
 124                 if self.header.prev_blockhash != previous_header.block_hash {
 125                         return Err(BlockSourceError::persistent("invalid previous block hash"));
 126                 }
 127
 128                 if self.height != previous_header.height + 1 {
 129                         return Err(BlockSourceError::persistent("invalid block height"));
 130                 }
 131
 132                 let work = self.header.work();
 133                 if self.chainwork != previous_header.chainwork + work {
 134                         return Err(BlockSourceError::persistent("invalid chainwork"));
 135                 }
 136
 137                 if let Network::Bitcoin = network {
 138                         if self.height % 2016 == 0 {
 139                                 let previous_work = previous_header.header.work();
 140                                 if work > (previous_work << 2) || work < (previous_work >> 2) {
 141                                         return Err(BlockSourceError::persistent("invalid difficulty transition"))
 142                                 }
 143                         } else if self.header.bits != previous_header.header.bits {
 144                                 return Err(BlockSourceError::persistent("invalid difficulty"))
 145                         }
 146                 }
 147
 148                 Ok(())
 149         }
 150
 151     /// Returns the [`BestBlock`] corresponding to this validated block header, which can be passed
 152     /// into [`ChannelManager::new`] as part of its [`ChainParameters`]. Useful for ensuring that
 153     /// the [`SpvClient`] and [`ChannelManager`] are initialized to the same block during a fresh
 154     /// start.
 155     ///
 156     /// [`SpvClient`]: crate::SpvClient
 157     /// [`ChainParameters`]: lightning::ln::channelmanager::ChainParameters
 158     /// [`ChannelManager`]: lightning::ln::channelmanager::ChannelManager
 159     /// [`ChannelManager::new`]: lightning::ln::channelmanager::ChannelManager::new
 160     pub fn to_best_block(&self) -> BestBlock {
 161         BestBlock::new(self.block_hash, self.inner.height)
 162     }
 163 }
 164
 165 /// A block with validated data against its transaction list and corresponding block hash.
 166 pub struct ValidatedBlock {
 167         pub(crate) block_hash: BlockHash,
 168         inner: BlockData,
 169 }
 170
 171 impl std::ops::Deref for ValidatedBlock {
 172         type Target = BlockData;
 173
 174         fn deref(&self) -> &Self::Target {
 175                 &self.inner
 176         }
 177 }
 178
 179 mod sealed {
 180         /// Used to prevent implementing [`super::Validate`] outside the crate but still allow its use.
 181         pub trait Validate {}
 182
 183         impl Validate for crate::BlockHeaderData {}
 184         impl Validate for crate::BlockData {}
 185 }
 186
 187 /// The canonical `Poll` implementation used for a single `BlockSource`.
 188 ///
 189 /// Other `Poll` implementations should be built using `ChainPoller` as it provides the simplest way
 190 /// of validating chain data and checking consistency.
 191 pub struct ChainPoller<B: Deref<Target=T> + Sized + Send + Sync, T: BlockSource + ?Sized> {
 192         block_source: B,
 193         network: Network,
 194 }
 195
 196 impl<B: Deref<Target=T> + Sized + Send + Sync, T: BlockSource + ?Sized> ChainPoller<B, T> {
 197         /// Creates a new poller for the given block source.
 198         ///
 199         /// If the `network` parameter is mainnet, then the difficulty between blocks is checked for
 200         /// validity.
 201         pub fn new(block_source: B, network: Network) -> Self {
 202                 Self { block_source, network }
 203         }
 204 }
 205
 206 impl<B: Deref<Target=T> + Sized + Send + Sync, T: BlockSource + ?Sized> Poll for ChainPoller<B, T> {
 207         fn poll_chain_tip<'a>(&'a self, best_known_chain_tip: ValidatedBlockHeader) ->
 208                 AsyncBlockSourceResult<'a, ChainTip>
 209         {
 210                 Box::pin(async move {
 211                         let (block_hash, height) = self.block_source.get_best_block().await?;
 212                         if block_hash == best_known_chain_tip.header.block_hash() {
 213                                 return Ok(ChainTip::Common);
 214                         }
 215
 216                         let chain_tip = self.block_source
 217                                 .get_header(&block_hash, height).await?
 218                                 .validate(block_hash)?;
 219                         if chain_tip.chainwork > best_known_chain_tip.chainwork {
 220                                 Ok(ChainTip::Better(chain_tip))
 221                         } else {
 222                                 Ok(ChainTip::Worse(chain_tip))
 223                         }
 224                 })
 225         }
 226
 227         fn look_up_previous_header<'a>(&'a self, header: &'a ValidatedBlockHeader) ->
 228                 AsyncBlockSourceResult<'a, ValidatedBlockHeader>
 229         {
 230                 Box::pin(async move {
 231                         if header.height == 0 {
 232                                 return Err(BlockSourceError::persistent("genesis block reached"));
 233                         }
 234
 235                         let previous_hash = &header.header.prev_blockhash;
 236                         let height = header.height - 1;
 237                         let previous_header = self.block_source
 238                                 .get_header(previous_hash, Some(height)).await?
 239                                 .validate(*previous_hash)?;
 240                         header.check_builds_on(&previous_header, self.network)?;
 241
 242                         Ok(previous_header)
 243                 })
 244         }
 245
 246         fn fetch_block<'a>(&'a self, header: &'a ValidatedBlockHeader) ->
 247                 AsyncBlockSourceResult<'a, ValidatedBlock>
 248         {
 249                 Box::pin(async move {
 250                         self.block_source
 251                                 .get_block(&header.block_hash).await?
 252                                 .validate(header.block_hash)
 253                 })
 254         }
 255 }
 256
 257 #[cfg(test)]
 258 mod tests {
 259         use crate::*;
 260         use crate::test_utils::Blockchain;
 261         use super::*;
 262         use bitcoin::util::uint::Uint256;
 263
 264         #[tokio::test]
 265         async fn poll_empty_chain() {
 266                 let mut chain = Blockchain::default().with_height(0);
 267                 let best_known_chain_tip = chain.tip();
 268                 chain.disconnect_tip();
 269
 270                 let poller = ChainPoller::new(&chain, Network::Bitcoin);
 271                 match poller.poll_chain_tip(best_known_chain_tip).await {
 272                         Err(e) => {
 273                                 assert_eq!(e.kind(), BlockSourceErrorKind::Transient);
 274                                 assert_eq!(e.into_inner().as_ref().to_string(), "empty chain");
 275                         },
 276                         Ok(_) => panic!("Expected error"),
 277                 }
 278         }
 279
 280         #[tokio::test]
 281         async fn poll_chain_without_headers() {
 282                 let chain = Blockchain::default().with_height(1).without_headers();
 283                 let best_known_chain_tip = chain.at_height(0);
 284
 285                 let poller = ChainPoller::new(&chain, Network::Bitcoin);
 286                 match poller.poll_chain_tip(best_known_chain_tip).await {
 287                         Err(e) => {
 288                                 assert_eq!(e.kind(), BlockSourceErrorKind::Persistent);
 289                                 assert_eq!(e.into_inner().as_ref().to_string(), "header not found");
 290                         },
 291                         Ok(_) => panic!("Expected error"),
 292                 }
 293         }
 294
 295         #[tokio::test]
 296         async fn poll_chain_with_invalid_pow() {
 297                 let mut chain = Blockchain::default().with_height(1);
 298                 let best_known_chain_tip = chain.at_height(0);
 299
 300                 // Invalidate the tip by changing its target.
 301                 chain.blocks.last_mut().unwrap().header.bits =
 302                         BlockHeader::compact_target_from_u256(&Uint256::from_be_bytes([0; 32]));
 303
 304                 let poller = ChainPoller::new(&chain, Network::Bitcoin);
 305                 match poller.poll_chain_tip(best_known_chain_tip).await {
 306                         Err(e) => {
 307                                 assert_eq!(e.kind(), BlockSourceErrorKind::Persistent);
 308                                 assert_eq!(e.into_inner().as_ref().to_string(), "block target correct but not attained");
 309                         },
 310                         Ok(_) => panic!("Expected error"),
 311                 }
 312         }
 313
 314         #[tokio::test]
 315         async fn poll_chain_with_malformed_headers() {
 316                 let chain = Blockchain::default().with_height(1).malformed_headers();
 317                 let best_known_chain_tip = chain.at_height(0);
 318
 319                 let poller = ChainPoller::new(&chain, Network::Bitcoin);
 320                 match poller.poll_chain_tip(best_known_chain_tip).await {
 321                         Err(e) => {
 322                                 assert_eq!(e.kind(), BlockSourceErrorKind::Persistent);
 323                                 assert_eq!(e.into_inner().as_ref().to_string(), "invalid block hash");
 324                         },
 325                         Ok(_) => panic!("Expected error"),
 326                 }
 327         }
 328
 329         #[tokio::test]
 330         async fn poll_chain_with_common_tip() {
 331                 let chain = Blockchain::default().with_height(0);
 332                 let best_known_chain_tip = chain.tip();
 333
 334                 let poller = ChainPoller::new(&chain, Network::Bitcoin);
 335                 match poller.poll_chain_tip(best_known_chain_tip).await {
 336                         Err(e) => panic!("Unexpected error: {:?}", e),
 337                         Ok(tip) => assert_eq!(tip, ChainTip::Common),
 338                 }
 339         }
 340
 341         #[tokio::test]
 342         async fn poll_chain_with_uncommon_tip_but_equal_chainwork() {
 343                 let mut chain = Blockchain::default().with_height(1);
 344                 let best_known_chain_tip = chain.tip();
 345
 346                 // Change the nonce to get a different block hash with the same chainwork.
 347                 chain.blocks.last_mut().unwrap().header.nonce += 1;
 348                 let worse_chain_tip = chain.tip();
 349                 assert_eq!(best_known_chain_tip.chainwork, worse_chain_tip.chainwork);
 350
 351                 let poller = ChainPoller::new(&chain, Network::Bitcoin);
 352                 match poller.poll_chain_tip(best_known_chain_tip).await {
 353                         Err(e) => panic!("Unexpected error: {:?}", e),
 354                         Ok(tip) => assert_eq!(tip, ChainTip::Worse(worse_chain_tip)),
 355                 }
 356         }
 357
 358         #[tokio::test]
 359         async fn poll_chain_with_worse_tip() {
 360                 let mut chain = Blockchain::default().with_height(1);
 361                 let best_known_chain_tip = chain.tip();
 362
 363                 chain.disconnect_tip();
 364                 let worse_chain_tip = chain.tip();
 365
 366                 let poller = ChainPoller::new(&chain, Network::Bitcoin);
 367                 match poller.poll_chain_tip(best_known_chain_tip).await {
 368                         Err(e) => panic!("Unexpected error: {:?}", e),
 369                         Ok(tip) => assert_eq!(tip, ChainTip::Worse(worse_chain_tip)),
 370                 }
 371         }
 372
 373         #[tokio::test]
 374         async fn poll_chain_with_better_tip() {
 375                 let chain = Blockchain::default().with_height(1);
 376                 let best_known_chain_tip = chain.at_height(0);
 377
 378                 let better_chain_tip = chain.tip();
 379
 380                 let poller = ChainPoller::new(&chain, Network::Bitcoin);
 381                 match poller.poll_chain_tip(best_known_chain_tip).await {
 382                         Err(e) => panic!("Unexpected error: {:?}", e),
 383                         Ok(tip) => assert_eq!(tip, ChainTip::Better(better_chain_tip)),
 384                 }
 385         }
 386 }