Crate brk_types

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, Outpoint with 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, DecadeIndex with 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_error for error handling

Structs§

Addr: Bitcoin address string
AddrChainStats: Address statistics on the blockchain (confirmed transactions only)
AddrHash
AddrIndexOutPoint
AddrIndexTxIndex
AddrMempoolStats: Address statistics in the mempool (unconfirmed transactions only)
AddrStats: Address information compatible with mempool.space API format
AddrValidation: Address validation result
Age: Represents the age of a UTXO or address balance. Encapsulates all age-related calculations in one type-safe struct.
AnyAddrIndex: Unified index for any address type (funded or empty)
BasisPoints16: 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::MAX is reserved as a NaN sentinel.
BasisPoints32: 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::MAX is reserved as a NaN sentinel.
BasisPointsSigned16: 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::MIN is reserved as a NaN sentinel.
BasisPointsSigned32: 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::MIN is 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
BlockExtras: Extended block data matching mempool.space /api/v1/blocks extras
BlockFeeRatesEntry: A single block fee rates data point with percentiles.
BlockFeesEntry: A single block fees data point.
BlockHash: Block hash
BlockHashPrefix: First-8-bytes prefix of a block hash, packed as a u64. Both From<&BlockHash> (via from_le_bytes) and From<ByteView> (via from_be_bytes, inverse of the to_be_bytes writer) are host-independent so on-disk keys are portable across architectures.
BlockHeader: Block header matching mempool.space’s format. Contains the same fields as bitcoin::block::Header but serialized for the JSON API.
BlockInfo: Block information matching mempool.space /api/block/{hash}
BlockInfoV1: Block information with extras, matching mempool.space /api/v1/blocks
BlockPool: Mining pool identification for a block
BlockRewardsEntry: A single block rewards data point.
BlockSizeEntry: A single block size data point.
BlockSizesWeights: Combined block sizes and weights response.
BlockStatus: Block status indicating whether block is in the best chain
BlockTemplate: Projected next-block contents from Bitcoin Core’s getblocktemplate (block 0 of the snapshot). Returned by GET /api/v1/mempool/block-template.
BlockTemplateDiff: Delta between the current getblocktemplate projection and a prior one identified by since. Returned by GET /api/v1/mempool/block-template/diff/{hash}.
BlockTimestamp: Block information returned for timestamp queries
BlockTxIndex: Position of a transaction within a single block (0 = coinbase). Distinct from TxIndex, which is the chain-wide global tx index.
BlockWeightEntry: A single block weight data point.
Cents: Unsigned cents (u64) - for values that should never be negative. Used for invested capital, realized cap, etc.
CentsCompact: Compact unsigned cents (u32) - memory-efficient for map keys. Supports values from $0.00 to $42,949,672.95 (u32::MAX / 100).
CentsSats: Cents × Sats (u128) - price in cents multiplied by amount in sats. Uses u128 because large amounts at any price can overflow u64.
CentsSigned: Signed cents (i64) - for values that can be negative. Used for profit/loss calculations, deltas, etc.
CentsSquaredSats: Raw cents squared (u128) - stores cents² × sats without division. Used for precise accumulation of capitalized cap values: Σ(price² × sats). capitalized_price = capitalized_cap_raw / realized_cap_raw
ChunkInput: One cluster member’s input to Single Fee Linearization: its (fee, vsize) and parent edges as local indices into the same array.
Close: Closing price value for a time period
Cohort: URPD cohort identifier. Use GET /api/urpd to list available cohorts.
CoinbaseTag: Coinbase scriptSig tag for pool identification.
CostBasisSnapshot: Snapshot of cost basis related state. Uses CentsSats (u64) for single-UTXO values, CentsSquaredSats (u128) for capitalized cap.
CpfpCluster: CPFP cluster: the connected component the seed belongs to, plus its SFL linearization.
CpfpClusterChunk: One SFL chunk inside a CpfpCluster. txs is in topological order (matches CpfpCluster.txs ordering); the chunk’s feerate is the per-chunk SFL feerate and is the same for every tx in this chunk.
CpfpClusterTx: One entry in a CpfpCluster.txs array.
CpfpClusterTxIndex: Position of a transaction inside a CpfpCluster.txs array. Cluster-local, has no meaning outside the enclosing cluster.
CpfpEntry: A transaction in a CPFP relationship.
CpfpInfo: CPFP (Child Pays For Parent) information for a transaction.
DataRangeFormat: Range parameters with output format for API query parameters.
Date: Date in YYYYMMDD format stored as u32
DateSeriesData: Series data that is guaranteed to use a date-based index.
Day1
Day3
DetailedSeriesCount: Detailed series count with per-database breakdown
DifficultyAdjustment: Difficulty adjustment information.
DifficultyAdjustmentEntry: A single difficulty adjustment entry. Serializes as array: [timestamp, height, difficulty, change_percent]
DifficultyEntry: A single difficulty data point in the hashrate summary.
DiskUsage: Disk usage of the indexed data
Dollars: US Dollar amount
EmptyAddrData: Data of an empty address
EmptyAddrIndex
EmptyOutputIndex
Epoch
ExchangeRates: Exchange rates (USD base, on-chain only — no fiat pairs available)
Exit: Graceful shutdown coordinator for ensuring data consistency during program exit.
FeeRate: Fee rate in sat/vB
FeeRatePercentiles: Fee rate percentiles (min, 10%, 25%, 50%, 75%, 90%, max).
FundedAddrData: Data for a funded (non-empty) address with current balance
FundedAddrIndex
Halving
HashrateEntry: A single hashrate data point.
HashrateSummary: Summary of network hashrate and difficulty data.
Health: Server health status
Height: Block height
Hex: Hex-encoded string. Transparent wrapper over String: serializes as a plain JSON string and derefs to str, so anywhere &str or AsRef<[u8]> is expected the Hex “just works”.
High: Highest price value for a time period
Histogram: Fixed-length, log-scale bin histogram generic over the per-bin counter type. Instantiated as raw counts (u32), the smoothed EMA buffer (f64), or the quantized wire projection (u16). Serializes as a flat JSON array of N values. Deref exposes the underlying array for indexing and iteration.
HistoricalPrice: Historical price response
HistoricalPriceEntry: A single price data point
Hour1
Hour4
Hour12
IndexInfo: Information about an available index and its query aliases
Limit: Maximum number of results to return. Defaults to 100 if not specified.
Low: Lowest price value for a time period
MempoolBlock: Block info in a mempool.space like format for fee estimation.
MempoolEntryInfo: Mempool entry info from Bitcoin Core’s getmempoolentry.
MempoolInfo: Mempool statistics with incrementally maintained fee histogram.
MempoolRecentTx: Simplified mempool transaction for the /api/mempool/recent endpoint.
MerkleProof: Merkle inclusion proof for a transaction
Minute10
Minute30
Month1
Month3
Month6
NextBlockHash: Content hash of the projected next block (block 0 of the mempool snapshot). Same value as the mempool ETag. Opaque token: pass back as since on /api/v1/mempool/block-template/diff/{hash} to fetch deltas.
OHLCCents: OHLC (Open, High, Low, Close) data in cents
OHLCDollars: OHLC (Open, High, Low, Close) data in dollars
OHLCSats: OHLC (Open, High, Low, Close) data in satoshis
OpReturnIndex
Open: Opening price value for a time period
OutPoint
OutpointPrefix: Compact (TxidPrefix, Vout) outpoint identifier. Prefix collisions are possible and must be verified by the caller.
P2AAddrIndex
P2ABytes
P2MSOutputIndex
P2PK33AddrIndex
P2PK33Bytes
P2PK65AddrIndex
P2PK65Bytes
P2PKHAddrIndex
P2PKHBytes
P2SHAddrIndex
P2SHBytes
P2TRAddrIndex
P2TRBytes
P2WPKHAddrIndex
P2WPKHBytes
P2WSHAddrIndex
P2WSHBytes
PaginatedSeries: A paginated list of available series names (1000 per page)
Pagination: Pagination parameters for paginated API endpoints
Pool: Mining pool information
PoolBlockCounts: Block counts for different time periods
PoolBlockShares: Pool’s share of total blocks for different time periods
PoolDetail: Detailed pool information with statistics across time periods
PoolDetailInfo: Pool information for detail view
PoolHashrateEntry: A single pool hashrate data point.
PoolInfo: Basic pool information for listing all pools
PoolStats: Mining pool with block statistics for a time period
Pools
PoolsSummary: Mining pools response for a time period
Port: Server port. Defaults to 3110.
Prices: Current price response matching mempool.space /api/v1/prices format
RangeMap: Maps ranges of indices to values for efficient reverse lookups.
RawLockTime: Transaction locktime. Values below 500,000,000 are interpreted as block heights; values at or above are Unix timestamps.
RbfResponse: Response body for GET /api/v1/tx/:txid/rbf. Both fields are null when the tx has no known RBF history within the mempool monitor’s graveyard retention window.
RbfTx: Transaction summary carried inside an RBF replacement node. Shape matches mempool.space’s /api/v1/tx/:txid/rbf and /api/v1/replacements responses.
ReadBlock
RecommendedFees: Recommended fee rates in sat/vB
ReplacementNode: One node in an RBF replacement tree. The node’s tx replaced each entry in replaces, recursively.
RewardStats: Block reward statistics over a range of blocks
Sats: Amount in satoshis (1 BTC = 100,000,000 sats)
SatsFract: Fractional satoshis (f64) - for representing USD prices in sats
SatsSigned: Signed satoshis (i64) - for values that can be negative. Used for changes, deltas, profit/loss calculations, etc.
SearchQuery
SeriesCount: Series count statistics - distinct series and total series-index combinations
SeriesData: Series data with range information.
SeriesInfo: Metadata about a series
SeriesLeaf: Leaf node containing series metadata
SeriesLeafWithSchema: SeriesLeaf with JSON Schema for client generation
SeriesList: Comma-separated list of series names
SeriesName: Series name
SeriesNameWithIndex
SeriesOutput: Series output with metadata for caching.
SeriesOutputLegacy: Deprecated: Legacy series output with metadata for caching.
SeriesSelection: Selection of series to query
SeriesSelectionLegacy: Legacy series selection parameters (deprecated)
SigOps: BIP-141 sigop cost. The block-level budget is 80,000, so a u32 fits a single tx’s count with room to spare.
StoredBool: Fixed-size boolean value optimized for on-disk storage (stored as u8)
StoredF32: Stored 32-bit floating point value
StoredF64: Fixed-size 64-bit floating point value optimized for on-disk storage
StoredI8
StoredI16
StoredI64: Fixed-size 64-bit signed integer optimized for on-disk storage
StoredString
StoredU8
StoredU16
StoredU32: Fixed-size 32-bit unsigned integer optimized for on-disk storage
StoredU64: Fixed-size 64-bit unsigned integer optimized for on-disk storage
SupplyState: Current supply state tracking UTXO count and total value
SyncStatus: Sync status of the indexer
Timestamp: UNIX timestamp in seconds
Transaction: Transaction information compatible with mempool.space API format
TxIn: Transaction input
TxInIndex
TxIndex: Chain-wide transaction index (0 = the genesis coinbase). For an in-block position, use BlockTxIndex instead.
TxOut: Transaction output
TxOutIndex
TxOutspend: Status of an output indicating whether it has been spent
TxStatus: Transaction confirmation status
TxVersion: Transaction version number
TxVersionRaw: Raw transaction version (i32) from Bitcoin protocol. Unlike TxVersion (u8, indexed), this preserves non-standard values used in coinbase txs for miner signaling/branding.
Txid: Transaction ID (hash)
TxidPrefix: First-8-bytes prefix of a txid, packed as a u64. Both From<&Txid> (via from_le_bytes) and From<ByteView> (via from_be_bytes, inverse of the to_be_bytes writer) are host-independent so on-disk keys are portable across architectures.
TypeIndex: Index within its type (e.g., 0 for first P2WPKH address)
U8x2
U8x20
U8x32
U8x33
U8x65
Unit
UnknownOutputIndex
Urpd: UTXO Realized Price Distribution for a cohort on a specific date.
UrpdBucket: A single bucket in a URPD snapshot.
UrpdRaw: Raw on-disk URPD: a map of price (cents) to supply (sats). Processed into crate::Urpd for API responses.
Utxo: Unspent transaction output
VSize: Virtual size in vbytes (weight / 4, rounded up). Max block vsize is ~1,000,000 vB.
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: Weight in weight units (WU). Max block weight is 4,000,000 WU.
Witness: Transaction witness: a stack of byte arrays, one per witness item.
Year: Bitcoin year (2009, 2010, …, 2025+)
Year1
Year10

