mirror of
https://github.com/bitcoinresearchkit/brk.git
synced 2026-05-19 14:24:47 -07:00
67 lines
2.1 KiB
Markdown
67 lines
2.1 KiB
Markdown
# 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
|