OpenAPI / Swagger Documentation for RustChain Node API

Bounty: 30 RTC

Overview

Document all public RustChain node API endpoints in OpenAPI 3.0 format with a Swagger UI page.

Why This Matters

Developers building tools (wallets, dashboards, bots) currently have to reverse-engineer the API by reading server source code. Proper API docs lower the barrier to entry.

Known Endpoints to Document

Public (no auth)

• GET /health — Node health check
• GET /ready — Readiness probe
• GET /epoch — Current epoch, slot, enrolled miners
• GET /api/miners — Active miners with attestation data
• GET /api/stats — Network statistics
• GET /api/hall_of_fame — Hall of Fame leaderboard (5 categories)
• GET /api/fee_pool — RIP-301 fee pool statistics
• GET /balance?miner_id=X — Miner balance lookup
• GET /lottery/eligibility?miner_id=X — Epoch eligibility check
• GET /explorer — Block explorer page

Authenticated (X-Admin-Key header)

• POST /attest/submit — Submit hardware attestation
• POST /wallet/transfer/signed — Ed25519 signed transfer
• POST /wallet/transfer — Admin transfer (requires admin key)
• POST /withdraw/request — Withdrawal request

Deliverables

1. openapi.yaml — OpenAPI 3.0 spec file
2. swagger.html — Self-contained Swagger UI page
3. PR to Scottcjn/Rustchain in docs/api/

Verification

• Spec validates with swagger-cli validate openapi.yaml
• Swagger UI loads and all endpoints are documented with request/response examples
• Test at least 3 endpoints against live node to verify accuracy

Reference

• Live node: curl -sk https://rustchain.org/health