From 4840e564f45961b3f4da2f48fd60017f12295c7f Mon Sep 17 00:00:00 2001 From: nym21 Date: Thu, 2 Apr 2026 23:49:01 +0200 Subject: [PATCH] server: moved params from brk_types --- crates/brk_query/src/impl/mempool.rs | 6 +- crates/brk_query/src/impl/tx.rs | 42 ++++---- .../brk_server/src/api/mempool_space/addrs.rs | 11 +- .../src/api/mempool_space/blocks.rs | 11 +- .../src/api/mempool_space/general.rs | 8 +- .../src/api/mempool_space/mining.rs | 10 +- .../src/api/mempool_space/transactions.rs | 40 +++---- crates/brk_server/src/api/metrics/mod.rs | 8 +- crates/brk_server/src/api/series/mod.rs | 11 +- crates/brk_server/src/lib.rs | 1 + .../src/params}/addr_param.rs | 2 +- .../src/params}/addr_txids_param.rs | 2 +- .../src/params}/block_count_param.rs | 0 .../src/params}/blockhash_param.rs | 2 +- .../src/params}/blockhash_start_index.rs | 2 +- .../src/params}/blockhash_tx_index.rs | 2 +- .../src/params}/cost_basis_params.rs | 28 +---- .../src/params}/height_param.rs | 2 +- .../src/params}/limit_param.rs | 2 +- crates/brk_server/src/params/mod.rs | 35 ++++++ .../src/params}/pool_slug_param.rs | 2 +- .../src/params}/series_param.rs | 2 +- .../src/params}/time_period_param.rs | 2 +- .../src/params}/timestamp_param.rs | 2 +- .../src/params}/txid_param.rs | 2 +- .../src/params}/txid_vout.rs | 2 +- .../src/params}/txids_param.rs | 2 +- .../src/params}/validate_addr_param.rs | 0 crates/brk_types/src/cohort.rs | 28 +++++ crates/brk_types/src/lib.rs | 36 +------ modules/brk-client/index.js | 101 +++++++++--------- packages/brk_client/brk_client/__init__.py | 75 ++++++++++++- website/styles/panes/explorer.css | 32 ++++++ website/styles/variables.css | 1 + 34 files changed, 315 insertions(+), 197 deletions(-) rename crates/{brk_types/src => brk_server/src/params}/addr_param.rs (88%) rename crates/{brk_types/src => brk_server/src/params}/addr_txids_param.rs (91%) rename crates/{brk_types/src => brk_server/src/params}/block_count_param.rs (100%) rename crates/{brk_types/src => brk_server/src/params}/blockhash_param.rs (84%) rename crates/{brk_types/src => brk_server/src/params}/blockhash_start_index.rs (88%) rename crates/{brk_types/src => brk_server/src/params}/blockhash_tx_index.rs (88%) rename crates/{brk_types/src => brk_server/src/params}/cost_basis_params.rs (56%) rename crates/{brk_types/src => brk_server/src/params}/height_param.rs (85%) rename crates/{brk_types/src => brk_server/src/params}/limit_param.rs (87%) create mode 100644 crates/brk_server/src/params/mod.rs rename crates/{brk_types/src => brk_server/src/params}/pool_slug_param.rs (88%) rename crates/{brk_types/src => brk_server/src/params}/series_param.rs (84%) rename crates/{brk_types/src => brk_server/src/params}/time_period_param.rs (87%) rename crates/{brk_types/src => brk_server/src/params}/timestamp_param.rs (90%) rename crates/{brk_types/src => brk_server/src/params}/txid_param.rs (86%) rename crates/{brk_types/src => brk_server/src/params}/txid_vout.rs (89%) rename crates/{brk_types/src => brk_server/src/params}/txids_param.rs (97%) rename crates/{brk_types/src => brk_server/src/params}/validate_addr_param.rs (100%) create mode 100644 crates/brk_types/src/cohort.rs diff --git a/crates/brk_query/src/impl/mempool.rs b/crates/brk_query/src/impl/mempool.rs index 3d0135376..f6291767a 100644 --- a/crates/brk_query/src/impl/mempool.rs +++ b/crates/brk_query/src/impl/mempool.rs @@ -3,7 +3,7 @@ use std::cmp::Ordering; use brk_error::{Error, Result}; use brk_types::{ CpfpEntry, CpfpInfo, FeeRate, MempoolBlock, MempoolInfo, MempoolRecentTx, RecommendedFees, - Txid, TxidParam, TxidPrefix, Weight, + Txid, TxidPrefix, Weight, }; use crate::Query; @@ -51,10 +51,10 @@ impl Query { Ok(mempool.get_txs().recent().to_vec()) } - pub fn cpfp(&self, TxidParam { txid }: TxidParam) -> Result { + pub fn cpfp(&self, txid: &Txid) -> Result { let mempool = self.mempool().ok_or(Error::MempoolNotAvailable)?; let entries = mempool.get_entries(); - let prefix = TxidPrefix::from(&txid); + let prefix = TxidPrefix::from(txid); let entry = entries .get(&prefix) diff --git a/crates/brk_query/src/impl/tx.rs b/crates/brk_query/src/impl/tx.rs index 3008317cc..6e300b1f0 100644 --- a/crates/brk_query/src/impl/tx.rs +++ b/crates/brk_query/src/impl/tx.rs @@ -2,23 +2,23 @@ use bitcoin::hex::DisplayHex; use brk_error::{Error, Result}; use brk_types::{ BlockHash, Height, MerkleProof, Timestamp, TxInIndex, TxIndex, TxOutspend, TxStatus, - Transaction, Txid, TxidParam, TxidPrefix, Vin, Vout, + Transaction, Txid, TxidPrefix, Vin, Vout, }; use vecdb::{ReadableVec, VecIndex}; use crate::Query; impl Query { - pub fn transaction(&self, TxidParam { txid }: TxidParam) -> Result { + pub fn transaction(&self, txid: &Txid) -> Result { // First check mempool for unconfirmed transactions if let Some(mempool) = self.mempool() - && let Some(tx_with_hex) = mempool.get_txs().get(&txid) + && let Some(tx_with_hex) = mempool.get_txs().get(txid) { return Ok(tx_with_hex.tx().clone()); } // Look up confirmed transaction by txid prefix - let prefix = TxidPrefix::from(&txid); + let prefix = TxidPrefix::from(txid); let indexer = self.indexer(); let Ok(Some(tx_index)) = indexer .stores @@ -32,16 +32,16 @@ impl Query { self.transaction_by_index(tx_index) } - pub fn transaction_status(&self, TxidParam { txid }: TxidParam) -> Result { + pub fn transaction_status(&self, txid: &Txid) -> Result { // First check mempool for unconfirmed transactions if let Some(mempool) = self.mempool() - && mempool.get_txs().contains_key(&txid) + && mempool.get_txs().contains_key(txid) { return Ok(TxStatus::UNCONFIRMED); } // Look up confirmed transaction by txid prefix - let prefix = TxidPrefix::from(&txid); + let prefix = TxidPrefix::from(txid); let indexer = self.indexer(); let Ok(Some(tx_index)) = indexer .stores @@ -70,8 +70,8 @@ impl Query { }) } - pub fn transaction_raw(&self, TxidParam { txid }: TxidParam) -> Result> { - let prefix = TxidPrefix::from(&txid); + pub fn transaction_raw(&self, txid: &Txid) -> Result> { + let prefix = TxidPrefix::from(txid); let indexer = self.indexer(); let Ok(Some(tx_index)) = indexer .stores @@ -84,16 +84,16 @@ impl Query { self.transaction_raw_by_index(tx_index) } - pub fn transaction_hex(&self, TxidParam { txid }: TxidParam) -> Result { + pub fn transaction_hex(&self, txid: &Txid) -> Result { // First check mempool for unconfirmed transactions if let Some(mempool) = self.mempool() - && let Some(tx_with_hex) = mempool.get_txs().get(&txid) + && let Some(tx_with_hex) = mempool.get_txs().get(txid) { return Ok(tx_with_hex.hex().to_string()); } // Look up confirmed transaction by txid prefix - let prefix = TxidPrefix::from(&txid); + let prefix = TxidPrefix::from(txid); let indexer = self.indexer(); let Ok(Some(tx_index)) = indexer .stores @@ -107,24 +107,24 @@ impl Query { self.transaction_hex_by_index(tx_index) } - pub fn outspend(&self, txid: TxidParam, vout: Vout) -> Result { + pub fn outspend(&self, txid: &Txid, vout: Vout) -> Result { let all = self.outspends(txid)?; all.into_iter() .nth(usize::from(vout)) .ok_or(Error::OutOfRange("Output index out of range".into())) } - pub fn outspends(&self, TxidParam { txid }: TxidParam) -> Result> { + pub fn outspends(&self, txid: &Txid) -> Result> { // Mempool outputs are unspent in on-chain terms if let Some(mempool) = self.mempool() - && let Some(tx_with_hex) = mempool.get_txs().get(&txid) + && let Some(tx_with_hex) = mempool.get_txs().get(txid) { let output_count = tx_with_hex.tx().output.len(); return Ok(vec![TxOutspend::UNSPENT; output_count]); } // Look up confirmed transaction - let prefix = TxidPrefix::from(&txid); + let prefix = TxidPrefix::from(txid); let indexer = self.indexer(); let Ok(Some(tx_index)) = indexer .stores @@ -248,12 +248,12 @@ impl Query { self.client().send_raw_transaction(hex) } - pub fn merkleblock_proof(&self, txid_param: TxidParam) -> Result { - let (_, height) = self.resolve_tx(&txid_param.txid)?; + pub fn merkleblock_proof(&self, txid: &Txid) -> Result { + let (_, height) = self.resolve_tx(txid)?; let header = self.read_block_header(height)?; let txids = self.block_txids_by_height(height)?; - let target: bitcoin::Txid = (&txid_param.txid).into(); + let target: bitcoin::Txid = txid.into(); let btxids: Vec = txids.iter().map(bitcoin::Txid::from).collect(); let mb = bitcoin::MerkleBlock::from_header_txids_with_predicate(&header, &btxids, |t| { *t == target @@ -261,8 +261,8 @@ impl Query { Ok(bitcoin::consensus::encode::serialize_hex(&mb)) } - pub fn merkle_proof(&self, txid_param: TxidParam) -> Result { - let (tx_index, height) = self.resolve_tx(&txid_param.txid)?; + pub fn merkle_proof(&self, txid: &Txid) -> Result { + let (tx_index, height) = self.resolve_tx(txid)?; let first_tx = self .indexer() .vecs diff --git a/crates/brk_server/src/api/mempool_space/addrs.rs b/crates/brk_server/src/api/mempool_space/addrs.rs index d3f36a88f..f227123ac 100644 --- a/crates/brk_server/src/api/mempool_space/addrs.rs +++ b/crates/brk_server/src/api/mempool_space/addrs.rs @@ -5,12 +5,13 @@ use axum::{ response::Redirect, routing::get, }; -use brk_types::{ - AddrParam, AddrStats, AddrTxidsParam, AddrValidation, Transaction, Txid, Utxo, - ValidateAddrParam, Version, -}; +use brk_types::{AddrStats, AddrValidation, Transaction, Txid, Utxo, Version}; -use crate::{AppState, CacheStrategy, extended::TransformResponseExtended}; +use crate::{ + AppState, CacheStrategy, + extended::TransformResponseExtended, + params::{AddrParam, AddrTxidsParam, ValidateAddrParam}, +}; pub trait AddrRoutes { fn add_addr_routes(self) -> Self; diff --git a/crates/brk_server/src/api/mempool_space/blocks.rs b/crates/brk_server/src/api/mempool_space/blocks.rs index 252adb35e..c024eb5a5 100644 --- a/crates/brk_server/src/api/mempool_space/blocks.rs +++ b/crates/brk_server/src/api/mempool_space/blocks.rs @@ -4,12 +4,13 @@ use axum::{ http::{HeaderMap, Uri}, }; use brk_query::BLOCK_TXS_PAGE_SIZE; -use brk_types::{ - BlockHashParam, BlockHashStartIndex, BlockHashTxIndex, BlockInfo, BlockInfoV1, BlockStatus, - BlockTimestamp, HeightParam, TimestampParam, Transaction, TxIndex, Txid, Version, -}; +use brk_types::{BlockInfo, BlockInfoV1, BlockStatus, BlockTimestamp, Transaction, TxIndex, Txid, Version}; -use crate::{AppState, CacheStrategy, extended::TransformResponseExtended}; +use crate::{ + AppState, CacheStrategy, + extended::TransformResponseExtended, + params::{BlockHashParam, BlockHashStartIndex, BlockHashTxIndex, HeightParam, TimestampParam}, +}; pub trait BlockRoutes { fn add_block_routes(self) -> Self; diff --git a/crates/brk_server/src/api/mempool_space/general.rs b/crates/brk_server/src/api/mempool_space/general.rs index 818c2ad17..0671ea9b4 100644 --- a/crates/brk_server/src/api/mempool_space/general.rs +++ b/crates/brk_server/src/api/mempool_space/general.rs @@ -3,9 +3,13 @@ use axum::{ extract::{Query, State}, http::{HeaderMap, Uri}, }; -use brk_types::{DifficultyAdjustment, HistoricalPrice, OptionalTimestampParam, Prices, Timestamp}; +use brk_types::{DifficultyAdjustment, HistoricalPrice, Prices, Timestamp}; -use crate::{AppState, CacheStrategy, extended::TransformResponseExtended}; +use crate::{ + AppState, CacheStrategy, + extended::TransformResponseExtended, + params::OptionalTimestampParam, +}; pub trait GeneralRoutes { fn add_general_routes(self) -> Self; diff --git a/crates/brk_server/src/api/mempool_space/mining.rs b/crates/brk_server/src/api/mempool_space/mining.rs index c098a6e18..646fde1e3 100644 --- a/crates/brk_server/src/api/mempool_space/mining.rs +++ b/crates/brk_server/src/api/mempool_space/mining.rs @@ -6,12 +6,16 @@ use axum::{ routing::get, }; use brk_types::{ - BlockCountParam, BlockFeesEntry, BlockInfoV1, BlockRewardsEntry, BlockSizesWeights, + BlockFeesEntry, BlockInfoV1, BlockRewardsEntry, BlockSizesWeights, DifficultyAdjustmentEntry, HashrateSummary, PoolDetail, PoolHashrateEntry, PoolInfo, - PoolSlugAndHeightParam, PoolSlugParam, PoolsSummary, RewardStats, TimePeriodParam, + PoolsSummary, RewardStats, }; -use crate::{AppState, CacheStrategy, Error, extended::TransformResponseExtended}; +use crate::{ + AppState, CacheStrategy, Error, + extended::TransformResponseExtended, + params::{BlockCountParam, PoolSlugAndHeightParam, PoolSlugParam, TimePeriodParam}, +}; pub trait MiningRoutes { fn add_mining_routes(self) -> Self; diff --git a/crates/brk_server/src/api/mempool_space/transactions.rs b/crates/brk_server/src/api/mempool_space/transactions.rs index 55a465690..099ddeb87 100644 --- a/crates/brk_server/src/api/mempool_space/transactions.rs +++ b/crates/brk_server/src/api/mempool_space/transactions.rs @@ -6,12 +6,13 @@ use axum::{ extract::{Path, State}, http::{HeaderMap, Uri}, }; -use brk_types::{ - CpfpInfo, MerkleProof, Transaction, TxOutspend, TxStatus, Txid, TxidParam, TxidVout, - TxidsParam, Version, -}; +use brk_types::{CpfpInfo, MerkleProof, Transaction, TxOutspend, TxStatus, Txid, Version}; -use crate::{AppState, CacheStrategy, extended::TransformResponseExtended}; +use crate::{ + AppState, CacheStrategy, + extended::TransformResponseExtended, + params::{TxidParam, TxidVout, TxidsParam}, +}; pub trait TxRoutes { fn add_tx_routes(self) -> Self; @@ -24,7 +25,7 @@ impl TxRoutes for ApiRouter { "/api/v1/cpfp/{txid}", get_with( async |uri: Uri, headers: HeaderMap, Path(param): Path, State(state): State| { - state.cached_json(&headers, state.tx_cache(Version::ONE, ¶m.txid), &uri, move |q| q.cpfp(param)).await + state.cached_json(&headers, state.tx_cache(Version::ONE, ¶m.txid), &uri, move |q| q.cpfp(¶m.txid)).await }, |op| op .id("get_cpfp") @@ -45,7 +46,7 @@ impl TxRoutes for ApiRouter { Path(param): Path, State(state): State | { - state.cached_json(&headers, state.tx_cache(Version::ONE, ¶m.txid), &uri, move |q| q.transaction(param)).await + state.cached_json(&headers, state.tx_cache(Version::ONE, ¶m.txid), &uri, move |q| q.transaction(¶m.txid)).await }, |op| op .id("get_tx") @@ -67,10 +68,10 @@ impl TxRoutes for ApiRouter { async | uri: Uri, headers: HeaderMap, - Path(txid): Path, + Path(param): Path, State(state): State | { - state.cached_text(&headers, state.tx_cache(Version::ONE, &txid.txid), &uri, move |q| q.transaction_hex(txid)).await + state.cached_text(&headers, state.tx_cache(Version::ONE, ¶m.txid), &uri, move |q| q.transaction_hex(¶m.txid)).await }, |op| op .id("get_tx_hex") @@ -89,8 +90,8 @@ impl TxRoutes for ApiRouter { .api_route( "/api/tx/{txid}/merkleblock-proof", get_with( - async |uri: Uri, headers: HeaderMap, Path(txid): Path, State(state): State| { - state.cached_text(&headers, state.tx_cache(Version::ONE, &txid.txid), &uri, move |q| q.merkleblock_proof(txid)).await + async |uri: Uri, headers: HeaderMap, Path(param): Path, State(state): State| { + state.cached_text(&headers, state.tx_cache(Version::ONE, ¶m.txid), &uri, move |q| q.merkleblock_proof(¶m.txid)).await }, |op| op .id("get_tx_merkleblock_proof") @@ -107,8 +108,8 @@ impl TxRoutes for ApiRouter { .api_route( "/api/tx/{txid}/merkle-proof", get_with( - async |uri: Uri, headers: HeaderMap, Path(txid): Path, State(state): State| { - state.cached_json(&headers, state.tx_cache(Version::ONE, &txid.txid), &uri, move |q| q.merkle_proof(txid)).await + async |uri: Uri, headers: HeaderMap, Path(param): Path, State(state): State| { + state.cached_json(&headers, state.tx_cache(Version::ONE, ¶m.txid), &uri, move |q| q.merkle_proof(¶m.txid)).await }, |op| op .id("get_tx_merkle_proof") @@ -131,8 +132,7 @@ impl TxRoutes for ApiRouter { Path(path): Path, State(state): State | { - let txid = TxidParam { txid: path.txid }; - state.cached_json(&headers, CacheStrategy::Tip, &uri, move |q| q.outspend(txid, path.vout)).await + state.cached_json(&headers, CacheStrategy::Tip, &uri, move |q| q.outspend(&path.txid, path.vout)).await }, |op| op .id("get_tx_outspend") @@ -154,10 +154,10 @@ impl TxRoutes for ApiRouter { async | uri: Uri, headers: HeaderMap, - Path(txid): Path, + Path(param): Path, State(state): State | { - state.cached_json(&headers, CacheStrategy::Tip, &uri, move |q| q.outspends(txid)).await + state.cached_json(&headers, CacheStrategy::Tip, &uri, move |q| q.outspends(¶m.txid)).await }, |op| op .id("get_tx_outspends") @@ -176,8 +176,8 @@ impl TxRoutes for ApiRouter { .api_route( "/api/tx/{txid}/raw", get_with( - async |uri: Uri, headers: HeaderMap, Path(txid): Path, State(state): State| { - state.cached_bytes(&headers, state.tx_cache(Version::ONE, &txid.txid), &uri, move |q| q.transaction_raw(txid)).await + async |uri: Uri, headers: HeaderMap, Path(param): Path, State(state): State| { + state.cached_bytes(&headers, state.tx_cache(Version::ONE, ¶m.txid), &uri, move |q| q.transaction_raw(¶m.txid)).await }, |op| op .id("get_tx_raw") @@ -200,7 +200,7 @@ impl TxRoutes for ApiRouter { Path(param): Path, State(state): State | { - state.cached_json(&headers, state.tx_cache(Version::ONE, ¶m.txid), &uri, move |q| q.transaction_status(param)).await + state.cached_json(&headers, state.tx_cache(Version::ONE, ¶m.txid), &uri, move |q| q.transaction_status(¶m.txid)).await }, |op| op .id("get_tx_status") diff --git a/crates/brk_server/src/api/metrics/mod.rs b/crates/brk_server/src/api/metrics/mod.rs index 68e782c07..f7cb5886f 100644 --- a/crates/brk_server/src/api/metrics/mod.rs +++ b/crates/brk_server/src/api/metrics/mod.rs @@ -9,10 +9,12 @@ use axum::{ }; use brk_traversable::TreeNode; use brk_types::{ - CostBasisCohortParam, CostBasisFormatted, CostBasisParams, CostBasisQuery, DataRangeFormat, - Date, DetailedSeriesCount, Index, IndexInfo, PaginatedSeries, Pagination, SearchQuery, - SeriesData, SeriesInfo, SeriesList, SeriesName, SeriesSelection, SeriesSelectionLegacy, + CostBasisFormatted, DataRangeFormat, Date, DetailedSeriesCount, Index, IndexInfo, + PaginatedSeries, Pagination, SearchQuery, SeriesData, SeriesInfo, SeriesList, SeriesName, + SeriesSelection, SeriesSelectionLegacy, }; + +use crate::params::{CostBasisCohortParam, CostBasisParams, CostBasisQuery}; use schemars::JsonSchema; use serde::{Deserialize, Serialize}; diff --git a/crates/brk_server/src/api/series/mod.rs b/crates/brk_server/src/api/series/mod.rs index 02748af0f..9bae9d0eb 100644 --- a/crates/brk_server/src/api/series/mod.rs +++ b/crates/brk_server/src/api/series/mod.rs @@ -9,12 +9,15 @@ use axum::{ }; use brk_traversable::TreeNode; use brk_types::{ - CostBasisCohortParam, CostBasisFormatted, CostBasisParams, CostBasisQuery, DataRangeFormat, - Date, IndexInfo, PaginatedSeries, Pagination, SearchQuery, SeriesCount, SeriesData, SeriesInfo, - SeriesNameWithIndex, SeriesParam, SeriesSelection, + CostBasisFormatted, DataRangeFormat, Date, IndexInfo, PaginatedSeries, Pagination, SearchQuery, + SeriesCount, SeriesData, SeriesInfo, SeriesNameWithIndex, SeriesSelection, }; -use crate::{CacheStrategy, extended::TransformResponseExtended}; +use crate::{ + CacheStrategy, + extended::TransformResponseExtended, + params::{CostBasisCohortParam, CostBasisParams, CostBasisQuery, SeriesParam}, +}; use super::AppState; diff --git a/crates/brk_server/src/lib.rs b/crates/brk_server/src/lib.rs index a70b681e3..8d3cb26c0 100644 --- a/crates/brk_server/src/lib.rs +++ b/crates/brk_server/src/lib.rs @@ -36,6 +36,7 @@ mod api; pub mod cache; mod error; mod extended; +pub mod params; mod state; pub use api::ApiRoutes; diff --git a/crates/brk_types/src/addr_param.rs b/crates/brk_server/src/params/addr_param.rs similarity index 88% rename from crates/brk_types/src/addr_param.rs rename to crates/brk_server/src/params/addr_param.rs index 3057dd663..5ec38e391 100644 --- a/crates/brk_types/src/addr_param.rs +++ b/crates/brk_server/src/params/addr_param.rs @@ -1,7 +1,7 @@ use schemars::JsonSchema; use serde::Deserialize; -use crate::Addr; +use brk_types::Addr; #[derive(Deserialize, JsonSchema)] pub struct AddrParam { diff --git a/crates/brk_types/src/addr_txids_param.rs b/crates/brk_server/src/params/addr_txids_param.rs similarity index 91% rename from crates/brk_types/src/addr_txids_param.rs rename to crates/brk_server/src/params/addr_txids_param.rs index 367093ac5..05ac1b24d 100644 --- a/crates/brk_types/src/addr_txids_param.rs +++ b/crates/brk_server/src/params/addr_txids_param.rs @@ -1,7 +1,7 @@ use schemars::JsonSchema; use serde::Deserialize; -use crate::Txid; +use brk_types::Txid; #[derive(Debug, Default, Deserialize, JsonSchema)] pub struct AddrTxidsParam { diff --git a/crates/brk_types/src/block_count_param.rs b/crates/brk_server/src/params/block_count_param.rs similarity index 100% rename from crates/brk_types/src/block_count_param.rs rename to crates/brk_server/src/params/block_count_param.rs diff --git a/crates/brk_types/src/blockhash_param.rs b/crates/brk_server/src/params/blockhash_param.rs similarity index 84% rename from crates/brk_types/src/blockhash_param.rs rename to crates/brk_server/src/params/blockhash_param.rs index 10568d200..92fcbc7f8 100644 --- a/crates/brk_types/src/blockhash_param.rs +++ b/crates/brk_server/src/params/blockhash_param.rs @@ -1,7 +1,7 @@ use schemars::JsonSchema; use serde::Deserialize; -use crate::BlockHash; +use brk_types::BlockHash; #[derive(Deserialize, JsonSchema)] pub struct BlockHashParam { diff --git a/crates/brk_types/src/blockhash_start_index.rs b/crates/brk_server/src/params/blockhash_start_index.rs similarity index 88% rename from crates/brk_types/src/blockhash_start_index.rs rename to crates/brk_server/src/params/blockhash_start_index.rs index 2f819452b..742e584e7 100644 --- a/crates/brk_types/src/blockhash_start_index.rs +++ b/crates/brk_server/src/params/blockhash_start_index.rs @@ -1,7 +1,7 @@ use schemars::JsonSchema; use serde::Deserialize; -use crate::{BlockHash, TxIndex}; +use brk_types::{BlockHash, TxIndex}; #[derive(Deserialize, JsonSchema)] pub struct BlockHashStartIndex { diff --git a/crates/brk_types/src/blockhash_tx_index.rs b/crates/brk_server/src/params/blockhash_tx_index.rs similarity index 88% rename from crates/brk_types/src/blockhash_tx_index.rs rename to crates/brk_server/src/params/blockhash_tx_index.rs index ae5f120b4..574cc54ae 100644 --- a/crates/brk_types/src/blockhash_tx_index.rs +++ b/crates/brk_server/src/params/blockhash_tx_index.rs @@ -1,7 +1,7 @@ use schemars::JsonSchema; use serde::Deserialize; -use crate::{BlockHash, TxIndex}; +use brk_types::{BlockHash, TxIndex}; #[derive(Deserialize, JsonSchema)] pub struct BlockHashTxIndex { diff --git a/crates/brk_types/src/cost_basis_params.rs b/crates/brk_server/src/params/cost_basis_params.rs similarity index 56% rename from crates/brk_types/src/cost_basis_params.rs rename to crates/brk_server/src/params/cost_basis_params.rs index 119b54dd6..544bffdc3 100644 --- a/crates/brk_types/src/cost_basis_params.rs +++ b/crates/brk_server/src/params/cost_basis_params.rs @@ -1,33 +1,7 @@ -use std::{fmt, ops::Deref}; - use schemars::JsonSchema; use serde::Deserialize; -use crate::{CostBasisBucket, CostBasisValue, Date}; - -/// Cohort identifier for cost basis distribution. -#[derive(Deserialize, JsonSchema)] -#[schemars(example = &"all", example = &"sth", example = &"lth")] -pub struct Cohort(String); - -impl fmt::Display for Cohort { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.write_str(&self.0) - } -} - -impl> From for Cohort { - fn from(s: T) -> Self { - Self(s.into()) - } -} - -impl Deref for Cohort { - type Target = str; - fn deref(&self) -> &Self::Target { - &self.0 - } -} +use brk_types::{Cohort, CostBasisBucket, CostBasisValue, Date}; /// Path parameters for cost basis distribution endpoint. #[derive(Deserialize, JsonSchema)] diff --git a/crates/brk_types/src/height_param.rs b/crates/brk_server/src/params/height_param.rs similarity index 85% rename from crates/brk_types/src/height_param.rs rename to crates/brk_server/src/params/height_param.rs index 5c7301795..2c153cd8b 100644 --- a/crates/brk_types/src/height_param.rs +++ b/crates/brk_server/src/params/height_param.rs @@ -1,7 +1,7 @@ use schemars::JsonSchema; use serde::Deserialize; -use crate::Height; +use brk_types::Height; #[derive(Deserialize, JsonSchema)] pub struct HeightParam { diff --git a/crates/brk_types/src/limit_param.rs b/crates/brk_server/src/params/limit_param.rs similarity index 87% rename from crates/brk_types/src/limit_param.rs rename to crates/brk_server/src/params/limit_param.rs index 0fdc74ced..295107f01 100644 --- a/crates/brk_types/src/limit_param.rs +++ b/crates/brk_server/src/params/limit_param.rs @@ -1,7 +1,7 @@ use schemars::JsonSchema; use serde::Deserialize; -use crate::Limit; +use brk_types::Limit; #[derive(Deserialize, JsonSchema)] pub struct LimitParam { diff --git a/crates/brk_server/src/params/mod.rs b/crates/brk_server/src/params/mod.rs new file mode 100644 index 000000000..4af3e1774 --- /dev/null +++ b/crates/brk_server/src/params/mod.rs @@ -0,0 +1,35 @@ +mod addr_param; +mod addr_txids_param; +mod block_count_param; +mod blockhash_param; +mod blockhash_start_index; +mod blockhash_tx_index; +mod cost_basis_params; +mod height_param; +mod limit_param; +mod pool_slug_param; +mod series_param; +mod time_period_param; +mod timestamp_param; +mod txid_param; +mod txid_vout; +mod txids_param; +mod validate_addr_param; + +pub use addr_param::*; +pub use addr_txids_param::*; +pub use block_count_param::*; +pub use blockhash_param::*; +pub use blockhash_start_index::*; +pub use blockhash_tx_index::*; +pub use cost_basis_params::*; +pub use height_param::*; +pub use limit_param::*; +pub use pool_slug_param::*; +pub use series_param::*; +pub use time_period_param::*; +pub use timestamp_param::*; +pub use txid_param::*; +pub use txid_vout::*; +pub use txids_param::*; +pub use validate_addr_param::*; diff --git a/crates/brk_types/src/pool_slug_param.rs b/crates/brk_server/src/params/pool_slug_param.rs similarity index 88% rename from crates/brk_types/src/pool_slug_param.rs rename to crates/brk_server/src/params/pool_slug_param.rs index 877e77fe5..8aff97a02 100644 --- a/crates/brk_types/src/pool_slug_param.rs +++ b/crates/brk_server/src/params/pool_slug_param.rs @@ -1,7 +1,7 @@ use schemars::JsonSchema; use serde::Deserialize; -use super::{Height, PoolSlug}; +use brk_types::{Height, PoolSlug}; #[derive(Deserialize, JsonSchema)] pub struct PoolSlugParam { diff --git a/crates/brk_types/src/series_param.rs b/crates/brk_server/src/params/series_param.rs similarity index 84% rename from crates/brk_types/src/series_param.rs rename to crates/brk_server/src/params/series_param.rs index 6b7a02ba7..709304d9c 100644 --- a/crates/brk_types/src/series_param.rs +++ b/crates/brk_server/src/params/series_param.rs @@ -1,7 +1,7 @@ use schemars::JsonSchema; use serde::Deserialize; -use crate::SeriesName; +use brk_types::SeriesName; #[derive(Deserialize, JsonSchema)] pub struct SeriesParam { diff --git a/crates/brk_types/src/time_period_param.rs b/crates/brk_server/src/params/time_period_param.rs similarity index 87% rename from crates/brk_types/src/time_period_param.rs rename to crates/brk_server/src/params/time_period_param.rs index 08140cc4f..7df989e8a 100644 --- a/crates/brk_types/src/time_period_param.rs +++ b/crates/brk_server/src/params/time_period_param.rs @@ -1,7 +1,7 @@ use schemars::JsonSchema; use serde::Deserialize; -use super::TimePeriod; +use brk_types::TimePeriod; #[derive(Deserialize, JsonSchema)] pub struct TimePeriodParam { diff --git a/crates/brk_types/src/timestamp_param.rs b/crates/brk_server/src/params/timestamp_param.rs similarity index 90% rename from crates/brk_types/src/timestamp_param.rs rename to crates/brk_server/src/params/timestamp_param.rs index b786b4429..3ce70cf0f 100644 --- a/crates/brk_types/src/timestamp_param.rs +++ b/crates/brk_server/src/params/timestamp_param.rs @@ -1,7 +1,7 @@ use schemars::JsonSchema; use serde::Deserialize; -use crate::Timestamp; +use brk_types::Timestamp; #[derive(Deserialize, JsonSchema)] pub struct TimestampParam { diff --git a/crates/brk_types/src/txid_param.rs b/crates/brk_server/src/params/txid_param.rs similarity index 86% rename from crates/brk_types/src/txid_param.rs rename to crates/brk_server/src/params/txid_param.rs index 90696a47d..92fa5c0fc 100644 --- a/crates/brk_types/src/txid_param.rs +++ b/crates/brk_server/src/params/txid_param.rs @@ -1,7 +1,7 @@ use schemars::JsonSchema; use serde::Deserialize; -use crate::Txid; +use brk_types::Txid; #[derive(Deserialize, JsonSchema)] pub struct TxidParam { diff --git a/crates/brk_types/src/txid_vout.rs b/crates/brk_server/src/params/txid_vout.rs similarity index 89% rename from crates/brk_types/src/txid_vout.rs rename to crates/brk_server/src/params/txid_vout.rs index 5d50758de..fe9b53bc6 100644 --- a/crates/brk_types/src/txid_vout.rs +++ b/crates/brk_server/src/params/txid_vout.rs @@ -1,7 +1,7 @@ use schemars::JsonSchema; use serde::Deserialize; -use crate::{Txid, Vout}; +use brk_types::{Txid, Vout}; /// Transaction output reference (txid + output index) #[derive(Deserialize, JsonSchema)] diff --git a/crates/brk_types/src/txids_param.rs b/crates/brk_server/src/params/txids_param.rs similarity index 97% rename from crates/brk_types/src/txids_param.rs rename to crates/brk_server/src/params/txids_param.rs index 65fb25dbb..b0d614b6d 100644 --- a/crates/brk_types/src/txids_param.rs +++ b/crates/brk_server/src/params/txids_param.rs @@ -2,7 +2,7 @@ use std::str::FromStr; use schemars::JsonSchema; -use crate::Txid; +use brk_types::Txid; /// Query parameter for transaction-times endpoint. #[derive(JsonSchema)] diff --git a/crates/brk_types/src/validate_addr_param.rs b/crates/brk_server/src/params/validate_addr_param.rs similarity index 100% rename from crates/brk_types/src/validate_addr_param.rs rename to crates/brk_server/src/params/validate_addr_param.rs diff --git a/crates/brk_types/src/cohort.rs b/crates/brk_types/src/cohort.rs new file mode 100644 index 000000000..6154c9dd5 --- /dev/null +++ b/crates/brk_types/src/cohort.rs @@ -0,0 +1,28 @@ +use std::{fmt, ops::Deref}; + +use schemars::JsonSchema; +use serde::Deserialize; + +/// Cohort identifier for cost basis distribution. +#[derive(Deserialize, JsonSchema)] +#[schemars(example = &"all", example = &"sth", example = &"lth")] +pub struct Cohort(String); + +impl fmt::Display for Cohort { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.write_str(&self.0) + } +} + +impl> From for Cohort { + fn from(s: T) -> Self { + Self(s.into()) + } +} + +impl Deref for Cohort { + type Target = str; + fn deref(&self) -> &Self::Target { + &self.0 + } +} diff --git a/crates/brk_types/src/lib.rs b/crates/brk_types/src/lib.rs index be6fbacab..acfddc99a 100644 --- a/crates/brk_types/src/lib.rs +++ b/crates/brk_types/src/lib.rs @@ -10,9 +10,7 @@ mod addr_index_any; mod addr_index_outpoint; mod addr_index_tx_index; mod addr_mempool_stats; -mod addr_param; mod addr_stats; -mod addr_txids_param; mod addr_validation; mod age; mod basis_points_16; @@ -23,7 +21,6 @@ mod bitcoin; mod blk_metadata; mod blk_position; mod block; -mod block_count_param; mod block_extras; mod block_fee_rates_entry; mod block_fees_entry; @@ -38,21 +35,18 @@ mod block_status; mod block_timestamp; mod block_weight_entry; mod blockhash; -mod blockhash_param; mod blockhash_prefix; -mod blockhash_start_index; -mod blockhash_tx_index; mod bytes; mod cents; mod cents_compact; mod cents_sats; mod cents_signed; mod cents_squared_sats; +mod cohort; mod coinbase_tag; mod cpfp; mod cost_basis_bucket; mod cost_basis_distribution; -mod cost_basis_params; mod cost_basis_value; mod data_range; mod data_range_format; @@ -83,7 +77,6 @@ mod hashrate_summary; mod health; mod height; mod historical_price; -mod height_param; mod hex; mod hour1; mod hour12; @@ -92,7 +85,6 @@ mod index; mod index_info; mod indexes; mod limit; -mod limit_param; mod mempool_block; mod mempool_entry_info; mod mempool_info; @@ -135,7 +127,6 @@ mod pool_detail; mod pool_info; mod pool_hashrate_entry; mod pool_slug; -mod pool_slug_param; mod pool_stats; mod pools; mod pools_summary; @@ -157,7 +148,6 @@ mod series_name; mod series_name_with_index; mod series_output; mod series_paginated; -mod series_param; mod series_selection; mod series_selection_legacy; mod stored_bool; @@ -175,9 +165,7 @@ mod supply_state; mod sync_status; mod term; mod time_period; -mod time_period_param; mod timestamp; -mod timestamp_param; mod tree_node; mod tx; mod tx_index; @@ -185,10 +173,7 @@ mod tx_status; mod tx_version; mod tx_with_hex; mod txid; -mod txid_param; mod txid_prefix; -mod txids_param; -mod txid_vout; mod txin; mod txin_index; mod txout; @@ -198,7 +183,6 @@ mod type_index; mod unit; mod unknown_output_index; mod utxo; -mod validate_addr_param; mod vin; mod vout; mod vsize; @@ -216,9 +200,7 @@ pub use addr_index_any::*; pub use addr_index_outpoint::*; pub use addr_index_tx_index::*; pub use addr_mempool_stats::*; -pub use addr_param::*; pub use addr_stats::*; -pub use addr_txids_param::*; pub use addr_validation::*; pub use age::*; pub use basis_points_16::*; @@ -229,7 +211,6 @@ pub use bitcoin::*; pub use blk_metadata::*; pub use blk_position::*; pub use block::*; -pub use block_count_param::*; pub use block_extras::*; pub use block_fee_rates_entry::*; pub use block_fees_entry::*; @@ -244,21 +225,18 @@ pub use block_status::*; pub use block_timestamp::*; pub use block_weight_entry::*; pub use blockhash::*; -pub use blockhash_param::*; pub use blockhash_prefix::*; -pub use blockhash_start_index::*; -pub use blockhash_tx_index::*; pub use bytes::*; pub use cents::*; pub use cents_compact::*; pub use cents_sats::*; pub use cents_signed::*; pub use cents_squared_sats::*; +pub use cohort::*; pub use coinbase_tag::*; pub use cpfp::*; pub use cost_basis_bucket::*; pub use cost_basis_distribution::*; -pub use cost_basis_params::*; pub use cost_basis_value::*; pub use data_range::*; pub use data_range_format::*; @@ -289,7 +267,6 @@ pub use hashrate_summary::*; pub use health::*; pub use height::*; pub use historical_price::*; -pub use height_param::*; pub use hex::*; pub use hour1::*; pub use hour4::*; @@ -298,7 +275,6 @@ pub use index::*; pub use index_info::*; pub use indexes::*; pub use limit::*; -pub use limit_param::*; pub use mempool_block::*; pub use mempool_entry_info::*; pub use mempool_info::*; @@ -341,7 +317,6 @@ pub use pool_detail::*; pub use pool_info::*; pub use pool_hashrate_entry::*; pub use pool_slug::*; -pub use pool_slug_param::*; pub use pool_stats::*; pub use pools::*; pub use pools_summary::*; @@ -363,7 +338,6 @@ pub use series_name::*; pub use series_name_with_index::*; pub use series_output::*; pub use series_paginated::*; -pub use series_param::*; pub use series_selection::*; pub use series_selection_legacy::*; pub use stored_bool::*; @@ -381,9 +355,7 @@ pub use supply_state::*; pub use sync_status::*; pub use term::*; pub use time_period::*; -pub use time_period_param::*; pub use timestamp::*; -pub use timestamp_param::*; pub use tree_node::*; pub use tx::*; pub use tx_index::*; @@ -391,10 +363,7 @@ pub use tx_status::*; pub use tx_version::*; pub use tx_with_hex::*; pub use txid::*; -pub use txid_param::*; pub use txid_prefix::*; -pub use txids_param::*; -pub use txid_vout::*; pub use txin::*; pub use txin_index::*; pub use txout::*; @@ -404,7 +373,6 @@ pub use type_index::*; pub use unit::*; pub use unknown_output_index::*; pub use utxo::*; -pub use validate_addr_param::*; pub use vin::*; pub use vout::*; pub use vsize::*; diff --git a/modules/brk-client/index.js b/modules/brk-client/index.js index c5b756361..108088ff9 100644 --- a/modules/brk-client/index.js +++ b/modules/brk-client/index.js @@ -144,10 +144,10 @@ * A single block fees data point. * * @typedef {Object} BlockFeesEntry - * @property {Height} avgHeight - * @property {Timestamp} timestamp - * @property {Sats} avgFees - * @property {Dollars} uSD - BTC/USD price at that height + * @property {Height} avgHeight - Average block height in this window + * @property {Timestamp} timestamp - Unix timestamp at the window midpoint + * @property {Sats} avgFees - Average fees per block in this window (sats) + * @property {Dollars} uSD - BTC/USD price at this height */ /** * Block hash @@ -203,7 +203,6 @@ * @property {number} nonce - Nonce * @property {number} bits - Compact target (bits) * @property {number} difficulty - Block difficulty - * @property {boolean=} stale - Whether this block is stale (orphaned) * @property {BlockExtras} extras - Extended block data */ /** @@ -219,25 +218,25 @@ * A single block rewards data point. * * @typedef {Object} BlockRewardsEntry - * @property {Height} avgHeight - * @property {Timestamp} timestamp - * @property {Sats} avgRewards - * @property {Dollars} uSD - BTC/USD price at that height + * @property {Height} avgHeight - Average block height in this window + * @property {Timestamp} timestamp - Unix timestamp at the window midpoint + * @property {Sats} avgRewards - Average coinbase reward per block (subsidy + fees, sats) + * @property {Dollars} uSD - BTC/USD price at this height */ /** * A single block size data point. * * @typedef {Object} BlockSizeEntry - * @property {Height} avgHeight - * @property {Timestamp} timestamp - * @property {number} avgSize + * @property {Height} avgHeight - Average block height in this window + * @property {Timestamp} timestamp - Unix timestamp at the window midpoint + * @property {number} avgSize - Rolling 24h median block size (bytes) */ /** * Combined block sizes and weights response. * * @typedef {Object} BlockSizesWeights - * @property {BlockSizeEntry[]} sizes - * @property {BlockWeightEntry[]} weights + * @property {BlockSizeEntry[]} sizes - Block size data points + * @property {BlockWeightEntry[]} weights - Block weight data points */ /** * Block status indicating whether block is in the best chain @@ -259,9 +258,9 @@ * A single block weight data point. * * @typedef {Object} BlockWeightEntry - * @property {Height} avgHeight - * @property {Timestamp} timestamp - * @property {Weight} avgWeight + * @property {Height} avgHeight - Average block height in this window + * @property {Timestamp} timestamp - Unix timestamp at the window midpoint + * @property {Weight} avgWeight - Rolling 24h median block weight (weight units) */ /** * Unsigned cents (u64) - for values that should never be negative. @@ -409,10 +408,10 @@ * Serializes as array: [timestamp, height, difficulty, change_percent] * * @typedef {Object} DifficultyAdjustmentEntry - * @property {Timestamp} timestamp - * @property {Height} height - * @property {number} difficulty - * @property {number} changePercent + * @property {Timestamp} timestamp - Unix timestamp of the adjustment + * @property {Height} height - Block height of the adjustment + * @property {number} difficulty - Difficulty value + * @property {number} changePercent - Adjustment ratio (new/previous, e.g. 1.068 = +6.8%) */ /** * A single difficulty data point in the hashrate summary. @@ -509,10 +508,10 @@ * Server health status * * @typedef {Object} Health - * @property {string} status - * @property {string} service - * @property {string} version - * @property {string} timestamp + * @property {string} status - Health status ("healthy") + * @property {string} service - Service name + * @property {string} version - Server version + * @property {string} timestamp - Current server time (ISO 8601) * @property {string} startedAt - Server start time (ISO 8601) * @property {number} uptimeSeconds - Uptime in seconds * @property {Height} indexedHeight - Height of the last indexed block @@ -540,15 +539,15 @@ * Historical price response * * @typedef {Object} HistoricalPrice - * @property {HistoricalPriceEntry[]} prices - * @property {ExchangeRates} exchangeRates + * @property {HistoricalPriceEntry[]} prices - Price data points + * @property {ExchangeRates} exchangeRates - Exchange rates (currently empty) */ /** * A single price data point * * @typedef {Object} HistoricalPriceEntry - * @property {number} time - * @property {Dollars} uSD + * @property {number} time - Unix timestamp + * @property {Dollars} uSD - BTC/USD price */ /** @typedef {number} Hour1 */ /** @typedef {number} Hour12 */ @@ -610,21 +609,21 @@ * @property {{ [key: string]: VSize }} feeHistogram - Fee histogram: `[[fee_rate, vsize], ...]` sorted by descending fee rate */ /** - * Simplified mempool transaction for the recent transactions endpoint + * Simplified mempool transaction for the `/api/mempool/recent` endpoint. * * @typedef {Object} MempoolRecentTx - * @property {Txid} txid - * @property {Sats} fee - * @property {VSize} vsize - * @property {Sats} value + * @property {Txid} txid - Transaction ID + * @property {Sats} fee - Transaction fee (sats) + * @property {VSize} vsize - Virtual size (vbytes) + * @property {Sats} value - Total output value (sats) */ /** * Merkle inclusion proof for a transaction * * @typedef {Object} MerkleProof - * @property {Height} blockHeight - * @property {string[]} merkle - * @property {number} pos + * @property {Height} blockHeight - Block height containing the transaction + * @property {string[]} merkle - Merkle proof path (hex-encoded hashes) + * @property {number} pos - Transaction position in the block */ /** @typedef {number} Minute10 */ /** @typedef {number} Minute30 */ @@ -802,8 +801,8 @@ * Current price response matching mempool.space /api/v1/prices format * * @typedef {Object} Prices - * @property {Timestamp} time - * @property {Dollars} uSD + * @property {Timestamp} time - Unix timestamp + * @property {Dollars} uSD - BTC/USD price */ /** * A range boundary: integer index, date, or timestamp. @@ -831,9 +830,9 @@ * @typedef {Object} RewardStats * @property {Height} startBlock - First block in the range * @property {Height} endBlock - Last block in the range - * @property {Sats} totalReward - * @property {Sats} totalFee - * @property {number} totalTx + * @property {Sats} totalReward - Total coinbase rewards (subsidy + fees) in sats + * @property {Sats} totalFee - Total transaction fees in sats + * @property {number} totalTx - Total number of transactions */ /** * Satoshis @@ -1000,17 +999,17 @@ * Transaction information compatible with mempool.space API format * * @typedef {Object} Transaction - * @property {(TxIndex|null)=} index - * @property {Txid} txid - * @property {TxVersion} version - * @property {RawLockTime} locktime + * @property {(TxIndex|null)=} index - Internal transaction index (brk-specific, not in mempool.space) + * @property {Txid} txid - Transaction ID + * @property {TxVersion} version - Transaction version + * @property {RawLockTime} locktime - Transaction lock time * @property {TxIn[]} vin - Transaction inputs * @property {TxOut[]} vout - Transaction outputs * @property {number} size - Transaction size in bytes * @property {Weight} weight - Transaction weight * @property {number} sigops - Number of signature operations * @property {Sats} fee - Transaction fee in satoshis - * @property {TxStatus} status + * @property {TxStatus} status - Confirmation status (confirmed, block height/hash/time) */ /** * Hierarchical tree node for organizing series into categories @@ -1096,10 +1095,10 @@ * Unspent transaction output * * @typedef {Object} Utxo - * @property {Txid} txid - * @property {Vout} vout - * @property {TxStatus} status - * @property {Sats} value + * @property {Txid} txid - Transaction ID of the UTXO + * @property {Vout} vout - Output index + * @property {TxStatus} status - Confirmation status + * @property {Sats} value - Output value in satoshis */ /** * Virtual size in vbytes (weight / 4, rounded up) diff --git a/packages/brk_client/brk_client/__init__.py b/packages/brk_client/brk_client/__init__.py index 2a7cd2c4f..9075a7c75 100644 --- a/packages/brk_client/brk_client/__init__.py +++ b/packages/brk_client/brk_client/__init__.py @@ -387,7 +387,10 @@ class BlockFeesEntry(TypedDict): A single block fees data point. Attributes: - USD: BTC/USD price at that height + avgHeight: Average block height in this window + timestamp: Unix timestamp at the window midpoint + avgFees: Average fees per block in this window (sats) + USD: BTC/USD price at this height """ avgHeight: Height timestamp: Timestamp @@ -466,7 +469,6 @@ class BlockInfoV1(TypedDict): nonce: Nonce bits: Compact target (bits) difficulty: Block difficulty - stale: Whether this block is stale (orphaned) extras: Extended block data """ id: BlockHash @@ -482,7 +484,6 @@ class BlockInfoV1(TypedDict): nonce: int bits: int difficulty: float - stale: bool extras: BlockExtras class BlockRewardsEntry(TypedDict): @@ -490,7 +491,10 @@ class BlockRewardsEntry(TypedDict): A single block rewards data point. Attributes: - USD: BTC/USD price at that height + avgHeight: Average block height in this window + timestamp: Unix timestamp at the window midpoint + avgRewards: Average coinbase reward per block (subsidy + fees, sats) + USD: BTC/USD price at this height """ avgHeight: Height timestamp: Timestamp @@ -500,6 +504,11 @@ class BlockRewardsEntry(TypedDict): class BlockSizeEntry(TypedDict): """ A single block size data point. + + Attributes: + avgHeight: Average block height in this window + timestamp: Unix timestamp at the window midpoint + avgSize: Rolling 24h median block size (bytes) """ avgHeight: Height timestamp: Timestamp @@ -508,6 +517,11 @@ class BlockSizeEntry(TypedDict): class BlockWeightEntry(TypedDict): """ A single block weight data point. + + Attributes: + avgHeight: Average block height in this window + timestamp: Unix timestamp at the window midpoint + avgWeight: Rolling 24h median block weight (weight units) """ avgHeight: Height timestamp: Timestamp @@ -516,6 +530,10 @@ class BlockWeightEntry(TypedDict): class BlockSizesWeights(TypedDict): """ Combined block sizes and weights response. + + Attributes: + sizes: Block size data points + weights: Block weight data points """ sizes: List[BlockSizeEntry] weights: List[BlockWeightEntry] @@ -684,6 +702,12 @@ class DifficultyAdjustmentEntry(TypedDict): """ A single difficulty adjustment entry. Serializes as array: [timestamp, height, difficulty, change_percent] + + Attributes: + timestamp: Unix timestamp of the adjustment + height: Block height of the adjustment + difficulty: Difficulty value + change_percent: Adjustment ratio (new/previous, e.g. 1.068 = +6.8%) """ timestamp: Timestamp height: Height @@ -803,6 +827,10 @@ class Health(TypedDict): Server health status Attributes: + status: Health status ("healthy") + service: Service name + version: Server version + timestamp: Current server time (ISO 8601) started_at: Server start time (ISO 8601) uptime_seconds: Uptime in seconds indexed_height: Height of the last indexed block @@ -831,6 +859,10 @@ class HeightParam(TypedDict): class HistoricalPriceEntry(TypedDict): """ A single price data point + + Attributes: + time: Unix timestamp + USD: BTC/USD price """ time: int USD: Dollars @@ -838,6 +870,10 @@ class HistoricalPriceEntry(TypedDict): class HistoricalPrice(TypedDict): """ Historical price response + + Attributes: + prices: Price data points + exchangeRates: Exchange rates (currently empty) """ prices: List[HistoricalPriceEntry] exchangeRates: ExchangeRates @@ -902,7 +938,13 @@ class MempoolInfo(TypedDict): class MempoolRecentTx(TypedDict): """ - Simplified mempool transaction for the recent transactions endpoint + Simplified mempool transaction for the `/api/mempool/recent` endpoint. + + Attributes: + txid: Transaction ID + fee: Transaction fee (sats) + vsize: Virtual size (vbytes) + value: Total output value (sats) """ txid: Txid fee: Sats @@ -912,6 +954,11 @@ class MempoolRecentTx(TypedDict): class MerkleProof(TypedDict): """ Merkle inclusion proof for a transaction + + Attributes: + block_height: Block height containing the transaction + merkle: Merkle proof path (hex-encoded hashes) + pos: Transaction position in the block """ block_height: Height merkle: List[str] @@ -1121,6 +1168,10 @@ class PoolsSummary(TypedDict): class Prices(TypedDict): """ Current price response matching mempool.space /api/v1/prices format + + Attributes: + time: Unix timestamp + USD: BTC/USD price """ time: Timestamp USD: Dollars @@ -1149,6 +1200,9 @@ class RewardStats(TypedDict): Attributes: startBlock: First block in the range endBlock: Last block in the range + totalReward: Total coinbase rewards (subsidy + fees) in sats + totalFee: Total transaction fees in sats + totalTx: Total number of transactions """ startBlock: Height endBlock: Height @@ -1318,12 +1372,17 @@ class Transaction(TypedDict): Transaction information compatible with mempool.space API format Attributes: + index: Internal transaction index (brk-specific, not in mempool.space) + txid: Transaction ID + version: Transaction version + locktime: Transaction lock time vin: Transaction inputs vout: Transaction outputs size: Transaction size in bytes weight: Transaction weight sigops: Number of signature operations fee: Transaction fee in satoshis + status: Confirmation status (confirmed, block height/hash/time) """ index: Union[TxIndex, None] txid: Txid @@ -1369,6 +1428,12 @@ class TxidVout(TypedDict): class Utxo(TypedDict): """ Unspent transaction output + + Attributes: + txid: Transaction ID of the UTXO + vout: Output index + status: Confirmation status + value: Output value in satoshis """ txid: Txid vout: Vout diff --git a/website/styles/panes/explorer.css b/website/styles/panes/explorer.css index 5a281de3e..906114549 100644 --- a/website/styles/panes/explorer.css +++ b/website/styles/panes/explorer.css @@ -10,6 +10,7 @@ padding: 2rem; .cube { + cursor: pointer; width: var(--cube); height: var(--cube); overflow: hidden; @@ -17,6 +18,37 @@ line-height: var(--line-height-sm); --face-color: var(--border-color); color: var(--color); + transition: + color, + background-color, + border-color, + outline-color, + text-decoration-color, + fill, + stroke, + opacity, + box-shadow, + transform, + translate, + scale, + rotate, + filter, + -webkit-backdrop-filter, + backdrop-filter, + display, + content-visibility, + overlay, + pointer-events; + transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1); + transition-duration: 50ms; + user-select: none; + &:hover { + --face-color: var(--inv-border-color); + color: var(--background-color); + } + &:active { + --face-color: var(--orange); + } .face { transform-origin: 0 0; diff --git a/website/styles/variables.css b/website/styles/variables.css index ce08b0ffc..01ffe60c0 100644 --- a/website/styles/variables.css +++ b/website/styles/variables.css @@ -31,6 +31,7 @@ --color: light-dark(var(--black), var(--white)); --off-color: var(--gray); --border-color: light-dark(var(--light-gray), var(--dark-gray)); + --inv-border-color: light-dark(var(--dark-gray), var(--light-gray)); --off-border-color: light-dark(var(--dark-white), var(--light-black)); --font-size-xs: 0.75rem;