Move blockchain app READMEs to centralized documentation
Some checks failed
API Endpoint Tests / test-api-endpoints (push) Successful in 10s
Blockchain Synchronization Verification / sync-verification (push) Failing after 3s
CLI Tests / test-cli (push) Failing after 4s
Documentation Validation / validate-docs (push) Successful in 8s
Documentation Validation / validate-policies-strict (push) Successful in 4s
Integration Tests / test-service-integration (push) Successful in 38s
Multi-Node Blockchain Health Monitoring / health-check (push) Successful in 2s
P2P Network Verification / p2p-verification (push) Successful in 3s
Security Scanning / security-scan (push) Successful in 40s
Smart Contract Tests / test-solidity (map[name:aitbc-token path:packages/solidity/aitbc-token]) (push) Successful in 15s
Smart Contract Tests / lint-solidity (push) Successful in 8s

- Relocate blockchain-event-bridge README content to docs/apps/blockchain/blockchain-event-bridge.md
- Relocate blockchain-explorer README content to docs/apps/blockchain/blockchain-explorer.md
- Replace app READMEs with redirect notices pointing to new documentation location
- Consolidate documentation in central docs/ directory for better organization
This commit is contained in:
aitbc
2026-04-23 12:24:48 +02:00
parent cd240485c6
commit 522655ef92
55 changed files with 7033 additions and 1536 deletions

View File

@@ -1,55 +1,9 @@
# Coordinator API
## Purpose & Scope
**Documentation has moved to:** [docs/apps/coordinator/coordinator-api.md](../../docs/apps/coordinator/coordinator-api.md)
FastAPI service that accepts client compute jobs, matches miners, and tracks job lifecycle for the AITBC network.
---
## Marketplace Extensions
This file has been migrated to the central documentation location. Please update your bookmarks and references to point to the new location.
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:
```bash
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/`).
For the complete documentation, see the [Coordinator API documentation](../../docs/apps/coordinator/coordinator-api.md).