Expand description
§brk_types
Domain types for Bitcoin data analysis with serialization and indexing support.
§What It Enables
Work with Bitcoin primitives (heights, satoshis, addresses, transactions) through purpose-built types that handle encoding, arithmetic, time conversions, and database storage automatically.
§Key Features
- Bitcoin primitives:
Height,Sats,Txid,BlockHash,Outpointwith full arithmetic and conversion support - Address types: All output types (P2PK33, P2PK65, P2PKH, P2MS, P2SH, P2WPKH, P2WSH, P2TR, P2A, OP_RETURN) with address index variants
- Time indexes:
DateIndex,WeekIndex,MonthIndex,QuarterIndex,SemesterIndex,YearIndex,DecadeIndexwith cross-index conversion - Protocol types:
Epoch,Halving,TxVersion,RawLocktime - Financial types:
Dollars,Cents,OHLC(Open/High/Low/Close) - Serialization: Serde + JSON Schema generation via schemars
- Compression: PCO (Pco) derive for columnar compression in vecdb
§Type Categories
| Category | Examples |
|---|---|
| Block metadata | Height, BlockHash, BlockTimestamp, BlkPosition |
| Transaction | Txid, TxIndex, TxIn, TxOut, Vsize, Weight |
| Address | P2PKHAddressIndex, P2TRBytes, AnyAddressIndex, AddressStats |
| Value | Sats, Dollars, Cents, Bitcoin |
| Time | Date, DateIndex, WeekIndex, MonthIndex, … |
| Metric | Metric, MetricData, MetricSelection |
| API | Pagination, Health, RecommendedFees, MempoolInfo |
§Core API
All types implement standard traits: Debug, Clone, Serialize, Deserialize, plus domain-specific operations like CheckedSub, Formattable, and PrintableIndex.
ⓘ
use brk_types::{Height, Sats, DateIndex, Date};
let height = Height::new(840_000);
let reward = Sats::FIFTY_BTC / 16; // Post-4th-halving reward
let date_idx = DateIndex::try_from(Date::new(2024, 4, 20))?;§Built On
brk_errorfor error handling
Structs§
- Addr
- Bitcoin address string
- Addr
Chain Stats - Address statistics on the blockchain (confirmed transactions only)
- Addr
Hash - Addr
Index OutPoint - Addr
Index TxIndex - Addr
Mempool Stats - Address statistics in the mempool (unconfirmed transactions only)
- Addr
Param - Addr
Stats - Address information compatible with mempool.space API format
- Addr
Txids Param - Addr
Validation - Address validation result
- Age
- Represents the age of a UTXO or address balance. Encapsulates all age-related calculations in one type-safe struct.
- AnyAddr
Index - Unified index for any address type (funded or empty)
- Basis
Points16 - Unsigned basis points stored as u16.
1 bp = 0.0001. Range: 0–6.5535.
Use for bounded 0–1 ratios (dominance, adoption, liveliness, etc.).
u16::MAXis reserved as a NaN sentinel. - Basis
Points32 - Unsigned basis points stored as u32.
1 bp = 0.0001. Range: 0–429,496.7295.
Use for unbounded unsigned ratios (MVRV, NVT, SOPR, etc.).
u32::MAXis reserved as a NaN sentinel. - Basis
Points Signed16 - Signed basis points stored as i16.
1 bp = 0.0001. Range: -3.2767 to +3.2767.
Use for signed bounded ratios (NUPL, net PnL ratios, etc.).
i16::MINis reserved as a NaN sentinel. - Basis
Points Signed32 - Signed basis points stored as i32.
1 bp = 0.0001. Range: -214,748.3647 to +214,748.3647.
Use for unbounded signed values (returns, growth rates, volatility, z-scores, etc.).
i32::MINis reserved as a NaN sentinel. - Bitcoin
- Bitcoin amount as floating point (1 BTC = 100,000,000 satoshis)
- BlkMetadata
- BlkPosition
- Position within a .blk file, encoding file index and byte offset
- Block
- Block
Count Param - Block
FeeRates Entry - A single block fee rates data point with percentiles.
- Block
Fees Entry - A single block fees data point.
- Block
Hash - Block hash
- Block
Hash Param - Block
Hash Prefix - Block
Hash Start Index - Block
Hash TxIndex - Block
Info - Block information returned by the API
- Block
Rewards Entry - A single block rewards data point.
- Block
Size Entry - A single block size data point.
- Block
Sizes Weights - Combined block sizes and weights response.
- Block
Status - Block status indicating whether block is in the best chain
- Block
Timestamp - Block information returned for timestamp queries
- Block
Weight Entry - A single block weight data point.
- Cents
- Unsigned cents (u64) - for values that should never be negative. Used for invested capital, realized cap, etc.
- Cents
Compact - Compact unsigned cents (u32) - memory-efficient for map keys. Supports values from $0.00 to $42,949,672.95 (u32::MAX / 100).
- Cents
Sats - Cents × Sats (u128) - price in cents multiplied by amount in sats. Uses u128 because large amounts at any price can overflow u64.
- Cents
Signed - Signed cents (i64) - for values that can be negative. Used for profit/loss calculations, deltas, etc.
- Cents
Squared Sats - Raw cents squared (u128) - stores cents² × sats without division. Used for precise accumulation of investor cap values: Σ(price² × sats). investor_price = investor_cap_raw / realized_cap_raw
- Close
- Closing price value for a time period
- Cohort
- Cohort identifier for cost basis distribution.
- Cost
Basis Cohort Param - Path parameters for cost basis dates endpoint.
- Cost
Basis Distribution - Cost basis distribution: a map of price (cents) to sats.
- Cost
Basis Params - Path parameters for cost basis distribution endpoint.
- Cost
Basis Query - Query parameters for cost basis distribution endpoint.
- Cost
Basis Snapshot - Snapshot of cost basis related state. Uses CentsSats (u64) for single-UTXO values, CentsSquaredSats (u128) for investor cap.
- Data
Range - Range parameters for slicing data
- Data
Range Format - Data range with output format for API query parameters
- Date
- Date in YYYYMMDD format stored as u32
- Date
Series Data - Series data that is guaranteed to use a date-based index.
- Day1
- Day3
- Detailed
Series Count - Detailed series count with per-database breakdown
- Difficulty
Adjustment - Difficulty adjustment information.
- Difficulty
Adjustment Entry - A single difficulty adjustment entry. Serializes as array: [timestamp, height, difficulty, change_percent]
- Difficulty
Entry - A single difficulty data point.
- Disk
Usage - Disk usage of the indexed data
- Dollars
- US Dollar amount as floating point
- Empty
Addr Data - Data of an empty address
- Empty
Addr Index - Empty
Output Index - Epoch
- Etag
- HTTP ETag value.
- Exit
- Graceful shutdown coordinator for ensuring data consistency during program exit.
- FeeRate
- Fee rate in sats/vB
- FeeRate
Percentiles - Fee rate percentiles (min, 10%, 25%, 50%, 75%, 90%, max).
- Funded
Addr Data - Data for a funded (non-empty) address with current balance
- Funded
Addr Index - Halving
- Hashrate
Entry - A single hashrate data point.
- Hashrate
Summary - Summary of network hashrate and difficulty data.
- Health
- Server health status
- Height
- Block height
- Height
Param - Hex
- Hex-encoded string
- High
- Highest price value for a time period
- Hour1
- Hour4
- Hour12
- Index
Info - Information about an available index and its query aliases
- Indexes
- Blockchain-level indexes tracking current positions for various entity types. Used by brk_indexer during block processing.
- Limit
- Maximum number of results to return. Defaults to 100 if not specified.
- Limit
Param - Low
- Lowest price value for a time period
- Mempool
Block - Block info in a mempool.space like format for fee estimation.
- Mempool
Entry Info - Mempool entry info from Bitcoin Core’s getrawmempool verbose
- Mempool
Info - Mempool statistics
- Minute10
- Minute30
- Month1
- Month3
- Month6
- OHLC
Cents - OHLC (Open, High, Low, Close) data in cents
- OHLC
Dollars - OHLC (Open, High, Low, Close) data in dollars
- OHLC
Sats - OHLC (Open, High, Low, Close) data in satoshis
- OpReturn
Index - Open
- Opening price value for a time period
- Oracle
Bins - Phase histogram: counts per bin for frac(log10(sats))
- Oracle
Bins V2 - V2 Phase histogram: counts per bin for frac(log10(sats))
- OutPoint
- P2AAddr
Index - P2ABytes
- P2MS
Output Index - P2PK33
Addr Index - P2PK33
Bytes - P2PK65
Addr Index - P2PK65
Bytes - P2PKH
Addr Index - P2PKH
Bytes - P2SH
Addr Index - P2SH
Bytes - P2TR
Addr Index - P2TR
Bytes - P2WPKH
Addr Index - P2WPKH
Bytes - P2WSH
Addr Index - P2WSH
Bytes - Paginated
Series - A paginated list of available series names (1000 per page)
- Pagination
- Pagination parameters for paginated API endpoints
- Pagination
Index - Pagination parameters with an index filter
- Pool
- Mining pool information
- Pool
Block Counts - Block counts for different time periods
- Pool
Block Shares - Pool’s share of total blocks for different time periods
- Pool
Detail - Detailed pool information with statistics across time periods
- Pool
Detail Info - Pool information for detail view
- Pool
Info - Basic pool information for listing all pools
- Pool
Slug Param - Pool
Stats - Mining pool with block statistics for a time period
- Pools
- Pools
Summary - Mining pools response for a time period
- Port
- Server port. Defaults to 3110.
- Range
Map - Maps ranges of indices to values for efficient reverse lookups.
- RawLock
Time - Transaction locktime
- Read
Block - Recommended
Fees - Recommended fee rates in sat/vB
- Reward
Stats - Block reward statistics over a range of blocks
- Sats
- Satoshis
- Sats
Fract - Fractional satoshis (f64) - for representing USD prices in sats
- Sats
Signed - Signed satoshis (i64) - for values that can be negative. Used for changes, deltas, profit/loss calculations, etc.
- Search
Query - Series
Count - Series count statistics - distinct series and total series-index combinations
- Series
Data - Series data with range information.
- Series
Info - Metadata about a series
- Series
Leaf - Leaf node containing series metadata
- Series
Leaf With Schema - SeriesLeaf with JSON Schema for client generation
- Series
List - Comma-separated list of series names
- Series
Name - Series name
- Series
Name With Index - Series
Output - Series output with metadata for caching.
- Series
Output Legacy - Deprecated: Legacy series output with metadata for caching.
- Series
Param - Series
Selection - Selection of series to query
- Series
Selection Legacy - Legacy series selection parameters (deprecated)
- Stored
Bool - Fixed-size boolean value optimized for on-disk storage (stored as u8)
- Stored
F32 - Stored 32-bit floating point value
- Stored
F64 - Fixed-size 64-bit floating point value optimized for on-disk storage
- Stored
I8 - Stored
I16 - Stored
I64 - Fixed-size 64-bit signed integer optimized for on-disk storage
- Stored
String - Stored
U8 - Stored
U16 - Stored
U32 - Fixed-size 32-bit unsigned integer optimized for on-disk storage
- Stored
U64 - Fixed-size 64-bit unsigned integer optimized for on-disk storage
- Supply
State - Current supply state tracking UTXO count and total value
- Sync
Status - Sync status of the indexer
- Time
Period Param - Timestamp
- UNIX timestamp in seconds
- Timestamp
Param - Transaction
- Transaction information compatible with mempool.space API format
- TxIn
- Transaction input
- TxIn
Index - TxIndex
- TxOut
- Transaction output
- TxOut
Index - TxOutspend
- Status of an output indicating whether it has been spent
- TxStatus
- Transaction confirmation status
- TxVersion
- Transaction version number
- TxWith
Hex - A transaction with its raw hex representation
- Txid
- Transaction ID (hash)
- Txid
Param - Txid
Prefix - Txid
Vout - Transaction output reference (txid + output index)
- Type
Index - Index within its type (e.g., 0 for first P2WPKH address)
- U8x2
- U8x20
- U8x32
- U8x33
- U8x65
- Unit
- Unknown
Output Index - Utxo
- Unspent transaction output
- VSize
- Virtual size in vbytes (weight / 4, rounded up)
- Validate
Addr Param - Version
- Version tracking for data schema and computed values.
- Vin
- Input index in the spending transaction
- Vout
- Index of the output being spent in the previous transaction
- Week1
- Weight
- Transaction or block weight in weight units (WU)
- Year
- Bitcoin year (2009, 2010, …, 2025+)
- Year1
- Year10
Enums§
- Addr
Bytes - AnyAddr
Data Index Enum - Cost
Basis Bucket - Bucket type for cost basis aggregation. Options: raw (no aggregation), lin200/lin500/lin1000 (linear $200/$500/$1000), log10/log50/log100/log200 (logarithmic with 10/50/100/200 buckets per decade).
- Cost
Basis Value - Value type for cost basis distribution. Options: supply (BTC), realized (USD, price × supply), unrealized (USD, spot × supply).
- Format
- Output format for API responses
- Format
Response - Response type for endpoints that support multiple formats (JSON/CSV).
- Index
- Aggregation dimension for querying series. Includes time-based (date, week, month, year), block-based (height, tx_index), and address/output type indexes.
- Legacy
Value - Deprecated: Raw JSON without metadata wrapper.
- Output
- Series data output format
- Output
Legacy - Deprecated: Raw JSON without metadata wrapper
- Output
Type - Type (P2PKH, P2WPKH, P2SH, P2TR, etc.)
- Pool
Slug - Range
Index - A range boundary: integer index, date, or timestamp.
- Term
- Classification for short-term vs long-term holders. The threshold is 150 days (approximately 5 months) = 3600 hours.
- Time
Period - Time period for mining statistics.
- Tree
Node - Hierarchical tree node for organizing series into categories
Constants§
- BLOCKS_
PER_ DIFF_ EPOCHS - BLOCKS_
PER_ HALVING - DAY3_
INTERVAL - HOUR1_
INTERVAL - HOUR4_
INTERVAL - HOUR12_
INTERVAL - INDEX_
EPOCH - 2009-01-01 00:00:00 UTC — epoch for fixed-interval time indexes.
- MINUT
E10_ INTERVAL - MINUT
E30_ INTERVAL - ONE_
DAY_ IN_ SEC - ONE_
DAY_ IN_ SEC_ F64 - ONE_
HOUR_ IN_ SEC - PERCENTILES
- Standard percentile values used throughout BRK.
- PERCENTILES_
LEN - Length of the PERCENTILES array.
- PHASE_
BINS - Number of bins for the phase histogram
- PHASE_
BINS_ V2 - Number of bins for V2 phase histogram (0.5% resolution)
Traits§
- Checked
Sub - From
Coarser Index - Maps coarser-grained indices to ranges of finer-grained indices.
- Option
Ext - Extension trait for Option to provide shorter unwrap methods
- Printable
Index - Provides string representations of index types for display and region naming.
Functions§
- de_
unquote_ i64 - de_
unquote_ limit - de_
unquote_ usize - extract_
json_ type - Extract JSON type from a root schema, following $ref and composition keywords.
- get_
percentile - Get a percentile value from a sorted slice.
- pools
Type Aliases§
- Cost
Basis Formatted - Formatted cost basis output. Key: price floor in USD (dollars). Value: BTC (for supply) or USD (for realized/unrealized).
- Stored
Phantom