oib/aitbc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
aitbc/apps/coordinator-api/README.md
oib d98b2c7772 Based on the repository's commit message style and the changes in the diff, here's an appropriate commit message: 
```
feat: add websocket tests, PoA metrics, marketplace endpoints, and enhanced observability

- Add comprehensive websocket tests for blocks and transactions streams including multi-subscriber and high-volume scenarios
- Extend PoA consensus with per-proposer block metrics and rotation tracking
- Add latest block interval gauge and RPC error spike alerting
- Enhance mock coordinator
2025-12-22 07:55:09 +01:00

2.4 KiB
Raw Blame History

Coordinator API

Purpose & Scope

FastAPI service that accepts client compute jobs, matches miners, and tracks job lifecycle for the AITBC network.

Marketplace Extensions

Stage 2 introduces public marketplace endpoints exposed under /v1/marketplace:

  • GET /v1/marketplace/offers – list available provider offers (filterable by status).
  • GET /v1/marketplace/stats – aggregated supply/demand metrics surfaced in the marketplace web dashboard.
  • POST /v1/marketplace/bids – accept bid submissions for matching (mock-friendly; returns 202 Accepted).

These endpoints serve the apps/marketplace-web/ dashboard via VITE_MARKETPLACE_DATA_MODE=live.

Explorer Endpoints

The coordinator now exposes read-only explorer data under /v1/explorer for apps/explorer-web/ live mode:

  • GET /v1/explorer/blocks – block summaries derived from recent job activity.
  • GET /v1/explorer/transactions – transaction-like records for coordinator jobs.
  • GET /v1/explorer/addresses – aggregated address activity and balances.
  • GET /v1/explorer/receipts – latest job receipts (filterable by job_id).

Set VITE_DATA_MODE=live and VITE_COORDINATOR_API in the explorer web app to consume these APIs.

Development Setup

  1. Create a virtual environment in apps/coordinator-api/.venv.
  2. Install dependencies listed in pyproject.toml once added.
  3. Run the FastAPI app via uvicorn app.main:app --reload.

Configuration

Expects environment variables defined in .env (see docs/bootstrap/coordinator_api.md).

Signed receipts (optional)

  • Generate an Ed25519 key: 
    python - <<'PY'
from nacl.signing import SigningKey
sk = SigningKey.generate()
print(sk.encode().hex())
PY
  • Set RECEIPT_SIGNING_KEY_HEX in the .env file to the printed hex string to enable signed receipts returned by /v1/miners/{job_id}/result and retrievable via /v1/jobs/{job_id}/receipt.
  • Receipt history is available at /v1/jobs/{job_id}/receipts (requires client API key) and returns all stored signed payloads.
  • To enable coordinator attestations, set RECEIPT_ATTESTATION_KEY_HEX to a separate Ed25519 private key; responses include an attestations array alongside the miner signature.
  • Clients can verify signature objects using the aitbc_crypto package (see protocols/receipts/spec.md).

Systemd

Service name: aitbc-coordinator-api (to be defined under configs/systemd/).