# 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
```rust
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
```rust
// 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
```rust
// Efficient serialization without copying
let height_bytes = height.as_bytes();
let recovered_height = Height::read_from_bytes(height_bytes)?;
```
### Data Grouping and Filtering
```rust
// 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*