Crate brk_cohort

Crate brk_cohort 

Source
Expand description

§brk_cohort

UTXO and address cohort filtering for on-chain analytics.

§What It Enables

Slice the UTXO set and address population by age, amount, output type, halving epoch, or holder classification (STH/LTH). Build complex cohorts by combining filters for metrics like “realized cap of 1+ BTC UTXOs older than 150 days.”

§Key Features

  • Age-based: TimeFilter::GreaterOrEqual(hours), TimeFilter::Range(hours..hours), TimeFilter::LowerThan(hours)
  • Amount-based: AmountFilter::GreaterOrEqual(Sats::_1BTC), AmountFilter::Range(Sats::_100K..Sats::_1M)
  • Term classification: Term::Sth (short-term holders, <150 days), Term::Lth (long-term holders)
  • Epoch filters: Group by halving epoch
  • Type filters: Segment by output type (P2PKH, P2TR, etc.)
  • Context-aware naming: Automatic prefix generation (utxos_, addrs_) based on cohort context
  • Inclusion logic: Filter hierarchy for aggregation (Filter::includes)

§Filter Types

ⓘ
pub enum Filter {
    All,
    Term(Term),           // STH/LTH
    Time(TimeFilter),     // Age-based
    Amount(AmountFilter), // Value-based
    Epoch(HalvingEpoch),  // Halving epoch
    Year(Year),           // Calendar year
    Type(OutputType),     // P2PKH, P2TR, etc.
}

§Core API

ⓘ
// TimeFilter values are in hours (e.g., 3600 hours = 150 days)
let filter = Filter::Time(TimeFilter::GreaterOrEqual(3600));

// Check membership
filter.contains_time(4000);  // true (4000 hours > 3600 hours)
filter.contains_amount(sats);

// Generate metric names (via CohortContext)
let ctx = CohortContext::Utxo;
ctx.full_name(&filter, "min_age_150d");  // "utxos_min_age_150d"

§Built On

  • brk_error for error handling
  • brk_types for Sats, HalvingEpoch, OutputType
  • brk_traversable for data structure traversal

Structs§

AddressGroups
Age
Represents the age of a UTXO or address balance. Encapsulates all age-related calculations in one type-safe struct.
AmountBucket
Bucket index for amount ranges. Use for cheap comparisons and direct lookups.
ByAddressType
ByAgeRange
ByAmountRange
ByAnyAddress
ByEpoch
ByGreatEqualAmount
ByLowerThanAmount
ByMaxAge
ByMinAge
BySpendableType
ByTerm
ByUnspendableType
ByYear
CohortName
Display names for a cohort with id (for storage/API), short (for charts), and long (for tooltips/labels)
GroupedByType
UTXOGroups

Enums§

AmountFilter
CohortContext
Context for cohort naming - determines whether a prefix is needed.
Filter
StateLevel
Controls the level of state tracking for a cohort.
Term
Classification for short-term vs long-term holders. The threshold is 150 days (approximately 5 months) = 3600 hours.
TimeFilter

Constants§

AGE_BOUNDARIES
Age boundaries in hours. Defines the cohort ranges: [0, 1h), [1h, 1d), [1d, 1w), [1w, 1m), …, [15y, ∞)
AGE_RANGE_BOUNDS
Age range bounds (end = usize::MAX means unbounded)
AGE_RANGE_FILTERS
Age range filters
AGE_RANGE_NAMES
Age range names
AMOUNT_RANGE_BOUNDS
Amount range bounds
AMOUNT_RANGE_FILTERS
Amount range filters
AMOUNT_RANGE_NAMES
Amount range names
EPOCH_FILTERS
Epoch filters
EPOCH_NAMES
Epoch names
EPOCH_VALUES
Epoch values
GE_AMOUNT_FILTERS
Greater-or-equal amount filters
GE_AMOUNT_NAMES
Greater-or-equal amount names
GE_AMOUNT_THRESHOLDS
Greater-or-equal amount thresholds
HOURS_1D
HOURS_1H
HOURS_1M
HOURS_1W
HOURS_1Y
HOURS_2M
HOURS_2Y
HOURS_3M
HOURS_3Y
HOURS_4M
HOURS_4Y
HOURS_5M
HOURS_5Y
HOURS_6M
HOURS_6Y
HOURS_7Y
HOURS_8Y
HOURS_10Y
HOURS_12Y
HOURS_15Y
LT_AMOUNT_FILTERS
Lower-than amount filters
LT_AMOUNT_NAMES
Lower-than amount names
LT_AMOUNT_THRESHOLDS
Lower-than amount thresholds
MAX_AGE_FILTERS
Max age filters (LowerThan threshold in hours)
MAX_AGE_HOURS
Max age thresholds in hours
MAX_AGE_NAMES
Max age names
MIN_AGE_FILTERS
Min age filters (GreaterOrEqual threshold in hours)
MIN_AGE_HOURS
Min age thresholds in hours
MIN_AGE_NAMES
Min age names
P2A
P2PK33
P2PK65
P2PKH
P2SH
P2TR
P2WPKH
P2WSH
SPENDABLE_TYPE_FILTERS
Spendable type filters
SPENDABLE_TYPE_NAMES
Spendable type names
SPENDABLE_TYPE_VALUES
Spendable type values
TERM_FILTERS
Term filters
TERM_NAMES
Term names
TERM_VALUES
Term values
YEAR_FILTERS
Year filters
YEAR_NAMES
Year names
YEAR_VALUES
Year values

Traits§

Filtered

Functions§

amounts_in_different_buckets
Check if two amounts are in different buckets. O(1).