|
| 1 | +//! Compact block filters sync over RPC, see also [BIP157][0]. |
| 2 | +//! |
| 3 | +//! This module is home to [`FilterIter`], a structure that returns bitcoin blocks by matching |
| 4 | +//! a list of script pubkeys against a [BIP158][1] [`BlockFilter`]. |
| 5 | +//! |
| 6 | +//! [0]: https://github.com/bitcoin/bips/blob/master/bip-0157.mediawiki |
| 7 | +//! [1]: https://github.com/bitcoin/bips/blob/master/bip-0158.mediawiki |
| 8 | +
|
| 9 | +use bdk_core::collections::BTreeMap; |
| 10 | +use core::fmt; |
| 11 | + |
| 12 | +use bdk_core::bitcoin; |
| 13 | +use bdk_core::{BlockId, CheckPoint}; |
| 14 | +use bitcoin::{ |
| 15 | + bip158::{self, BlockFilter}, |
| 16 | + Block, BlockHash, ScriptBuf, |
| 17 | +}; |
| 18 | +use bitcoincore_rpc; |
| 19 | +use bitcoincore_rpc::RpcApi; |
| 20 | + |
| 21 | +/// Block height |
| 22 | +type Height = u32; |
| 23 | + |
| 24 | +/// Type that generates block [`Event`]s by matching a list of script pubkeys against a |
| 25 | +/// [`BlockFilter`]. |
| 26 | +#[derive(Debug)] |
| 27 | +pub struct FilterIter<'c, C> { |
| 28 | + // RPC client |
| 29 | + client: &'c C, |
| 30 | + // SPK inventory |
| 31 | + spks: Vec<ScriptBuf>, |
| 32 | + // local cp |
| 33 | + cp: Option<CheckPoint>, |
| 34 | + // blocks map |
| 35 | + blocks: BTreeMap<Height, BlockHash>, |
| 36 | + // next filter |
| 37 | + next_filter: Option<NextFilter>, |
| 38 | + // best height counter |
| 39 | + height: Height, |
| 40 | + // stop height |
| 41 | + stop: Height, |
| 42 | +} |
| 43 | + |
| 44 | +impl<'c, C: RpcApi> FilterIter<'c, C> { |
| 45 | + /// Construct [`FilterIter`] from a given `client` and start `height`. |
| 46 | + pub fn new_with_height(client: &'c C, height: u32) -> Self { |
| 47 | + Self { |
| 48 | + client, |
| 49 | + spks: vec![], |
| 50 | + cp: None, |
| 51 | + blocks: BTreeMap::new(), |
| 52 | + next_filter: None, |
| 53 | + height, |
| 54 | + stop: 0, |
| 55 | + } |
| 56 | + } |
| 57 | + |
| 58 | + /// Construct [`FilterIter`] from a given `client` and [`CheckPoint`]. |
| 59 | + pub fn new_with_checkpoint(client: &'c C, cp: CheckPoint) -> Self { |
| 60 | + let mut filter_iter = Self::new_with_height(client, cp.height()); |
| 61 | + filter_iter.cp = Some(cp); |
| 62 | + filter_iter |
| 63 | + } |
| 64 | + |
| 65 | + /// Extends `self` with an iterator of spks. |
| 66 | + pub fn add_spks(&mut self, spks: impl IntoIterator<Item = ScriptBuf>) { |
| 67 | + self.spks.extend(spks) |
| 68 | + } |
| 69 | + |
| 70 | + /// Add spk to the list of spks to scan with. |
| 71 | + pub fn add_spk(&mut self, spk: ScriptBuf) { |
| 72 | + self.spks.push(spk); |
| 73 | + } |
| 74 | + |
| 75 | + /// Get the next filter and increment the current best height. |
| 76 | + /// |
| 77 | + /// Returns `Ok(None)` when the stop height is exceeded. |
| 78 | + fn next_filter(&mut self) -> Result<Option<NextFilter>, Error> { |
| 79 | + if self.height > self.stop { |
| 80 | + return Ok(None); |
| 81 | + } |
| 82 | + let height = self.height; |
| 83 | + let hash = match self.blocks.get(&height) { |
| 84 | + Some(h) => *h, |
| 85 | + None => self.client.get_block_hash(height as u64)?, |
| 86 | + }; |
| 87 | + let filter_bytes = self.client.get_block_filter(&hash)?.filter; |
| 88 | + let filter = BlockFilter::new(&filter_bytes); |
| 89 | + self.height += 1; |
| 90 | + Ok(Some((BlockId { height, hash }, filter))) |
| 91 | + } |
| 92 | + |
| 93 | + /// Get the remote tip. |
| 94 | + /// |
| 95 | + /// Returns `None` if there's no difference between the height of this [`FilterIter`] and the |
| 96 | + /// remote height. |
| 97 | + pub fn get_tip(&mut self) -> Result<Option<BlockId>, Error> { |
| 98 | + let tip_hash = self.client.get_best_block_hash()?; |
| 99 | + let mut header = self.client.get_block_header_info(&tip_hash)?; |
| 100 | + let tip_height = header.height as u32; |
| 101 | + if self.height == tip_height { |
| 102 | + // nothing to do |
| 103 | + return Ok(None); |
| 104 | + } |
| 105 | + self.blocks.insert(tip_height, tip_hash); |
| 106 | + |
| 107 | + // if we have a checkpoint we use a lookback of ten blocks |
| 108 | + // to ensure consistency of the local chain |
| 109 | + if let Some(cp) = self.cp.as_ref() { |
| 110 | + // adjust start height to point of agreement + 1 |
| 111 | + let base = self.find_base_with(cp.clone())?; |
| 112 | + self.height = base.height + 1; |
| 113 | + |
| 114 | + for _ in 0..9 { |
| 115 | + let hash = match header.previous_block_hash { |
| 116 | + Some(hash) => hash, |
| 117 | + None => break, |
| 118 | + }; |
| 119 | + header = self.client.get_block_header_info(&hash)?; |
| 120 | + let height = header.height as u32; |
| 121 | + if height < self.height { |
| 122 | + break; |
| 123 | + } |
| 124 | + self.blocks.insert(height, hash); |
| 125 | + } |
| 126 | + } |
| 127 | + |
| 128 | + self.stop = tip_height; |
| 129 | + |
| 130 | + // get the first filter |
| 131 | + self.next_filter = self.next_filter()?; |
| 132 | + |
| 133 | + Ok(Some(BlockId { |
| 134 | + height: tip_height, |
| 135 | + hash: self.blocks[&tip_height], |
| 136 | + })) |
| 137 | + } |
| 138 | +} |
| 139 | + |
| 140 | +/// Alias for a compact filter and associated block id. |
| 141 | +type NextFilter = (BlockId, BlockFilter); |
| 142 | + |
| 143 | +/// Event inner type |
| 144 | +#[derive(Debug, Clone)] |
| 145 | +pub struct EventInner { |
| 146 | + /// Height |
| 147 | + pub height: Height, |
| 148 | + /// Block |
| 149 | + pub block: Block, |
| 150 | +} |
| 151 | + |
| 152 | +/// Kind of event produced by [`FilterIter`]. |
| 153 | +#[derive(Debug, Clone)] |
| 154 | +pub enum Event { |
| 155 | + /// Block |
| 156 | + Block(EventInner), |
| 157 | + /// No match |
| 158 | + NoMatch(Height), |
| 159 | +} |
| 160 | + |
| 161 | +impl Event { |
| 162 | + /// Whether this event contains a matching block. |
| 163 | + pub fn is_match(&self) -> bool { |
| 164 | + matches!(self, Event::Block(_)) |
| 165 | + } |
| 166 | + |
| 167 | + /// Get the height of this event. |
| 168 | + pub fn height(&self) -> Height { |
| 169 | + match self { |
| 170 | + Self::Block(EventInner { height, .. }) => *height, |
| 171 | + Self::NoMatch(h) => *h, |
| 172 | + } |
| 173 | + } |
| 174 | +} |
| 175 | + |
| 176 | +impl<'c, C: RpcApi> Iterator for FilterIter<'c, C> { |
| 177 | + type Item = Result<Event, Error>; |
| 178 | + |
| 179 | + fn next(&mut self) -> Option<Self::Item> { |
| 180 | + let (block, filter) = self.next_filter.clone()?; |
| 181 | + |
| 182 | + (|| -> Result<_, Error> { |
| 183 | + // if the next filter matches any of our watched spks, get the block |
| 184 | + // and return it, inserting relevant block ids along the way |
| 185 | + let height = block.height; |
| 186 | + let hash = block.hash; |
| 187 | + |
| 188 | + let result = if self.spks.is_empty() { |
| 189 | + Err(Error::NoScripts) |
| 190 | + } else if filter |
| 191 | + .match_any(&hash, self.spks.iter().map(|script| script.as_bytes())) |
| 192 | + .map_err(Error::Bip158)? |
| 193 | + { |
| 194 | + let block = self.client.get_block(&hash)?; |
| 195 | + self.blocks.insert(height, hash); |
| 196 | + let inner = EventInner { height, block }; |
| 197 | + Ok(Some(Event::Block(inner))) |
| 198 | + } else { |
| 199 | + Ok(Some(Event::NoMatch(height))) |
| 200 | + }; |
| 201 | + |
| 202 | + self.next_filter = self.next_filter()?; |
| 203 | + |
| 204 | + result |
| 205 | + })() |
| 206 | + .transpose() |
| 207 | + } |
| 208 | +} |
| 209 | + |
| 210 | +impl<'c, C: RpcApi> FilterIter<'c, C> { |
| 211 | + /// Returns the point of agreement between `self` and the given `cp`. |
| 212 | + fn find_base_with(&mut self, mut cp: CheckPoint) -> Result<BlockId, Error> { |
| 213 | + loop { |
| 214 | + let height = cp.height(); |
| 215 | + let fetched_hash = match self.blocks.get(&height) { |
| 216 | + Some(hash) => *hash, |
| 217 | + None if height == 0 => cp.hash(), |
| 218 | + _ => self.client.get_block_hash(height as _)?, |
| 219 | + }; |
| 220 | + if cp.hash() == fetched_hash { |
| 221 | + // ensure this block also exists in self |
| 222 | + self.blocks.insert(height, cp.hash()); |
| 223 | + return Ok(cp.block_id()); |
| 224 | + } |
| 225 | + // remember conflicts |
| 226 | + self.blocks.insert(height, fetched_hash); |
| 227 | + cp = cp.prev().expect("must break before genesis"); |
| 228 | + } |
| 229 | + } |
| 230 | + |
| 231 | + /// Returns a chain update from the newly scanned blocks. |
| 232 | + /// |
| 233 | + /// Returns `None` if this [`FilterIter`] was not constructed using a [`CheckPoint`], or |
| 234 | + /// if no blocks have been fetched for example by using [`get_tip`](Self::get_tip). |
| 235 | + pub fn chain_update(&mut self) -> Option<CheckPoint> { |
| 236 | + if self.cp.is_none() || self.blocks.is_empty() { |
| 237 | + return None; |
| 238 | + } |
| 239 | + |
| 240 | + // note: to connect with the local chain we must guarantee that `self.blocks.first()` |
| 241 | + // is also the point of agreement with `self.cp`. |
| 242 | + Some( |
| 243 | + CheckPoint::from_block_ids(self.blocks.iter().map(BlockId::from)) |
| 244 | + .expect("blocks must be in order"), |
| 245 | + ) |
| 246 | + } |
| 247 | +} |
| 248 | + |
| 249 | +/// Errors that may occur during a compact filters sync. |
| 250 | +#[derive(Debug)] |
| 251 | +pub enum Error { |
| 252 | + /// bitcoin bip158 error |
| 253 | + Bip158(bip158::Error), |
| 254 | + /// attempted to scan blocks without any script pubkeys |
| 255 | + NoScripts, |
| 256 | + /// bitcoincore_rpc error |
| 257 | + Rpc(bitcoincore_rpc::Error), |
| 258 | +} |
| 259 | + |
| 260 | +impl From<bitcoincore_rpc::Error> for Error { |
| 261 | + fn from(e: bitcoincore_rpc::Error) -> Self { |
| 262 | + Self::Rpc(e) |
| 263 | + } |
| 264 | +} |
| 265 | + |
| 266 | +impl fmt::Display for Error { |
| 267 | + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
| 268 | + match self { |
| 269 | + Self::Bip158(e) => e.fmt(f), |
| 270 | + Self::NoScripts => write!(f, "no script pubkeys were provided to match with"), |
| 271 | + Self::Rpc(e) => e.fmt(f), |
| 272 | + } |
| 273 | + } |
| 274 | +} |
| 275 | + |
| 276 | +#[cfg(feature = "std")] |
| 277 | +impl std::error::Error for Error {} |
0 commit comments