From 7c86c803fa11a6634a53cad8556d868bc7093526 Mon Sep 17 00:00:00 2001 From: nym21 Date: Fri, 19 Dec 2025 00:26:44 +0100 Subject: [PATCH] changelog: update --- crates/brk_bencher/Cargo.toml | 1 + crates/brk_bencher_visualizer/Cargo.toml | 1 + crates/brk_computer/examples/full_bench.rs | 83 ++++++ docs/CHANGELOG.md | 316 +++++++++++++++++++++ 4 files changed, 401 insertions(+) create mode 100644 crates/brk_computer/examples/full_bench.rs diff --git a/crates/brk_bencher/Cargo.toml b/crates/brk_bencher/Cargo.toml index 04eba1b8b..1ceca31ba 100644 --- a/crates/brk_bencher/Cargo.toml +++ b/crates/brk_bencher/Cargo.toml @@ -6,6 +6,7 @@ edition.workspace = true license.workspace = true homepage.workspace = true repository.workspace = true +publish = false build = "build.rs" [dependencies] diff --git a/crates/brk_bencher_visualizer/Cargo.toml b/crates/brk_bencher_visualizer/Cargo.toml index cbe8b553f..877a5e515 100644 --- a/crates/brk_bencher_visualizer/Cargo.toml +++ b/crates/brk_bencher_visualizer/Cargo.toml @@ -6,6 +6,7 @@ edition.workspace = true license.workspace = true homepage.workspace = true repository.workspace = true +publish = false build = "build.rs" [dependencies] diff --git a/crates/brk_computer/examples/full_bench.rs b/crates/brk_computer/examples/full_bench.rs new file mode 100644 index 000000000..3cf6d98bf --- /dev/null +++ b/crates/brk_computer/examples/full_bench.rs @@ -0,0 +1,83 @@ +use std::{ + env, fs, + path::Path, + thread::{self, sleep}, + time::{Duration, Instant}, +}; + +use brk_bencher::Bencher; +use brk_computer::Computer; +use brk_error::Result; +use brk_fetcher::Fetcher; +use brk_indexer::Indexer; +use brk_iterator::Blocks; +use brk_reader::Reader; +use brk_rpc::{Auth, Client}; +use log::{debug, info}; +use mimalloc::MiMalloc; +use vecdb::Exit; + +#[global_allocator] +static GLOBAL: MiMalloc = MiMalloc; + +pub fn main() -> color_eyre::Result<()> { + color_eyre::install()?; + + // Can't increase main thread's stack size, thus we need to use another thread + thread::Builder::new() + .stack_size(512 * 1024 * 1024) + .spawn(run)? + .join() + .unwrap()?; + + Ok(()) +} + +fn run() -> Result<()> { + let bitcoin_dir = Client::default_bitcoin_path(); + // let bitcoin_dir = Path::new("/Volumes/WD_BLACK1/bitcoin"); + + let outputs_dir = Path::new(&env::var("HOME").unwrap()).join(".brk"); + // let outputs_dir = Path::new("/Volumes/WD_BLACK1/brk"); + fs::create_dir_all(&outputs_dir)?; + + brk_logger::init(Some(&outputs_dir.join("log")))?; + + let client = Client::new( + Client::default_url(), + Auth::CookieFile(bitcoin_dir.join(".cookie")), + )?; + + let reader = Reader::new(bitcoin_dir.join("blocks"), &client); + + let blocks = Blocks::new(&client, &reader); + + let mut indexer = Indexer::forced_import(&outputs_dir)?; + + let fetcher = Fetcher::import(true, None)?; + + let mut computer = Computer::forced_import(&outputs_dir, &indexer, Some(fetcher))?; + + let mut bencher = Bencher::from_cargo_env("brk", &outputs_dir)?; + bencher.start()?; + + let exit = Exit::new(); + exit.set_ctrlc_handler(); + let bencher_clone = bencher.clone(); + exit.register_cleanup(move || { + let _ = bencher_clone.stop(); + debug!("Bench stopped."); + }); + + loop { + let i = Instant::now(); + let starting_indexes = indexer.index(&blocks, &client, &exit)?; + info!("Done in {:?}", i.elapsed()); + + let i = Instant::now(); + computer.compute(&indexer, starting_indexes, &reader, &exit)?; + info!("Done in {:?}", i.elapsed()); + + sleep(Duration::from_secs(60)); + } +} diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index c556108f2..36bdd189e 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -4,6 +4,322 @@ All notable changes to the Bitcoin Research Kit (BRK) project will be documented > *This changelog was generated by Claude Code* +## [v0.1.0-alpha.0](https://github.com/bitcoinresearchkit/brk/releases/tag/v0.1.0-alpha.0) - 2025-12-18 + +### Breaking Changes +#### `brk_structs` → `brk_types` +- Renamed `brk_structs` crate to `brk_types` with complete reorganization of all Bitcoin data types into 150+ dedicated modules ([source](https://github.com/bitcoinresearchkit/brk/blob/v0.1.0-alpha.0/crates/brk_types/src/lib.rs)) + +#### `brk_parser` → `brk_reader` +- Renamed `brk_parser` crate to `brk_reader` with simplified scope focused exclusively on BLK file reading and XOR decryption ([source](https://github.com/bitcoinresearchkit/brk/blob/v0.1.0-alpha.0/crates/brk_reader/src/lib.rs)) +- Moved block iteration logic to new `brk_iterator` crate + +#### `brk_interface` +- Removed `brk_interface` crate entirely, replacing it with the more comprehensive `brk_query` crate + +#### `brk_store` +- Upgraded storage backend from fjall v2.11.2 to fjall v3.0.0-rc.6 with breaking API changes ([source](https://github.com/bitcoinresearchkit/brk/blob/v0.1.0-alpha.0/crates/brk_store/Cargo.toml)) + +#### `brk_indexer` +- Replaced `brk_parser::Parser` with `brk_iterator::Blocks` for block iteration ([source](https://github.com/bitcoinresearchkit/brk/blob/v0.1.0-alpha.0/crates/brk_indexer/src/lib.rs)) +- Renamed `OutputIndex` and `InputIndex` to `TxOutIndex` and `TxInIndex` throughout the codebase for clarity +- Changed address indexing from `addressindex->txoutindex` to `addressindex->txindex` and `addressindex->outpoint` patterns for more flexible queries + +#### `brk_computer` +- Replaced `brk_parser::Parser` with `brk_reader::Reader` for block file access +- Reorganized stateful computation architecture with new cohort-based grouping system +- Removed `states` module, integrating state management directly into `stateful` module + +### New Features + +#### `brk_mempool` (New Crate) +- Created comprehensive mempool monitoring crate with real-time transaction tracking and fee estimation ([source](https://github.com/bitcoinresearchkit/brk/blob/v0.1.0-alpha.0/crates/brk_mempool/src/lib.rs)) +- Implemented CPFP-aware block builder algorithm using dependency graph analysis and heap-based transaction selection ([source](https://github.com/bitcoinresearchkit/brk/blob/v0.1.0-alpha.0/crates/brk_mempool/src/block_builder/mod.rs)) +- Created `Selector` component that greedily selects highest fee-rate transactions while respecting ancestor dependencies +- Implemented `Partitioner` that groups selected transactions into projected blocks of ~1MB vsize each (8 blocks projected) +- Added `Package` abstraction for atomic transaction groups where children pay for parents (CPFP) +- Created `Graph` structure tracking transaction dependencies with ancestor fee/size aggregation +- Implemented `RecommendedFees` computation providing fee estimates for fastest, half-hour, hour, economy, and minimum confirmation targets ([source](https://github.com/bitcoinresearchkit/brk/blob/v0.1.0-alpha.0/crates/brk_mempool/src/projected_blocks/fees.rs)) +- Created `AddressTracker` for monitoring mempool transactions affecting specific addresses with add/remove tracking ([source](https://github.com/bitcoinresearchkit/brk/blob/v0.1.0-alpha.0/crates/brk_mempool/src/addresses.rs)) +- Implemented `EntryPool` with slot-based entry management using generation counters for efficient reuse +- Added `Snapshot` system capturing point-in-time mempool state with per-block statistics (tx count, vsize, fees, fee range) ([source](https://github.com/bitcoinresearchkit/brk/blob/v0.1.0-alpha.0/crates/brk_mempool/src/projected_blocks/snapshot.rs)) +- Created `TxStore` for mempool transaction storage with prefix-based lookups using TxidPrefix +- Implemented `MempoolInfo` tracking aggregate statistics: tx count, total vsize, total fees +- Added automatic synchronization loop with 1-second update interval and rate-limited rebuilds (minimum 1 second between rebuilds) ([source](https://github.com/bitcoinresearchkit/brk/blob/v0.1.0-alpha.0/crates/brk_mempool/src/sync.rs)) +- Created dirty flag mechanism for efficient change detection and rebuild triggering + +#### `brk_query` (New Crate) +- Created unified query interface combining indexer, computer, reader, and mempool access into single `Query` struct ([source](https://github.com/bitcoinresearchkit/brk/blob/v0.1.0-alpha.0/crates/brk_query/src/lib.rs)) +- Implemented address query methods ([source](https://github.com/bitcoinresearchkit/brk/blob/v0.1.0-alpha.0/crates/brk_query/src/impl/address.rs)): + - `address()` - Returns `AddressStats` with chain stats (funded/spent txo counts and sums, tx count) and optional mempool stats + - `address_txids()` - Returns paginated transaction IDs for an address with `after_txid` cursor support + - `address_utxos()` - Returns all unspent outputs for an address with full status information + - `address_mempool_txids()` - Returns up to 50 unconfirmed transaction IDs affecting an address + - `resolve_address()` - Helper converting address string to output type and type_index +- Implemented block query methods ([source](https://github.com/bitcoinresearchkit/brk/blob/v0.1.0-alpha.0/crates/brk_query/src/impl/block/)): + - `block()` / `block_by_height()` - Returns `BlockInfo` with hash, height, timestamp, difficulty, size, weight, tx count + - `blocks()` - Returns last 10 blocks, optionally starting from a specific height + - `block_status()` - Returns `BlockStatus` with in_best_chain flag, height, and next_best hash + - `block_timestamp()` - Returns `BlockTimestamp` for timestamp-based block lookup + - `block_txids()` - Returns all transaction IDs in a block + - `block_txs()` - Returns paginated full transactions (25 per page) + - `block_txid_at_index()` - Returns single txid at specific index within block + - `block_raw()` - Returns raw block bytes read directly from blk file with XOR decoding + - `block_by_timestamp()` - Finds block closest to given UNIX timestamp using binary search +- Implemented transaction query methods ([source](https://github.com/bitcoinresearchkit/brk/blob/v0.1.0-alpha.0/crates/brk_query/src/impl/transaction.rs)): + - `transaction()` - Returns full `Transaction` with inputs (including prevout values), outputs, fee, status; checks mempool first for unconfirmed txs + - `transaction_by_index()` - Internal method reading tx from blk file and reconstructing full transaction object + - `transaction_status()` - Returns `TxStatus` with confirmed flag, block height/hash/time + - `transaction_hex()` - Returns raw transaction as hex string + - `outspend()` - Returns `TxOutspend` for single output with spending tx details if spent + - `outspends()` - Returns spend status for all outputs in a transaction + - `outspend_details()` - Helper computing spending txid, vin, and status from txinindex +- Implemented mempool query methods ([source](https://github.com/bitcoinresearchkit/brk/blob/v0.1.0-alpha.0/crates/brk_query/src/impl/mempool.rs)): + - `mempool_info()` - Returns `MempoolInfo` with aggregate statistics + - `mempool_txids()` - Returns all transaction IDs currently in mempool + - `recommended_fees()` - Returns `RecommendedFees` with fee rate targets + - `mempool_blocks()` - Returns `Vec` with projected block statistics +- Implemented mining query methods ([source](https://github.com/bitcoinresearchkit/brk/blob/v0.1.0-alpha.0/crates/brk_query/src/impl/mining/)): + - `mining_pools()` - Returns `PoolsSummary` with pool statistics for time period (24h, 3d, 1w, 1m, 3m, 6m, 1y, 2y, 3y) + - `all_pools()` - Returns `Vec` with all 166 known mining pools + - `pool_detail()` - Returns `PoolDetail` with block counts/shares for all time, 24h, and 1 week + - `hashrate()` - Returns `HashrateSummary` with network hashrate and difficulty data + - `difficulty_adjustment()` - Returns current `DifficultyAdjustment` with epoch progress and retarget estimate + - `difficulty_adjustments()` - Returns historical `Vec` (timestamp, height, difficulty, change%) + - `block_fees()` - Returns `Vec` with average fees per time period + - `block_rewards()` - Returns `Vec` with average coinbase rewards + - `block_sizes_weights()` - Returns `BlockSizesWeights` with average sizes and weights + - `reward_stats()` - Returns `RewardStats` for last N blocks +- Implemented metrics query methods ([source](https://github.com/bitcoinresearchkit/brk/blob/v0.1.0-alpha.0/crates/brk_query/src/impl/metrics.rs)): + - `metric_count()` - Returns count of available metrics + - `indexes()` - Returns all available index types with accepted aliases + - `metrics()` - Returns paginated list of metrics with offset/limit support + - `metrics_catalog()` - Returns hierarchical `TreeNode` of all metrics organized by category + - `match_metric()` - Fuzzy search for metrics by name with configurable result limit + - `metric_to_indexes()` - Returns supported indexes for a specific metric + - `metric_data()` - Returns `MetricData` with values for metric/index combination and date range +- Added async query support via optional `tokio` feature for non-blocking database access + +#### `brk_iterator` (New Crate) +- Created `Blocks` factory for iterating over Bitcoin blocks with smart source selection ([source](https://github.com/bitcoinresearchkit/brk/blob/v0.1.0-alpha.0/crates/brk_iterator/src/lib.rs)) +- Implemented three source modes: + - `Smart` - Auto-selects RPC for ranges ≤10 blocks, Reader for larger ranges + - `Rpc` - Always uses Bitcoin Core RPC for block retrieval + - `Reader` - Always uses BLK file reader for block retrieval +- Created flexible range specifications: + - `range(start, end)` - Iterate over specific block range (inclusive) + - `start(height)` - Iterate from height to chain tip + - `end(height)` - Iterate from genesis to height + - `last(n)` - Iterate over last n blocks + - `after(hash)` - Iterate after a specific block hash (for incremental syncing) +- Implemented `BlockIterator` with chain reorganization detection that stops iteration on prev_hash discontinuity +- Added `BlockRange` enum for type-safe range specification +- Created `State` struct managing iteration progress with RPC or Reader backend + +#### `brk_rpc` (New Crate) +- Created Bitcoin Core RPC client wrapper with automatic retry logic and configurable timeouts ([source](https://github.com/bitcoinresearchkit/brk/blob/v0.1.0-alpha.0/crates/brk_rpc/src/lib.rs)) +- Implemented comprehensive RPC methods: + - `get_blockchain_info()` - Chain state and sync status + - `get_block()` / `get_block_count()` / `get_last_height()` - Block retrieval and chain height + - `get_block_hash()` / `get_block_header()` / `get_block_info()` / `get_block_header_info()` - Block metadata + - `get_transaction()` / `get_raw_transaction()` / `get_raw_transaction_hex()` - Transaction retrieval + - `get_tx_out()` - UTXO lookup with optional mempool inclusion + - `get_raw_mempool()` - Mempool transaction IDs + - `get_raw_mempool_verbose()` - Returns `Vec` with fee/ancestor data for all mempool entries + - `get_mempool_transaction()` - Returns `TxWithHex` with full transaction data including resolved prevouts + - `is_in_main_chain()` - Check if block is in best chain + - `get_closest_valid_height()` - Find closest valid ancestor for reorg recovery + - `wait_for_synced_node()` - Block until node headers == blocks +- Created `ClientInner` with retry mechanism (default 1M retries, 1s delay) ([source](https://github.com/bitcoinresearchkit/brk/blob/v0.1.0-alpha.0/crates/brk_rpc/src/inner.rs)) +- Added default path resolution for macOS (`~/Library/Application Support/Bitcoin`) and Linux (`~/.bitcoin`) + +#### `brk_types` (New Crate) +- Created comprehensive type library with 150+ Bitcoin-related types organized into dedicated modules ([source](https://github.com/bitcoinresearchkit/brk/blob/v0.1.0-alpha.0/crates/brk_types/src/lib.rs)) +- Added mempool types: `MempoolBlock` (tx_count, total_vsize, total_fee, fee_range), `MempoolEntryInfo`, `MempoolInfo`, `RecommendedFees` (fastest_fee, half_hour_fee, hour_fee, economy_fee, minimum_fee) +- Created API parameter types with serde deserialization: `AddressParam`, `AddressTxidsParam`, `BlockHashParam`, `BlockCountParam`, `HeightParam`, `TxidParam`, `TxidVout`, `LimitParam`, `TimePeriodParam`, `PoolSlugParam`, `TimestampParam`, `ValidateAddressParam` +- Added mining types: `Pool` (id, name, slug, addresses, tags, link), `PoolDetail`, `PoolDetailInfo`, `PoolInfo`, `PoolStats`, `PoolBlockCounts`, `PoolBlockShares`, `PoolsSummary`, `HashrateSummary`, `HashrateEntry`, `DifficultyAdjustment`, `DifficultyAdjustmentEntry`, `DifficultyEntry`, `DifficultyEpoch`, `RewardStats` +- Implemented metric types: `Metric`, `MetricCount`, `MetricData`, `MetricParam`, `Metrics`, `MetricSelection`, `MetricSelectionLegacy`, `MetricWithIndex`, `PaginatedMetrics`, `DataRange`, `DataRangeFormat` +- Added block types: `BlockInfo`, `BlockStatus`, `BlockTimestamp`, `BlockSizesWeights`, `BlockFeesEntry`, `BlockFeeRatesEntry`, `BlockRewardsEntry`, `BlockSizeEntry`, `BlockWeightEntry` +- Created transaction types: `Transaction`, `TxIn`, `TxOut`, `TxStatus`, `TxOutspend`, `TxWithHex`, `TxIndex`, `TxInIndex`, `TxOutIndex` +- Added address types: `Address`, `AddressBytes`, `AddressHash`, `AddressChainStats`, `AddressMempoolStats`, `AddressStats`, `AddressValidation`, `AnyAddressIndex`, `EmptyAddressIndex`, `LoadedAddressIndex`, with separate types for each output type (P2PKH, P2SH, P2WPKH, P2WSH, P2TR, P2PK33, P2PK65, P2A, P2MS, OpReturn, Unknown) +- Implemented index types: `Index` enum (Height, DateIndex, WeekIndex, MonthIndex, QuarterIndex, SemesterIndex, YearIndex, DecadeIndex, TxIndex, P2PKHIndex, etc.), `IndexInfo` +- Added stored numeric types: `StoredBool`, `StoredF32`, `StoredF64`, `StoredI16`, `StoredU8`, `StoredU16`, `StoredU32`, `StoredU64`, `StoredString` +- Created utility types: `Health`, `TreeNode`, `Unit`, `Pagination`, `PaginationIndex`, `Limit`, `OutPoint`, `Utxo`, `Vin`, `Vout` + +#### `brk_grouper` (New Crate) +- Created cohort filtering and grouping infrastructure for UTXO and address analysis ([source](https://github.com/bitcoinresearchkit/brk/blob/v0.1.0-alpha.0/crates/brk_grouper/src/lib.rs)) +- Implemented filter modules: + - `ByAddressType` - Filter by output type (P2PKH, P2SH, P2WPKH, etc.) + - `ByAgeRange` - Filter by UTXO age in blocks + - `ByAmountRange` - Filter by satoshi value range + - `ByEpoch` - Filter by halving epoch + - `ByTerm` - Filter by holder term classification (STH/LTH) + - `ByYear` - Filter by creation year + - `ByMinAge` / `ByMaxAge` - Filter by minimum/maximum UTXO age + - `ByGeAmount` / `ByLtAmount` - Filter by amount thresholds + - `BySpendableType` / `ByUnspendableType` - Filter by spendability + - `ByAnyAddress` - Filter by specific address membership + - `ByType` / `ByValue` - Generic type and value filters +- Created `AmountFilter` and `TimeFilter` base traits for composable filtering +- Implemented `CohortContext` for managing filter state during cohort analysis +- Added `Filtered` wrapper for filtered iterators with lazy evaluation +- Created `StateLevel` enum for controlling computation granularity +- Implemented `Term` type for STH (Short Term Holder) / LTH (Long Term Holder) classification +- Added `AddressCohort` and `UtxoCohort` traits for cohort membership testing + +#### `brk_traversable` and `brk_traversable_derive` (New Crates) +- Created `Traversable` trait for vector tree navigation ([source](https://github.com/bitcoinresearchkit/brk/blob/v0.1.0-alpha.0/crates/brk_traversable/src/lib.rs)): + - `to_tree_node()` - Converts struct to hierarchical `TreeNode` representation + - `iter_any_exportable()` - Returns iterator over all exportable vectors in the tree +- Implemented trait for all vecdb vector types: `BytesVec`, `ZeroCopyVec`, `PcoVec`, `LZ4Vec`, `ZstdVec`, `EagerVec`, `LazyVecFrom1/2/3` +- Added implementations for container types: `Box`, `Option`, `BTreeMap` +- Created derive macro for automatic `Traversable` implementation on structs ([source](https://github.com/bitcoinresearchkit/brk/blob/v0.1.0-alpha.0/crates/brk_traversable_derive/src/lib.rs)) +- Added `TreeNode` type with `Leaf(String)` and `Branch(BTreeMap)` variants + +#### `brk_bencher` and `brk_bencher_visualizer` (New Crates) +- Created benchmarking infrastructure with multi-metric monitoring ([source](https://github.com/bitcoinresearchkit/brk/blob/v0.1.0-alpha.0/crates/brk_bencher/src/lib.rs)): + - `DiskMonitor` - Tracks directory size changes over time + - `MemoryMonitor` - Tracks process RSS memory using system APIs + - `IoMonitor` - Tracks read/write bytes using process I/O statistics + - `ProgressionMonitor` - Tracks computation progress via log message pattern matching +- Implemented `Bencher` struct with: + - Automatic benchmark directory creation under `workspace_root/benches/{crate_name}/{timestamp}/` + - Background monitoring thread with 5-second sample interval + - Logger hook registration for progress tracking + - CSV output for all metrics with millisecond timestamps +- Created `brk_bencher_visualizer` for generating SVG charts from benchmark data ([source](https://github.com/bitcoinresearchkit/brk/blob/v0.1.0-alpha.0/crates/brk_bencher_visualizer/src/lib.rs)): + - `Chart` struct for SVG chart generation with configurable dimensions + - `Data` module for CSV parsing and data transformation + - `Format` module for human-readable byte/number formatting + - Command-line tool for batch chart generation from benchmark directories + +#### `brk_reader` (Renamed from brk_parser) +- Implemented thread-safe BLK file reader with parallel block decoding ([source](https://github.com/bitcoinresearchkit/brk/blob/v0.1.0-alpha.0/crates/brk_reader/src/lib.rs)) +- Created multi-stage pipeline: + - Stage 1: Sequential BLK file reading with magic byte detection and XOR decoding + - Stage 2: Parallel block parsing using dedicated rayon thread pool (half of available threads) + - Stage 3: Block ordering with future block buffering for out-of-order handling +- Added binary search optimization for finding starting BLK file index when parsing from specific heights +- Created `read_raw_bytes()` method for reading arbitrary byte ranges from blk files with XOR decoding +- Implemented chain continuity verification that detects prev_hash discontinuities and logs errors +- Added `BlkIndexToBlkPath` mapping with automatic BLK file discovery and caching +- Created `XORBytes` and `XORIndex` types for efficient XOR decryption state management + +#### `brk_server` - REST API +- Added comprehensive OpenAPI documentation using aide with Scalar UI at `/api` endpoint ([source](https://github.com/bitcoinresearchkit/brk/blob/v0.1.0-alpha.0/crates/brk_server/src/api/openapi.rs)) +- Created Address API endpoints ([source](https://github.com/bitcoinresearchkit/brk/blob/v0.1.0-alpha.0/crates/brk_server/src/api/addresses/mod.rs)): + - `GET /api/address/{address}` - Address information with chain and mempool stats + - `GET /api/address/{address}/txs` - Paginated transaction IDs with `after_txid` and `limit` params + - `GET /api/address/{address}/utxo` - Unspent transaction outputs + - `GET /api/address/{address}/txs/mempool` - Unconfirmed transactions (max 50) + - `GET /api/validate-address/{address}` - Address validation with type detection +- Created Block API endpoints ([source](https://github.com/bitcoinresearchkit/brk/blob/v0.1.0-alpha.0/crates/brk_server/src/api/blocks/mod.rs)): + - `GET /api/blocks` - Last 10 blocks + - `GET /api/blocks/{height}` - 10 blocks backwards from height + - `GET /api/block/{hash}` - Block information by hash + - `GET /api/block/{hash}/status` - Block status (in_best_chain, next_best) + - `GET /api/block/{hash}/txids` - All transaction IDs in block + - `GET /api/block/{hash}/txs/{start_index}` - Paginated transactions (25 per page) + - `GET /api/block/{hash}/txid/{index}` - Single txid at index + - `GET /api/block/{hash}/raw` - Raw block bytes + - `GET /api/block-height/{height}` - Block by height + - `GET /api/v1/mining/blocks/timestamp/{timestamp}` - Block by timestamp +- Created Transaction API endpoints ([source](https://github.com/bitcoinresearchkit/brk/blob/v0.1.0-alpha.0/crates/brk_server/src/api/transactions/mod.rs)): + - `GET /api/tx/{txid}` - Full transaction data with inputs/outputs + - `GET /api/tx/{txid}/status` - Confirmation status + - `GET /api/tx/{txid}/hex` - Raw transaction hex + - `GET /api/tx/{txid}/outspend/{vout}` - Single output spend status + - `GET /api/tx/{txid}/outspends` - All output spend statuses +- Created Mempool API endpoints ([source](https://github.com/bitcoinresearchkit/brk/blob/v0.1.0-alpha.0/crates/brk_server/src/api/mempool/mod.rs)): + - `GET /api/mempool/info` - Mempool statistics (tx count, vsize, fees) + - `GET /api/mempool/txids` - All mempool transaction IDs + - `GET /api/v1/fees/recommended` - Recommended fee rates for confirmation targets + - `GET /api/v1/fees/mempool-blocks` - Projected blocks with fee statistics +- Created Mining API endpoints ([source](https://github.com/bitcoinresearchkit/brk/blob/v0.1.0-alpha.0/crates/brk_server/src/api/mining/mod.rs)): + - `GET /api/v1/difficulty-adjustment` - Current difficulty adjustment info + - `GET /api/v1/mining/pools` - List all known mining pools + - `GET /api/v1/mining/pools/{time_period}` - Pool statistics for time period + - `GET /api/v1/mining/pool/{slug}` - Detailed pool information + - `GET /api/v1/mining/hashrate` / `GET /api/v1/mining/hashrate/{time_period}` - Network hashrate + - `GET /api/v1/mining/difficulty-adjustments` / `GET /api/v1/mining/difficulty-adjustments/{time_period}` - Historical adjustments + - `GET /api/v1/mining/blocks/fees/{time_period}` - Block fee statistics + - `GET /api/v1/mining/blocks/rewards/{time_period}` - Block reward statistics + - `GET /api/v1/mining/blocks/sizes-weights/{time_period}` - Block size/weight statistics + - `GET /api/v1/mining/reward-stats/{block_count}` - Reward stats for last N blocks +- Created Metrics API endpoints ([source](https://github.com/bitcoinresearchkit/brk/blob/v0.1.0-alpha.0/crates/brk_server/src/api/metrics/mod.rs)): + - `GET /api/metrics/count` - Total metric count + - `GET /api/metrics/indexes` - Available indexes with aliases + - `GET /api/metrics/list` - Paginated metric list + - `GET /api/metrics/catalog` - Hierarchical metric tree + - `GET /api/metrics/search/{metric}` - Fuzzy metric search + - `GET /api/metric/{metric}` - Supported indexes for metric + - `GET /api/metric/{metric}/{index}` - Metric data with date range filtering + - `GET /api/metrics/bulk` - Bulk metric query (max 650KB response weight) + - `GET /api/vecs/{variant}` - Legacy variant endpoint (deprecated, sunset 2027-01-01) + - `GET /api/vecs/query` - Legacy query endpoint (deprecated) +- Created Server API endpoints: + - `GET /version` - API version + - `GET /health` - Health check with timestamp + - `GET /api.json` - OpenAPI specification + - `GET /api` - Scalar API documentation UI +- Implemented `CacheStrategy` enum for response caching: `Static` (immutable), `Height` (ETag based on block height), `MaxAge(seconds)` (Cache-Control max-age) +- Added response transformations in `extended` module: `HeaderMapExtended`, `ResponseExtended`, `TransformResponseExtended` + +#### `brk_computer` +- Achieved ~3x computation speed improvement through optimized vecdb iterators and major stateful processing optimizations +- Added `Traversable` derive macro support for automatic vector tree generation +- Implemented parallel import for indexes, fetched data, and blks vectors using 512MB stack-size threads ([source](https://github.com/bitcoinresearchkit/brk/blob/v0.1.0-alpha.0/crates/brk_computer/src/lib.rs)) +- Created new `blks` module with `txindex_to_position` and `txindex_to_len` vectors for transaction location tracking + +#### `brk_indexer` +- Achieved ~4x indexing speed improvement (~12h → ~3h for full chain) through parallel TXID computation, parallel input/output processing, efficient same-block spend detection, fjall v3, and mimalloc +- Implemented parallel import for vecs and stores using scoped threads ([source](https://github.com/bitcoinresearchkit/brk/blob/v0.1.0-alpha.0/crates/brk_indexer/src/lib.rs)) +- Added `Readers` struct providing typed vector iterators for efficient batch data access +- Created `Processor` for block processing with address and transaction indexing +- Added automatic file handle limit increase at startup (minimum 10,000 via rlimit) + +#### `brk_binder` +- Added Rust binding generator for type-safe metric access alongside existing JavaScript generator ([source](https://github.com/bitcoinresearchkit/brk/blob/v0.1.0-alpha.0/crates/brk_binder/src/rust.rs)) + +### Internal Changes +#### `brk_indexer` +- Split indexer code into dedicated modules: `constants`, `indexes`, `processor`, `readers`, `stores`, `vecs` +- Moved address vector handling into nested `vecs/address.rs` module +- Separated block, transaction, txin, and txout vectors into dedicated submodules + +#### `brk_computer` +- Major refactoring of stateful computation architecture with new module structure +- Split `cohorts` into `address.rs`, `address_cohorts.rs`, `traits.rs`, `utxo.rs`, and `utxo_cohorts/` (mod, receive, send, tick_tock) +- Created `compute` module with `aggregates`, `block_loop`, `context`, `readers`, `recover`, and `write` submodules +- Reorganized `metrics` into `activity`, `config`, `price_paid`, `realized`, `relative`, `supply`, and `unrealized` submodules +- Added `process` module with `address_updates`, `cache`, `inputs`, `lookup`, `outputs`, `range_map`, `received`, `sent`, `tx_counts`, `with_source` +- Created `states` module with `address_cohort`, `block`, `cohort`, `fenwick`, `price_buckets`, `price_to_amount`, `realized`, `supply`, `transacted`, `unrealized`, `utxo_cohort` +- Added `address` module in stateful with `address_count`, `any_address_indexes`, `data`, `height_type_vec`, `type_index_map`, `type_vec` +- Created `addresstype` module with `addresscount`, `height_to_addresscount`, `height_to_vec`, `indexes_to_addresscount`, `typeindex_tree`, `vec` + +#### `brk_fetcher` +- Restructured fetcher into dedicated source modules: `binance.rs`, `brk.rs`, `kraken.rs` +- Added `retry.rs` module for fetch retry logic with exponential backoff +- Created `ohlc.rs` module for OHLC data aggregation and transformation +- Added `source.rs` module for abstracting data source selection + +#### `brk_store` +- Simplified store implementation to use `brk_types` instead of `brk_structs` +- Added `rustc-hash` for faster FxHashMap operations + +#### `brk_logger` +- Added hook registration system via `register_hook()` for external log message monitoring ([source](https://github.com/bitcoinresearchkit/brk/blob/v0.1.0-alpha.0/crates/brk_logger/src/lib.rs)) + +### Documentation +#### Benchmarks +- Added benchmark data and visualizations for `brk_computer` and `brk_indexer` across multiple hardware configurations +- Created benchmark directories with disk, I/O, memory, and progress CSV/SVG files: + - `benches/brk_computer/` - Computer benchmark visualizations + - `benches/brk_indexer/mac_mini_m4_16gb_ext_ssd/` - Mac Mini M4 with external SSD + - `benches/brk_indexer/mbp_m3_pro_36gb_int_ssd/` - MacBook Pro M3 Pro with internal SSD + +[View changes](https://github.com/bitcoinresearchkit/brk/compare/v0.0.111...v0.1.0-alpha.0) + ## [v0.0.111](https://github.com/bitcoinresearchkit/brk/releases/tag/v0.0.111) - 2025-10-03 ### Breaking Changes