15427c96c0
- Change file mode from 644 to 755 for all project files - Add chain_id parameter to get_balance RPC endpoint with default "ait-devnet" - Rename Miner.extra_meta_data to extra_metadata for consistency
251 lines
9.7 KiB
HTML
Executable File
251 lines
9.7 KiB
HTML
Executable File
<!DOCTYPE html>
|
||
<html lang="en" data-theme="dark">
|
||
<head>
|
||
<meta charset="UTF-8">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
<title>Coordinator API - AITBC Documentation</title>
|
||
|
||
<link rel="stylesheet" href="css/docs.css">
|
||
<link rel="stylesheet" href="/assets/css/site-header.css">
|
||
<link rel="preload" href="/assets/css/font-awesome.min.css" as="style" onload="this.onload=null;this.rel='stylesheet'">
|
||
<noscript><link rel="stylesheet" href="/assets/css/font-awesome.min.css"></noscript>
|
||
<!-- Font Awesome CDN fallback -->
|
||
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.1/css/all.min.css" crossorigin="anonymous" media="print" onload="this.media='all'; this.onload=null;">
|
||
</head>
|
||
<body>
|
||
<div data-global-header></div>
|
||
|
||
<!-- Main Content -->
|
||
<main>
|
||
<div class="container">
|
||
<!-- Breadcrumb -->
|
||
<div class="breadcrumb">
|
||
<a href="index.html">Documentation</a>
|
||
<span>›</span>
|
||
<a href="components.html">Components</a>
|
||
<span>›</span>
|
||
<span>Coordinator API</span>
|
||
</div>
|
||
|
||
<!-- Back Button -->
|
||
<a href="components.html" class="back-button">
|
||
<i class="fas fa-arrow-left"></i>
|
||
Back to Components
|
||
</a>
|
||
|
||
<!-- Header -->
|
||
<div class="doc-header">
|
||
<h1><i class="fas fa-server"></i> Coordinator API</h1>
|
||
<p>FastAPI service for job submission, miner registration, and receipt management with SQLite persistence</p>
|
||
<span class="status-badge live">● Live</span>
|
||
</div>
|
||
|
||
<!-- Overview -->
|
||
<section class="content-section">
|
||
<div class="alert alert-info">
|
||
<i class="fas fa-info-circle"></i>
|
||
<strong>System Flow:</strong> See the <a href="flowchart.html">complete system flow diagram</a> to understand how the coordinator API fits into the overall AITBC architecture.
|
||
</div>
|
||
|
||
<h2>Overview</h2>
|
||
<p>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.</p>
|
||
|
||
<h3>Key Features</h3>
|
||
<ul>
|
||
<li>Job submission and tracking</li>
|
||
<li>Miner registration and heartbeat monitoring</li>
|
||
<li>Receipt management and verification</li>
|
||
<li>User management with wallet-based authentication</li>
|
||
<li>SQLite persistence with SQLModel ORM</li>
|
||
<li>Comprehensive API documentation with OpenAPI</li>
|
||
</ul>
|
||
</section>
|
||
|
||
<!-- Architecture -->
|
||
<section class="content-section">
|
||
<h2>Architecture</h2>
|
||
<p>The Coordinator API follows a clean architecture with separation of concerns for domain models, API routes, and business logic.</p>
|
||
|
||
<div class="feature-grid">
|
||
<div class="feature-card">
|
||
<h4>API Layer</h4>
|
||
<p>FastAPI routers for clients, miners, admin, and users</p>
|
||
</div>
|
||
<div class="feature-card">
|
||
<h4>Domain Models</h4>
|
||
<p>SQLModel definitions for jobs, miners, receipts, users</p>
|
||
</div>
|
||
<div class="feature-card">
|
||
<h4>Business Logic</h4>
|
||
<p>Service layer handling job orchestration</p>
|
||
</div>
|
||
<div class="feature-card">
|
||
<h4>Persistence</h4>
|
||
<p>SQLite database with Alembic migrations</p>
|
||
</div>
|
||
</div>
|
||
</section>
|
||
|
||
<!-- API Reference -->
|
||
<section class="content-section">
|
||
<h2>API Reference</h2>
|
||
<p>The Coordinator API provides RESTful endpoints for all major operations.</p>
|
||
|
||
<h3>Client Endpoints</h3>
|
||
<div class="api-endpoint">
|
||
<code>POST /v1/client/jobs</code>
|
||
<p>Submit a new computation job</p>
|
||
</div>
|
||
|
||
<div class="api-endpoint">
|
||
<code>GET /v1/client/jobs/{job_id}/status</code>
|
||
<p>Get job status and progress</p>
|
||
</div>
|
||
|
||
<div class="api-endpoint">
|
||
<code>GET /v1/client/jobs/{job_id}/receipts</code>
|
||
<p>Retrieve computation receipts</p>
|
||
</div>
|
||
|
||
<h3>Miner Endpoints</h3>
|
||
<div class="api-endpoint">
|
||
<code>POST /v1/miner/register</code>
|
||
<p>Register as a compute provider</p>
|
||
</div>
|
||
|
||
<div class="api-endpoint">
|
||
<code>POST /v1/miner/heartbeat</code>
|
||
<p>Send miner heartbeat</p>
|
||
</div>
|
||
|
||
<div class="api-endpoint">
|
||
<code>GET /v1/miner/jobs</code>
|
||
<p>Fetch available jobs</p>
|
||
</div>
|
||
|
||
<div class="api-endpoint">
|
||
<code>POST /v1/miner/result</code>
|
||
<p>Submit job result</p>
|
||
</div>
|
||
|
||
<h3>User Management</h3>
|
||
<div class="api-endpoint">
|
||
<code>POST /v1/users/login</code>
|
||
<p>Login or register with wallet</p>
|
||
</div>
|
||
|
||
<div class="api-endpoint">
|
||
<code>GET /v1/users/me</code>
|
||
<p>Get current user profile</p>
|
||
</div>
|
||
|
||
<div class="api-endpoint">
|
||
<code>GET /v1/users/{user_id}/balance</code>
|
||
<p>Get user wallet balance</p>
|
||
</div>
|
||
|
||
<h3>Exchange Endpoints</h3>
|
||
<div class="api-endpoint">
|
||
<code>POST /v1/exchange/create-payment</code>
|
||
<p>Create Bitcoin payment request</p>
|
||
</div>
|
||
|
||
<div class="api-endpoint">
|
||
<code>GET /v1/exchange/payment-status/{id}</code>
|
||
<p>Check payment status</p>
|
||
</div>
|
||
</section>
|
||
|
||
<!-- Authentication -->
|
||
<section class="content-section">
|
||
<h2>Authentication</h2>
|
||
<p>The API uses API key authentication for clients and miners, and session-based authentication for users.</p>
|
||
|
||
<h3>API Keys</h3>
|
||
<pre><code>X-Api-Key: your-api-key-here</code></pre>
|
||
|
||
<h3>Session Tokens</h3>
|
||
<pre><code>X-Session-Token: sha256-token-here</code></pre>
|
||
|
||
<h3>Example Request</h3>
|
||
<pre><code>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": {...}
|
||
}'</code></pre>
|
||
</section>
|
||
|
||
<!-- Configuration -->
|
||
<section class="content-section">
|
||
<h2>Configuration</h2>
|
||
<p>The Coordinator API can be configured via environment variables.</p>
|
||
|
||
<h3>Environment Variables</h3>
|
||
<pre><code># 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</code></pre>
|
||
</section>
|
||
|
||
<!-- Deployment -->
|
||
<section class="content-section">
|
||
<h2>Deployment</h2>
|
||
<p>The Coordinator API runs in a Docker container with nginx proxy.</p>
|
||
|
||
<h3>Docker Deployment</h3>
|
||
<pre><code># 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</code></pre>
|
||
|
||
<h3>Systemd Service</h3>
|
||
<pre><code># Start service
|
||
sudo systemctl start aitbc-coordinator
|
||
|
||
# Check status
|
||
sudo systemctl status aitbc-coordinator
|
||
|
||
# View logs
|
||
sudo journalctl -u aitbc-coordinator -f</code></pre>
|
||
</section>
|
||
|
||
<!-- API Documentation -->
|
||
<section class="content-section">
|
||
<h2>Interactive API Documentation</h2>
|
||
<p>Interactive API documentation is available via Swagger UI and ReDoc.</p>
|
||
|
||
<ul>
|
||
<li><a href="https://aitbc.bubuit.net/api/docs" target="_blank">Swagger UI</a></li>
|
||
<li><a href="https://aitbc.bubuit.net/api/redoc" target="_blank">ReDoc</a></li>
|
||
<li><a href="https://aitbc.bubuit.net/api/openapi.json" target="_blank">OpenAPI Spec</a></li>
|
||
</ul>
|
||
</section>
|
||
</div>
|
||
</main>
|
||
|
||
<script>
|
||
// Add any interactive functionality here
|
||
</script>
|
||
<script src="js/theme.js"></script>
|
||
<script src="/assets/js/global-header.js"></script>
|
||
</body>
|
||
</html>
|