server: api + doc

crates/brk_structs/src/addressinfo.rs

@@ -0,0 +1,69 @@
+use schemars::JsonSchema;
+use serde::Serialize;
+
+use crate::{Dollars, OutputType, Sats, TypeIndex};
+
+#[derive(Debug, Serialize, JsonSchema)]
+/// Address information
+pub struct AddressInfo {
+    /// Bitcoin address string
+    #[schemars(example = &"04678afdb0fe5548271967f1a67130b7105cd6a828e03909a67962e0ea1f61deb649f6bc3f4cef38c4f35504e51ec112de5c384df7ba0b8d578a4c702b6bf11d5f")]
+    pub address: String,
+
+    #[schemars(example = OutputType::P2PK65)]
+    pub r#type: OutputType,
+
+    #[schemars(example = TypeIndex::new(0))]
+    pub type_index: TypeIndex,
+
+    /// Total satoshis ever sent from this address
+    #[schemars(example = Sats::new(0))]
+    pub total_sent: Sats,
+
+    /// Total satoshis ever received by this address
+    #[schemars(example = Sats::new(5001008380))]
+    pub total_received: Sats,
+
+    /// Number of unspent transaction outputs (UTXOs)
+    #[schemars(example = 10)]
+    pub utxo_count: u32,
+
+    /// Current spendable balance in satoshis (total_received - total_sent)
+    #[schemars(example = Sats::new(5001008380))]
+    pub balance: Sats,
+
+    /// Current balance value in USD at current market price
+    #[schemars(example = Some(Dollars::mint(6_157_891.64)))]
+    pub balance_usd: Option<Dollars>,
+
+    /// Estimated total USD value at time of deposit for coins currently in this address (not including coins that were later sent out). Not suitable for tax calculations
+    #[schemars(example = Some(Dollars::mint(6.2)))]
+    pub estimated_total_invested: Option<Dollars>,
+
+    /// Estimated average BTC price at time of deposit for coins currently in this address (USD). Not suitable for tax calculations
+    #[schemars(example = Some(Dollars::mint(0.12)))]
+    pub estimated_avg_entry_price: Option<Dollars>,
+    //
+    // Transaction count?
+    // First/last activity timestamps?
+    // Realized/unrealized gains?
+    // Current value (balance × current price)?
+    // "address": address,
+    // "type": output_type,
+    // "index": addri,
+    // "chain_stats": {
+    //     "funded_txo_count":	null,
+    //     "funded_txo_sum": addr_data.received,
+    //     "spent_txo_count": null,
+    //     "spent_txo_sum": addr_data.sent,
+    //     "utxo_count": addr_data.utxos,
+    //     "balance": amount,
+    //     "balance_usd": price.map_or(Value::new(), |p| {
+    //         Value::from(Number::from_f64(*(p * Bitcoin::from(amount))).unwrap())
+    //     }),
+    //     "realized_value": addr_data.realized_cap,
+    //     "tx_count":	null,
+    //     "avg_cost_basis": addr_data.realized_price()
+    // },
+    // "mempool_stats": null
+}

crates/brk_structs/src/addresspath.rs

@@ -0,0 +1,9 @@
+use schemars::JsonSchema;
+use serde::Deserialize;
+
+#[derive(Deserialize, JsonSchema)]
+pub struct AddressPath {
+    /// Bitcoin address string
+    #[schemars(example = &"04678afdb0fe5548271967f1a67130b7105cd6a828e03909a67962e0ea1f61deb649f6bc3f4cef38c4f35504e51ec112de5c384df7ba0b8d578a4c702b6bf11d5f")]
+    pub address: String,
+}

crates/brk_structs/src/anyaddressindex.rs

