mirror of
https://github.com/bitcoinresearchkit/brk.git
synced 2026-05-03 02:50:00 -07:00
94 lines
3.1 KiB
Markdown
94 lines
3.1 KiB
Markdown
# brk_structs
|
|
|
|
Core data structures and types used throughout the Bitcoin Research Kit that provide efficient, zero-copy serializable representations of Bitcoin blockchain data. This crate defines strongly-typed wrappers around primitive types with specialized functionality for Bitcoin analysis, storage optimization, and data grouping operations.
|
|
|
|
## Core Types
|
|
|
|
### Blockchain Data
|
|
- **Height**: Block height with arithmetic operations
|
|
- **Date**, **Timestamp**: Time representations with Bitcoin epoch awareness
|
|
- **Txid**, **BlockHash**: Transaction and block identifiers with prefix variants
|
|
- **TxIndex**, **InputIndex**, **OutputIndex**: Transaction component indices
|
|
|
|
### Value Types
|
|
- **Sats**: Satoshi amounts with conversion utilities
|
|
- **Bitcoin**: BTC amounts with precision handling
|
|
- **Dollars**, **Cents**: Fiat currency representations
|
|
- **OHLC**: Open/High/Low/Close price data structures
|
|
|
|
### Address Types
|
|
- **AddressBytes**: Raw address data with type information
|
|
- **P2PKH**, **P2SH**, **P2WPKH**, **P2WSH**, **P2TR**: Address type indices
|
|
- **AnyAddressIndex**: Unified address index type
|
|
|
|
### Storage Types
|
|
- **StoredU8/U16/U32/U64**: Optimized integer storage
|
|
- **StoredF32/F64**: Floating-point storage with compression
|
|
- **StoredBool**: Compact boolean storage
|
|
|
|
### Time Indices
|
|
- **DateIndex**, **WeekIndex**, **MonthIndex**, **QuarterIndex**
|
|
- **SemesterIndex**, **YearIndex**, **DecadeIndex**: Time-based grouping
|
|
- **HalvingEpoch**, **DifficultyEpoch**: Bitcoin-specific time periods
|
|
|
|
## Grouping Operations
|
|
|
|
The crate provides powerful grouping and filtering capabilities:
|
|
|
|
```rust
|
|
use brk_structs::*;
|
|
|
|
// Group by address type
|
|
let p2pkh_addresses = ByAddressType::P2PKH;
|
|
|
|
// Group by value ranges
|
|
let small_utxos = ByLtAmount::new(Sats::_1BTC);
|
|
let large_utxos = ByGeAmount::new(Sats::_10BTC);
|
|
|
|
// Group by age ranges
|
|
let recent_utxos = ByMaxAge::new(Height::new(144)); // Last day
|
|
let old_utxos = ByMinAge::new(Height::new(52560)); // Last year
|
|
|
|
// Combine filters
|
|
let filter = Filter::new()
|
|
.by_spendable_type()
|
|
.by_amount_range(Sats::_1K, Sats::_1M)
|
|
.by_address_type(ByAddressType::P2WPKH);
|
|
```
|
|
|
|
## Features
|
|
|
|
- **Zero-copy serialization**: All types implement `FromBytes`/`IntoBytes` for efficient storage
|
|
- **Storage compression**: Built-in compression support via `StoredCompressed` trait
|
|
- **Type safety**: Strongly-typed wrappers prevent value confusion
|
|
- **Bitcoin-aware**: Constants and operations specific to Bitcoin protocol
|
|
- **Efficient grouping**: Flexible data filtering and categorization system
|
|
- **Time handling**: Comprehensive time representation with epoch support
|
|
|
|
## Usage
|
|
|
|
```rust
|
|
use brk_structs::*;
|
|
|
|
// Create blockchain data types
|
|
let height = Height::new(800_000);
|
|
let amount = Sats::_1BTC;
|
|
let date = Date::new(2024, 1, 15);
|
|
|
|
// Work with addresses
|
|
let address_data = AddressBytes::from_script(&script);
|
|
let address_index = P2WPKHAddressIndex::from_address_bytes(&address_data);
|
|
|
|
// Price data
|
|
let ohlc = OHLCCents::new(
|
|
Open::new(45000_00),
|
|
High::new(46000_00),
|
|
Low::new(44000_00),
|
|
Close::new(45500_00)
|
|
);
|
|
|
|
// Time-based analysis
|
|
let month_index = MonthIndex::from(date);
|
|
let halving_epoch = HalvingEpoch::from(height);
|
|
```
|