19d415a235
- Add SQLCipher encryption for ait-mainnet database with configurable flag - Add db_encryption_enabled and db_encryption_key_path config settings - Implement encryption key loading and PRAGMA key setup via connection events - Add shutdown_db function for proper database cleanup - Export middleware classes in aitbc/__init__.py - Fix import path in sync.py for settings - Remove duplicate agent documentation from docs
6.6 KiB
Coordinator API - AITBC Documentation
FastAPI service for job submission, miner registration, and receipt management. SQLite persistence with comprehensive endpoints.
● Live
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
X-Api-Key: your-api-key-here
Session Tokens
X-Session-Token: sha256-token-here
Example Request
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
# 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
# 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
# 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.
Data Models
Job
{
"id": "uuid",
"client_id": "string",
"job_type": "llm_inference",
"parameters": {},
"status": "pending|running|completed|failed",
"created_at": "timestamp",
"updated_at": "timestamp"
}
Miner
{
"id": "uuid",
"address": "string",
"endpoint": "string",
"capabilities": [],
"status": "active|inactive",
"last_heartbeat": "timestamp"
}
Receipt
{
"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:
{
"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 requestsapi_request_duration_seconds- Request latencyactive_jobs- Currently active jobsregistered_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