Expand description
§brk_structs
Bitcoin-aware type system and zero-copy data structures for blockchain analysis.
§Overview
This crate provides a comprehensive type system for Bitcoin blockchain analysis, featuring zero-copy data structures, memory-efficient storage types, and Bitcoin-specific primitives. Built on zerocopy and vecdb, it offers type-safe representations for blockchain data with optimized serialization and database integration.
Key Features:
- Zero-copy data structures with
zerocopyderives for high-performance serialization - Bitcoin-specific types for heights, timestamps, addresses, and transaction data
- OHLC (Open, High, Low, Close) price data structures for financial analysis
- Comprehensive address type classification (P2PK, P2PKH, P2SH, P2WPKH, P2WSH, P2TR, etc.)
- Time-based indexing types (Date, DateIndex, WeekIndex, MonthIndex, etc.)
- Memory allocation tracking with
allocativeintegration - Stored primitive wrappers for space-efficient database storage
Target Use Cases:
- Bitcoin blockchain analysis and research tools
- Financial data processing and OHLC calculations
- Database-backed blockchain indexing systems
- Memory-efficient UTXO set management
§Installation
cargo add brk_structs§Quick Start
use brk_structs::*;
// Bitcoin-specific types
let height = Height::new(800000);
let timestamp = Timestamp::from(1684771200u32);
let date = Date::from(timestamp);
let sats = Sats::new(100_000_000); // 1 BTC in satoshis
// Price data structures
let price_cents = Cents::from(Dollars::from(50000.0));
let ohlc = OHLCCents::from((
Open::new(price_cents),
High::new(price_cents * 1.02),
Low::new(price_cents * 0.98),
Close::new(price_cents * 1.01),
));
// Address classification
let output_type = OutputType::P2PKH;
println!("Is spendable: {}", output_type.is_spendable());
println!("Has address: {}", output_type.is_address());
// Time indexing
let date_index = DateIndex::try_from(date)?;
let week_index = WeekIndex::from(date);§API Overview
§Core Bitcoin Types
Height: Block height with overflow-safe arithmetic operationsTimestamp: Unix timestamp with Bitcoin genesis epoch supportDate: Calendar date with blockchain-specific formatting (YYYYMMDD)Sats: Satoshi amounts with comprehensive arithmetic operationsBitcoin: Floating-point BTC amounts with satoshi conversionBlockHash/TxId: Cryptographic hash identifiers
§Address and Output Types
-
OutputType: Comprehensive Bitcoin script type classification- Standard types: P2PK (33/65-byte), P2PKH, P2SH, P2WPKH, P2WSH, P2TR
- Special types: P2MS (multisig), OpReturn, P2A (address), Empty, Unknown
- Type-checking methods:
is_spendable(),is_address(),is_unspendable()
-
Address Index Types: Specialized indexes for each address type
P2PKHAddressIndex,P2SHAddressIndex,P2WPKHAddressIndexP2WSHAddressIndex,P2TRAddressIndex, etc.
§Financial Data Types
Price Representations:
Cents: Integer cent representation for precise financial calculationsDollars: Floating-point dollar amounts with cent conversionOHLCCents/OHLCDollars/OHLCSats: OHLC data in different denominations
OHLC Components:
Open<T>,High<T>,Low<T>,Close<T>: Generic price point wrappers- Support for arithmetic operations and automatic conversions
§Time Indexing System
Calendar Types:
DateIndex: Days since Bitcoin genesis (2009-01-03)WeekIndex: Week-based indexing for aggregationMonthIndex,QuarterIndex,SemesterIndex: Hierarchical time periodsYearIndex,DecadeIndex: Long-term time categorization
Epoch Types:
HalvingEpoch: Bitcoin halving period classificationDifficultyEpoch: Difficulty adjustment epoch tracking
§Storage Types
Stored Primitives: Memory-efficient wrappers for database storage
StoredU8,StoredU16,StoredU32,StoredU64: Unsigned integersStoredI16: Signed integersStoredF32,StoredF64: Floating-point numbersStoredBool: Boolean valuesStoredString: String storage optimization
§Examples
§Block Height Operations
use brk_structs::Height;
let current_height = Height::new(800000);
let next_height = current_height.incremented();
// Check halving schedule
let blocks_until_halving = current_height.left_before_next_halving();
println!("Blocks until next halving: {}", blocks_until_halving);
// Difficulty adjustment tracking
let blocks_until_adjustment = current_height.left_before_next_diff_adj();§Price Data Processing
use brk_structs::*;
// Create OHLC data from individual price points
let daily_ohlc = OHLCDollars::from((
Open::from(45000.0),
High::from(47500.0),
Low::from(44000.0),
Close::from(46800.0),
));
// Convert between price denominations
let ohlc_cents: OHLCCents = daily_ohlc.into();
let sats_per_dollar = Sats::_1BTC / daily_ohlc.close;
// Aggregate multiple OHLC periods
let weekly_close = vec![
Close::from(46800.0),
Close::from(48200.0),
Close::from(47100.0),
].iter().sum::<Close<Dollars>>();§Address Type Classification
use brk_structs::OutputType;
use bitcoin::{Address, Network};
let address_str = "1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2";
let address = Address::from_str(address_str)?.assume_checked();
let output_type = OutputType::from(&address);
match output_type {
OutputType::P2PKH => println!("Legacy address"),
OutputType::P2WPKH => println!("Native SegWit address"),
OutputType::P2SH => println!("Script hash address"),
OutputType::P2TR => println!("Taproot address"),
_ => println!("Other address type: {:?}", output_type),
}
// Check spend conditions
if output_type.is_spendable() && output_type.is_address() {
println!("Spendable address-based output");
}§Time-Based Indexing
use brk_structs::*;
let date = Date::new(2023, 6, 15);
let date_index = DateIndex::try_from(date)?;
// Convert to different time granularities
let week_index = WeekIndex::from(date);
let month_index = MonthIndex::from(date);
let quarter_index = QuarterIndex::from(date);
// Calculate completion percentage for current day
let completion_pct = date.completion();
println!("Day {}% complete", completion_pct * 100.0);§Architecture
§Zero-Copy Design
All major types implement zerocopy traits (FromBytes, IntoBytes, KnownLayout) enabling:
- Direct memory mapping from serialized data
- Efficient network protocol handling
- High-performance database operations
- Memory layout guarantees for cross-platform compatibility
§Type Safety
The type system enforces Bitcoin domain constraints:
Heightprevents integer overflow in block calculationsTimestamphandles Unix epoch edge casesOutputTypeenum covers all Bitcoin script patterns- Address types ensure correct hash length validation
§Memory Efficiency
Storage types provide space optimization:
- Stored primitives reduce allocation overhead
- OHLC structures support both heap and stack allocation
- Index types enable efficient range queries
- Hash types use fixed-size arrays for predictable memory usage
§Code Analysis Summary
Main Categories: 70+ struct types across Bitcoin primitives, financial data, time indexing, and storage optimization
Zero-Copy Support: Comprehensive zerocopy implementation for all major types
Type Safety: Bitcoin domain-specific constraints with overflow protection and validation
Financial Types: Multi-denomination OHLC support with automatic conversions
Address System: Complete Bitcoin script type classification with 280 enum variants
Time Indexing: Hierarchical calendar system from daily to decade-level granularity
Storage Integration: vecdb::StoredCompressed traits for efficient database operations
Architecture: Type-driven design prioritizing memory efficiency and domain correctness
This README was generated by Claude Code
Structs§
- Address
Bytes Hash - Address
Groups - AnyAddress
Index - Bitcoin
- BlkMetadata
- BlkPosition
- Block
- Block
Hash - Block
Hash Prefix - ByAddress
Type - ByAge
Range - ByAmount
Range - ByAny
Address - ByEpoch
- ByGreat
Equal Amount - ByLower
Than Amount - ByMax
Age - ByMin
Age - BySpendable
Type - ByTerm
- ByUnspendable
Type - Cents
- Close
- Date
- Date
Index - Decade
Index - Difficulty
Epoch - Dollars
- Empty
Address Data - Empty
Address Index - Empty
Output Index - Exit
- FeeRate
- Grouped
ByType - Halving
Epoch - Height
- High
- Input
Index - JSON
Pool - Loaded
Address Data - Loaded
Address Index - Low
- Month
Index - OHLC
Cents - OHLC
Dollars - OHLC
Sats - OpReturn
Index - Open
- Output
Index - P2AAddress
Index - P2ABytes
- P2MS
Output Index - P2PK33
Address Index - P2PK33
Bytes - P2PK65
Address Index - P2PK65
Bytes - P2PKH
Address Index - P2PKH
Bytes - P2SH
Address Index - P2SH
Bytes - P2TR
Address Index - P2TR
Bytes - P2WPKH
Address Index - P2WPKH
Bytes - P2WSH
Address Index - P2WSH
Bytes - Parsed
Block - Pool
- Pools
- Quarter
Index - RawLock
Time - Sats
- Semester
Index - Stored
Bool - Stored
F32 - Stored
F64 - Stored
I16 - Stored
String - Stored
U8 - Stored
U16 - Stored
U32 - Stored
U64 - Timestamp
- TxIndex
- TxVersion
- Txid
- Txid
Prefix - Type
Index - Type
Index With Outputindex - U8x2
- U8x20
- U8x32
- U8x33
- U8x64
- U8x65
- UTXO
Groups - Unit
- Unknown
Output Index - Version
- Vin
- Vout
- Week
Index - Weight
- Year
Index