Enums§

AddrBytes
AnyAddrDataIndexEnum
BlockTemplateDiffEntry: One slot of the new template in a BlockTemplateDiff.
CacheClass: How the trailing edge of an Index mutates over time. Drives the series cache: bucketed indexes have a small fixed volatile tail, entity indexes derive their stable count from a height→first-index mapping, and mutable addr indexes have no immutable region (entries change retroactively).
Format: Output format for API responses
FormatResponse: 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.
LegacyValue: Deprecated: Raw JSON without metadata wrapper.
Output: Series data output format
OutputLegacy: Deprecated: Raw JSON without metadata wrapper
OutputType: Type (P2PKH, P2WPKH, P2SH, P2TR, etc.)
PoolSlug: URL-friendly mining pool identifier
RangeIndex: 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.
TimePeriod: Time period for mining statistics.
TreeNode: Hierarchical tree node for organizing series into categories
UrpdAggregation: Aggregation strategy for URPD buckets. Options: raw (no aggregation), lin200/lin500/lin1000 (linear $200/$500/$1000), log10/log50/log100/log200/log500/log1000/log2000 (logarithmic with 10/50/100/200/500/1000/2000 buckets per decade).

Constants§

BLOCKS_PER_DIFF_EPOCHS
BLOCKS_PER_HALVING
CPFP_CHAIN_LIMIT: Bitcoin Core’s default mempool ancestor/descendant chain cap, also used by mempool.space-style truncation in CPFP walks.
DAY3_INTERVAL
HOUR1_INTERVAL
HOUR4_INTERVAL
HOUR12_INTERVAL
INDEX_EPOCH: 2009-01-01 00:00:00 UTC — epoch for fixed-interval time indexes.
MINUTE10_INTERVAL
MINUTE30_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.

Traits§

CheckedSub: Subtraction that returns None on underflow.
FromCoarserIndex: Maps coarser-grained indices to ranges of finer-grained indices.
OptionExt: Extension trait for Option to provide shorter unwrap methods
PrintableIndex: 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.
find_seed_chunk: Find the chunk containing seed_local and return (chunk_index, feerate). Falls back to (0, fallback) when the seed isn’t in any chunk - shouldn’t happen for a well-formed linearization but keeps callers’ wire shape valid.
get_percentile: Get a percentile value from a sorted slice using nearest-rank method.
get_weighted_percentile: Get a percentile value from a sorted (value, vsize) slice using vsize-weighted interpolation — matches mempool.space’s feeRange calculation.
linearize: Linearize items into chunks. items must be in topological order (parents before children); parents indices must point earlier in the slice. Returns chunks sorted by descending feerate, with each chunk’s txs listed in the input topological order.
pools

Type Aliases§

StoredPhantom

Crate brk_types

Crate brk_types Copy item path

§brk_types

§What It Enables

§Key Features

§Type Categories

§Core API

§Built On

Structs§

Enums§

Constants§

Traits§

Functions§

Type Aliases§

Crate brk_types