mirror of
https://github.com/bitcoinresearchkit/brk.git
synced 2026-04-24 22:59:58 -07:00
100 lines
2.9 KiB
Markdown
100 lines
2.9 KiB
Markdown
# Architecture
|
|
|
|
## Overview
|
|
|
|
```
|
|
blk*.dat ──▶ Reader ──┐
|
|
├──▶ Indexer ──▶ Computer ──┐
|
|
RPC Client ──┤ ├──▶ Query ──▶ Server
|
|
└──▶ Mempool ───────────────┘
|
|
```
|
|
|
|
## Components
|
|
|
|
### Reader (`brk_reader`)
|
|
|
|
Parses Bitcoin Core's `blk*.dat` files directly, bypassing RPC for historical data. Supports parallel parsing and handles XOR-encoded blocks (Bitcoin Core 28+).
|
|
|
|
### RPC Client (`brk_rpc`)
|
|
|
|
Connects to Bitcoin Core for real-time data: new blocks, mempool transactions, and fee estimates. Thread-safe with automatic retries.
|
|
|
|
### Indexer (`brk_indexer`)
|
|
|
|
Builds lookup tables from parsed blocks:
|
|
- Transaction index (txid → block position)
|
|
- Address index (address → transactions, UTXOs)
|
|
- UTXO set tracking
|
|
- Output type classification (P2PKH, P2WPKH, P2TR, etc.)
|
|
|
|
### Computer (`brk_computer`)
|
|
|
|
Derives analytics from indexed data:
|
|
- Market metrics: realized cap, MVRV, SOPR, NVT
|
|
- Supply metrics: circulating, liquid, illiquid
|
|
- UTXO cohorts: by age, size, type
|
|
- Address cohorts: by balance, activity
|
|
- Pricing models: thermocap, realized price bands
|
|
|
|
Metrics are computed across multiple time resolutions (daily, weekly, monthly, by block height).
|
|
|
|
### Mempool (`brk_mempool`)
|
|
|
|
Monitors unconfirmed transactions:
|
|
- Fee rate distribution and estimation
|
|
- Projected block templates
|
|
- Address mempool activity
|
|
|
|
### Query (`brk_query`)
|
|
|
|
Unified interface to all data sources:
|
|
- Block and transaction lookups
|
|
- Address balances and history
|
|
- Computed metrics with range queries
|
|
- Mempool state
|
|
|
|
### Server (`brk_server`)
|
|
|
|
REST API exposing Query functionality:
|
|
- OpenAPI documentation (Scalar UI)
|
|
- JSON and CSV output formats
|
|
- ETag caching
|
|
- mempool.space compatible endpoints
|
|
|
|
## Data Flow
|
|
|
|
**Initial sync:**
|
|
1. Reader parses all `blk*.dat` files in parallel
|
|
2. Indexer processes blocks sequentially, building indexes
|
|
3. Computer derives metrics from indexed data
|
|
4. Server starts accepting requests
|
|
|
|
**Ongoing operation:**
|
|
1. RPC client polls for new blocks
|
|
2. Reader fetches block data
|
|
3. Indexer updates indexes
|
|
4. Computer recalculates affected metrics
|
|
5. Mempool monitors transaction pool
|
|
|
|
## Storage
|
|
|
|
Data is stored in `~/.brk/` (configurable):
|
|
|
|
```
|
|
~/.brk/
|
|
├── indexer/ # Transaction and address indexes (fjall)
|
|
├── computer/ # Computed metrics (vecdb)
|
|
└── config.toml # Configuration
|
|
```
|
|
|
|
Disk usage scales with blockchain size. Full index with metrics: ~400 GB.
|
|
|
|
## Dependencies
|
|
|
|
Built on:
|
|
- [`rust-bitcoin`](https://github.com/rust-bitcoin/rust-bitcoin) - Bitcoin primitives
|
|
- [`fjall`](https://github.com/fjall-rs/fjall) - LSM-tree storage
|
|
- [`vecdb`](https://github.com/anydb-rs/anydb) - Vector storage
|
|
- [`axum`](https://github.com/tokio-rs/axum) - HTTP server
|
|
- [`aide`](https://github.com/tamasfe/aide) - OpenAPI generation
|