Mirror/brk

mirror of https://github.com/bitcoinresearchkit/brk.git synced 2026-04-24 22:59:58 -07:00

Files

Brandon Collins 5ecfd6cd42 fix: address vecdb compatibility and add unit tests

- Switch to vecdb 0.6.0 for compatibility with brk_types u8/i8
- Add proper trait imports (VecIndex, AnyVec, IterableVec, etc.)
- Add unit tests for Reserve Risk formula validation:
  - test_hodl_bank_formula: Verifies cumulative calculation
  - test_reserve_risk_formula: Verifies division formula
  - test_reserve_risk_interpretation: Documents metric semantics
  - test_hodl_bank_negative_contribution: Tests edge case

All 16 tests pass (12 existing + 4 new).

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-01-20 11:15:30 -05:00

examples

global: snapshot

2026-01-17 22:35:13 +01:00

src

fix: address vecdb compatibility and add unit tests

2026-01-20 11:15:30 -05:00

.gitignore

global: snapshot

2026-01-13 22:32:29 +01:00

Cargo.toml

global: snapshot

2026-01-20 15:04:00 +01:00

flamegraph.sh

global: perf + resource imprv

2025-07-12 15:07:02 +02:00

README.md

global: snapshot

2026-01-14 16:38:53 +01:00

samply.sh

global: perf + resource imprv

2025-07-12 15:07:02 +02:00

README.md

brk_computer

Derived metrics computation engine for Bitcoin on-chain analytics.

What It Enables

Compute 1000+ on-chain metrics from indexed blockchain data: supply breakdowns, realized/unrealized P&L, SOPR, MVRV, cohort analysis (by age, amount, address type), cointime economics, mining pool attribution, and price-weighted valuations.

Key Features

Cohort metrics: Filter by UTXO age (STH/LTH, age bands), amount ranges, address types
Stateful computation: Track per-UTXO cost basis, realized/unrealized states
Multi-index support: Metrics available by height, date, week, month, year, decade
Price integration: USD-denominated metrics when price data available
Mining pool attribution: Tag blocks/rewards to known pools
Cointime economics: Liveliness, vaultedness, activity-weighted metrics
Incremental updates: Resume from checkpoints, compute only new blocks

Core API

let mut computer = Computer::forced_import(&outputs_path, &indexer, Some(fetcher))?;

// Compute all metrics for new blocks
computer.compute(&indexer, starting_indexes, &reader, &exit)?;

// Access computed data via traversable vecs
let supply = computer.distribution.utxo_cohorts.all.metrics.supply.total.sats.height;
let realized_cap = computer.distribution.utxo_cohorts.all.metrics.realized.unwrap().realized_cap.height;

Metric Categories

Module	Examples
`blocks`	Block count, interval, size, mining metrics, rewards
`transactions`	Transaction count, fee, size, volume
`scripts`	Output type counts
`distribution`	Realized cap, MVRV, SOPR, unrealized P&L, supply
`cointime`	Liveliness, vaultedness, true market mean
`pools`	Per-pool block counts, rewards, fees
`market`	Market cap, NVT, Puell multiple
`price`	Height-to-price mapping from fetched data

Cohort System

UTXO and address cohorts support filtering by:

Age: STH (<150d), LTH (≥150d), 21 age bands (<1h, 1h-1d, 1d-1w, 1w-1m, 1m-2m, ..., 6m-1y, 1y-2y, ..., 12y-15y, 15y+)
Amount: 0-0.001 BTC, 0.001-0.01, ..., 10k+ BTC
Type: P2PK, P2PKH, P2MS, P2SH, P2WPKH, P2WSH, P2TR, P2A
Epoch: By halving epoch

Performance

End-to-End

Full pipeline benchmarks (indexer + computer):

Machine	Time	Disk	Peak Disk	Memory	Peak Memory
MBP M3 Pro (36GB, internal SSD)	4.4h	345 GB	348 GB	3.3 GB	11 GB
Mac Mini M4 (16GB, external SSD)	7h	344 GB	346 GB	4 GB	10 GB

Full benchmark data: bitcoinresearchkit/benches

Recommended: mimalloc v3

Use mimalloc v3 as the global allocator to reduce memory usage.

Built On

brk_indexer for indexed blockchain data
brk_cohort for cohort filtering
brk_fetcher for price data
brk_reader for raw block access
brk_traversable for data export