blk_reader/lib.rs
1//! Fast reader for Bitcoin Core `blk*.dat` files.
2//!
3//! Reads raw block data directly from Bitcoin Core's block storage, using the
4//! LevelDB index to locate blocks by height. Automatically detects and decodes
5//! the XOR encoding introduced in Bitcoin Core 28.0.
6//!
7//! # Quick start
8//!
9//! ```no_run
10//! use blk_reader::{BlockIterator, BlkReaderConfig};
11//! use std::path::PathBuf;
12//!
13//! let config = BlkReaderConfig {
14//! blocks_dir: PathBuf::from("/home/user/.bitcoin/blocks"),
15//! index_dir: PathBuf::from("/home/user/.bitcoin/blocks/index"),
16//! start_height: 0,
17//! end_height: 100,
18//! ..Default::default()
19//! };
20//!
21//! for result in BlockIterator::new(config).unwrap() {
22//! let block = result.unwrap();
23//! println!("height={} size={} bytes", block.height, block.data.len());
24//! }
25//! ```
26//!
27//! # XOR decoding
28//!
29//! Bitcoin Core 28.0 introduced XOR encoding of `blk*.dat` files to prevent
30//! false-positive virus scanner alerts. The key is stored in `blocks/xor.dat`.
31//! This crate detects the file automatically — no configuration needed.
32//!
33//! # Reading a single block
34//!
35//! If you already know the file index and byte offset (e.g. from your own
36//! LevelDB query), use [`BlkReader`] directly:
37//!
38//! ```no_run
39//! use blk_reader::BlkReader;
40//! use std::path::PathBuf;
41//!
42//! let mut reader = BlkReader::new(
43//! PathBuf::from("/home/user/.bitcoin/blocks"),
44//! 8 * 1024 * 1024, // read buffer
45//! );
46//! // Genesis block: file 0, data offset 8
47//! let raw = reader.read_block_at(0, 8).unwrap();
48//! assert_eq!(raw.len(), 285);
49//! ```
50
51mod error;
52mod varint;
53mod index;
54mod reader;
55mod iterator;
56
57pub use error::BlkReaderError;
58pub use index::{BlockIndexEntry, IndexReader};
59pub use reader::BlkReader;
60pub use iterator::{BlkReaderConfig, BlockIterator, RawBlock};