@@ -19,7 +19,7 @@ impl AnyAddressIndex {
 impl From<LoadedAddressIndex> for AnyAddressIndex {
     fn from(value: LoadedAddressIndex) -> Self {
         if u32::from(value) >= MIN_EMPTY_INDEX {
-            panic!("")
+            panic!("{value} is higher than MIN_EMPTY_INDEX ({MIN_EMPTY_INDEX})")
         }
         Self(*value)
     }

crates/brk_structs/src/format.rs

@@ -0,0 +1,26 @@
+use schemars::JsonSchema;
+use serde::Deserialize;
+
+#[allow(clippy::upper_case_acronyms)]
+#[derive(Default, Debug, Clone, Copy, PartialEq, Eq, Deserialize, JsonSchema)]
+#[serde(rename_all = "lowercase")]
+pub enum Format {
+    #[default]
+    #[serde(alias = "json")]
+    JSON,
+    #[serde(alias = "csv")]
+    CSV,
+}
+
+impl From<Option<String>> for Format {
+    fn from(value: Option<String>) -> Self {
+        if let Some(value) = value {
+            let value = value.to_lowercase();
+            let value = value.as_str();
+            if value == "csv" {
+                return Self::CSV;
+            }
+        }
+        Self::JSON
+    }
+}

crates/brk_structs/src/health.rs

@@ -0,0 +1,10 @@
+use schemars::JsonSchema;
+use serde::Serialize;
+
+#[derive(Debug, Serialize, JsonSchema)]
+/// Server health status
+pub struct Health {
+    pub status: String,
+    pub service: String,
+    pub timestamp: String,
+}

crates/brk_structs/src/lib.rs

@@ -6,6 +6,8 @@ use brk_error::{Error, Result};
 
 mod addressbytes;
 mod addressbyteshash;
+mod addressinfo;
+mod addresspath;
 mod anyaddressindex;
 mod bitcoin;
 mod blkmetadata;
@@ -23,13 +25,17 @@ mod emptyaddressdata;
 mod emptyaddressindex;
 mod emptyoutputindex;
 mod feerate;
+mod format;
 mod halvingepoch;
+mod health;
 mod height;
 mod index;
 mod indexinfo;
 mod inputindex;
 mod loadedaddressdata;
 mod loadedaddressindex;
+mod metriccount;
+mod metricpath;
 mod monthindex;
 mod ohlc;
 mod opreturnindex;
@@ -63,8 +69,10 @@ mod stored_u8;
 mod timestamp;
 mod treenode;
 mod txid;
+mod txidpath;
 mod txidprefix;
 mod txindex;
+mod txinfo;
 mod txversion;
 mod typeindex;
 mod typeindex_with_outputindex;
@@ -78,6 +86,8 @@ mod yearindex;
 
 pub use addressbytes::*;
 pub use addressbyteshash::*;
+pub use addressinfo::*;
+pub use addresspath::*;
 pub use anyaddressindex::*;
 pub use bitcoin::*;
 pub use blkmetadata::*;
@@ -95,13 +105,17 @@ pub use emptyaddressdata::*;
 pub use emptyaddressindex::*;
 pub use emptyoutputindex::*;
 pub use feerate::*;
+pub use format::*;
 pub use halvingepoch::*;
+pub use health::*;
 pub use height::*;
 pub use index::*;
 pub use indexinfo::*;
 pub use inputindex::*;
 pub use loadedaddressdata::*;
 pub use loadedaddressindex::*;
+pub use metriccount::*;
+pub use metricpath::*;
 pub use monthindex::*;
 pub use ohlc::*;
 pub use opreturnindex::*;
@@ -135,8 +149,10 @@ pub use stored_u64::*;
 pub use timestamp::*;
 pub use treenode::*;
 pub use txid::*;
+pub use txidpath::*;
 pub use txidprefix::*;
 pub use txindex::*;
+pub use txinfo::*;
 pub use txversion::*;
 pub use typeindex::*;
 pub use typeindex_with_outputindex::*;

crates/brk_structs/src/metriccount.rs

@@ -0,0 +1,13 @@
+use schemars::JsonSchema;
+use serde::Serialize;
+
+#[derive(Debug, Serialize, JsonSchema)]
+/// Metric count statistics - distinct metrics and total metric-index combinations
+pub struct MetricCount {
+    #[schemars(example = 3141)]
+    /// Number of unique metrics available (e.g., realized_price, market_cap)
+    pub distinct_metrics: usize,
+    #[schemars(example = 21000)]
+    /// Total number of metric-index combinations across all timeframes
+    pub total_endpoints: usize,
+}

crates/brk_structs/src/metricpath.rs

@@ -0,0 +1,9 @@
+use schemars::JsonSchema;
+use serde::Deserialize;
+
+#[derive(Deserialize, JsonSchema)]
+pub struct MetricPath {
+    /// Metric name
+    #[schemars(example = &"price_close", example = &"market_cap", example = &"realized_price")]
+    pub metric: String,
+}

crates/brk_structs/src/txidpath.rs

@@ -0,0 +1,9 @@
+use schemars::JsonSchema;
+use serde::Deserialize;
+
+#[derive(Deserialize, JsonSchema)]
+pub struct TxidPath {
+    /// Bitcoin transaction id
+    #[schemars(example = &"4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b")]
+    pub txid: String,
+}

crates/brk_structs/src/txinfo.rs

@@ -0,0 +1,19 @@
+use schemars::JsonSchema;
+use serde::Serialize;
+
+use crate::{TxIndex, Txid};
+
+#[derive(Serialize, JsonSchema)]
+/// Transaction Information
+pub struct TransactionInfo {
+    #[schemars(
+        with = "String",
+        example = "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b"
+    )]
+    pub txid: Txid,
+    #[schemars(example = TxIndex::new(0))]
+    pub index: TxIndex,
+    // #[serde(flatten)]
+    // #[schemars(with = "serde_json::Value")]
+    // pub tx: Transaction,
+}