mirror of
https://github.com/bitcoinresearchkit/brk.git
synced 2026-04-24 22:59:58 -07:00
105 lines
3.5 KiB
Markdown
105 lines
3.5 KiB
Markdown
# 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* |