diff --git a/crates/brk_server/src/api/mempool_space/blocks.rs b/crates/brk_server/src/api/mempool_space/blocks.rs index 980221d05..252adb35e 100644 --- a/crates/brk_server/src/api/mempool_space/blocks.rs +++ b/crates/brk_server/src/api/mempool_space/blocks.rs @@ -199,7 +199,7 @@ impl BlockRoutes for ApiRouter { "/api/blocks/tip/hash", get_with( async |uri: Uri, headers: HeaderMap, State(state): State| { - state.cached_text(&headers, CacheStrategy::Tip, &uri, |q| q.block_hash_by_height(q.height()).map(|h| h.to_string())).await + state.cached_text(&headers, CacheStrategy::Tip, &uri, |q| Ok(q.tip_blockhash().to_string())).await }, |op| { op.id("get_block_tip_hash") diff --git a/crates/brk_types/src/block_fee_rates_entry.rs b/crates/brk_types/src/block_fee_rates_entry.rs index cb4f94e27..279d44ae6 100644 --- a/crates/brk_types/src/block_fee_rates_entry.rs +++ b/crates/brk_types/src/block_fee_rates_entry.rs @@ -9,8 +9,11 @@ use super::FeeRatePercentiles; #[derive(Debug, Serialize, JsonSchema)] #[serde(rename_all = "camelCase")] pub struct BlockFeeRatesEntry { + /// Average block height in this window pub avg_height: Height, + /// Unix timestamp at the window midpoint pub timestamp: Timestamp, + /// Fee rate percentiles (min, 10th, 25th, median, 75th, 90th, max) #[serde(flatten)] pub percentiles: FeeRatePercentiles, } diff --git a/crates/brk_types/src/block_fees_entry.rs b/crates/brk_types/src/block_fees_entry.rs index e9a67b460..002e8ca34 100644 --- a/crates/brk_types/src/block_fees_entry.rs +++ b/crates/brk_types/src/block_fees_entry.rs @@ -7,10 +7,17 @@ use crate::{Dollars, Height, Sats, Timestamp}; #[derive(Debug, Serialize, Deserialize, JsonSchema)] #[serde(rename_all = "camelCase")] pub struct BlockFeesEntry { + /// Average block height in this window + #[schemars(example = 890621)] pub avg_height: Height, + /// Unix timestamp at the window midpoint + #[schemars(example = 1743631892)] pub timestamp: Timestamp, + /// Average fees per block in this window (sats) + #[schemars(example = 3215861)] pub avg_fees: Sats, - /// BTC/USD price at that height + /// BTC/USD price at this height #[serde(rename = "USD")] + #[schemars(example = 84342.12)] pub usd: Dollars, } diff --git a/crates/brk_types/src/block_rewards_entry.rs b/crates/brk_types/src/block_rewards_entry.rs index fb7e0d9cd..f7ad386f7 100644 --- a/crates/brk_types/src/block_rewards_entry.rs +++ b/crates/brk_types/src/block_rewards_entry.rs @@ -7,10 +7,17 @@ use crate::{Dollars, Height, Sats, Timestamp}; #[derive(Debug, Serialize, Deserialize, JsonSchema)] #[serde(rename_all = "camelCase")] pub struct BlockRewardsEntry { + /// Average block height in this window + #[schemars(example = 890621)] pub avg_height: Height, + /// Unix timestamp at the window midpoint + #[schemars(example = 1743631892)] pub timestamp: Timestamp, + /// Average coinbase reward per block (subsidy + fees, sats) + #[schemars(example = 315715861)] pub avg_rewards: Sats, - /// BTC/USD price at that height + /// BTC/USD price at this height #[serde(rename = "USD")] + #[schemars(example = 84342.12)] pub usd: Dollars, } diff --git a/crates/brk_types/src/block_size_entry.rs b/crates/brk_types/src/block_size_entry.rs index f5541284c..922c92d9c 100644 --- a/crates/brk_types/src/block_size_entry.rs +++ b/crates/brk_types/src/block_size_entry.rs @@ -7,7 +7,13 @@ use crate::{Height, Timestamp}; #[derive(Debug, Serialize, Deserialize, JsonSchema)] #[serde(rename_all = "camelCase")] pub struct BlockSizeEntry { + /// Average block height in this window + #[schemars(example = 890621)] pub avg_height: Height, + /// Unix timestamp at the window midpoint + #[schemars(example = 1743631892)] pub timestamp: Timestamp, + /// Rolling 24h median block size (bytes) + #[schemars(example = 1580000)] pub avg_size: u64, } diff --git a/crates/brk_types/src/block_sizes_weights.rs b/crates/brk_types/src/block_sizes_weights.rs index d52d15641..1ecf9de48 100644 --- a/crates/brk_types/src/block_sizes_weights.rs +++ b/crates/brk_types/src/block_sizes_weights.rs @@ -6,6 +6,8 @@ use super::{BlockSizeEntry, BlockWeightEntry}; /// Combined block sizes and weights response. #[derive(Debug, Serialize, Deserialize, JsonSchema)] pub struct BlockSizesWeights { + /// Block size data points pub sizes: Vec, + /// Block weight data points pub weights: Vec, } diff --git a/crates/brk_types/src/block_weight_entry.rs b/crates/brk_types/src/block_weight_entry.rs index fc001d41c..b8d55ad7b 100644 --- a/crates/brk_types/src/block_weight_entry.rs +++ b/crates/brk_types/src/block_weight_entry.rs @@ -7,7 +7,13 @@ use crate::{Height, Timestamp, Weight}; #[derive(Debug, Serialize, Deserialize, JsonSchema)] #[serde(rename_all = "camelCase")] pub struct BlockWeightEntry { + /// Average block height in this window + #[schemars(example = 890621)] pub avg_height: Height, + /// Unix timestamp at the window midpoint + #[schemars(example = 1743631892)] pub timestamp: Timestamp, + /// Rolling 24h median block weight (weight units) + #[schemars(example = 3990000)] pub avg_weight: Weight, } diff --git a/crates/brk_types/src/difficulty_adjustment_entry.rs b/crates/brk_types/src/difficulty_adjustment_entry.rs index 4f3349656..eef1d55ab 100644 --- a/crates/brk_types/src/difficulty_adjustment_entry.rs +++ b/crates/brk_types/src/difficulty_adjustment_entry.rs @@ -8,9 +8,13 @@ use crate::{Height, Timestamp}; /// Serializes as array: [timestamp, height, difficulty, change_percent] #[derive(Debug, Deserialize, JsonSchema)] pub struct DifficultyAdjustmentEntry { + /// Unix timestamp of the adjustment pub timestamp: Timestamp, + /// Block height of the adjustment pub height: Height, + /// Difficulty value pub difficulty: f64, + /// Adjustment ratio (new/previous, e.g. 1.068 = +6.8%) pub change_percent: f64, } diff --git a/crates/brk_types/src/health.rs b/crates/brk_types/src/health.rs index 6187dd4bc..6ee250146 100644 --- a/crates/brk_types/src/health.rs +++ b/crates/brk_types/src/health.rs @@ -8,14 +8,19 @@ use crate::SyncStatus; /// Server health status #[derive(Debug, Serialize, Deserialize, JsonSchema)] pub struct Health { + /// Health status ("healthy") pub status: Cow<'static, str>, + /// Service name pub service: Cow<'static, str>, + /// Server version pub version: Cow<'static, str>, + /// Current server time (ISO 8601) pub timestamp: String, /// Server start time (ISO 8601) pub started_at: String, /// Uptime in seconds pub uptime_seconds: u64, + /// Sync status #[serde(flatten)] pub sync: SyncStatus, } diff --git a/crates/brk_types/src/historical_price.rs b/crates/brk_types/src/historical_price.rs index 3cc1a993d..c6338ac5b 100644 --- a/crates/brk_types/src/historical_price.rs +++ b/crates/brk_types/src/historical_price.rs @@ -6,7 +6,9 @@ use crate::{Dollars, Timestamp}; /// Current price response matching mempool.space /api/v1/prices format #[derive(Debug, Serialize, Deserialize, JsonSchema)] pub struct Prices { + /// Unix timestamp pub time: Timestamp, + /// BTC/USD price #[serde(rename = "USD")] pub usd: Dollars, } @@ -14,7 +16,9 @@ pub struct Prices { /// Historical price response #[derive(Debug, Serialize, Deserialize, JsonSchema)] pub struct HistoricalPrice { + /// Price data points pub prices: Vec, + /// Exchange rates (currently empty) #[serde(rename = "exchangeRates")] pub exchange_rates: ExchangeRates, } @@ -22,7 +26,9 @@ pub struct HistoricalPrice { /// A single price data point #[derive(Debug, Serialize, Deserialize, JsonSchema)] pub struct HistoricalPriceEntry { + /// Unix timestamp pub time: u64, + /// BTC/USD price #[serde(rename = "USD")] pub usd: Dollars, } diff --git a/crates/brk_types/src/mempool_recent_tx.rs b/crates/brk_types/src/mempool_recent_tx.rs index f7b242d8c..64c166df0 100644 --- a/crates/brk_types/src/mempool_recent_tx.rs +++ b/crates/brk_types/src/mempool_recent_tx.rs @@ -3,12 +3,16 @@ use serde::{Deserialize, Serialize}; use crate::{Sats, Transaction, Txid, VSize}; -/// Simplified mempool transaction for the recent transactions endpoint +/// Simplified mempool transaction for the `/api/mempool/recent` endpoint. #[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)] pub struct MempoolRecentTx { + /// Transaction ID pub txid: Txid, + /// Transaction fee (sats) pub fee: Sats, + /// Virtual size (vbytes) pub vsize: VSize, + /// Total output value (sats) pub value: Sats, } diff --git a/crates/brk_types/src/merkle_proof.rs b/crates/brk_types/src/merkle_proof.rs index 9f5969a6b..db694dd52 100644 --- a/crates/brk_types/src/merkle_proof.rs +++ b/crates/brk_types/src/merkle_proof.rs @@ -6,7 +6,10 @@ use crate::Height; /// Merkle inclusion proof for a transaction #[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)] pub struct MerkleProof { + /// Block height containing the transaction pub block_height: Height, + /// Merkle proof path (hex-encoded hashes) pub merkle: Vec, + /// Transaction position in the block pub pos: usize, } diff --git a/crates/brk_types/src/reward_stats.rs b/crates/brk_types/src/reward_stats.rs index 46facd871..aee6ffa46 100644 --- a/crates/brk_types/src/reward_stats.rs +++ b/crates/brk_types/src/reward_stats.rs @@ -11,10 +11,13 @@ pub struct RewardStats { pub start_block: Height, /// Last block in the range pub end_block: Height, + /// Total coinbase rewards (subsidy + fees) in sats #[serde(serialize_with = "sats_as_string")] pub total_reward: Sats, + /// Total transaction fees in sats #[serde(serialize_with = "sats_as_string")] pub total_fee: Sats, + /// Total number of transactions #[serde(serialize_with = "u64_as_string")] pub total_tx: u64, } diff --git a/crates/brk_types/src/tx.rs b/crates/brk_types/src/tx.rs index 3c1de9114..c0a291766 100644 --- a/crates/brk_types/src/tx.rs +++ b/crates/brk_types/src/tx.rs @@ -8,15 +8,19 @@ use vecdb::CheckedSub; /// Transaction information compatible with mempool.space API format #[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)] pub struct Transaction { + /// Internal transaction index (brk-specific, not in mempool.space) #[schemars(example = TxIndex::new(0))] pub index: Option, + /// Transaction ID #[schemars(example = "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b")] pub txid: Txid, + /// Transaction version #[schemars(example = 2)] pub version: TxVersion, + /// Transaction lock time #[schemars(example = 0)] #[serde(rename = "locktime")] pub lock_time: RawLockTime, @@ -47,6 +51,7 @@ pub struct Transaction { #[schemars(example = Sats::new(31))] pub fee: Sats, + /// Confirmation status (confirmed, block height/hash/time) pub status: TxStatus, } diff --git a/crates/brk_types/src/utxo.rs b/crates/brk_types/src/utxo.rs index 72cad1614..72c7997f2 100644 --- a/crates/brk_types/src/utxo.rs +++ b/crates/brk_types/src/utxo.rs @@ -6,8 +6,12 @@ use crate::{Sats, TxStatus, Txid, Vout}; /// Unspent transaction output #[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)] pub struct Utxo { + /// Transaction ID of the UTXO pub txid: Txid, + /// Output index pub vout: Vout, + /// Confirmation status pub status: TxStatus, + /// Output value in satoshis pub value: Sats, }