readmes: simplified

2026-07-24 09:28:11 -07:00 · 2025-12-18 17:10:23 +01:00
parent 549e2da05b
commit c5657b9c31
23 changed files with 812 additions and 2968 deletions
@@ -1,39 +1,53 @@
 # brk_server

-HTTP server for the Bitcoin Research Kit.
+HTTP API server for Bitcoin on-chain analytics.

-[![Crates.io](https://img.shields.io/crates/v/brk_server.svg)](https://crates.io/crates/brk_server)
-[![Documentation](https://docs.rs/brk_server/badge.svg)](https://docs.rs/brk_server)
+## What It Enables

-## Overview
+Serve BRK data via REST API with OpenAPI documentation, response caching, MCP endpoint, and optional static file hosting for web interfaces.

-This crate provides an HTTP server that exposes BRK's blockchain data through a REST API. It serves as the web interface layer for the Bitcoin Research Kit, making data accessible to applications, dashboards, and research tools.
+## Key Features

-Built on `axum` with automatic OpenAPI documentation via Scalar.
+- **OpenAPI spec**: Auto-generated documentation at `/api/openapi.json`
+- **Response caching**: LRU cache with 5000 entries for repeated queries
+- **Compression**: Brotli, gzip, deflate, zstd support
+- **MCP endpoint**: Server-Sent Events transport at `/mcp/sse`
+- **Static files**: Optional web interface hosting
+- **Request logging**: Colorized status/latency logging

-## Usage
+## Core API

 ```rust
-use brk_server::Server;
-use brk_query::AsyncQuery;
-
-let query = AsyncQuery::build(&reader, &indexer, &computer, Some(mempool));
-let server = Server::new(&query, None);
-
-// Starts on port 3110 (or next available)
-server.serve(true).await?;
+let server = Server::new(&async_query, Some(files_path));
+server.serve(true).await?;  // true enables MCP endpoint
 ```

-Once running:
- **API Documentation**: `http://localhost:3110/api`
- **OpenAPI Spec**: `http://localhost:3110/api.json`
+## API Endpoints

-## Features
+| Path | Description |
+|------|-------------|
+| `/api/blocks/{height}` | Block info, transactions, status |
+| `/api/txs/{txid}` | Transaction details, status, merkle proof |
+| `/api/addresses/{addr}` | Address stats, transactions, UTXOs |
+| `/api/metrics` | Metric catalog and data queries |
+| `/api/mining/*` | Hashrate, difficulty, pools, epochs |
+| `/api/mempool/*` | Fee estimates, projected blocks |
+| `/mcp/sse` | MCP Server-Sent Events endpoint |

- **REST API** for addresses, blocks, transactions, mempool, mining stats, and metrics
- **OpenAPI documentation** with interactive Scalar UI
- **Multiple formats**: JSON and CSV output
- **HTTP caching**: ETag-based conditional requests
- **Compression**: Gzip, Brotli, Deflate, Zstd
- **MCP support**: Model Context Protocol for AI integrations
- **Static file serving**: Optional web interface hosting
+## Caching
+
+Uses ETag-based caching with stale-while-revalidate semantics:
+- Height-indexed data: Cache until height changes
+- Date-indexed data: Cache with longer TTL
+- Mempool data: Short TTL, frequent updates
+
+## Configuration
+
+Server binds to port 3110 by default, auto-incrementing if busy (up to 3210).
+
+## Built On
+
+- `brk_query` for data access
+- `brk_mcp` for MCP protocol
+- `aide` + `axum` for HTTP routing and OpenAPI
+- `tower-http` for compression and tracing