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

brk_structs 0.0.107