brk_structs

Bitcoin-aware type system and data structures for blockchain analysis

brk_structs provides the foundational type system for the Bitcoin Research Kit (BRK). It offers strongly-typed, storage-optimized data structures that encode Bitcoin protocol knowledge and enable efficient blockchain data analysis.

What it provides

• Type Safety: Distinct wrapper types prevent common mistakes (e.g., confusing block height with transaction index)
• Storage Optimization: Zero-copy serialization and optional compression for efficient disk storage
• Bitcoin Protocol Knowledge: Built-in understanding of halving epochs, address types, and blockchain constants
• Comprehensive Time Indexing: Multiple temporal granularities for time-series analysis
• Flexible Grouping: Framework for categorizing and filtering blockchain data

Key Features

Core Blockchain Types

• Height - Block heights with Bitcoin-specific arithmetic
• Txid/BlockHash - Transaction and block identifiers with prefix optimization
• TxIndex/InputIndex/OutputIndex - Component indices with type safety
• Date/Timestamp - Time representations anchored to Bitcoin genesis block

Value and Currency Types

• Sats - Satoshi amounts with comprehensive arithmetic operations
• Bitcoin - BTC amounts with precision handling
• Dollars/Cents - Fiat currency for price analysis
• OHLC types (Open<T>, High<T>, Low<T>, Close<T>) for market data

Address System

• OutputType - All Bitcoin script types (P2PKH, P2SH, P2WPKH, P2WSH, P2TR, etc.)
• AddressBytes - Type-safe address data extraction
• Address-specific indices for each output type
• AnyAddressIndex - Unified address indexing

Temporal Indexing

• DateIndex - Days since Bitcoin genesis
• Time granularities: WeekIndex, MonthIndex, QuarterIndex, YearIndex, DecadeIndex
• HalvingEpoch - Bitcoin halving periods (every 210,000 blocks)
• DifficultyEpoch - Difficulty adjustment periods

Usage

Basic Types and Conversions

use brk_structs::*;

// Type-safe blockchain data
let height = Height::new(800_000);
let epoch = HalvingEpoch::from(height);
let amount = Sats::_1BTC * 2;

// Time-based indexing
let date = Date::new(2024, 1, 15);
let month_idx = MonthIndex::from(date);

Address Handling

// Extract address information from Bitcoin scripts
let output_type = OutputType::from(&script);
if output_type.is_address() {
    let address_bytes = AddressBytes::try_from((&script, output_type))?;
}

Zero-Copy Storage

// Efficient serialization without copying
let height_bytes = height.as_bytes();
let recovered_height = Height::read_from_bytes(height_bytes)?;

Data Grouping and Filtering

// Flexible filtering for analytics
let utxo_groups = UTXOGroups {
    all: total_utxos,
    age_range: ByAgeRange::new(age_filtered_utxos),
    epoch: ByEpoch::new(epoch_filtered_utxos),
    // ... more groupings
};

Storage Optimization

All types implement zero-copy serialization traits:

• Zero overhead: Direct memory mapping without serialization costs
• Optional compression: Configurable zstd compression for space efficiency
• Type safety: Compile-time guarantees about data layout and endianness

Dependencies

• bitcoin - Bitcoin protocol types and script parsing
• vecdb - Vector database storage traits
• zerocopy - Zero-copy serialization framework
• serde - JSON serialization support
• jiff - Modern date/time handling

This README was generated by Claude Code