blockchain_zc_parser/
lib.rs

1//! # blockchain-zc-parser
2//!
3//! A **zero-copy**, allocation-free parser for Bitcoin blockchain binary data.
4//!
5//! ## Design goals
6//!
7//! | Goal | How |
8//! |------|-----|
9//! | **Zero-copy** | All parsed structures borrow `&'a [u8]` from the input — no `memcpy`. |
10//! | **No alloc** | Compatible with `#![no_std]` — no heap allocations required. |
11//! | **Streaming** | [`block::BlockTxIter`] and [`transaction::TransactionParser`] parse lazily via callbacks. |
12//! | **Safe** | `unsafe` only for pointer-arithmetic inside [`cursor`] after bounds checks. |
13//! | **Fast** | A single block header parse requires only ~10 integer reads from a contiguous buffer. |
14//!
15//! ## Supported formats
16//!
17//! - Bitcoin block headers (80 bytes)
18//! - Legacy and SegWit (BIP 141) transactions
19//! - Bitcoin script (`scriptPubKey` / `scriptSig`), including pattern matching for
20//!   P2PKH, P2SH, P2WPKH, P2WSH, P2TR, P2PK, OP_RETURN
21//! - Raw block files (`blkNNNNN.dat`) written by Bitcoin Core
22//!
23//! ## Quick start
24//!
25//! ```rust
26//! use blockchain_zc_parser::{
27//!     block::BlockHeader,
28//!     cursor::Cursor,
29//! };
30//!
31//! // Any &[u8] — memory-mapped file, network buffer, test fixture, …
32//! let raw: &[u8] = &[0u8; 80]; // placeholder
33//! let mut cursor = Cursor::new(raw);
34//! // let header = BlockHeader::parse(&mut cursor)?;
35//! ```
36//!
37//! ## Safety
38//!
39//! The crate contains a small amount of `unsafe` code inside [`cursor`].
40//! Every `unsafe` block is immediately preceded by a comment explaining the
41//! invariant that makes it sound.  The invariant is always a prior bounds-
42//! check performed by safe Rust code.
43
44#![cfg_attr(not(feature = "std"), no_std)]
45#![warn(missing_docs)]
46#![warn(clippy::undocumented_unsafe_blocks)]
47#![deny(clippy::panic)]
48
49pub mod block;
50pub mod cursor;
51pub mod error;
52pub mod hash;
53pub mod script;
54pub mod transaction;
55
56// Re-export the most commonly used types at the crate root.
57pub use block::{BlkFileIter, BlockHeader, BlockTxIter};
58pub use cursor::Cursor;
59pub use error::{ParseError, ParseResult};
60pub use hash::{Hash20, Hash32};
61pub use script::{Instruction, Instructions, Script, ScriptType};
62pub use transaction::{OutPoint, TransactionParser, TxInput, TxOutput};
blockchain_zc_parser/lib.rs

blockchain_zc_parser/
lib.rs
