Crate brk_grouper

Crate brk_grouper 

Source
Expand description

§brk_grouper

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 155 days.”

§Key Features

  • Age-based: TimeFilter::GreaterOrEqual(155), TimeFilter::Range(30..90), TimeFilter::LowerThan(7)
  • Amount-based: AmountFilter::GreaterOrEqual(Sats::_1BTC), AmountFilter::Range(Sats::_100K..Sats::_1M)
  • Term classification: Term::Sth (short-term holders, <155 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
    Type(OutputType),     // P2PKH, P2TR, etc.
}

§Core API

ⓘ
let filter = Filter::Time(TimeFilter::GreaterOrEqual(155));

// Check membership
filter.contains_time(200);  // true
filter.contains_amount(sats);

// Generate metric names
filter.to_full_name(CohortContext::Utxo);  // "utxos_min_age_155d"

§Built On

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

Structs§

AddressGroups
ByAddressType
ByAgeRange
ByAmountRange
ByAnyAddress
ByEpoch
ByGreatEqualAmount
ByLowerThanAmount
ByMaxAge
ByMinAge
BySpendableType
ByTerm
ByUnspendableType
ByYear
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).
TimeFilter

Constants§

AGE_BOUNDARIES
Age boundaries in days. Defines the cohort ranges: [0, B[0]), [B[0], B[1]), [B[1], B[2]), …, [B[n-1], ∞)
DAYS_1D
DAYS_1M
DAYS_1W
DAYS_1Y
DAYS_2M
DAYS_2Y
DAYS_3M
DAYS_3Y
DAYS_4M
DAYS_4Y
DAYS_5M
DAYS_5Y
DAYS_6M
DAYS_6Y
DAYS_7Y
DAYS_8Y
DAYS_10Y
DAYS_12Y
DAYS_15Y
P2A
P2PK33
P2PK65
P2PKH
P2SH
P2TR
P2WPKH
P2WSH

Traits§

Filtered

Functions§

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