types: docs

crates/brk_server/src/api/mempool_space/blocks.rs

@@ -199,7 +199,7 @@ impl BlockRoutes for ApiRouter<AppState> {
                 "/api/blocks/tip/hash",
                 get_with(
                     async |uri: Uri, headers: HeaderMap, State(state): State<AppState>| {
-                        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")

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,
 }

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,
 }

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,
 }

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,
 }

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<BlockSizeEntry>,
+    /// Block weight data points
     pub weights: Vec<BlockWeightEntry>,
 }

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,
 }

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,
 }
 

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,
 }

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<HistoricalPriceEntry>,
+    /// 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,
 }

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,
 }
 

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<String>,
+    /// Transaction position in the block
     pub pos: usize,
 }

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,
 }

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<TxIndex>,
 
+    /// 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,
 }
 

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,
 }