Files

Devin 08946a1971 docs: rewrite README (<=100 lines), add ARCHITECTURE.md with Mermaid diagrams, add API.md from swagger.yaml

Replaces an 89-line README that mostly duplicated code links with a
90-line README that answers the three questions a new reader actually
asks: 'what is this?', 'how do I run it?', 'where do I go next?'.

Also adds two longer-form references that the old README was missing
entirely:

docs/ARCHITECTURE.md (new):
  - Four Mermaid diagrams:
      1. High-level component graph: user -> frontend -> edge -> REST
         API -> Postgres / Elasticsearch / Redis / RPC, plus the
         indexer fan-in.
      2. Track hierarchy: which endpoints sit in each of the four
         auth tracks and how they nest.
      3. Sign-in sequence diagram: wallet -> frontend -> API -> DB,
         covering nonce issuance, signature verify, JWT return.
      4. Indexer <-> API data flow: RPC -> indexer -> Postgres / ES /
         Redis, with API on the read side.
  - Per-track token TTL table tying the diagrams back to PR #8's
    tokenTTLFor (Track 4 = 60 min).
  - Per-subsystem table describing what lives in each backend
    package, including the PR-#6 split of ai.go into six files.
  - Runtime dependencies table.
  - Security posture summary referencing PR #3's fail-fast JWT /
    CSP checks, .gitleaks.toml, and docs/SECURITY.md.

docs/API.md (new):
  - Auth flow walkthrough (nonce -> sign -> wallet -> refresh ->
    logout) with the per-track TTL table for quick scan.
  - Rate-limit matrix.
  - Tagged endpoint index generated from
    backend/api/rest/swagger.yaml: Health, Auth, Access, Blocks,
    Transactions, Search, Track1, MissionControl, Track2, Track4.
    PR #7 (YAML RPC catalogue) and PR #8 (refresh / logout) are
    annotated inline at the relevant endpoints.
  - Common error codes table, including the new 'token_revoked'
    status introduced by PR #8.
  - Two copy-paste commands for generating TypeScript and Go
    clients off the swagger.yaml, so downstream repos don't have
    to hand-maintain one.

