callbacks: provide access to block headers

For some callbacks access to only the header
may be sufficient, at which point deserializing
the whole block would be wasteful. We thus
provide a new hook that gets called with the
header.

If the `on_block()` hook remains unused, the
`block` variable being deserialized should be
optimized away by the compiler.

Author: dspicher

src/callbacks/balances.rs

@@ -43,6 +43,14 @@ impl Callback for Balances {
         Ok(())
     }
 
+    fn on_header(
+        &mut self,
+        _header: &bitcoin::blockdata::block::Header,
+        _block_height: u64,
+    ) -> anyhow::Result<()> {
+        Ok(())
+    }
+
     /// For each transaction in the block
     ///   1. apply input transactions (remove (TxID == prevTxIDOut and prevOutID == spentOutID))
     ///   2. apply output transactions (add (TxID + curOutID -> HashMapVal))

src/callbacks/mod.rs

@@ -17,6 +17,13 @@ pub trait Callback {
     /// Gets called shortly before the blocks are parsed.
     fn on_start(&mut self, block_height: u64) -> anyhow::Result<()>;
 
+    /// Gets called if a new header is available.
+    fn on_header(
+        &mut self,
+        _header: &bitcoin::blockdata::block::Header,
+        _block_height: u64,
+    ) -> anyhow::Result<()>;
+
     /// Gets called if a new block is available.
     fn on_block(&mut self, block: &bitcoin::Block, block_height: u64) -> anyhow::Result<()>;
 

src/callbacks/opreturn.rs

@@ -18,6 +18,14 @@ impl Callback for OpReturn {
         Ok(())
     }
 
+    fn on_header(
+        &mut self,
+        _header: &bitcoin::blockdata::block::Header,
+        _block_height: u64,
+    ) -> anyhow::Result<()> {
+        Ok(())
+    }
+
     fn on_block(&mut self, block: &bitcoin::Block, block_height: u64) -> anyhow::Result<()> {
         for tx in &block.txdata {
             for out in &tx.output {

src/callbacks/simplestats.rs

@@ -186,6 +186,14 @@ impl Callback for SimpleStats {
         Ok(())
     }
 
+    fn on_header(
+        &mut self,
+        _header: &bitcoin::blockdata::block::Header,
+        _block_height: u64,
+    ) -> anyhow::Result<()> {
+        Ok(())
+    }
+
     fn on_block(&mut self, block: &bitcoin::Block, block_height: u64) -> anyhow::Result<()> {
         self.n_valid_blocks += 1;
         self.n_tx += block.txdata.len();

src/callbacks/unspentcsvdump.rs

@@ -45,6 +45,14 @@ impl crate::callbacks::Callback for UnspentCsvDump {
         Ok(())
     }
 
+    fn on_header(
+        &mut self,
+        _header: &bitcoin::blockdata::block::Header,
+        _block_height: u64,
+    ) -> anyhow::Result<()> {
+        Ok(())
+    }
+
     /// For each transaction in the block
     ///   1. apply input transactions (remove (TxID == prevTxIDOut and prevOutID == spentOutID))
     ///   2. apply output transactions (add (TxID + curOutID -> HashMapVal))

src/parser/blkfile.rs

@@ -41,6 +41,15 @@ impl BlkFile {
         }
     }
 
+    pub fn read_header(
+        &mut self,
+        offset: u64,
+    ) -> anyhow::Result<bitcoin::blockdata::block::Header> {
+        let reader = self.open()?;
+        reader.seek(SeekFrom::Start(offset))?;
+        reader.read_header()
+    }
+
     pub fn read_block(&mut self, offset: u64) -> anyhow::Result<bitcoin::Block> {
         let reader = self.open()?;
         reader.seek(SeekFrom::Start(offset))?;

src/parser/chain.rs

@@ -21,6 +21,21 @@ impl ChainStorage {
         })
     }
 
+    /// Returns the header of a given height.
+    #[must_use]
+    pub fn get_header(&mut self, height: u64) -> Option<bitcoin::blockdata::block::Header> {
+        // Read block
+        let block_meta = self.chain_index.get(height)?;
+        let blk_file = self.blk_files.get_mut(&block_meta.blk_index)?;
+        let header = blk_file.read_header(block_meta.data_offset).ok()?;
+
+        // Check if blk file can be closed
+        if height == self.chain_index.max_height_by_blk(block_meta.blk_index) {
+            blk_file.close();
+        }
+        Some(header)
+    }
+
     /// Returns the block of a given height.
     #[must_use]
     pub fn get_block(&mut self, height: u64) -> Option<bitcoin::Block> {

src/parser/mod.rs

@@ -53,7 +53,9 @@ impl BlockchainParser {
         tracing::debug!(target: "parser", "Starting worker ...");
 
         self.on_start(self.cur_height)?;
-        while let Some(block) = self.chain_storage.get_block(self.cur_height) {
+        while let Some(header) = self.chain_storage.get_header(self.cur_height) {
+            self.on_header(&header, self.cur_height)?;
+            let block = self.chain_storage.get_block(self.cur_height).unwrap();
             self.on_block(&block, self.cur_height)?;
             self.cur_height += 1;
         }
@@ -79,6 +81,17 @@ impl BlockchainParser {
         Ok(())
     }
 
+    /// Triggers the on_block() callback and updates statistics.
+    fn on_header(
+        &mut self,
+        header: &bitcoin::blockdata::block::Header,
+        height: u64,
+    ) -> anyhow::Result<()> {
+        self.callback.on_header(header, height)?;
+        tracing::trace!(target: "parser", "on_header(height={}) called", height);
+        Ok(())
+    }
+
     /// Triggers the on_block() callback and updates statistics.
     fn on_block(&mut self, block: &bitcoin::Block, height: u64) -> anyhow::Result<()> {
         self.callback.on_block(block, height)?;

src/parser/reader.rs

@@ -6,6 +6,11 @@ pub trait BlockchainRead: std::io::Read {
     fn read_block(&mut self) -> anyhow::Result<bitcoin::Block> {
         Ok(bitcoin::Block::consensus_decode(self).unwrap())
     }
+
+    /// Reads a block as specified here: https://en.bitcoin.it/wiki/Protocol_specification#block
+    fn read_header(&mut self) -> anyhow::Result<bitcoin::blockdata::block::Header> {
+        Ok(bitcoin::blockdata::block::Header::consensus_decode(self).unwrap())
+    }
 }
 
 /// All types that implement `Read` get methods defined in `BlockchainRead`

tests/bitcoin.rs

@@ -79,6 +79,16 @@ fn test_bitcoin_genesis() {
     assert_eq!(0x0000_0000, genesis.txdata[0].lock_time.to_consensus_u32());
 }
 
+#[test]
+fn test_genesis_header() {
+    let header = STORAGE.lock().unwrap().get_header(0).unwrap();
+    assert_eq!(
+        header,
+        bitcoin::blockdata::constants::genesis_block(bitcoin::network::constants::Network::Bitcoin)
+            .header
+    );
+}
+
 #[test]
 fn test_blockdata_parsing() {
     for height in 0..=169 {
@@ -97,3 +107,10 @@ fn test_blockdata_parsing() {
         40 * bitcoin::Amount::ONE_BTC.to_sat()
     );
 }
+
+#[test]
+fn test_timing() {
+    for height in 0..=169 {
+        STORAGE.lock().unwrap().get_header(height).unwrap();
+    }
+}