# brk_server

HTTP API server for Bitcoin on-chain analytics.

## Features

- **OpenAPI spec**: Auto-generated docs at `/api` with full spec at `/openapi.json`
- **LLM-optimized**: Compact spec at `/api.json` for AI tools
- **Response caching**: ETag-based with LRU cache (1000 entries by default, configurable via `ServerConfig::cache_size`)
- **Compression**: Brotli, gzip, deflate, zstd
- **Static files**: Optional web interface hosting

## Usage

```rust,ignore
let server = Server::new(
    &async_query,
    ServerConfig {
        data_path,
        website: Website::Filesystem(files_path),
        ..Default::default()
    },
);
server.serve(None).await?;
```

## Endpoints

| Path | Description |
|------|-------------|
| `/api` | Interactive API documentation |
| `/openapi.json` | Full OpenAPI specification |
| `/api.json` | Compact OpenAPI for LLMs |
| `/api/address/{address}` | Address stats, transactions, UTXOs |
| `/api/block/{hash}` | Block info, transactions, status |
| `/api/block-height/{height}` | Block by height |
| `/api/tx/{txid}` | Transaction details, status, hex |
| `/api/mempool` | Fee estimates, mempool stats |
| `/api/metrics` | Metric catalog and data queries |
| `/api/v1/mining/...` | Hashrate, difficulty, pools |

## Caching

ETag-based revalidation. Five strategies pick the etag scheme:

- **Tip**: chain-state, etag = tip hash prefix (invalidates per block + reorgs)
- **Immutable**: deeply-confirmed data, etag = format version
- **BlockBound**: data tied to a specific block hash (reorg-safe)
- **Deploy**: catalog/static data, etag = build version
- **MempoolHash**: mempool data, etag = projected next-block hash

Browser sees `Cache-Control: public, no-cache, stale-if-error=86400` (always
revalidate, ETag makes it cheap). CDN sees a separate `CDN-Cache-Control`
directive whose stable tier is selected by `CdnCacheMode` (`Live` revalidates
every request; `Aggressive` caches up to a year as `immutable` and requires a
purge on deploy).

## Configuration

Binds to port 3110, auto-incrementing up to 3210 if busy.

## Dependencies

- `brk_query` - data access
- `aide` + `axum` - HTTP routing and OpenAPI
- `tower-http` - compression and tracing