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
2026-02-13 22:39:43 +01:00
parent 0cbd2b507c
commit 06e48ef34b
196 changed files with 4660 additions and 20090 deletions
--- a/docs/2_clients/0_readme.md
+++ b/docs/2_clients/0_readme.md
@@ -0,0 +1,19 @@
+# Client Documentation
+
+Rent GPU computing power for AI/ML workloads on the AITBC network.
+
+## Reading Order
+
+| # | File | What you learn |
+|---|------|----------------|
+| 1 | [1_quick-start.md](./1_quick-start.md) | Get running in 5 minutes |
+| 2 | [2_job-submission.md](./2_job-submission.md) | Submit and configure jobs |
+| 3 | [3_job-lifecycle.md](./3_job-lifecycle.md) | Track status, get results, view history, cancel |
+| 4 | [4_wallet.md](./4_wallet.md) | Manage tokens and payments |
+| 5 | [5_pricing-billing.md](./5_pricing-billing.md) | Understand costs and invoices |
+| 6 | [6_api-reference.md](./6_api-reference.md) | REST API endpoints for integration |
+
+## Related
+
+- [CLI Guide](../0_getting_started/3_cli.md) — Command-line reference
+- [Miner Docs](../3_miners/0_readme.md) — If you also want to provide GPU resources
--- a/docs/2_clients/1_quick-start.md
+++ b/docs/2_clients/1_quick-start.md
@@ -0,0 +1,38 @@
+# Client Quick Start
+
+**5 minutes** — Install, configure, submit your first job.
+
+## 1. Install & Configure
+
+```bash
+pip install -e .                                        # from monorepo root
+aitbc config set coordinator_url http://localhost:8000
+export AITBC_API_KEY=your-key
+```
+
+## 2. Create Wallet
+
+```bash
+aitbc wallet create --name my-wallet
+```
+
+Save your seed phrase securely.
+
+## 3. Submit a Job
+
+```bash
+aitbc client submit --prompt "Summarize this document" --input data.txt
+```
+
+## 4. Track & Download
+
+```bash
+aitbc client status --job-id <JOB_ID>
+aitbc client download --job-id <JOB_ID> --output ./results
+```
+
+## Next
+
+- [2_job-submission.md](./2_job-submission.md) — Advanced job options (GPU, priority, batch)
+- [3_job-lifecycle.md](./3_job-lifecycle.md) — Status tracking, results, history
+- [5_pricing-billing.md](./5_pricing-billing.md) — Cost structure
--- a/docs/2_clients/2_job-submission.md
+++ b/docs/2_clients/2_job-submission.md
@@ -0,0 +1,135 @@
+# Job Submission Guide
+
+Submit compute jobs to the AITBC network.
+
+## Basic Submission
+
+```bash
+aitbc client submit --model gpt2 --input data.txt --output results/
+```
+
+## Options Reference
+
+| Option | Required | Description |
+|--------|----------|-------------|
+| `--model` | Yes | Model to run (e.g., gpt2, llama, stable-diffusion) |
+| `--input` | Yes | Input file or data |
+| `--output` | Yes | Output directory |
+| `--gpu` | No | GPU requirements (v100, a100, rtx3090) |
+| `--gpu-count` | No | Number of GPUs (default: 1) |
+| `--timeout` | No | Job timeout in seconds (default: 3600) |
+| `--priority` | No | Job priority (low, normal, high) |
+
+## GPU Requirements
+
+### Single GPU
+
+```bash
+aitbc client submit --model gpt2 --input data.txt --gpu v100
+```
+
+### Multiple GPUs
+
+```bash
+aitbc client submit --model llama --input data.txt --gpu a100 --gpu-count 4
+```
+
+### Specific GPU Type
+
+```bash
+aitbc client submit --model stable-diffusion --input data.txt --gpu rtx3090
+```
+
+## Input Methods
+
+### File Input
+
+```bash
+aitbc client submit --model gpt2 --input ./data/training_data.txt
+```
+
+### Inline Input
+
+```bash
+aitbc client submit --model gpt2 --input "Hello, world!"
+```
+
+### URL Input
+
+```bash
+aitbc client submit --model gpt2 --input https://example.com/data.txt
+```
+
+## Output Options
+
+### Local Directory
+
+```bash
+aitbc client submit --model gpt2 --input data.txt --output ./results
+```
+
+### S3 Compatible Storage
+
+```bash
+aitbc client submit --model gpt2 --input data.txt --output s3://my-bucket/results
+```
+
+## Job Priority
+
+| Priority | Speed | Cost |
+|----------|-------|------|
+| low | Standard | 1x |
+| normal | Fast | 1.5x |
+| high | Priority | 2x |
+
+## Examples
+
+### Training Job
+
+```bash
+aitbc client submit \
+  --model llama \
+  --input ./training_data.csv \
+  --output ./model_weights \
+  --gpu a100 \
+  --gpu-count 4 \
+  --timeout 7200 \
+  --priority high
+```
+
+### Inference Job
+
+```bash
+aitbc client submit \
+  --model gpt2 \
+  --input ./prompts.txt \
+  --output ./outputs \
+  --gpu v100 \
+  --timeout 600
+```
+
+## Batch Jobs
+
+Submit multiple jobs at once:
+
+```bash
+# Using a job file
+aitbc client submit-batch --file jobs.yaml
+```
+
+Example `jobs.yaml`:
+
+```yaml
+jobs:
+  - model: gpt2
+    input: data1.txt
+    output: results1/
+  - model: gpt2
+    input: data2.txt
+    output: results2/
+```
+
+## Next
+
+- [3_job-lifecycle.md](./3_job-lifecycle.md) — Status, results, history, cancellation
+- [5_pricing-billing.md](./5_pricing-billing.md) — Cost structure and invoices
--- a/docs/2_clients/3_job-lifecycle.md
+++ b/docs/2_clients/3_job-lifecycle.md
@@ -0,0 +1,292 @@
+# Job Status Guide
+Understand job states and how to track progress.
+
+## Job States
+
+| State | Description | Actions |
+|-------|-------------|---------|
+| pending | Job queued, waiting for miner | Wait |
+| assigned | Miner assigned, starting soon | Wait |
+| running | Job executing | Monitor |
+| completed | Job finished successfully | Download |
+| failed | Job error occurred | Retry/Contact |
+| canceled | Job cancelled by user | None |
+
+## Check Status
+
+### Using CLI
+
+```bash
+aitbc client status --job-id <JOB_ID>
+```
+
+### Using API
+
+```python
+import requests
+
+response = requests.get(
+    "http://localhost:8000/v1/jobs/{job_id}",
+    headers={"X-Api-Key": "your-key"}
+)
+print(response.json())
+```
+
+## Status Response Example
+
+```json
+{
+  "job_id": "job_abc123",
+  "status": "running",
+  "progress": 45,
+  "miner_id": "miner_xyz789",
+  "created_at": "2026-02-13T10:00:00Z",
+  "started_at": "2026-02-13T10:01:00Z",
+  "estimated_completion": "2026-02-13T10:30:00Z"
+}
+```
+
+## Progress Tracking
+
+### Real-time Updates
+
+```bash
+aitbc client watch --job-id <JOB_ID>
+```
+
+### WebSocket Updates
+
+```python
+import websocket
+
+def on_message(ws, message):
+    print(message)
+
+ws = websocket.WebSocketApp(
+    "ws://localhost:8000/v1/jobs/ws",
+    on_message=on_message
+)
+ws.run_forever()
+```
+
+## State Transitions
+
+```
+pending → assigned → running → completed
+    ↓           ↓          ↓
+  failed    failed     failed
+    ↓           ↓          ↓
+  canceled  canceled   canceled
+```
+
+## Next Steps
+
+- [Job Submission](./2_job-submission.md) - Submitting jobs
+- [Results](./3_job-lifecycle.md) - Managing results
+- [Job History](./3_job-lifecycle.md) - Viewing past jobs
+
+---
+Learn how to download and manage job results.
+
+## Overview
+
+Results are stored after job completion. This guide covers downloading and managing outputs.
+
+## Download Results
+
+### Using CLI
+
+```bash
+aitbc client download --job-id <JOB_ID> --output ./results
+```
+
+### Using API
+
+```python
+import requests
+
+response = requests.get(
+    "http://localhost:8000/v1/jobs/{job_id}/download",
+    headers={"X-Api-Key": "your-key"}
+)
+
+with open("output.zip", "wb") as f:
+    f.write(response.content)
+```
+
+## Result Formats
+
+| Format | Extension | Description |
+|--------|-----------|-------------|
+| JSON | `.json` | Structured data output |
+| Text | `.txt` | Plain text output |
+| Binary | `.bin` | Model weights, tensors |
+| Archive | `.zip` | Multiple files |
+
+## Result Contents
+
+A typical result package includes:
+
+```
+job_<ID>/
+├── output.json          # Job metadata and status
+├── result.txt           # Main output
+├── logs/                # Execution logs
+│   ├── stdout.log
+│   └── stderr.log
+└── artifacts/           # Model files, etc.
+    └── model.bin
+```
+
+## Result Retention
+
+| Plan | Retention |
+|------|-----------|
+| Free | 7 days |
+| Pro | 30 days |
+| Enterprise | 90 days |
+
+## Sharing Results
+
+### Generate Share Link
+
+```bash
+aitbc client share --job-id <JOB_ID>
+```
+
+### Set Expiration
+
+```bash
+aitbc client share --job-id <JOB_ID> --expires 7d
+```
+
+## Verify Results
+
+### Check Integrity
+
+```bash
+aitbc client verify --job-id <JOB_ID>
+```
+
+### Compare Checksums
+
+```bash
+# Download checksum file
+aitbc client download --job-id <JOB_ID> --checksum
+
+# Verify
+sha256sum -c output.sha256
+```
+
+## Delete Results
+
+```bash
+aitbc client delete --job-id <JOB_ID>
+```
+
+## Next Steps
+
+- [Job Status](./3_job-lifecycle.md) - Understanding job states
+- [Job Submission](./2_job-submission.md) - Submitting jobs
+- [Billing](./5_pricing-billing.md) - Understanding charges
+
+---
+View and manage your past jobs.
+
+## List All Jobs
+
+```bash
+aitbc client list
+```
+
+### Filter by Status
+
+```bash
+# Running jobs
+aitbc client list --status running
+
+# Completed jobs
+aitbc client list --status completed
+
+# Failed jobs
+aitbc client list --status failed
+```
+
+### Filter by Date
+
+```bash
+# Last 7 days
+aitbc client list --days 7
+
+# Specific date range
+aitbc client list --from 2026-01-01 --to 2026-01-31
+```
+
+## Job Details
+
+```bash
+aitbc client get --job-id <JOB_ID>
+```
+
+## Export History
+
+```bash
+# Export to JSON
+aitbc client export --format json --output jobs.json
+
+# Export to CSV
+aitbc client export --format csv --output jobs.csv
+```
+
+## Statistics
+
+```bash
+aitbc client stats
+```
+
+Shows:
+- Total jobs submitted
+- Success rate
+- Average completion time
+- Total spent
+
+## Next Steps
+
+- [Job Status](./3_job-lifecycle.md) - Understanding job states
+- [Job Cancellation](./3_job-lifecycle.md) - Canceling jobs
+- [Billing](./5_pricing-billing.md) - Understanding charges
+
+---
+How to cancel jobs and manage running operations.
+
+## Cancel a Job
+
+```bash
+aitbc client cancel --job-id <JOB_ID>
+```
+
+## Confirmation
+
+```bash
+aitbc client cancel --job-id <JOB_ID> --force
+```
+
+## Cancellation States
+
+| State | Description |
+|-------|-------------|
+| canceling | Cancellation requested |
+| canceled | Job successfully canceled |
+| failed | Cancellation failed |
+
+## Effects
+
+- Job stops immediately
+- Partial results may be available
+- Charges apply for resources used
+
+## Next Steps
+
+- [Job Submission](./2_job-submission.md) - Submitting jobs
+- [Job History](./3_job-lifecycle.md) - Viewing past jobs
+- [Pricing](./5_pricing-billing.md) - Cost structure
--- a/docs/2_clients/4_wallet.md
+++ b/docs/2_clients/4_wallet.md
@@ -0,0 +1,78 @@
+# Wallet Management
+
+Manage your AITBC wallet and tokens.
+
+## Create Wallet
+
+```bash
+aitbc wallet create --name my-wallet
+```
+
+Save the seed phrase securely!
+
+## Import Wallet
+
+```bash
+aitbc wallet import --seed "your seed phrase words"
+```
+
+## View Balance
+
+```bash
+aitbc wallet balance
+```
+
+### Detailed Balance
+
+```bash
+aitbc wallet balance --detailed
+```
+
+Shows:
+- Available balance
+- Pending transactions
+- Locked tokens
+
+## Send Tokens
+
+```bash
+aitbc wallet send --to <ADDRESS> --amount 100
+```
+
+### With Memo
+
+```bash
+aitbc wallet send --to <ADDRESS> --amount 100 --memo "Payment for job"
+```
+
+## Transaction History
+
+```bash
+aitbc wallet history
+```
+
+### Filter
+
+```bash
+aitbc wallet history --type sent
+aitbc wallet history --type received
+```
+
+## Security
+
+### Backup Wallet
+
+```bash
+aitbc wallet export --output wallet.json
+```
+
+### Change Password
+
+```bash
+aitbc wallet change-password
+```
+
+## Next
+
+- [5_pricing-billing.md](./5_pricing-billing.md) — Cost structure and invoices
+- [CLI Guide](../0_getting_started/3_cli.md) — Full CLI reference
--- a/docs/2_clients/5_pricing-billing.md
+++ b/docs/2_clients/5_pricing-billing.md
@@ -0,0 +1,119 @@
+# Pricing & Costs
+Understand the cost structure for using AITBC.
+
+## Cost Structure
+
+### Per-Job Pricing
+
+| Resource | Unit | Price |
+|----------|------|-------|
+| GPU (V100) | per hour | 0.05 AITBC |
+| GPU (A100) | per hour | 0.10 AITBC |
+| GPU (RTX3090) | per hour | 0.03 AITBC |
+| Storage | per GB/day | 0.001 AITBC |
+
+### Priority Pricing
+
+| Priority | Multiplier |
+|----------|------------|
+| Low | 0.8x |
+| Normal | 1.0x |
+| High | 1.5x |
+| Urgent | 2.0x |
+
+## Cost Examples
+
+### Small Job (V100, 1 hour)
+
+```
+Base: 0.05 AITBC
+Normal priority: 1.0x
+Total: 0.05 AITBC
+```
+
+### Large Job (A100, 4 GPUs, 4 hours)
+
+```
+Base: 0.10 AITBC × 4 GPUs × 4 hours = 1.60 AITBC
+High priority: 1.5x
+Total: 2.40 AITBC
+```
+
+## Free Tier
+
+- 10 GPU hours per month
+- 1 GB storage
+- Limited to V100 GPUs
+
+## Enterprise Plans
+
+| Feature | Basic | Pro | Enterprise |
+|---------|-------|-----|------------|
+| GPU hours/month | 100 | 500 | Unlimited |
+| Priority | Normal | High | Urgent |
+| Support | Email | 24/7 Chat | Dedicated |
+| SLA | 99% | 99.9% | 99.99% |
+
+## Next Steps
+
+- [Billing](./5_pricing-billing.md) - Billing and invoices
+- [Wallet](./4_wallet.md) - Managing your wallet
+- [Job Submission](./2_job-submission.md) - Submitting jobs
+
+---
+Manage billing and view invoices.
+
+## View Invoices
+
+```bash
+aitbc billing list
+```
+
+### Filter by Date
+
+```bash
+aitbc billing list --from 2026-01-01 --to 2026-01-31
+```
+
+### Download Invoice
+
+```bash
+aitbc billing download --invoice-id <INV_ID>
+```
+
+## Payment Methods
+
+### Add Payment Method
+
+```bash
+aitbc billing add-card --number 4111111111111111 --expiry 12/26 --cvc 123
+```
+
+### Set Default
+
+```bash
+aitbc billing set-default --card-id <CARD_ID>
+```
+
+## Auto-Pay
+
+```bash
+# Enable auto-pay
+aitbc billing auto-pay enable
+
+# Disable auto-pay
+aitbc billing auto-pay disable
+```
+
+## Billing Alerts
+
+```bash
+# Set spending limit
+aitbc billing alert --limit 100 --email you@example.com
+```
+
+## Next Steps
+
+- [Pricing](./5_pricing-billing.md) - Cost structure
+- [Wallet](./4_wallet.md) - Managing your wallet
+- [Job Submission](./2_job-submission.md) - Submitting jobs
--- a/docs/2_clients/6_api-reference.md
+++ b/docs/2_clients/6_api-reference.md
@@ -0,0 +1,124 @@
+# Client API Reference
+
+REST API endpoints for client operations.
+
+## Endpoints
+
+### Submit Job
+
+```
+POST /v1/jobs
+```
+
+**Request Body:**
+
+```json
+{
+  "model": "gpt2",
+  "input": "string or file_id",
+  "output_config": {
+    "destination": "local or s3://bucket/path",
+    "format": "json"
+  },
+  "requirements": {
+    "gpu_type": "v100",
+    "gpu_count": 1,
+    "min_vram_gb": 16
+  },
+  "priority": "normal",
+  "timeout_seconds": 3600
+}
+```
+
+**Response:**
+
+```json
+{
+  "job_id": "job_abc123",
+  "estimated_cost": 0.05,
+  "estimated_time_seconds": 600
+}
+```
+
+### Get Job Status
+
+```
+GET /v1/jobs/{job_id}
+```
+
+**Response:**
+
+```json
+{
+  "job_id": "job_abc123",
+  "status": "running",
+  "progress": 45,
+  "miner_id": "miner_xyz789",
+  "created_at": "2026-02-13T10:00:00Z",
+  "started_at": "2026-02-13T10:01:00Z",
+  "completed_at": null,
+  "result": null
+}
+```
+
+### List Jobs
+
+```
+GET /v1/jobs?status=running&limit=10
+```
+
+**Response:**
+
+```json
+{
+  "jobs": [
+    {
+      "job_id": "job_abc123",
+      "status": "running",
+      "model": "gpt2"
+    }
+  ],
+  "total": 1,
+  "has_more": false
+}
+```
+
+### Cancel Job
+
+```
+DELETE /v1/jobs/{job_id}
+```
+
+### Download Results
+
+```
+GET /v1/jobs/{job_id}/download
+```
+
+### Get Job History
+
+```
+GET /v1/jobs/history?from=2026-01-01&to=2026-01-31
+```
+
+## Error Codes
+
+| Code | Description |
+|------|-------------|
+| 400 | Invalid request |
+| 401 | Unauthorized |
+| 404 | Job not found |
+| 422 | Validation error |
+| 429 | Rate limited |
+| 500 | Server error |
+
+## Rate Limits
+
+- 60 requests/minute
+- 1000 requests/hour
+
+## Next
+
+- [1_quick-start.md](./1_quick-start.md) — Get started quickly
+- [2_job-submission.md](./2_job-submission.md) — CLI-based job submission
+- [CLI Guide](../0_getting_started/3_cli.md) — Full CLI reference