mirror of
https://github.com/bitcoinresearchkit/brk.git
synced 2026-04-25 07:09:59 -07:00
readmes: update
This commit is contained in:
nym21
@@ -1,93 +1,105 @@
|
||||
# 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.
|
||||
**Bitcoin-aware type system and data structures for blockchain analysis**
|
||||
|
||||
## Core Types
|
||||
`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.
|
||||
|
||||
### 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
|
||||
## What it provides
|
||||
|
||||
### 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
|
||||
- **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
|
||||
|
||||
### Address Types
|
||||
- **AddressBytes**: Raw address data with type information
|
||||
- **P2PKH**, **P2SH**, **P2WPKH**, **P2WSH**, **P2TR**: Address type indices
|
||||
- **AnyAddressIndex**: Unified address index type
|
||||
## Key Features
|
||||
|
||||
### Storage Types
|
||||
- **StoredU8/U16/U32/U64**: Optimized integer storage
|
||||
- **StoredF32/F64**: Floating-point storage with compression
|
||||
- **StoredBool**: Compact boolean storage
|
||||
### 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
|
||||
|
||||
### Time Indices
|
||||
- **DateIndex**, **WeekIndex**, **MonthIndex**, **QuarterIndex**
|
||||
- **SemesterIndex**, **YearIndex**, **DecadeIndex**: Time-based grouping
|
||||
- **HalvingEpoch**, **DifficultyEpoch**: Bitcoin-specific time periods
|
||||
### 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
|
||||
|
||||
## Grouping Operations
|
||||
### 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
|
||||
|
||||
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
|
||||
### 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::*;
|
||||
|
||||
// Create blockchain data types
|
||||
// Type-safe blockchain data
|
||||
let height = Height::new(800_000);
|
||||
let amount = Sats::_1BTC;
|
||||
let epoch = HalvingEpoch::from(height);
|
||||
let amount = Sats::_1BTC * 2;
|
||||
|
||||
// Time-based indexing
|
||||
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);
|
||||
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*
|
||||
Reference in New Issue
Block a user