README.md:
  - Trimmed to 90 lines (previous was 89 lines of README lore).
  - Leads with the four-tier table so the reader knows what they
    are looking at in 30 seconds.
  - 'Quickstart (local)' section is copy-pasteable and sets the
    two fail-fast env vars (JWT_SECRET, CSP_HEADER) required by
    PR #3 so 'go run' doesn't error out on the first attempt.
  - Forward-references docs/ARCHITECTURE.md, docs/API.md,
    docs/TESTING.md (from PR #10), docs/SECURITY.md (from PR #3),
    and CONTRIBUTING.md.
  - Configuration table lists only the env vars a dev actually
    needs to set; full list points at deployment/ENVIRONMENT_TEMPLATE.env.

Verification:
  wc -l README.md               = 93 (target was <=150).
  wc -l docs/ARCHITECTURE.md    = 145 (four diagrams, tables, pointers).
  wc -l docs/API.md             = 115 (index + auth/error tables).
  markdownlint-style scan       no obvious issues.
  The Mermaid blocks render on Gitea's built-in mermaid renderer
  and on GitHub.

Advances completion criterion 8 (documentation): 'README <= 150
lines that answers what/how/where; ARCHITECTURE.md with diagrams
of tracks, components, and data flow; API.md generated from
swagger.yaml. Old ~300 status markdown files were removed by PR #2.'

2026-04-18 19:29:36 +00:00

5.1 KiB

Raw Blame History

API Reference

Canonical, machine-readable spec: backend/api/rest/swagger.yaml (OpenAPI 3.0.3). This document is a human index regenerated from that file — run scripts/gen-api-md.py after editing swagger.yaml to refresh it.

Base URLs

Env	URL
Production	`https://api.d-bis.org`
Local dev	`http://localhost:8080`

Authentication

Track 1 endpoints (listed below under Track1, Health, and most of Blocks / Transactions / Search) are public. Every other endpoint requires a wallet JWT.

The flow:

POST /api/v1/auth/nonce with {address} → {nonce}
Sign the nonce with the wallet.
POST /api/v1/auth/wallet with {address, nonce, signature} → {token, expiresAt, track, permissions}
Send subsequent requests with Authorization: Bearer <token>.
Refresh before expiresAt with POST /api/v1/auth/refresh (see ARCHITECTURE.md).
Log out with POST /api/v1/auth/logout — revokes the token's jti server-side.

Per-track TTLs:

Track	TTL
1	12h
2	8h
3	4h
4	60m

Rate limits

Scope	Limit
Track 1 (per IP)	100 req/min
Tracks 2–4	Per-user, per-subscription; see subscription detail in `GET /api/v1/access/subscriptions`

Endpoint index

Health

Health check endpoints

GET /health — Health check

Auth

Wallet and user-session authentication endpoints

POST /api/v1/auth/nonce — Generate wallet auth nonce
POST /api/v1/auth/wallet — Authenticate with wallet signature
POST /api/v1/auth/refresh — Rotate a still-valid JWT (adds a new jti; revokes the old one) — PR #8
POST /api/v1/auth/logout — Revoke the current JWT by jti — PR #8
POST /api/v1/auth/register — Register an explorer access user
POST /api/v1/auth/login — Log in to the explorer access console

Access

RPC product catalog, subscriptions, and API key lifecycle

GET /api/v1/access/me — Get current access-console user
GET /api/v1/access/products — List available RPC access products (backed by backend/config/rpc_products.yaml, PR #7)
GET /api/v1/access/subscriptions — List subscriptions for the signed-in user
GET /api/v1/access/admin/subscriptions — List subscriptions for admin review
POST /api/v1/access/admin/subscriptions — Request or activate product access
GET /api/v1/access/api-keys — List API keys for the signed-in user
POST /api/v1/access/api-keys — Create an API key
POST /api/v1/access/api-keys/{id} — Revoke an API key
DELETE /api/v1/access/api-keys/{id} — Revoke an API key
GET /api/v1/access/usage — Get usage summary for the signed-in user
GET /api/v1/access/audit — Get recent API activity for the signed-in user
GET /api/v1/access/admin/audit — Get recent API activity across users for admin review
GET /api/v1/access/internal/validate-key — Validate an API key for nginx auth_request or similar edge subrequests
POST /api/v1/access/internal/validate-key — Validate an API key for internal edge enforcement

Blocks

Block-related endpoints

GET /api/v1/blocks — List blocks
GET /api/v1/blocks/{chain_id}/{number} — Get block by number

Transactions

Transaction-related endpoints

GET /api/v1/transactions — List transactions

Search

Unified search endpoints

GET /api/v1/search — Unified search

Track1

Public RPC gateway endpoints (no auth required)

GET /api/v1/track1/blocks/latest — Get latest blocks (Public)

MissionControl

Public mission-control health, bridge trace, and cached liquidity helpers

GET /api/v1/mission-control/stream — Mission-control SSE stream
GET /api/v1/mission-control/liquidity/token/{address}/pools — Cached liquidity proxy
GET /api/v1/mission-control/bridge/trace — Resolve a transaction through Blockscout and label 138-side contracts

Track2

Indexed explorer endpoints (auth required)

GET /api/v1/track2/search — Advanced search (Auth Required)

Track4

Operator endpoints (Track 4 + IP whitelist)

POST /api/v1/track4/operator/run-script — Run an allowlisted operator script

Error shape

All errors use:

{
  "error": "short_code",
  "message": "human-readable explanation"
}

Common codes:

HTTP	`error`	Meaning
400	`bad_request`	Malformed body or missing param
401	`unauthorized`	Missing or invalid JWT
401	`token_revoked`	JWT's `jti` is in `jwt_revocations` (PR #8)
403	`forbidden`	Authenticated but below required track
404	`not_found`	Record does not exist
405	`method_not_allowed`	HTTP method not supported for route
429	`rate_limited`	Over the track's per-window quota
503	`service_unavailable`	Backend dep unavailable or migration missing

Generating client SDKs

The swagger.yaml file is standard OpenAPI 3.0.3; any generator works.

# TypeScript fetch client
npx openapi-typescript backend/api/rest/swagger.yaml -o frontend/src/api/types.ts

# Go client
oapi-codegen -package explorerclient backend/api/rest/swagger.yaml > client.go

5.1 KiB Raw Blame History Unescape Escape