chore: standardize configuration, logging, and error handling across blockchain node and coordinator API
- Add infrastructure.md and workflow files to .gitignore to prevent sensitive info leaks - Change blockchain node mempool backend default from memory to database for persistence - Refactor blockchain node logger with StructuredLogFormatter and AuditLogger (consistent with coordinator) - Add structured logging fields: service, module, function, line number - Unify coordinator config with Database
This commit is contained in:
oib
340
docs/6_architecture/3_coordinator-api.md
Normal file
340
docs/6_architecture/3_coordinator-api.md
Normal file
@@ -0,0 +1,340 @@
|
||||
# Coordinator API - AITBC Documentation
|
||||
|
||||
FastAPI service for job submission, miner registration, and receipt management. SQLite persistence with comprehensive endpoints.
|
||||
|
||||
<span class="component-status live">● Live</span>
|
||||
|
||||
## Overview
|
||||
|
||||
The Coordinator API is the central orchestration layer that manages job distribution between clients and miners in the AITBC network. It handles job submissions, miner registrations, and tracks all computation receipts.
|
||||
|
||||
### Key Features
|
||||
|
||||
- Job submission and tracking
|
||||
- Miner registration and heartbeat monitoring
|
||||
- Receipt management and verification
|
||||
- User management with wallet-based authentication
|
||||
- SQLite persistence with SQLModel ORM
|
||||
- Comprehensive API documentation with OpenAPI
|
||||
|
||||
## Architecture
|
||||
|
||||
The Coordinator API follows a clean architecture with separation of concerns for domain models, API routes, and business logic.
|
||||
|
||||
#### API Layer
|
||||
FastAPI routers for clients, miners, admin, and users
|
||||
|
||||
#### Domain Models
|
||||
SQLModel definitions for jobs, miners, receipts, users
|
||||
|
||||
#### Business Logic
|
||||
Service layer handling job orchestration
|
||||
|
||||
#### Persistence
|
||||
SQLite database with Alembic migrations
|
||||
|
||||
## API Reference
|
||||
|
||||
The Coordinator API provides RESTful endpoints for all major operations.
|
||||
|
||||
### Client Endpoints
|
||||
|
||||
`POST /v1/client/jobs`
|
||||
Submit a new computation job
|
||||
|
||||
`GET /v1/client/jobs/{job_id}/status`
|
||||
Get job status and progress
|
||||
|
||||
`GET /v1/client/jobs/{job_id}/receipts`
|
||||
Retrieve computation receipts
|
||||
|
||||
### Miner Endpoints
|
||||
|
||||
`POST /v1/miner/register`
|
||||
Register as a compute provider
|
||||
|
||||
`POST /v1/miner/heartbeat`
|
||||
Send miner heartbeat
|
||||
|
||||
`GET /v1/miner/jobs`
|
||||
Fetch available jobs
|
||||
|
||||
`POST /v1/miner/result`
|
||||
Submit job result
|
||||
|
||||
### User Management
|
||||
|
||||
`POST /v1/users/login`
|
||||
Login or register with wallet
|
||||
|
||||
`GET /v1/users/me`
|
||||
Get current user profile
|
||||
|
||||
`GET /v1/users/{user_id}/balance`
|
||||
Get user wallet balance
|
||||
|
||||
### GPU Marketplace Endpoints
|
||||
|
||||
`POST /v1/marketplace/gpu/register`
|
||||
Register a GPU on the marketplace
|
||||
|
||||
`GET /v1/marketplace/gpu/list`
|
||||
List available GPUs (filter by available, model, price, region)
|
||||
|
||||
`GET /v1/marketplace/gpu/{gpu_id}`
|
||||
Get GPU details
|
||||
|
||||
`POST /v1/marketplace/gpu/{gpu_id}/book`
|
||||
Book a GPU for a duration
|
||||
|
||||
`POST /v1/marketplace/gpu/{gpu_id}/release`
|
||||
Release a booked GPU
|
||||
|
||||
`GET /v1/marketplace/gpu/{gpu_id}/reviews`
|
||||
Get reviews for a GPU
|
||||
|
||||
`POST /v1/marketplace/gpu/{gpu_id}/reviews`
|
||||
Add a review for a GPU
|
||||
|
||||
`GET /v1/marketplace/orders`
|
||||
List marketplace orders
|
||||
|
||||
`GET /v1/marketplace/pricing/{model}`
|
||||
Get pricing for a GPU model
|
||||
|
||||
### Payment Endpoints
|
||||
|
||||
`POST /v1/payments`
|
||||
Create payment for a job
|
||||
|
||||
`GET /v1/payments/{payment_id}`
|
||||
Get payment details
|
||||
|
||||
`GET /v1/jobs/{job_id}/payment`
|
||||
Get payment for a job
|
||||
|
||||
`POST /v1/payments/{payment_id}/release`
|
||||
Release payment from escrow
|
||||
|
||||
`POST /v1/payments/{payment_id}/refund`
|
||||
Refund payment
|
||||
|
||||
`GET /v1/payments/{payment_id}/receipt`
|
||||
Get payment receipt
|
||||
|
||||
### Governance Endpoints
|
||||
|
||||
`POST /v1/governance/proposals`
|
||||
Create a governance proposal
|
||||
|
||||
`GET /v1/governance/proposals`
|
||||
List proposals (filter by status)
|
||||
|
||||
`GET /v1/governance/proposals/{proposal_id}`
|
||||
Get proposal details
|
||||
|
||||
`POST /v1/governance/vote`
|
||||
Submit a vote on a proposal
|
||||
|
||||
`GET /v1/governance/voting-power/{user_id}`
|
||||
Get voting power for a user
|
||||
|
||||
`GET /v1/governance/parameters`
|
||||
Get governance parameters
|
||||
|
||||
`POST /v1/governance/execute/{proposal_id}`
|
||||
Execute an approved proposal
|
||||
|
||||
### Explorer Endpoints
|
||||
|
||||
`GET /v1/explorer/blocks`
|
||||
List recent blocks
|
||||
|
||||
`GET /v1/explorer/transactions`
|
||||
List recent transactions
|
||||
|
||||
`GET /v1/explorer/addresses`
|
||||
List address summaries
|
||||
|
||||
`GET /v1/explorer/receipts`
|
||||
List job receipts
|
||||
|
||||
### Exchange Endpoints
|
||||
|
||||
`POST /v1/exchange/create-payment`
|
||||
Create Bitcoin payment request
|
||||
|
||||
`GET /v1/exchange/payment-status/{id}`
|
||||
Check payment status
|
||||
|
||||
## Authentication
|
||||
|
||||
The API uses API key authentication for clients and miners, and session-based authentication for users.
|
||||
|
||||
### API Keys
|
||||
|
||||
```http
|
||||
X-Api-Key: your-api-key-here
|
||||
```
|
||||
|
||||
### Session Tokens
|
||||
|
||||
```http
|
||||
X-Session-Token: sha256-token-here
|
||||
```
|
||||
|
||||
### Example Request
|
||||
|
||||
```bash
|
||||
curl -X POST "https://aitbc.bubuit.net/api/v1/client/jobs" \
|
||||
-H "X-Api-Key: your-key" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"job_type": "llm_inference",
|
||||
"parameters": {...}
|
||||
}'
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
The Coordinator API can be configured via environment variables.
|
||||
|
||||
### Environment Variables
|
||||
|
||||
```bash
|
||||
# Database
|
||||
DATABASE_URL=sqlite:///coordinator.db
|
||||
|
||||
# API Settings
|
||||
API_HOST=0.0.0.0
|
||||
API_PORT=8000
|
||||
|
||||
# Security
|
||||
SECRET_KEY=your-secret-key
|
||||
API_KEYS=key1,key2,key3
|
||||
|
||||
# Exchange
|
||||
BITCOIN_ADDRESS=tb1qxy2...
|
||||
BTC_TO_AITBC_RATE=100000
|
||||
```
|
||||
|
||||
## Deployment
|
||||
|
||||
The Coordinator API runs in a Docker container with nginx proxy.
|
||||
|
||||
### Docker Deployment
|
||||
|
||||
```bash
|
||||
# Build image
|
||||
docker build -t aitbc-coordinator .
|
||||
|
||||
# Run container
|
||||
docker run -d \
|
||||
--name aitbc-coordinator \
|
||||
-p 8000:8000 \
|
||||
-e DATABASE_URL=sqlite:///data/coordinator.db \
|
||||
-v $(pwd)/data:/app/data \
|
||||
aitbc-coordinator
|
||||
```
|
||||
|
||||
### Systemd Service
|
||||
|
||||
```bash
|
||||
# Start service
|
||||
sudo systemctl start aitbc-coordinator
|
||||
|
||||
# Check status
|
||||
sudo systemctl status aitbc-coordinator
|
||||
|
||||
# View logs
|
||||
sudo journalctl -u aitbc-coordinator -f
|
||||
```
|
||||
|
||||
## Interactive API Documentation
|
||||
|
||||
Interactive API documentation is available via Swagger UI and ReDoc.
|
||||
|
||||
- [Swagger UI](https://aitbc.bubuit.net/api/docs)
|
||||
- [ReDoc](https://aitbc.bubuit.net/api/redoc)
|
||||
- [OpenAPI Spec](https://aitbc.bubuit.net/api/openapi.json)
|
||||
|
||||
## Data Models
|
||||
|
||||
### Job
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "uuid",
|
||||
"client_id": "string",
|
||||
"job_type": "llm_inference",
|
||||
"parameters": {},
|
||||
"status": "pending|running|completed|failed",
|
||||
"created_at": "timestamp",
|
||||
"updated_at": "timestamp"
|
||||
}
|
||||
```
|
||||
|
||||
### Miner
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "uuid",
|
||||
"address": "string",
|
||||
"endpoint": "string",
|
||||
"capabilities": [],
|
||||
"status": "active|inactive",
|
||||
"last_heartbeat": "timestamp"
|
||||
}
|
||||
```
|
||||
|
||||
### Receipt
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "uuid",
|
||||
"job_id": "uuid",
|
||||
"miner_id": "uuid",
|
||||
"result": {},
|
||||
"proof": "string",
|
||||
"created_at": "timestamp"
|
||||
}
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
The API returns standard HTTP status codes with detailed error messages:
|
||||
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"code": "INVALID_JOB_TYPE",
|
||||
"message": "The specified job type is not supported",
|
||||
"details": {}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Rate Limiting
|
||||
|
||||
API endpoints are rate-limited to prevent abuse:
|
||||
|
||||
- Client endpoints: 100 requests/minute
|
||||
- Miner endpoints: 1000 requests/minute
|
||||
- User endpoints: 60 requests/minute
|
||||
|
||||
## Monitoring
|
||||
|
||||
The Coordinator API exposes metrics at `/metrics` endpoint:
|
||||
|
||||
- `api_requests_total` - Total API requests
|
||||
- `api_request_duration_seconds` - Request latency
|
||||
- `active_jobs` - Currently active jobs
|
||||
- `registered_miners` - Number of registered miners
|
||||
|
||||
## Security
|
||||
|
||||
- All sensitive endpoints require authentication
|
||||
- API keys should be kept confidential
|
||||
- HTTPS is required in production
|
||||
- Input validation on all endpoints
|
||||
- SQL injection prevention via ORM
|
||||
Reference in New Issue
Block a user