oib/aitbc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: standardize configuration, logging, and error handling across blockchain node and coordinator API

Browse Source 
- 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
2026-02-13 22:39:43 +01:00
parent 0cbd2b507c
commit 06e48ef34b
196 changed files with 4660 additions and 20090 deletions
Download Patch File Download Diff File Expand all files Collapse all files

47
docs/0_getting_started/1_intro.md Normal file
View File

@@ -0,0 +1,47 @@
# What is AITBC?
AITBC is a decentralized GPU computing platform that connects AI workloads with GPU providers through a blockchain-coordinated marketplace.
| Role | What you do |
|------|-------------|
| **Client** | Rent GPU power, submit AI/ML jobs, pay with AITBC tokens |
| **Miner** | Provide GPU resources, process jobs, earn AITBC tokens |
| **Node Operator** | Run blockchain infrastructure, validate transactions |
## Key Components
| Component | Purpose |
|-----------|---------|
| Coordinator API | Job orchestration, miner matching, receipt management |
| Blockchain Node | PoA consensus, transaction ledger, token transfers |
| Marketplace Web | GPU offer/bid UI, stats dashboard |
| Trade Exchange | BTC-to-AITBC trading, QR payments |
| Wallet | Key management, staking, multi-sig support |
| CLI | 90+ commands across 12 groups for all roles |
## Quick Start by Role
**Clients** → [2_clients/1_quick-start.md](../2_clients/1_quick-start.md)
```bash
pip install -e .
aitbc config set coordinator_url http://localhost:8000
aitbc client submit --prompt "What is AI?"
```
**Miners** → [3_miners/1_quick-start.md](../3_miners/1_quick-start.md)
```bash
aitbc miner register --name my-gpu --gpu a100 --count 1
aitbc miner poll
```
**Node Operators** → [4_blockchain/1_quick-start.md](../4_blockchain/1_quick-start.md)
```bash
aitbc-node init --chain-id ait-devnet
aitbc-node start
```
## Next Steps
- [2_installation.md](./2_installation.md) — Install all components
- [3_cli.md](./3_cli.md) — Full CLI usage guide
- [../README.md](../README.md) — Documentation navigation

71
docs/0_getting_started/2_installation.md Normal file
View File

@@ -0,0 +1,71 @@
# Installation
## Prerequisites
- Python 3.10+
- Git
- (Optional) PostgreSQL 14+ for production
- (Optional) NVIDIA GPU + CUDA for mining
## Monorepo Install
```bash
git clone https://github.com/oib/AITBC.git
cd aitbc
python -m venv .venv && source .venv/bin/activate
pip install -e .
```
This installs the CLI, coordinator API, and blockchain node from the monorepo.
## Environment Configuration
### Coordinator API
Create `apps/coordinator-api/.env`:
```env
JWT_SECRET=your-secret-key
DATABASE_URL=sqlite:///./data/coordinator.db # or postgresql://user:pass@localhost/aitbc
LOG_LEVEL=INFO
```
### Blockchain Node
Create `apps/blockchain-node/.env`:
```env
CHAIN_ID=ait-devnet
RPC_BIND_HOST=0.0.0.0
RPC_BIND_PORT=8080
MEMPOOL_BACKEND=database
```
## Systemd Services (Production)
```bash
sudo cp systemd/aitbc-*.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now aitbc-coordinator-api
sudo systemctl enable --now aitbc-blockchain-node-1
```
## Verify
```bash
systemctl status aitbc-coordinator-api
curl http://localhost:8000/v1/health
aitbc blockchain status
```
## Troubleshooting
| Problem | Fix |
|---------|-----|
| Port in use | `sudo lsof -i :8000` then `kill` the PID |
| DB corrupt | `rm -f data/coordinator.db && python -m app.storage init` |
| Module not found | Ensure venv is active: `source .venv/bin/activate` |
## Next Steps
- [3_cli.md](./3_cli.md) — CLI usage guide
- [../2_clients/1_quick-start.md](../2_clients/1_quick-start.md) — Client quick start
- [../3_miners/1_quick-start.md](../3_miners/1_quick-start.md) — Miner quick start

73
docs/0_getting_started/3_cli.md Normal file
View File

@@ -0,0 +1,73 @@
# CLI Usage
## Setup
```bash
pip install -e . # from monorepo root
aitbc config set coordinator_url http://localhost:8000
export AITBC_API_KEY=your-key # or use --api-key
```
## Global Options
| Option | Description |
|--------|-------------|
| `--url URL` | Coordinator API URL |
| `--api-key KEY` | API key for authentication |
| `--output table\|json\|yaml` | Output format |
| `-v / -vv / -vvv` | Verbosity level |
| `--debug` | Debug mode |
## Command Groups
| Group | Key commands |
|-------|-------------|
| `client` | `submit`, `status`, `list`, `cancel`, `download`, `batch-submit` |
| `miner` | `register`, `poll`, `mine`, `earnings`, `deregister` |
| `wallet` | `balance`, `send`, `stake`, `backup`, `multisig-create` |
| `auth` | `login`, `logout`, `token`, `keys` |
| `blockchain` | `status`, `blocks`, `transaction`, `validators` |
| `marketplace` | `gpu list`, `gpu book`, `orders`, `reviews` |
| `admin` | `status`, `jobs`, `miners`, `audit-log` |
| `config` | `set`, `show`, `profiles`, `secrets` |
| `monitor` | `dashboard`, `metrics`, `alerts`, `webhooks` |
| `simulate` | `workflow`, `load-test`, `scenario` |
## Client Workflow
```bash
aitbc wallet balance # check funds
aitbc client submit --prompt "What is AI?" # submit job
aitbc client status --job-id <JOB_ID> # check progress
aitbc client download --job-id <JOB_ID> --output ./ # get results
```
## Miner Workflow
```bash
aitbc miner register --name gpu-1 --gpu a100 --count 4
aitbc miner poll # start accepting jobs
aitbc wallet balance # check earnings
```
## Configuration
Config file: `~/.aitbc/config.yaml`
```yaml
coordinator_url: http://localhost:8000
api_key: your-api-key
output_format: table
log_level: INFO
```
## Troubleshooting
| Problem | Fix |
|---------|-----|
| Auth error | `export AITBC_API_KEY=your-key` or `aitbc auth login` |
| Connection refused | Check coordinator: `curl http://localhost:8000/v1/health` |
| Unknown command | Update CLI: `pip install -e .` from monorepo root |
## Full Reference
See [5_reference/1_cli-reference.md](../5_reference/1_cli-reference.md) for all 90+ commands with detailed options.

0
docs/files.md → docs/1_project/1_files.md
View File

142
docs/roadmap.md → docs/1_project/2_roadmap.md
View File

@@ -797,7 +797,147 @@ Current Status: Canonical receipt schema specification moved from `protocols/rec
- ✅ Site B (ns3): No action needed (blockchain node only)
- ✅ Commit: `26edd70` - Changes committed and deployed
## Recent Progress (2026-02-11)
## Recent Progress (2026-02-13) - Code Quality & Observability ✅ COMPLETE
### Structured Logging Implementation
- ✅ Added JSON structured logging to Coordinator API
- `StructuredLogFormatter` class for consistent log output
- Added `AuditLogger` class for tracking sensitive operations
- Configurable JSON/text format via settings
- ✅ Added JSON structured logging to Blockchain Node
- Consistent log format with Coordinator API
- Added `service` field for log parsing
- Added `get_audit_logger()` function
### Structured Error Responses
- ✅ Implemented standardized error responses across all APIs
- Added `ErrorResponse` and `ErrorDetail` Pydantic models
- All exceptions now have `error_code`, `status_code`, and `to_response()` method
- Added new exception types: `AuthorizationError`, `NotFoundError`, `ConflictError`
- Added exception handlers in main.py for consistent error formatting
### OpenAPI Documentation
- ✅ Enabled OpenAPI documentation with ReDoc
- Added `docs_url="/docs"`, `redoc_url="/redoc"`, `openapi_url="/openapi.json"`
- Added OpenAPI tags for all router groups (health, client, miner, admin, marketplace, exchange, governance, zk)
- Structured endpoint organization for better API discoverability
### Health Check Endpoints
- ✅ Added liveness and readiness probes
- `/health/live` - Simple alive check
- `/health/ready` - Database connectivity check
- Used by orchestrators for service health monitoring
### Unified Configuration
- ✅ Consolidated configuration with environment-based adapter selection
- Added `DatabaseConfig` class with adapter selection (sqlite/postgresql)
- Added connection pooling settings (`pool_size`, `max_overflow`, `pool_pre_ping`)
- Added `validate_secrets()` method for production environments
- Added `mempool_backend` configuration for persistence
- Backward compatible `database_url` property
### Connection Pooling
- ✅ Added database connection pooling
- `QueuePool` for PostgreSQL with configurable pool settings
- `pool_size=10`, `max_overflow=20`, `pool_pre_ping=True`
- Improved session scope with proper commit/rollback handling
- Better resource management under load
### Unified SessionDep
- ✅ Completed migration to unified `storage.SessionDep`
- All routers now use `SessionDep` dependency injection
- Removed legacy session code paths
- Consistent database session management across services
### DatabaseMempool Default
- ✅ Changed mempool backend to use database persistence by default
- `mempool_backend: str = "database"` (was "memory")
- Transaction persistence across restarts
- Better reliability for production deployments
### Systemd Service Standardization
- ✅ Standardized all service paths to `/opt/<service-name>` convention
- Updated 10 systemd service files:
- aitbc-coordinator-api.service
- aitbc-exchange-api.service
- aitbc-exchange-frontend.service
- aitbc-wallet.service
- aitbc-node.service
- aitbc-gpu-miner.service
- aitbc-gpu-miner-root.service
- aitbc-host-gpu-miner.service
- aitbc-gpu-registry.service
- aitbc-coordinator-proxy-health.service
- Consistent deployment paths across all services
## Upcoming Improvements (2026-02-14+)
### High Priority - Security & Stability
- **Redis-backed Rate Limiting**
- Replace in-memory rate limiter with Redis-backed implementation
- Support for distributed rate limiting across multiple instances
- Configurable limits per endpoint
- Status: Pending implementation
- **Request Validation Middleware**
- Add request size limits for all endpoints
- Input sanitization for all user inputs
- SQL injection and XSS prevention
- Status: Pending implementation
- **Audit Logging**
- Comprehensive audit logging for sensitive operations
- Track: API key usage, admin actions, configuration changes
- Integration with existing `AuditLogger` class
- Status: Pending implementation
### Medium Priority - Performance & Quality
- **Redis-backed Mempool (Production)**
- Add Redis adapter for mempool in production
- Support for distributed mempool across nodes
- Better persistence and recovery
- Status: Pending implementation
- **Async I/O Conversion**
- Convert blocking I/O operations to async where possible
- Use `aiohttp` or `httpx` async clients for external API calls
- Async database operations with SQLModel
- Status: Pending implementation
- **Custom Business Metrics**
- Add Prometheus metrics for business logic
- Track: jobs created, miners registered, payments processed
- Custom dashboards for operational visibility
- Status: Pending implementation
### Low Priority - Polish & Documentation
- **API Documentation Enhancement**
- Add detailed endpoint descriptions
- Include request/response examples
- Add code samples for common operations
- Status: Pending implementation
- **Architecture Diagrams**
- Create architecture diagrams for `docs/`
- Include data flow diagrams
- Service interaction diagrams
- Deployment architecture diagrams
- Status: Pending implementation
- **Operational Runbook**
- Create operational runbook for production
- Include: deployment procedures, troubleshooting guides
- Escalation procedures and contact information
- Status: Pending implementation
- **Chaos Engineering Tests**
- Add tests for service failures
- Test network partitions and recovery
- Simulate database outages
- Status: Pending implementation
### Git & Repository Hygiene ✅ COMPLETE
- Renamed local `master` branch to `main` and set tracking to `github/main`

19
docs/done.md → docs/1_project/5_done.md
View File

@@ -619,3 +619,22 @@ This document tracks components that have been successfully deployed and are ope
- ✅ **Site A** (aitbc.bubuit.net): All security fixes deployed and active
- ✅ **Site B** (ns3): No action needed - only blockchain node running
- ✅ **Commit**: `26edd70` - All changes committed and deployed
### Legacy Service Cleanup (2026-02-13)
- ✅ Removed legacy `aitbc-blockchain.service` running on port 9080
- ✅ Confirmed only 2 blockchain nodes running (ports 8081 and 8082)
- ✅ Both active nodes responding correctly to RPC requests
### Systemd Service Naming Standardization (2026-02-13)
- ✅ Renamed all services to use `aitbc-` prefix for consistency
- ✅ Site A updates:
- `blockchain-node.service` → `aitbc-blockchain-node-1.service`
- `blockchain-node-2.service` → `aitbc-blockchain-node-2.service`
- `blockchain-rpc.service` → `aitbc-blockchain-rpc-1.service`
- `blockchain-rpc-2.service` → `aitbc-blockchain-rpc-2.service`
- `coordinator-api.service` → `aitbc-coordinator-api.service`
- `exchange-mock-api.service` → `aitbc-exchange-mock-api.service`
- ✅ Site B updates:
- `blockchain-node.service` → `aitbc-blockchain-node-3.service`
- `blockchain-rpc.service` → `aitbc-blockchain-rpc-3.service`
- ✅ All services restarted and verified operational

0
docs/issues/2026-01-29_cross-site-sync-resolved.md → docs/1_project/6_cross-site-sync-resolved.md
View File

19
docs/2_clients/0_readme.md Normal file
View File

@@ -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

38
docs/2_clients/1_quick-start.md Normal file
View File

@@ -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

135
docs/2_clients/2_job-submission.md Normal file
View File

@@ -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

292
docs/2_clients/3_job-lifecycle.md Normal file
View File

@@ -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

78
docs/2_clients/4_wallet.md Normal file
View File

@@ -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

119
docs/2_clients/5_pricing-billing.md Normal file
View File

@@ -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

124
docs/2_clients/6_api-reference.md Normal file
View File

@@ -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

20
docs/3_miners/0_readme.md Normal file
View File

@@ -0,0 +1,20 @@
# Miner Documentation
Provide GPU resources to the AITBC network and earn tokens.
## Reading Order
| # | File | What you learn |
|---|------|----------------|
| 1 | [1_quick-start.md](./1_quick-start.md) | Get mining in 5 minutes |
| 2 | [2_registration.md](./2_registration.md) | Register GPU with the network |
| 3 | [3_job-management.md](./3_job-management.md) | Accept and complete jobs |
| 4 | [4_earnings.md](./4_earnings.md) | Track and withdraw earnings |
| 5 | [5_gpu-setup.md](./5_gpu-setup.md) | GPU drivers, CUDA, optimization |
| 6 | [6_monitoring.md](./6_monitoring.md) | Dashboards, alerts, health checks |
| 7 | [7_api-miner.md](./7_api-miner.md) | REST API endpoints for integration |
## Related
- [CLI Guide](../0_getting_started/3_cli.md) — Command-line reference
- [Client Docs](../2_clients/0_readme.md) — If you also want to submit jobs

37
docs/3_miners/1_quick-start.md Normal file
View File

@@ -0,0 +1,37 @@
# Miner Quick Start
**5 minutes** — Register your GPU and start earning AITBC tokens.
## Prerequisites
- NVIDIA GPU with 16GB+ VRAM (V100, A100, RTX 3090+)
- Python 3.10+, CUDA drivers installed
- 50GB+ storage, stable internet
## 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. Register & Start
```bash
aitbc miner register --name my-gpu --gpu v100 --count 1
aitbc miner poll # start accepting jobs
```
## 3. Verify
```bash
aitbc miner status # GPU status + earnings
aitbc wallet balance # check token balance
```
## Next
- [2_registration.md](./2_registration.md) — Advanced registration options
- [3_job-management.md](./3_job-management.md) — Job acceptance and completion
- [5_gpu-setup.md](./5_gpu-setup.md) — GPU driver and CUDA setup

80
docs/3_miners/2_registration.md Normal file
View File

@@ -0,0 +1,80 @@
# Miner Registration
Register your miner with the AITBC network.
## Requirements
### Hardware Requirements
| Resource | Minimum | Recommended |
|----------|---------|-------------|
| GPU VRAM | 8GB | 16GB+ |
| RAM | 16GB | 32GB+ |
| Storage | 50GB | 100GB+ |
| Bandwidth | 10 Mbps | 100 Mbps |
### Supported GPUs
- NVIDIA V100 (16GB/32GB)
- NVIDIA A100 (40GB/80GB)
- NVIDIA RTX 3090 (24GB)
- NVIDIA RTX 4090 (24GB)
## Registration
### Basic Registration
```bash
aitbc miner register --name my-miner --gpu v100 --count 1
```
### Advanced Registration
```bash
aitbc miner register \
--name my-miner \
--gpu a100 \
--count 4 \
--location us-east \
--price 0.10 \
--max-concurrent 4
```
### Flags Reference
| Flag | Description |
|------|-------------|
| `--name` | Miner name |
| `--gpu` | GPU type (v100, a100, rtx3090, rtx4090) |
| `--count` | Number of GPUs |
| `--location` | Geographic location |
| `--price` | Price per GPU/hour in AITBC |
| `--max-concurrent` | Maximum concurrent jobs |
## Verification
```bash
aitbc miner status
```
Shows:
- Registration status
- GPU availability
- Current jobs
## Update Registration
```bash
aitbc miner update --price 0.12 --max-concurrent 8
```
## De-register
```bash
aitbc miner deregister --confirm
```
## Next
- [Job Management](./3_job-management.md) — Job management
- [Earnings](./4_earnings.md) — Earnings tracking
- [GPU Setup](./5_gpu-setup.md) — GPU configuration

96
docs/3_miners/3_job-management.md Normal file
View File

@@ -0,0 +1,96 @@
# Job Management
Accept and complete jobs on the AITBC network.
## Overview
Jobs are assigned to miners based on GPU availability, price, and reputation.
## Accept Jobs
### Manual Acceptance
```bash
aitbc miner jobs --available
aitbc miner accept --job-id <JOB_ID>
```
### Auto-Accept
```bash
aitbc miner auto-accept enable --max-concurrent 4
```
### Auto-Accept Settings
```bash
# Set GPU requirements
aitbc miner auto-accept --gpu v100 --gpu-count 1-4
# Set price range
aitbc miner auto-accept --min-price 0.08 --max-price 0.12
```
## Job States
| State | Description |
|-------|-------------|
| assigned | Job assigned, waiting to start |
| starting | Preparing environment |
| running | Executing job |
| uploading | Uploading results |
| completed | Job finished successfully |
| failed | Job error occurred |
## Monitor Jobs
### Check Status
```bash
aitbc miner job-status --job-id <JOB_ID>
```
### Watch Progress
```bash
aitbc miner watch --job-id <JOB_ID>
```
### List Active Jobs
```bash
aitbc miner jobs --active
```
## Complete Jobs
### Manual Completion
```bash
aitbc miner complete --job-id <JOB_ID>
```
### Upload Results
```bash
aitbc miner upload --job-id <JOB_ID> --path ./results
```
## Handle Failures
### Retry Job
```bash
aitbc miner retry --job-id <JOB_ID>
```
### Report Issue
```bash
aitbc miner report --job-id <JOB_ID> --reason "gpu-error"
```
## Next
- [Earnings](./4_earnings.md) — Earnings tracking
- [GPU Setup](./5_gpu-setup.md) — GPU configuration
- [Monitoring](./6_monitoring.md) - Monitor your miner

66
docs/3_miners/4_earnings.md Normal file
View File

@@ -0,0 +1,66 @@
# Earnings & Payouts
Track and manage your mining earnings.
## Earnings Overview
```bash
aitbc miner earnings
```
Shows:
- Total earned
- Pending balance
- Last payout
## Earnings Breakdown
| Source | Description |
|--------|-------------|
| job_completion | Payment for completed jobs |
| bonus | Performance bonuses |
| referral | Referral rewards |
## Payout Schedule
| Plan | Schedule | Minimum |
|------|----------|---------|
| Automatic | Daily | 10 AITBC |
| Manual | On request | 1 AITBC |
## Request Payout
```bash
aitbc wallet withdraw --amount 100 --address <WALLET_ADDRESS>
```
## Earnings History
```bash
aitbc miner earnings --history --days 30
```
## Performance Metrics
```bash
aitbc miner stats
```
Shows:
- Success rate
- Average completion time
- Total jobs completed
- Earnings per GPU/hour
## Tax Reporting
```bash
aitbc miner earnings --export --year 2026
```
Export for tax purposes.
## Next
- [Job Management](./3_job-management.md) — Job management
- [Monitoring](./6_monitoring.md) - Monitor your miner
- [GPU Setup](./5_gpu-setup.md) — GPU configuration

111
docs/3_miners/5_gpu-setup.md Normal file
View File

@@ -0,0 +1,111 @@
# GPU Setup & Configuration
Configure and optimize your GPU setup for mining.
## Prerequisites
### Driver Installation
```bash
# Ubuntu/Debian
sudo apt install nvidia-driver-535
# Verify installation
nvidia-smi
```
### CUDA Installation
```bash
# Download CUDA from NVIDIA
wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb
sudo apt-get update
sudo apt-get install cuda-toolkit-12-3
```
## Configuration
### Miner Config
Create `~/.aitbc/miner.yaml`:
```yaml
gpu:
type: v100
count: 1
cuda_devices: 0
performance:
max_memory_percent: 90
max_gpu_temp: 80
power_limit: 250
jobs:
max_concurrent: 4
timeout_grace: 300
```
### Environment Variables
```bash
export CUDA_VISIBLE_DEVICES=0
export NVIDIA_VISIBLE_DEVICES=all
export AITBC_GPU_MEMORY_LIMIT=0.9
```
## Optimization
### Memory Settings
```yaml
performance:
tensor_cores: true
fp16: true # Use half precision
max_memory_percent: 90
```
### Thermal Management
```yaml
thermal:
target_temp: 70
max_temp: 85
fan_curve:
- temp: 50
fan: 30
- temp: 70
fan: 60
- temp: 85
fan: 100
```
## Troubleshooting
### GPU Not Detected
```bash
# Check driver
nvidia-smi
# Check CUDA
nvcc --version
# Restart miner
aitbc miner restart
```
### Temperature Issues
```bash
# Monitor temperature
nvidia-smi -l 1
# Check cooling
ipmitool sdr list | grep Temp
```
## Next
- [Quick Start](./1_quick-start.md) — Get started
- [Monitoring](./6_monitoring.md) - Monitor your miner
- [Job Management](./3_job-management.md) — Job management

110
docs/3_miners/6_monitoring.md Normal file
View File

@@ -0,0 +1,110 @@
# Monitoring & Alerts
Monitor your miner performance and set up alerts.
## Real-time Monitoring
### Dashboard
```bash
aitbc miner dashboard
```
Shows:
- GPU utilization
- Memory usage
- Temperature
- Active jobs
- Earnings rate
### CLI Stats
```bash
aitbc miner stats
```
### Prometheus Metrics
```bash
# Enable metrics endpoint
aitbc miner metrics --port 9090
```
Available at: http://localhost:9090/metrics
## Alert Configuration
### Set Alerts
```bash
# GPU temperature alert
aitbc miner alert --metric temp --threshold 85 --action notify
# Memory usage alert
aitbc miner alert --metric memory --threshold 90 --action throttle
# Job failure alert
aitbc miner alert --metric failures --threshold 3 --action pause
```
### Alert Types
| Type | Description |
|------|-------------|
| temp | GPU temperature |
| memory | GPU memory usage |
| utilization | GPU utilization |
| jobs | Job success/failure rate |
| earnings | Earnings below threshold |
### Alert Actions
| Action | Description |
|--------|-------------|
| notify | Send notification |
| throttle | Reduce job acceptance |
| pause | Stop accepting jobs |
| restart | Restart miner |
## Log Management
### View Logs
```bash
# Recent logs
aitbc miner logs --tail 100
# Filter by level
aitbc miner logs --level error
# Filter by job
aitbc miner logs --job-id <JOB_ID>
```
### Log Rotation
```bash
# Configure log rotation
aitbc miner logs --rotate --max-size 100MB --keep 5
```
## Health Checks
```bash
# Run health check
aitbc miner health
# Detailed health report
aitbc miner health --detailed
```
Shows:
- GPU health
- Driver status
- Network connectivity
- Storage availability
## Next
- [Quick Start](./1_quick-start.md) — Get started
- [GPU Setup](./5_gpu-setup.md) — GPU configuration
- [Job Management](./3_job-management.md) — Job management

141
docs/3_miners/7_api-miner.md Normal file
View File

@@ -0,0 +1,141 @@
# Miner API Reference
Complete API reference for miner operations.
## Endpoints
### Register Miner
```
POST /v1/miners
```
**Request Body:**
```json
{
"name": "my-miner",
"gpu_type": "v100",
"gpu_count": 1,
"location": "us-east",
"price_per_hour": 0.05,
"max_concurrent": 4
}
```
**Response:**
```json
{
"miner_id": "miner_xyz789",
"api_key": "key_abc123",
"status": "pending"
}
```
### Update Miner
```
PUT /v1/miners/{miner_id}
```
### Heartbeat
```
POST /v1/miners/{miner_id}/heartbeat
```
**Response:**
```json
{
"status": "ok",
"jobs_assigned": 0,
"queue_length": 5
}
```
### List Available Jobs
```
GET /v1/miners/{miner_id}/jobs/available
```
**Response:**
```json
{
"jobs": [
{
"job_id": "job_abc123",
"model": "gpt2",
"gpu_type": "v100",
"gpu_count": 1,
"estimated_time": 600,
"price": 0.05
}
]
}
```
### Accept Job
```
POST /v1/miners/{miner_id}/jobs/{job_id}/accept
```
### Complete Job
```
POST /v1/miners/{miner_id}/jobs/{job_id}/complete
```
**Request Body:**
```json
{
"result_hash": "sha256:abc123...",
"metrics": {
"execution_time_seconds": 600,
"gpu_time_seconds": 600
}
}
```
### Get Miner Stats
```
GET /v1/miners/{miner_id}/stats
```
**Response:**
```json
{
"total_jobs": 100,
"success_rate": 0.98,
"average_completion_time": 600,
"earnings": 50.5,
"earnings_per_gpu_hour": 0.05
}
```
## Error Codes
| Code | Description |
|------|-------------|
| 400 | Invalid request |
| 401 | Unauthorized |
| 404 | Miner/job not found |
| 409 | Job already assigned |
| 422 | Validation error |
## Rate Limits
- 60 requests/minute
- 10 job operations/minute
## Next
- [Quick Start](./1_quick-start.md) — Get started
- [Job Management](./3_job-management.md) — Job management
- [Monitoring](./6_monitoring.md) - Monitor your miner

23
docs/4_blockchain/0_readme.md Normal file
View File

@@ -0,0 +1,23 @@
# Blockchain Node Documentation
Run a blockchain node: validate transactions, produce blocks, maintain the AITBC ledger.
## Reading Order
| # | File | What you learn |
|---|------|----------------|
| 1 | [1_quick-start.md](./1_quick-start.md) | Get a node running in 10 minutes |
| 2 | [2_configuration.md](./2_configuration.md) | Node, RPC, P2P, mempool settings |
| 3 | [3_operations.md](./3_operations.md) | Start/stop, sync, peers, backups |
| 4 | [4_consensus.md](./4_consensus.md) | PoA consensus mechanism |
| 5 | [5_validator.md](./5_validator.md) | Become a validator, duties, rewards |
| 6 | [6_networking.md](./6_networking.md) | Firewall, NAT, bootstrap nodes |
| 7 | [7_monitoring.md](./7_monitoring.md) | Prometheus, dashboards, alerts |
| 8 | [8_troubleshooting.md](./8_troubleshooting.md) | Common issues and fixes |
| 9 | [9_upgrades.md](./9_upgrades.md) | Version upgrades, rollback |
| 10 | [10_api-blockchain.md](./10_api-blockchain.md) | RPC and WebSocket API reference |
## Related
- [Installation](../0_getting_started/2_installation.md) — Install all components
- [CLI Guide](../0_getting_started/3_cli.md) — `aitbc blockchain` commands

202
docs/4_blockchain/10_api-blockchain.md Normal file
View File

@@ -0,0 +1,202 @@
# Blockchain API Reference
Complete API reference for blockchain node operations.
## RPC Endpoints
### Get Block
```
GET /rpc/block/{height}
```
**Response:**
```json
{
"block": {
"header": {
"height": 100,
"timestamp": "2026-02-13T10:00:00Z",
"proposer": "ait-devnet-proposer-1",
"parent_hash": "0xabc123...",
"state_root": "0xdef456...",
"tx_root": "0xghi789..."
},
"transactions": [...],
"receipts": [...]
},
"block_id": "0xjkl012..."
}
```
### Get Transaction
```
GET /rpc/tx/{tx_hash}
```
**Response:**
```json
{
"tx": {
"hash": "0xabc123...",
"type": "transfer",
"from": "0x1234...",
"to": "0x5678...",
"value": 100,
"gas": 21000,
"data": "0x..."
},
"height": 100,
"index": 0
}
```
### Submit Transaction
```
POST /rpc/broadcast_tx_commit
```
**Request Body:**
```json
{
"tx": "0xabc123...",
"type": "transfer",
"from": "0x1234...",
"to": "0x5678...",
"value": 100,
"data": "0x..."
}
```
**Response:**
```json
{
"tx_response": {
"code": 0,
"data": "0x...",
"log": "success",
"hash": "0xabc123..."
},
"height": 100,
"index": 0
}
```
### Get Status
```
GET /rpc/status
```
**Response:**
```json
{
"node_info": {
"protocol_version": "v0.1.0",
"network": "ait-devnet",
"node_id": "12D3KooW...",
"listen_addr": "tcp://0.0.0.0:7070"
},
"sync_info": {
"latest_block_height": 1000,
"catching_up": false,
"earliest_block_height": 1
},
"validator_info": {
"voting_power": 1000,
"proposer": true
}
}
```
### Get Mempool
```
GET /rpc/mempool
```
**Response:**
```json
{
"size": 50,
"txs": [
{
"hash": "0xabc123...",
"fee": 0.001,
"size": 200
}
]
}
```
## WebSocket Endpoints
### Subscribe to Blocks
```
WS /rpc/block
```
**Message:**
```json
{
"type": "new_block",
"data": {
"height": 1001,
"hash": "0x...",
"proposer": "ait-devnet-proposer-1"
}
}
```
### Subscribe to Transactions
```
WS /rpc/tx
```
**Message:**
```json
{
"type": "new_tx",
"data": {
"hash": "0xabc123...",
"type": "transfer",
"from": "0x1234...",
"to": "0x5678...",
"value": 100
}
}
```
## Error Codes
| Code | Description |
|------|-------------|
| 0 | Success |
| 1 | Internal error |
| 2 | Invalid transaction |
| 3 | Invalid request |
| 4 | Not found |
| 5 | Conflict |
## Rate Limits
- 1000 requests/minute for RPC
- 100 requests/minute for writes
- 10 connections per IP
## Next
- [Quick Start](./1_quick-start.md) — Get started
- [Configuration](./2_configuration.md) - Configure your node
- [Operations](./3_operations.md) — Day-to-day ops

54
docs/4_blockchain/1_quick-start.md Normal file
View File

@@ -0,0 +1,54 @@
# Node Quick Start
**10 minutes** — Install, configure, and sync a blockchain node.
## Prerequisites
| Resource | Minimum |
|----------|---------|
| CPU | 4 cores |
| RAM | 16 GB |
| Storage | 100 GB SSD |
| Network | 100 Mbps stable |
## 1. Install
```bash
cd /home/oib/windsurf/aitbc
python -m venv .venv && source .venv/bin/activate
pip install -e .
```
## 2. Initialize & Configure
```bash
aitbc-chain init --name my-node --network ait-devnet
```
Edit `~/.aitbc/chain.yaml`:
```yaml
node:
name: my-node
data_dir: ./data
rpc:
bind_host: 0.0.0.0
bind_port: 8080
p2p:
bind_port: 7070
bootstrap_nodes:
- /dns4/node-1.aitbc.com/tcp/7070/p2p/...
```
## 3. Start & Verify
```bash
aitbc-chain start
aitbc-chain status # node info + sync progress
curl http://localhost:8080/rpc/health # RPC health check
```
## Next
- [2_configuration.md](./2_configuration.md) — Full config reference
- [3_operations.md](./3_operations.md) — Day-to-day ops
- [7_monitoring.md](./7_monitoring.md) — Prometheus + dashboards

87
docs/4_blockchain/2_configuration.md Normal file
View File

@@ -0,0 +1,87 @@
# Blockchain Node Configuration
Configure your blockchain node for optimal performance.
## Configuration File
Location: `~/.aitbc/chain.yaml`
## Node Configuration
```yaml
node:
name: my-node
network: ait-devnet # or ait-mainnet
data_dir: /opt/blockchain-node/data
log_level: info
```
## RPC Configuration
```yaml
rpc:
enabled: true
bind_host: 0.0.0.0
bind_port: 8080
cors_origins:
- http://localhost:3000
- http://localhost:8000
rate_limit: 1000 # requests per minute
```
## P2P Configuration
```yaml
p2p:
enabled: true
bind_host: 0.0.0.0
bind_port: 7070
bootstrap_nodes:
- /dns4/node-1.aitbc.com/tcp/7070/p2p/...
max_peers: 50
min_peers: 5
```
## Mempool Configuration
```yaml
mempool:
backend: database # or memory
max_size: 10000
min_fee: 0
eviction_interval: 60
```
## Database Configuration
```yaml
database:
adapter: postgresql # or sqlite
url: postgresql://user:pass@localhost/aitbc_chain
pool_size: 10
max_overflow: 20
```
## Validator Configuration
```yaml
validator:
enabled: true
key: <VALIDATOR_PRIVATE_KEY>
block_time: 2 # seconds
max_block_size: 1000000 # bytes
max_txs_per_block: 500
```
## Environment Variables
```bash
export AITBC_CHAIN_DATA_DIR=/opt/blockchain-node/data
export AITBC_CHAIN_RPC_PORT=8080
export AITBC_CHAIN_P2P_PORT=7070
```
## Next
- [Quick Start](./1_quick-start.md) — Get started
- [Operations](./3_operations.md) — Day-to-day ops
- [Consensus](./4_consensus.md) — Consensus mechanism

102
docs/4_blockchain/3_operations.md Normal file
View File

@@ -0,0 +1,102 @@
# Node Operations
Day-to-day operations for blockchain nodes.
## Starting the Node
```bash
# Start in foreground (for testing)
aitbc-chain start
# Start as daemon
aitbc-chain start --daemon
# Start with custom config
aitbc-chain start --config /path/to/config.yaml
```
## Stopping the Node
```bash
# Graceful shutdown
aitbc-chain stop
# Force stop
aitbc-chain stop --force
```
## Node Status
```bash
aitbc-chain status
```
Shows:
- Block height
- Peers connected
- Mempool size
- Last block time
## Checking Sync Status
```bash
aitbc-chain sync-status
```
Shows:
- Current height
- Target height
- Sync progress percentage
- Estimated time to sync
## Managing Peers
### List Peers
```bash
aitbc-chain peers list
```
### Add Peer
```bash
aitbc-chain peers add /dns4/new-node.example.com/tcp/7070/p2p/...
```
### Remove Peer
```bash
aitbc-chain peers remove <PEER_ID>
```
## Backup & Restore
### Backup Data
```bash
aitbc-chain backup --output /backup/chain-backup.tar.gz
```
### Restore Data
```bash
aitbc-chain restore --input /backup/chain-backup.tar.gz
```
## Log Management
```bash
# View logs
aitbc-chain logs --tail 100
# Filter by level
aitbc-chain logs --level error
# Export logs
aitbc-chain logs --export /var/log/aitbc-chain.log
```
## Next
- [Quick Start](./1_quick-start.md) — Get started
- [Configuration](./2_configuration.md) - Configure your node
- [Consensus](./4_consensus.md) — Consensus mechanism

65
docs/4_blockchain/4_consensus.md Normal file
View File

@@ -0,0 +1,65 @@
# Consensus Mechanism
Understand AITBC's proof-of-authority consensus mechanism.
## Overview
AITBC uses a Proof-of-Authority (PoA) consensus mechanism with:
- Fixed block time: 2 seconds
- Authority set of validated proposers
- Transaction finality on each block
## Block Production
### Proposer Selection
Proposers take turns producing blocks in a round-robin fashion. Each proposer gets a fixed time slot.
### Block Structure
```json
{
"header": {
"height": 100,
"timestamp": "2026-02-13T10:00:00Z",
"proposer": "ait-devnet-proposer-1",
"parent_hash": "0xabc123...",
"state_root": "0xdef456...",
"tx_root": "0xghi789..."
},
"transactions": [...],
"receipts": [...]
}
```
## Consensus Rules
1. **Block Time**: 2 seconds minimum
2. **Block Size**: 1 MB maximum
3. **Transactions**: 500 maximum per block
4. **Fee**: Minimum 0 (configurable)
## Validator Requirements
| Requirement | Value |
|-------------|-------|
| Uptime | 99% minimum |
| Latency | < 100ms to peers |
| Stake | 1000 AITBC |
## Fork Selection
Longest chain rule applies:
- Validators always extend the longest known chain
- Reorgs occur only on conflicting blocks within the last 10 blocks
## Finality
Blocks are considered final after:
- 1 confirmation for normal transactions
- 3 confirmations for high-value transactions
## Next
- [Quick Start](./1_quick-start.md) — Get started
- [Validator Operations](./5_validator.md) - Validator guide
- [Networking](./6_networking.md) - P2P networking

95
docs/4_blockchain/5_validator.md Normal file
View File

@@ -0,0 +1,95 @@
# Validator Operations
Guide for running a validator node in the AITBC network.
## Becoming a Validator
### Requirements
| Requirement | Value |
|-------------|-------|
| Stake | 1000 AITBC |
| Node uptime | 99%+ |
| Technical capability | Must run node 24/7 |
| Geographic distribution | One per region preferred |
### Registration
```bash
aitbc-chain validator register --stake 1000
```
### Activate Validator Status
```bash
aitbc-chain validator activate
```
## Validator Duties
### Block Production
Validators take turns producing blocks:
- Round-robin selection
- Fixed 2-second block time
- Missed blocks result in reduced rewards
### Transaction Validation
- Verify transaction signatures
- Check sender balance
- Validate smart contract execution
### Network Participation
- Maintain P2P connections
- Propagate blocks to peers
- Participate in consensus votes
## Validator Rewards
### Block Rewards
| Block Position | Reward |
|----------------|--------|
| Proposer | 1 AITBC |
| Validator (any) | 0.1 AITBC |
### Performance Bonuses
- 100% uptime: 1.5x multiplier
- 99-100% uptime: 1.2x multiplier
- <99% uptime: 1.0x multiplier
## Validator Monitoring
```bash
# Check validator status
aitbc-chain validator status
# View performance metrics
aitbc-chain validator metrics
# Check missed blocks
aitbc-chain validator missed-blocks
```
## Validator Slashing
### Slashing Conditions
| Violation | Penalty |
|-----------|---------|
| Double signing | 5% stake |
| Extended downtime | 1% stake |
| Invalid block | 2% stake |
### Recovery
- Partial slashing can be recovered
- Full slashing requires re-registration
## Next
- [Quick Start](./1_quick-start.md) — Get started
- [Consensus](./4_consensus.md) — Consensus mechanism
- [Monitoring](./7_monitoring.md) — Monitoring

107
docs/4_blockchain/6_networking.md Normal file
View File

@@ -0,0 +1,107 @@
# Networking Configuration
Configure P2P networking for your blockchain node.
## Network Settings
### Firewall Configuration
```bash
# Allow P2P port
sudo ufw allow 7070/tcp
# Allow RPC port
sudo ufw allow 8080/tcp
# Allow from specific IPs
sudo ufw allow from 10.0.0.0/8 to any port 8080
```
### Port Forwarding
If behind a NAT, configure port forwarding:
- External port 7070 → Internal IP:7070
- External port 8080 → Internal IP:8080
## Bootstrap Nodes
### Default Bootstrap Nodes
```yaml
p2p:
bootstrap_nodes:
- /dns4/node-1.aitbc.com/tcp/7070/p2p/12D3KooW...
- /dns4/node-2.aitbc.com/tcp/7070/p2p/12D3KooW...
- /dns4/node-3.aitbc.com/tcp/7070/p2p/12D3KooW...
```
### Adding Custom Bootstrap Nodes
```bash
aitbc-chain p2p add-bootstrap /dns4/my-node.example.com/tcp/7070/p2p/...
```
## Peer Management
### Connection Limits
```yaml
p2p:
max_peers: 50
min_peers: 5
outbound_peers: 10
inbound_peers: 40
```
### Peer Scoring
Nodes are scored based on:
- Latency
- Availability
- Protocol compliance
- Block propagation speed
## NAT Traversal
### Supported Methods
| Method | Description |
|--------|-------------|
| AutoNAT | Automatic NAT detection |
| Hole Punching | UDP hole punching |
| Relay | TURN relay fallback |
### Configuration
```yaml
p2p:
nat:
enabled: true
method: auto # auto, hole_punching, relay
external_ip: 203.0.113.1
```
## Troubleshooting
### Check Connectivity
```bash
aitbc-chain p2p check-connectivity
```
### List Active Connections
```bash
aitbc-chain p2p connections
```
### Debug Mode
```bash
aitbc-chain start --log-level debug
```
## Next
- [Quick Start](./1_quick-start.md) — Get started
- [Configuration](./2_configuration.md) - Configure your node
- [Operations](./3_operations.md) — Day-to-day ops

89
docs/4_blockchain/7_monitoring.md Normal file
View File

@@ -0,0 +1,89 @@
# Node Monitoring
Monitor your blockchain node performance and health.
## Dashboard
```bash
aitbc-chain dashboard
```
Shows:
- Block height
- Peers connected
- Mempool size
- CPU/Memory/GPU usage
- Network traffic
## Prometheus Metrics
```bash
# Enable metrics
aitbc-chain metrics --port 9090
```
Available metrics:
- `aitbc_block_height` - Current block height
- `aitbc_peers_count` - Number of connected peers
- `aitbc_mempool_size` - Transactions in mempool
- `aitbc_block_production_time` - Block production time
- `aitbc_cpu_usage` - CPU utilization
- `aitbc_memory_usage` - Memory utilization
## Alert Configuration
### Set Alerts
```bash
# Low peers alert
aitbc-chain alert --metric peers --threshold 3 --action notify
# High mempool alert
aitbc-chain alert --metric mempool --threshold 5000 --action notify
# Sync delay alert
aitbc-chain alert --metric sync_delay --threshold 100 --action notify
```
### Alert Actions
| Action | Description |
|--------|-------------|
| notify | Send notification |
| restart | Restart node |
| pause | Pause block production |
## Log Monitoring
```bash
# Real-time logs
aitbc-chain logs --tail
# Search logs
aitbc-chain logs --grep "error" --since "1h"
# Export logs
aitbc-chain logs --export /var/log/aitbc-chain/
```
## Health Checks
```bash
# Run health check
aitbc-chain health
# Detailed report
aitbc-chain health --detailed
```
Checks:
- Disk space
- Memory
- P2P connectivity
- RPC availability
- Database sync
## Next
- [Quick Start](./1_quick-start.md) — Get started
- [Configuration](./2_configuration.md) - Configure your node
- [Operations](./3_operations.md) — Day-to-day ops

153
docs/4_blockchain/8_troubleshooting.md Normal file
View File

@@ -0,0 +1,153 @@
# Troubleshooting
Common issues and solutions for blockchain nodes.
## Common Issues
### Node Won't Start
```bash
# Check logs
tail -f ~/.aitbc/logs/chain.log
# Common causes:
# - Port already in use
# - Corrupted database
# - Invalid configuration
```
**Solutions:**
```bash
# Kill existing process
sudo lsof -i :8080
sudo kill $(sudo lsof -t -i :8080)
# Reset database
rm -rf ~/.aitbc/data/chain.db
aitbc-chain init
# Validate config
aitbc-chain validate-config
```
### Sync Stuck
```bash
# Check sync status
aitbc-chain sync-status
# Force sync from scratch
aitbc-chain reset --hard
# Check peer connectivity
aitbc-chain p2p connections
```
**Solutions:**
```bash
# Add more peers
aitbc-chain p2p add-bootstrap /dns4/new-peer.example.com/tcp/7070/p2p/...
# Clear peer database
rm -rf ~/.aitbc/data/peers.db
# Restart with fresh sync
aitbc-chain start --sync-mode full
```
### P2P Connection Issues
```bash
# Check connectivity
aitbc-chain p2p check-connectivity
# Test port forwarding
curl http://localhost:8080/rpc/net_info
```
**Solutions:**
```bash
# Open firewall
sudo ufw allow 7070/tcp
sudo ufw allow 8080/tcp
# Check NAT configuration
aitbc-chain p2p nat-status
# Use relay mode
aitbc-chain start --p2p-relay-enabled
```
### High Memory Usage
```bash
# Check memory usage
htop | grep aitbc-chain
# Check database size
du -sh ~/.aitbc/data/
```
**Solutions:**
```bash
# Prune old data
aitbc-chain prune --keep-blocks 10000
# Reduce peer count
# Edit config: max_peers: 25
# Enable compression
aitbc-chain start --db-compression
```
### RPC Not Responding
```bash
# Check RPC status
curl http://localhost:8080/rpc/health
# Check if RPC is enabled
aitbc-chain status | grep RPC
```
**Solutions:**
```bash
# Restart with RPC enabled
aitbc-chain start --rpc-enabled
# Check CORS settings
# Edit config: rpc.cors_origins
# Increase rate limits
# Edit config: rpc.rate_limit: 2000
```
## Diagnostic Commands
```bash
# Full system check
aitbc-chain doctor
# Network diagnostics
aitbc-chain diagnose network
# Database diagnostics
aitbc-chain diagnose database
# Log analysis
aitbc-chain logs --analyze
```
## Getting Help
```bash
# Generate debug report
aitbc-chain debug-report > debug.txt
# Share on Discord or GitHub Issues
```
## Next
- [Quick Start](./1_quick-start.md) — Get started
- [Configuration](./2_configuration.md) - Configure your node
- [Operations](./3_operations.md) — Day-to-day ops

77
docs/4_blockchain/9_upgrades.md Normal file
View File

@@ -0,0 +1,77 @@
# Node Upgrades
Guide for upgrading your blockchain node.
## Upgrade Process
### Check Current Version
```bash
aitbc-chain version
```
### Check for Updates
```bash
aitbc-chain check-update
```
### Upgrade Steps
```bash
# 1. Backup data
aitbc-chain backup --output /backup/chain-$(date +%Y%m%d).tar.gz
# 2. Stop node gracefully
aitbc-chain stop
# 3. Upgrade software
pip install --upgrade aitbc-chain
# 4. Review migration notes
cat CHANGELOG.md
# 5. Start node
aitbc-chain start
```
## Version-Specific Upgrades
### v0.1.0 → v0.2.0
```bash
# Database migration required
aitbc-chain migrate --from v0.1.0
```
### v0.2.0 → v0.3.0
```bash
# Configuration changes
aitbc-chain migrate-config --from v0.2.0
```
## Rollback Procedure
```bash
# If issues occur, rollback
pip install aitbc-chain==0.1.0
# Restore from backup
aitbc-chain restore --input /backup/chain-YYYYMMDD.tar.gz
# Start old version
aitbc-chain start
```
## Upgrade Notifications
```bash
# Enable upgrade alerts
aitbc-chain alert --metric upgrade_available --action notify
```
## Next
- [Quick Start](./1_quick-start.md) — Get started
- [Operations](./3_operations.md) — Day-to-day ops
- [Monitoring](./7_monitoring.md) — Monitoring

28
docs/5_reference/0_index.md Normal file
View File

@@ -0,0 +1,28 @@
# Technical Reference
Specifications, audits, and implementation records for AITBC internals.
## Reading Order
| # | File | Topic |
|---|------|-------|
| 1 | [1_cli-reference.md](./1_cli-reference.md) | Full CLI command reference (90+ commands) |
| 2 | [2_payment-architecture.md](./2_payment-architecture.md) | Payment system design |
| 3 | [3_wallet-coordinator-integration.md](./3_wallet-coordinator-integration.md) | Wallet ↔ coordinator flow |
| 4 | [4_confidential-transactions.md](./4_confidential-transactions.md) | Confidential tx architecture + implementation |
| 5 | [5_zk-proofs.md](./5_zk-proofs.md) | ZK receipt attestation design + comparison |
| 6 | [6_enterprise-sla.md](./6_enterprise-sla.md) | Enterprise SLA definitions |
| 7 | [7_threat-modeling.md](./7_threat-modeling.md) | Privacy feature threat model |
| 8 | [8_blockchain-deployment-summary.md](./8_blockchain-deployment-summary.md) | Node deployment record |
| 9 | [9_payment-integration-complete.md](./9_payment-integration-complete.md) | Payment integration status |
| 10 | [10_implementation-complete-summary.md](./10_implementation-complete-summary.md) | Feature completion record |
| 11–14 | `11_`–`14_` | Integration test fixes, updates, status reports |
| 15 | [15_skipped-tests-roadmap.md](./15_skipped-tests-roadmap.md) | Skipped tests plan |
| 16 | [16_security-audit-2026-02-13.md](./16_security-audit-2026-02-13.md) | Security audit results |
| 17 | [17_docs-gaps.md](./17_docs-gaps.md) | Documentation gap analysis |
## Related
- [Architecture](../6_architecture/) — System design docs
- [Security](../9_security/) — Security guides
- [Roadmap](../1_project/2_roadmap.md) — Development roadmap

0
docs/reports/IMPLEMENTATION_COMPLETE_SUMMARY.md → docs/5_reference/10_implementation-complete-summary.md
View File

0
docs/reports/INTEGRATION_TEST_FIXES.md → docs/5_reference/11_integration-test-fixes.md
View File

0
docs/reports/INTEGRATION_TEST_UPDATES.md → docs/5_reference/12_integration-test-updates.md
View File

0
docs/reports/TEST_FIXES_COMPLETE.md → docs/5_reference/13_test-fixes-complete.md
View File

0
docs/reports/TESTING_STATUS_REPORT.md → docs/5_reference/14_testing-status-report.md
View File

0
docs/reports/SKIPPED_TESTS_ROADMAP.md → docs/5_reference/15_skipped-tests-roadmap.md
View File

36
docs/reports/security-audit-2026-02-13.md → docs/5_reference/16_security-audit-2026-02-13.md
View File

@@ -126,6 +126,42 @@ encrypted = encrypt_value(private_key, password) # Fernet
- Replaced `requests` with `httpx` (already a dependency)
- Added graceful fallback for missing dependencies
### Code Quality & Observability ✅
#### Structured Logging
- ✅ Added JSON structured logging to Coordinator API
- `StructuredLogFormatter` class for consistent log output
- Added `AuditLogger` class for tracking sensitive operations
- Configurable JSON/text format via settings
- ✅ Added JSON structured logging to Blockchain Node
- Consistent log format with Coordinator API
- Added `service` field for log parsing
#### Structured Error Responses
- ✅ Implemented standardized error responses across all APIs
- Added `ErrorResponse` and `ErrorDetail` Pydantic models
- All exceptions now have `error_code`, `status_code`, and `to_response()` method
- Added new exception types: `AuthorizationError`, `NotFoundError`, `ConflictError`
#### OpenAPI Documentation
- ✅ Enabled OpenAPI documentation with ReDoc
- Added `docs_url="/docs"`, `redoc_url="/redoc"`, `openapi_url="/openapi.json"`
- Added OpenAPI tags for all router groups
#### Health Check Endpoints
- ✅ Added liveness and readiness probes
- `/health/live` - Simple alive check
- `/health/ready` - Database connectivity check
#### Connection Pooling
- ✅ Added database connection pooling
- `QueuePool` for PostgreSQL with configurable pool settings
- `pool_size=10`, `max_overflow=20`, `pool_pre_ping=True`
#### Systemd Service Standardization
- ✅ Standardized all service paths to `/opt/<service-name>` convention
- Updated 10 systemd service files for consistent deployment paths
## Deployment
### Site A (aitbc.bubuit.net)

0
docs/reference/docs-gaps.md → docs/5_reference/17_docs-gaps.md
View File

0
docs/cli-reference.md → docs/5_reference/1_cli-reference.md
View File

0
docs/reports/AITBC_PAYMENT_ARCHITECTURE.md → docs/5_reference/2_payment-architecture.md
View File

0
docs/reports/WALLET_COORDINATOR_INTEGRATION.md → docs/5_reference/3_wallet-coordinator-integration.md
View File

188
docs/reference/confidential-transactions.md → docs/5_reference/4_confidential-transactions.md
View File

@@ -1,4 +1,190 @@
# Confidential Transactions Architecture
# Confidential Transactions Implementation Summary
## Overview
Successfully implemented a comprehensive confidential transaction system for AITBC with opt-in encryption, selective disclosure, and full audit compliance. The implementation provides privacy for sensitive transaction data while maintaining regulatory compliance.
## Completed Components
### 1. Encryption Service ✅
- **Hybrid Encryption**: AES-256-GCM for data encryption, X25519 for key exchange
- **Envelope Pattern**: Random DEK per transaction, encrypted for each participant
- **Audit Escrow**: Separate encryption key for regulatory access
- **Performance**: Efficient batch operations, key caching
### 2. Key Management ✅
- **Per-Participant Keys**: X25519 key pairs for each participant
- **Key Rotation**: Automated rotation with re-encryption of active data
- **Secure Storage**: File-based storage (development), HSM-ready interface
- **Access Control**: Role-based permissions for key operations
### 3. Access Control ✅
- **Role-Based Policies**: Client, Miner, Coordinator, Auditor, Regulator roles
- **Time Restrictions**: Business hours, retention periods
- **Purpose-Based Access**: Settlement, Audit, Compliance, Dispute, Support
- **Dynamic Policies**: Custom policy creation and management
### 4. Audit Logging ✅
- **Tamper-Evident**: Chain of hashes for integrity verification
- **Comprehensive**: All access, key operations, policy changes
- **Export Capabilities**: JSON, CSV formats for regulators
- **Retention**: Configurable retention periods by role
### 5. API Endpoints ✅
- **/confidential/transactions**: Create and manage confidential transactions
- **/confidential/access**: Request access to encrypted data
- **/confidential/audit**: Regulatory access with authorization
- **/confidential/keys**: Key registration and rotation
- **Rate Limiting**: Protection against abuse
### 6. Data Models ✅
- **ConfidentialTransaction**: Opt-in privacy flags
- **Access Control Models**: Requests, responses, logs
- **Key Management Models**: Registration, rotation, audit
## Security Features
### Encryption
- AES-256-GCM provides confidentiality + integrity
- X25519 ECDH for secure key exchange
- Per-transaction DEKs for forward secrecy
- Random IVs per encryption
### Access Control
- Multi-factor authentication ready
- Time-bound access permissions
- Business hour restrictions for auditors
- Retention period enforcement
### Audit Compliance
- GDPR right to encryption
- SEC Rule 17a-4 compliance
- Immutable audit trails
- Regulatory access with court orders
## Current Limitations
### 1. Database Persistence ❌
- Current implementation uses mock storage
- Needs SQLModel/SQLAlchemy integration
- Transaction storage and querying
- Encrypted data BLOB handling
### 2. Private Key Security ❌
- File storage writes keys unencrypted
- Needs HSM or KMS integration
- Key escrow for recovery
- Hardware security module support
### 3. Async Issues ❌
- AuditLogger uses threading in async context
- Needs asyncio task conversion
- Background writer refactoring
- Proper async/await patterns
### 4. Rate Limiting ⚠️
- slowapi not properly integrated
- Needs FastAPI app state setup
- Distributed rate limiting for production
- Redis backend for scalability
## Production Readiness Checklist
### Critical (Must Fix)
- [ ] Database persistence layer
- [ ] HSM/KMS integration for private keys
- [ ] Fix async issues in audit logging
- [ ] Proper rate limiting setup
### Important (Should Fix)
- [ ] Performance optimization for high volume
- [ ] Distributed key management
- [ ] Backup and recovery procedures
- [ ] Monitoring and alerting
### Nice to Have (Future)
- [ ] Multi-party computation
- [ ] Zero-knowledge proofs integration
- [ ] Advanced privacy features
- [ ] Cross-chain confidential settlements
## Testing Coverage
### Unit Tests ✅
- Encryption/decryption correctness
- Key management operations
- Access control logic
- Audit logging functionality
### Integration Tests ✅
- End-to-end transaction flow
- Cross-service integration
- API endpoint testing
- Error handling scenarios
### Performance Tests ⚠️
- Basic benchmarks included
- Needs load testing
- Scalability assessment
- Resource usage profiling
## Migration Strategy
### Phase 1: Infrastructure (Week 1-2)
1. Implement database persistence
2. Integrate HSM for key storage
3. Fix async issues
4. Set up proper rate limiting
### Phase 2: Security Hardening (Week 3-4)
1. Security audit and penetration testing
2. Implement additional monitoring
3. Create backup procedures
4. Document security controls
### Phase 3: Production Rollout (Month 2)
1. Gradual rollout with feature flags
2. Performance monitoring
3. User training and documentation
4. Compliance validation
## Compliance Status
### GDPR ✅
- Right to encryption implemented
- Data minimization by design
- Privacy by default
### Financial Regulations ✅
- SEC Rule 17a-4 audit logs
- MiFID II transaction reporting
- AML/KYC integration points
### Industry Standards ✅
- ISO 27001 alignment
- NIST Cybersecurity Framework
- PCI DSS considerations
## Next Steps
1. **Immediate**: Fix database persistence and HSM integration
2. **Short-term**: Complete security hardening and testing
3. **Long-term**: Production deployment and monitoring
## Documentation
- [Architecture Design](confidential-transactions.md)
- [API Documentation](../6_architecture/3_coordinator-api.md)
- [Security Guide](security-guidelines.md)
- [Compliance Matrix](compliance-matrix.md)
## Conclusion
The confidential transaction system provides a solid foundation for privacy-preserving transactions in AITBC. While the core functionality is complete and tested, several production readiness items need to be addressed before deployment.
The modular design allows for incremental improvements and ensures the system can evolve with changing requirements and regulations.
---
## Overview

609
docs/5_reference/5_zk-proofs.md Normal file
View File

@@ -0,0 +1,609 @@
# ZK Receipt Attestation Implementation Summary
## Overview
Successfully implemented a zero-knowledge proof system for privacy-preserving receipt attestation in AITBC, enabling confidential settlements while maintaining verifiability.
## Components Implemented
### 1. ZK Circuits (`apps/zk-circuits/`)
- **Basic Circuit**: Receipt hash preimage proof in circom
- **Advanced Circuit**: Full receipt validation with pricing (WIP)
- **Build System**: npm scripts for compilation, setup, and proving
- **Testing**: Proof generation and verification tests
- **Benchmarking**: Performance measurement tools
### 2. Proof Service (`apps/coordinator-api/src/app/services/zk_proofs.py`)
- **ZKProofService**: Handles proof generation and verification
- **Privacy Levels**: Basic (hide computation) and Enhanced (hide amounts)
- **Integration**: Works with existing receipt signing system
- **Error Handling**: Graceful fallback when ZK unavailable
### 3. Receipt Integration (`apps/coordinator-api/src/app/services/receipts.py`)
- **Async Support**: Updated create_receipt to support async ZK generation
- **Optional Privacy**: ZK proofs generated only when requested
- **Backward Compatibility**: Existing receipts work unchanged
### 4. Verification Contract (`contracts/ZKReceiptVerifier.sol`)
- **On-Chain Verification**: Groth16 proof verification
- **Security Features**: Double-spend prevention, timestamp validation
- **Authorization**: Controlled access to verification functions
- **Batch Support**: Efficient batch verification
### 5. Settlement Integration (`apps/coordinator-api/aitbc/settlement/hooks.py`)
- **Privacy Options**: Settlement requests can specify privacy level
- **Proof Inclusion**: ZK proofs included in settlement messages
- **Bridge Support**: Works with existing cross-chain bridges
## Key Features
### Privacy Levels
1. **Basic**: Hide computation details, reveal settlement amount
2. **Enhanced**: Hide all amounts, prove correctness mathematically
### Performance Metrics
- **Proof Size**: ~200 bytes (Groth16)
- **Generation Time**: 5-15 seconds
- **Verification Time**: <5ms on-chain
- **Gas Cost**: ~200k gas
### Security Measures
- Trusted setup requirements documented
- Circuit audit procedures defined
- Gradual rollout strategy
- Emergency pause capabilities
## Testing Coverage
### Unit Tests
- Proof generation with various inputs
- Verification success/failure scenarios
- Privacy level validation
- Error handling
### Integration Tests
- Receipt creation with ZK proofs
- Settlement flow with privacy
- Cross-chain bridge integration
### Benchmarks
- Proof generation time measurement
- Verification performance
- Memory usage tracking
- Gas cost estimation
## Usage Examples
### Creating Private Receipt
```python
receipt = await receipt_service.create_receipt(
job=job,
miner_id=miner_id,
job_result=result,
result_metrics=metrics,
privacy_level="basic" # Enable ZK proof
)
```
### Cross-Chain Settlement with Privacy
```python
settlement = await settlement_hook.initiate_manual_settlement(
job_id="job-123",
target_chain_id=2,
use_zk_proof=True,
privacy_level="enhanced"
)
```
### On-Chain Verification
```solidity
bool verified = verifier.verifyAndRecord(
proof.a,
proof.b,
proof.c,
proof.publicSignals
);
```
## Current Status
### Completed ✅
1. Research and technology selection (Groth16)
2. Development environment setup
3. Basic circuit implementation
4. Proof generation service
5. Verification contract
6. Settlement integration
7. Comprehensive testing
8. Performance benchmarking
### Pending ⏳
1. Trusted setup ceremony (production requirement)
2. Circuit security audit
3. Full receipt validation circuit
4. Production deployment
## Next Steps for Production
### Immediate (Week 1-2)
1. Run end-to-end tests with real data
2. Performance optimization based on benchmarks
3. Security review of implementation
### Short Term (Month 1)
1. Plan and execute trusted setup ceremony
2. Complete advanced circuit with signature verification
3. Third-party security audit
### Long Term (Month 2-3)
1. Production deployment with gradual rollout
2. Monitor performance and gas costs
3. Consider PLONK for universal setup
## Risks and Mitigations
### Technical Risks
- **Trusted Setup**: Mitigate with multi-party ceremony
- **Performance**: Optimize circuits and use batch verification
- **Complexity**: Maintain clear documentation and examples
### Operational Risks
- **User Adoption**: Provide clear UI indicators for privacy
- **Gas Costs**: Optimize proof size and verification
- **Regulatory**: Ensure compliance with privacy regulations
## Documentation
- [ZK Technology Comparison](zk-technology-comparison.md)
- [Circuit Design](zk-receipt-attestation.md)
- [Development Guide](./5_zk-proofs.md)
- [API Documentation](../6_architecture/3_coordinator-api.md)
## Conclusion
The ZK receipt attestation system provides a solid foundation for privacy-preserving settlements in AITBC. The implementation balances privacy, performance, and usability while maintaining backward compatibility with existing systems.
The modular design allows for gradual adoption and future enhancements, making it suitable for both testing and production deployment.
---
## Overview
This document outlines the design for adding zero-knowledge proof capabilities to the AITBC receipt attestation system, enabling privacy-preserving settlement flows while maintaining verifiability.
## Goals
1. **Privacy**: Hide sensitive transaction details (amounts, parties, specific computations)
2. **Verifiability**: Prove receipts are valid and correctly signed without revealing contents
3. **Compatibility**: Work with existing receipt signing and settlement systems
4. **Efficiency**: Minimize proof generation and verification overhead
## Architecture
### Current Receipt System
The existing system has:
- Receipt signing with coordinator private key
- Optional coordinator attestations
- History retrieval endpoints
- Cross-chain settlement hooks
Receipt structure includes:
- Job ID and metadata
- Computation results
- Pricing information
- Miner and coordinator signatures
### Privacy-Preserving Flow
```
1. Job Execution
↓
2. Receipt Generation (clear text)
↓
3. ZK Circuit Input Preparation
↓
4. ZK Proof Generation
↓
5. On-Chain Settlement (with proof)
↓
6. Verification (without revealing data)
```
## ZK Circuit Design
### What to Prove
1. **Receipt Validity**
- Receipt was signed by coordinator
- Computation was performed correctly
- Pricing follows agreed rules
2. **Settlement Conditions**
- Amount owed is correctly calculated
- Parties have sufficient funds/balance
- Cross-chain transfer conditions met
### What to Hide
1. **Sensitive Data**
- Actual computation amounts
- Specific job details
- Pricing rates
- Participant identities
### Circuit Components
```circom
// High-level circuit structure
template ReceiptAttestation() {
// Public inputs
signal input receiptHash;
signal input settlementAmount;
signal input timestamp;
// Private inputs
signal input receipt;
signal input computationResult;
signal input pricingRate;
signal input minerReward;
// Verify receipt signature
component signatureVerifier = ECDSAVerify();
// ... signature verification logic
// Verify computation correctness
component computationChecker = ComputationVerify();
// ... computation verification logic
// Verify pricing calculation
component pricingVerifier = PricingVerify();
// ... pricing verification logic
// Output settlement proof
settlementAmount <== minerReward + coordinatorFee;
}
```
## Implementation Plan
### Phase 1: Research & Prototyping
1. **Library Selection**
- snarkjs for development (JavaScript/TypeScript)
- circomlib2 for standard circuits
- Web3.js for blockchain integration
2. **Basic Circuit**
- Simple receipt hash preimage proof
- ECDSA signature verification
- Basic arithmetic operations
### Phase 2: Integration
1. **Coordinator API Updates**
- Add ZK proof generation endpoint
- Integrate with existing receipt signing
- Add proof verification utilities
2. **Settlement Flow**
- Modify cross-chain hooks to accept proofs
- Update verification logic
- Maintain backward compatibility
### Phase 3: Optimization
1. **Performance**
- Trusted setup for Groth16
- Batch proof generation
- Recursive proofs for complex receipts
2. **Security**
- Audit circuits
- Formal verification
- Side-channel resistance
## Data Flow
### Proof Generation (Coordinator)
```python
async def generate_receipt_proof(receipt: Receipt) -> ZKProof:
# 1. Prepare circuit inputs
public_inputs = {
"receiptHash": hash_receipt(receipt),
"settlementAmount": calculate_settlement(receipt),
"timestamp": receipt.timestamp
}
private_inputs = {
"receipt": receipt,
"computationResult": receipt.result,
"pricingRate": receipt.pricing.rate,
"minerReward": receipt.pricing.miner_reward
}
# 2. Generate witness
witness = generate_witness(public_inputs, private_inputs)
# 3. Generate proof
proof = groth16.prove(witness, proving_key)
return {
"proof": proof,
"publicSignals": public_inputs
}
```
### Proof Verification (On-Chain/Settlement Layer)
```solidity
contract SettlementVerifier {
// Groth16 verifier
function verifySettlement(
uint256[2] memory a,
uint256[2][2] memory b,
uint256[2] memory c,
uint256[] memory input
) public pure returns (bool) {
return verifyProof(a, b, c, input);
}
function settleWithProof(
address recipient,
uint256 amount,
ZKProof memory proof
) public {
require(verifySettlement(proof.a, proof.b, proof.c, proof.inputs));
// Execute settlement
_transfer(recipient, amount);
}
}
```
## Privacy Levels
### Level 1: Basic Privacy
- Hide computation amounts
- Prove pricing correctness
- Reveal participant identities
### Level 2: Enhanced Privacy
- Hide all amounts
- Zero-knowledge participant proofs
- Anonymous settlement
### Level 3: Full Privacy
- Complete transaction privacy
- Ring signatures or similar
- Confidential transfers
## Security Considerations
1. **Trusted Setup**
- Multi-party ceremony for Groth16
- Documentation of setup process
- Toxic waste destruction proof
2. **Circuit Security**
- Constant-time operations
- No side-channel leaks
- Formal verification where possible
3. **Integration Security**
- Maintain existing security guarantees
- Fail-safe verification
- Gradual rollout with monitoring
## Migration Strategy
1. **Parallel Operation**
- Run both clear and ZK receipts
- Gradual opt-in adoption
- Performance monitoring
2. **Backward Compatibility**
- Existing receipts remain valid
- Optional ZK proofs
- Graceful degradation
3. **Network Upgrade**
- Coordinate with all participants
- Clear communication
- Rollback capability
## Next Steps
1. **Research Task**
- Evaluate zk-SNARKs vs zk-STARKs trade-offs
- Benchmark proof generation times
- Assess gas costs for on-chain verification
2. **Prototype Development**
- Implement basic circuit in circom
- Create proof generation service
- Build verification contract
3. **Integration Planning**
- Design API changes
- Plan data migration
- Prepare rollout strategy
---
## Overview
Analysis of zero-knowledge proof systems for AITBC receipt attestation, focusing on practical considerations for integration with existing infrastructure.
## Technology Options
### 1. zk-SNARKs (Zero-Knowledge Succinct Non-Interactive Argument of Knowledge)
**Examples**: Groth16, PLONK, Halo2
**Pros**:
- **Small proof size**: ~200 bytes for Groth16
- **Fast verification**: Constant time, ~3ms on-chain
- **Mature ecosystem**: circom, snarkjs, bellman, arkworks
- **Low gas costs**: ~200k gas for verification on Ethereum
- **Industry adoption**: Used by Aztec, Tornado Cash, Zcash
**Cons**:
- **Trusted setup**: Required for Groth16 (toxic waste problem)
- **Longer proof generation**: 10-30 seconds depending on circuit size
- **Complex setup**: Ceremony needs multiple participants
- **Quantum vulnerability**: Not post-quantum secure
### 2. zk-STARKs (Zero-Knowledge Scalable Transparent Argument of Knowledge)
**Examples**: STARKEx, Winterfell, gnark
**Pros**:
- **No trusted setup**: Transparent setup process
- **Post-quantum secure**: Resistant to quantum attacks
- **Faster proving**: Often faster than SNARKs for large circuits
- **Transparent**: No toxic waste, fully verifiable setup
**Cons**:
- **Larger proofs**: ~45KB for typical circuits
- **Higher verification cost**: ~500k-1M gas on-chain
- **Newer ecosystem**: Fewer tools and libraries
- **Less adoption**: Limited production deployments
## Use Case Analysis
### Receipt Attestation Requirements
1. **Proof Size**: Important for on-chain storage costs
2. **Verification Speed**: Critical for settlement latency
3. **Setup Complexity**: Affects deployment timeline
4. **Ecosystem Maturity**: Impacts development speed
5. **Privacy Needs**: Moderate (hiding amounts, not full anonymity)
### Quantitative Comparison
| Metric | Groth16 (SNARK) | PLONK (SNARK) | STARK |
|--------|----------------|---------------|-------|
| Proof Size | 200 bytes | 400-500 bytes | 45KB |
| Prover Time | 10-30s | 5-15s | 2-10s |
| Verifier Time | 3ms | 5ms | 50ms |
| Gas Cost | 200k | 300k | 800k |
| Trusted Setup | Yes | Universal | No |
| Library Support | Excellent | Good | Limited |
## Recommendation
### Phase 1: Groth16 for MVP
**Rationale**:
1. **Proven technology**: Battle-tested in production
2. **Small proofs**: Essential for cost-effective on-chain verification
3. **Fast verification**: Critical for settlement performance
4. **Tool maturity**: circom + snarkjs ecosystem
5. **Community knowledge**: Extensive documentation and examples
**Mitigations for trusted setup**:
- Multi-party ceremony with >100 participants
- Public documentation of process
- Consider PLONK for Phase 2 if setup becomes bottleneck
### Phase 2: Evaluate PLONK
**Rationale**:
- Universal trusted setup (one-time for all circuits)
- Slightly larger proofs but acceptable
- More flexible for circuit updates
- Growing ecosystem support
### Phase 3: Consider STARKs
**Rationale**:
- If quantum resistance becomes priority
- If proof size optimizations improve
- If gas costs become less critical
## Implementation Strategy
### Circuit Complexity Analysis
**Basic Receipt Circuit**:
- Hash verification: ~50 constraints
- Signature verification: ~10,000 constraints
- Arithmetic operations: ~100 constraints
- Total: ~10,150 constraints
**With Privacy Features**:
- Range proofs: ~1,000 constraints
- Merkle proofs: ~1,000 constraints
- Additional checks: ~500 constraints
- Total: ~12,650 constraints
### Performance Estimates
**Groth16**:
- Setup time: 2-5 hours
- Proving time: 5-15 seconds
- Verification: 3ms
- Proof size: 200 bytes
**Infrastructure Impact**:
- Coordinator: Additional 5-15s per receipt
- Settlement layer: Minimal impact (fast verification)
- Storage: Negligible increase
## Security Considerations
### Trusted Setup Risks
1. **Toxic Waste**: If compromised, can forge proofs
2. **Setup Integrity**: Requires honest participants
3. **Documentation**: Must be publicly verifiable
### Mitigation Strategies
1. **Multi-party Ceremony**:
- Minimum 100 participants
- Geographically distributed
- Public livestream
2. **Circuit Audits**:
- Formal verification where possible
- Third-party security review
- Public disclosure of circuits
3. **Gradual Rollout**:
- Start with low-value transactions
- Monitor for anomalies
- Emergency pause capability
## Development Plan
### Week 1-2: Environment Setup
- Install circom and snarkjs
- Create basic test circuit
- Benchmark proof generation
### Week 3-4: Basic Circuit
- Implement receipt hash verification
- Add signature verification
- Test with sample receipts
### Week 5-6: Integration
- Add to coordinator API
- Create verification contract
- Test settlement flow
### Week 7-8: Trusted Setup
- Plan ceremony logistics
- Prepare ceremony software
- Execute multi-party setup
### Week 9-10: Testing & Audit
- End-to-end testing
- Security review
- Performance optimization
## Next Steps
1. **Immediate**: Set up development environment
2. **Research**: Deep dive into circom best practices
3. **Prototype**: Build minimal viable circuit
4. **Evaluate**: Performance with real receipt data
5. **Decide**: Final technology choice based on testing

0
docs/reference/enterprise-sla.md → docs/5_reference/6_enterprise-sla.md
View File

0
docs/reference/threat-modeling.md → docs/5_reference/7_threat-modeling.md
View File

0
docs/reports/BLOCKCHAIN_DEPLOYMENT_SUMMARY.md → docs/5_reference/8_blockchain-deployment-summary.md
View File

0
docs/reports/PAYMENT_INTEGRATION_COMPLETE.md → docs/5_reference/9_payment-integration-complete.md
View File

0
docs/flowchart.md → docs/6_architecture/1_system-flow.md
View File

0
docs/components.md → docs/6_architecture/2_components-overview.md
View File

0
docs/coordinator-api.md → docs/6_architecture/3_coordinator-api.md
View File

0
docs/blockchain-node.md → docs/6_architecture/4_blockchain-node.md
View File

0
docs/marketplace-web.md → docs/6_architecture/5_marketplace-web.md
View File

0
docs/trade-exchange.md → docs/6_architecture/6_trade-exchange.md
View File

0
docs/wallet-documentation.md → docs/6_architecture/7_wallet.md
View File

0
docs/structure.md → docs/6_architecture/8_codebase-structure.md
View File

0
docs/full-documentation.md → docs/6_architecture/9_full-technical-reference.md
View File

20
docs/7_deployment/0_index.md Normal file
View File

@@ -0,0 +1,20 @@
# Deployment & Operations
Deploy, operate, and maintain AITBC infrastructure.
## Reading Order
| # | File | What you learn |
|---|------|----------------|
| 1 | [1_remote-deployment-guide.md](./1_remote-deployment-guide.md) | Deploy to remote servers |
| 2 | [2_service-naming-convention.md](./2_service-naming-convention.md) | Systemd service names and standards |
| 3 | [3_backup-restore.md](./3_backup-restore.md) | Backup PostgreSQL, Redis, ledger data |
| 4 | [4_incident-runbooks.md](./4_incident-runbooks.md) | Handle outages and incidents |
| 5 | [5_marketplace-deployment.md](./5_marketplace-deployment.md) | Deploy GPU marketplace endpoints |
| 6 | [6_beta-release-plan.md](./6_beta-release-plan.md) | Beta release checklist and timeline |
## Related
- [Installation](../0_getting_started/2_installation.md) — Initial setup
- [Security](../9_security/) — Security architecture and hardening
- [Architecture](../6_architecture/) — System design docs

0
docs/REMOTE_DEPLOYMENT_GUIDE.md → docs/7_deployment/1_remote-deployment-guide.md
View File

85
docs/7_deployment/2_service-naming-convention.md Normal file
View File

@@ -0,0 +1,85 @@
# AITBC Service Naming Convention
## Updated Service Names (2026-02-13)
All AITBC systemd services now follow the `aitbc-` prefix convention for consistency and easier management.
### Site A (aitbc.bubuit.net) - Production Services
| Old Name | New Name | Port | Description |
|----------|----------|------|-------------|
| blockchain-node.service | aitbc-blockchain-node-1.service | 8081 | Blockchain Node 1 |
| blockchain-node-2.service | aitbc-blockchain-node-2.service | 8082 | Blockchain Node 2 |
| blockchain-rpc.service | aitbc-blockchain-rpc-1.service | - | RPC API for Node 1 |
| blockchain-rpc-2.service | aitbc-blockchain-rpc-2.service | - | RPC API for Node 2 |
| coordinator-api.service | aitbc-coordinator-api.service | 8000 | Coordinator API |
| exchange-mock-api.service | aitbc-exchange-mock-api.service | - | Exchange Mock API |
### Site B (ns3 container) - Remote Node
| Old Name | New Name | Port | Description |
|----------|----------|------|-------------|
| blockchain-node.service | aitbc-blockchain-node-3.service | 8082 | Blockchain Node 3 |
| blockchain-rpc.service | aitbc-blockchain-rpc-3.service | - | RPC API for Node 3 |
### Already Compliant Services
These services already had the `aitbc-` prefix:
- aitbc-exchange-api.service (port 3003)
- aitbc-exchange.service (port 3002)
- aitbc-miner-dashboard.service
### Removed Services
- aitbc-blockchain.service (legacy, was on port 9080)
## Management Commands
### Check Service Status
```bash
# Site A (via SSH)
ssh aitbc-cascade "systemctl status aitbc-blockchain-node-1.service"
# Site B (via SSH)
ssh ns3-root "incus exec aitbc -- systemctl status aitbc-blockchain-node-3.service"
```
### Restart Services
```bash
# Site A
ssh aitbc-cascade "sudo systemctl restart aitbc-blockchain-node-1.service"
# Site B
ssh ns3-root "incus exec aitbc -- sudo systemctl restart aitbc-blockchain-node-3.service"
```
### View Logs
```bash
# Site A
ssh aitbc-cascade "journalctl -u aitbc-blockchain-node-1.service -f"
# Site B
ssh ns3-root "incus exec aitbc -- journalctl -u aitbc-blockchain-node-3.service -f"
```
## Service Dependencies
### Blockchain Nodes
- Node 1: `/opt/blockchain-node` → port 8081
- Node 2: `/opt/blockchain-node-2` → port 8082
- Node 3: `/opt/blockchain-node` → port 8082 (Site B)
### RPC Services
- RPC services are companion services to the main nodes
- They provide HTTP API endpoints for blockchain operations
### Coordinator API
- Main API for job submission, miner management, and receipts
- Runs on localhost:8000 inside container
- Proxied via nginx at https://aitbc.bubuit.net/api/
## Benefits of Standardized Naming
1. **Clarity**: Easy to identify AITBC services among system services
2. **Management**: Simpler to filter and manage with wildcards (`systemctl status aitbc-*`)
3. **Documentation**: Consistent naming across all documentation
4. **Automation**: Easier scripting and automation with predictable names
5. **Debugging**: Faster identification of service-related issues

0
docs/operator/backup_restore.md → docs/7_deployment/3_backup-restore.md
View File

0
docs/operator/incident-runbooks.md → docs/7_deployment/4_incident-runbooks.md
View File

0
docs/marketplace-deployment-summary.md → docs/7_deployment/5_marketplace-deployment.md
View File

0
docs/operator/beta-release-plan.md → docs/7_deployment/6_beta-release-plan.md
View File

31
docs/8_development/0_index.md Normal file
View File

@@ -0,0 +1,31 @@
# Developer Documentation
Build on the AITBC platform: APIs, SDKs, and contribution guides.
## Reading Order
| # | File | What you learn |
|---|------|----------------|
| 1 | [1_overview.md](./1_overview.md) | Platform architecture for developers |
| 2 | [2_setup.md](./2_setup.md) | Dev environment setup |
| 3 | [3_contributing.md](./3_contributing.md) | How to contribute |
| 4 | [4_examples.md](./4_examples.md) | Code examples |
| 5 | [5_developer-guide.md](./5_developer-guide.md) | SDKs, APIs, bounties |
| 6 | [6_api-authentication.md](./6_api-authentication.md) | Auth flow and tokens |
| 7 | [7_payments-receipts.md](./7_payments-receipts.md) | Payment system internals |
| 8 | [8_blockchain-node-deployment.md](./8_blockchain-node-deployment.md) | Deploy a node |
| 9 | [9_block-production-runbook.md](./9_block-production-runbook.md) | Block production ops |
| 10 | [10_bitcoin-wallet-setup.md](./10_bitcoin-wallet-setup.md) | BTC wallet integration |
| 11 | [11_marketplace-backend-analysis.md](./11_marketplace-backend-analysis.md) | Marketplace internals |
| 12 | [12_marketplace-extensions.md](./12_marketplace-extensions.md) | Build marketplace plugins |
| 13 | [13_user-interface-guide.md](./13_user-interface-guide.md) | Trade exchange UI |
| 14 | [14_user-management-setup.md](./14_user-management-setup.md) | User management system |
| 15 | [15_ecosystem-initiatives.md](./15_ecosystem-initiatives.md) | Ecosystem roadmap |
| 16 | [16_local-assets.md](./16_local-assets.md) | Local asset management |
| 17 | [17_windsurf-testing.md](./17_windsurf-testing.md) | Testing with Windsurf |
## Related
- [Architecture](../6_architecture/) — System design docs
- [Deployment](../7_deployment/) — Production deployment guides
- [CLI Reference](../5_reference/1_cli-reference.md) — Full CLI docs

0
docs/user/guides/BITCOIN-WALLET-SETUP.md → docs/8_development/10_bitcoin-wallet-setup.md
View File

0
docs/marketplace-backend-analysis.md → docs/8_development/11_marketplace-backend-analysis.md
View File

0
docs/tutorials/marketplace-extensions.md → docs/8_development/12_marketplace-extensions.md
View File

0
docs/user/guides/USER-INTERFACE-GUIDE.md → docs/8_development/13_user-interface-guide.md
View File

0
docs/user/guides/USER-MANAGEMENT-SETUP.md → docs/8_development/14_user-management-setup.md
View File

0
docs/ecosystem/ecosystem-initiatives-summary.md → docs/8_development/15_ecosystem-initiatives.md
View File

0
docs/user/guides/LOCAL_ASSETS_SUMMARY.md → docs/8_development/16_local-assets.md
View File

41
docs/guides/WINDSURF_TESTING_GUIDE.md → docs/8_development/17_windsurf-testing.md
View File

@@ -172,3 +172,44 @@ Your Windsurf testing integration is now fully configured! You can:
- Use all pytest features
Happy testing! 🚀
---
## Issue
Unittest discovery errors when using Windsurf's test runner with the `tests/` folder.
## Solution
1. **Updated pyproject.toml** - Added `tests` to the testpaths configuration
2. **Created minimal conftest.py** - Removed complex imports that were causing discovery failures
3. **Test discovery now works** for files matching `test_*.py` pattern
## Current Status
- ✅ Test discovery works for simple tests (e.g., `tests/test_discovery.py`)
- ✅ All `test_*.py` files are discovered by pytest
- ⚠️ Tests with complex imports may fail during execution due to module path issues
## Running Tests
### For test discovery only (Windsurf integration):
```bash
cd /home/oib/windsurf/aitbc
python -m pytest --collect-only tests/
```
### For running all tests (with full setup):
```bash
cd /home/oib/windsurf/aitbc
python run_tests.py tests/
```
## Test Files Found
- `tests/e2e/test_wallet_daemon.py`
- `tests/integration/test_blockchain_node.py`
- `tests/security/test_confidential_transactions.py`
- `tests/unit/test_coordinator_api.py`
- `tests/test_discovery.py` (simple test file)
## Notes
- The original `conftest_full.py` contains complex fixtures requiring full module setup
- To run tests with full functionality, restore `conftest_full.py` and use the wrapper script
- For Windsurf's test discovery, the minimal `conftest.py` provides better experience

6
docs/developer/overview.md → docs/8_development/1_overview.md
View File

@@ -134,9 +134,9 @@ aitbc dev start
Choose a tutorial based on your interest:
- [AI Inference Service](../../tutorials/building-dapp.md)
- [Marketplace Bot](../../tutorials/integration-examples.md)
- [Mining Operation](../../tutorials/mining-setup.md)
- [AI Inference Service](./12_marketplace-extensions.md)
- [Marketplace Bot](./4_examples.md)
- [Mining Operation](../3_miners/1_quick-start.md)
## Developer Resources

0
docs/developer/setup.md → docs/8_development/2_setup.md
View File

0
docs/developer/contributing.md → docs/8_development/3_contributing.md
View File

0
docs/developer/examples.md → docs/8_development/4_examples.md
View File

0
docs/developer-documentation.md → docs/8_development/5_developer-guide.md
View File

0
docs/developer/api-authentication.md → docs/8_development/6_api-authentication.md
View File

4
docs/user/guides/payments-receipts.md → docs/8_development/7_payments-receipts.md
View File

@@ -113,7 +113,7 @@ See [Bitcoin Wallet Setup](BITCOIN-WALLET-SETUP.md) for detailed instructions.
### Via Mining
Earn AITBC by providing GPU compute:
- See [Miner Documentation](../../reference/components/miner_node.md)
- See [Miner Documentation](../6_architecture/4_blockchain-node.md)
## Verifying Receipts
@@ -133,7 +133,7 @@ print(f"Receipt valid: {is_valid}")
Receipts can be anchored on-chain for permanent proof:
- ZK proofs enable privacy-preserving verification
- See [ZK Applications](../../reference/components/zk-applications.md)
- See [ZK Applications](../5_reference/5_zk-proofs.md)
## Payment Disputes

0
docs/guides/blockchain-node-deployment.md → docs/8_development/8_blockchain-node-deployment.md
View File

0
docs/guides/block-production-runbook.md → docs/8_development/9_block-production-runbook.md
View File

10
docs/SECURITY_CLEANUP_GUIDE.md → docs/9_security/1_security-cleanup-guide.md
View File

@@ -29,6 +29,16 @@
- ✅ Removed legacy session dependencies
- ✅ Consistent session management across services
6. **Structured Error Responses**
- ✅ Implemented standardized error responses across all APIs
- ✅ Added `ErrorResponse` and `ErrorDetail` Pydantic models
- ✅ All exceptions now have `error_code`, `status_code`, and `to_response()` method
7. **Health Check Endpoints**
- ✅ Added liveness and readiness probes
- ✅ `/health/live` - Simple alive check
- ✅ `/health/ready` - Database connectivity check
## 🔐 SECURITY FINDINGS
### Files Currently Tracked That Should Be Removed

0
docs/operator/security.md → docs/9_security/2_security-architecture.md
View File

142
docs/README.md Normal file
View File

@@ -0,0 +1,142 @@
# AITBC Documentation
**AI Training Blockchain - Decentralized GPU Computing Platform**
Welcome to the AITBC documentation! This guide will help you navigate the documentation based on your role.
## Quick Navigation
### 👤 New Users - Start Here!
Start with the **Getting Started** section to learn the basics:
| Order | Topic | Description |
|-------|-------|-------------|
| 1 | [0_getting_started/1_intro.md](./0_getting_started/1_intro.md) | What is AITBC? |
| 2 | [0_getting_started/2_installation.md](./0_getting_started/2_installation.md) | Install AITBC |
| 3 | [0_getting_started/3_cli.md](./0_getting_started/3_cli.md) | Use the CLI |
### 💻 Clients
If you're a **client** looking to rent GPU computing power:
| Order | Topic | Description |
|-------|-------|-------------|
| 1 | [2_clients/1_quick-start.md](./2_clients/1_quick-start.md) | Quick start guide |
| 2 | [2_clients/2_job-submission.md](./2_clients/2_job-submission.md) | Submit compute jobs |
| 3 | [2_clients/3_job-lifecycle.md](./2_clients/3_job-lifecycle.md) | Status, results, history, cancellation |
| 4 | [2_clients/4_wallet.md](./2_clients/4_wallet.md) | Manage tokens |
| 5 | [2_clients/5_pricing-billing.md](./2_clients/5_pricing-billing.md) | Costs & invoices |
| 6 | [2_clients/6_api-reference.md](./2_clients/6_api-reference.md) | Client API reference |
### ⛏️ Miners
If you're a **miner** providing GPU resources:
| Order | Topic | Description |
|-------|-------|-------------|
| 1 | [3_miners/1_quick-start.md](./3_miners/1_quick-start.md) | Quick start guide |
| 2 | [3_miners/2_registration.md](./3_miners/2_registration.md) | Register your miner |
| 3 | [3_miners/3_job-management.md](./3_miners/3_job-management.md) | Handle jobs |
| 4 | [3_miners/4_earnings.md](./3_miners/4_earnings.md) | Track earnings |
| 5 | [3_miners/5_gpu-setup.md](./3_miners/5_gpu-setup.md) | Configure GPUs |
### 🔗 Node Operators
If you're running a **blockchain node**:
| Order | Topic | Description |
|-------|-------|-------------|
| 1 | [4_blockchain/1_quick-start.md](./4_blockchain/1_quick-start.md) | Quick start guide |
| 2 | [4_blockchain/2_configuration.md](./4_blockchain/2_configuration.md) | Configure your node |
| 3 | [4_blockchain/3_operations.md](./4_blockchain/3_operations.md) | Day-to-day operations |
| 4 | [4_blockchain/4_consensus.md](./4_blockchain/4_consensus.md) | Consensus mechanism |
| 5 | [4_blockchain/7_monitoring.md](./4_blockchain/7_monitoring.md) | Monitor your node |
## Documentation Structure
```
docs/
├── 0_getting_started/ # New users start here
│ ├── 1_intro.md # What is AITBC?
│ ├── 2_installation.md # Installation guide
│ └── 3_cli.md # CLI usage
├── 1_project/ # Project management
│ ├── 1_files.md # File reference
│ ├── 2_roadmap.md # Future plans
│ ├── 3_currenttask.md # Current task (gitignored)
│ ├── 4_currentissue.md # Current issue (gitignored)
│ ├── 5_done.md # Completed work
│ └── 6_cross-site-sync-resolved.md
├── 2_clients/ # Client docs (beginner → advanced)
│ ├── 0_readme.md # Overview
│ ├── 1_quick-start.md # Get started
│ ├── 2_job-submission.md # Submit jobs
│ ├── 3_job-lifecycle.md # Status, results, history, cancel
│ ├── 4_wallet.md # Token management
│ ├── 5_pricing-billing.md # Costs & invoices
│ └── 6_api-reference.md # API reference
├── 3_miners/ # Miner docs (beginner → advanced)
│ ├── 0_readme.md # Overview
│ ├── 1_quick-start.md → 7_api-miner.md
├── 4_blockchain/ # Node operator docs (beginner → advanced)
│ ├── 0_readme.md # Overview
│ ├── 1_quick-start.md → 10_api-blockchain.md
├── 5_reference/ # Technical reference (17 files)
│ ├── 0_index.md
│ ├── 1_cli-reference.md → 17_docs-gaps.md
├── 6_architecture/ # Architecture + component deep-dives
│ ├── 1_system-flow.md # End-to-end flow
│ ├── 2_components-overview.md
│ ├── 3_coordinator-api.md # Component docs
│ ├── 4_blockchain-node.md
│ ├── 5_marketplace-web.md
│ ├── 6_trade-exchange.md
│ ├── 7_wallet.md
│ ├── 8_codebase-structure.md
│ └── 9_full-technical-reference.md
├── 7_deployment/ # Deployment & ops
│ ├── 0_index.md
│ ├── 1_remote-deployment-guide.md → 6_beta-release-plan.md
├── 8_development/ # Developer guides (17 files)
│ ├── 0_index.md
│ ├── 1_overview.md → 17_windsurf-testing.md
├── 9_security/ # Security docs
│ ├── 1_security-cleanup-guide.md
│ └── 2_security-architecture.md
└── README.md # This navigation guide
```
## Common Tasks
| Task | Documentation |
|------|---------------|
| Install AITBC | [0_getting_started/2_installation.md](./0_getting_started/2_installation.md) |
| Submit a job | [2_clients/2_job-submission.md](./2_clients/2_job-submission.md) |
| Register as miner | [3_miners/2_registration.md](./3_miners/2_registration.md) |
| Set up a node | [4_blockchain/1_quick-start.md](./4_blockchain/1_quick-start.md) |
| Check balance | [2_clients/4_wallet.md](./2_clients/4_wallet.md) |
| Monitor node | [4_blockchain/7_monitoring.md](./4_blockchain/7_monitoring.md) |
| Troubleshooting | [4_blockchain/8_troubleshooting.md](./4_blockchain/8_troubleshooting.md) |
## Additional Resources
| Resource | Description |
|----------|-------------|
| [README.md](../README.md) | Project overview |
| [1_project/2_roadmap.md](./1_project/2_roadmap.md) | Development roadmap |
| [infrastructure.md](./infrastructure.md) | Network topology |
| [1_project/5_done.md](./1_project/5_done.md) | Completed features |
| [GitHub](https://github.com/oib/AITBC) | Source code |
## Support
- **Issues**: [GitHub Issues](https://github.com/oib/AITBC/issues)
- **Discord**: [Join our community](https://discord.gg/aitbc)
- **Email**: support@aitbc.io
---
**Version**: 1.0.0
**Last Updated**: 2026-02-13
**Maintainers**: AITBC Development Team

80
docs/cli-progress-summary.md
View File

@@ -1,80 +0,0 @@
# AITBC CLI Enhancement Progress Summary
## Status: ALL PHASES COMPLETE ✅
**141/141 tests passing** | **0 failures** | **12 command groups** | **90+ subcommands**
## Completed Phases
### Phase 0: Foundation ✅
- Standardized URLs, package structure, credential storage
- Created unified CLI entry point with Click framework
### Phase 1: Core Enhancements ✅
- **client.py**: Retry with exponential backoff, job history/filtering, batch submit (CSV/JSON), job templates
- **miner.py**: Earnings tracking, capability management, deregistration, job filtering, concurrent processing
- **wallet.py**: Multi-wallet, backup/restore, staking, `--wallet-path`, multi-signature wallets
- **auth.py**: Login/logout, token management, multi-environment, API key rotation
### Phase 2: New CLI Tools ✅
- blockchain.py, marketplace.py, admin.py, config.py, simulate.py
### Phase 3: Testing & Documentation ✅
- 141/141 CLI unit tests across 9 test files + 24 integration tests (0 failures)
- CI/CD: `.github/workflows/cli-tests.yml` (Python 3.10/3.11/3.12)
- CLI reference docs (`docs/cli-reference.md` — 560+ lines)
- Shell completion script, man page (`cli/man/aitbc.1`)
### Phase 4: Backend Integration ✅
- MarketplaceOffer model extended with GPU-specific fields
- GPU booking system, review system, sync-offers endpoint
### Phase 5: Advanced Features ✅
- **Scripting**: Batch CSV/JSON ops, job templates, webhook notifications, plugin system
- **Monitoring**: Real-time dashboard, metrics collection/export, alert configuration, historical analysis
- **Security**: Multi-signature wallets, encrypted config, audit logging
- **UX**: Rich progress bars, colored output, interactive prompts, auto-completion, man pages
## Test Coverage (141 tests)
| File | Tests |
|------|-------|
| test_config.py | 37 |
| test_wallet.py | 24 |
| test_auth.py | 15 |
| test_admin.py | 13 |
| test_governance.py | 13 |
| test_simulate.py | 12 |
| test_marketplace.py | 11 |
| test_blockchain.py | 10 |
| test_client.py | 12 |
## CLI Structure
```
aitbc
├── client - Submit/manage jobs, batch submit, templates, payments
├── miner - Register, mine, earnings, capabilities, concurrent
├── wallet - Balance, staking, multisig, backup/restore, liquidity
├── auth - Login/logout, tokens, API keys
├── blockchain - Blocks, transactions, validators, supply
├── marketplace - GPU list/book/release, orders, reviews
├── admin - Status, jobs, miners, maintenance, audit-log
├── config - Set/get, profiles, secrets, import/export
├── monitor - Dashboard, metrics, alerts, webhooks, campaigns
├── simulate - Init, users, workflow, load-test, scenarios
├── governance - Propose, vote, list, result
├── plugin - Install/uninstall/list/toggle custom commands
└── version - Show version information
```
## Quick Start
```bash
cd /home/oib/windsurf/aitbc && pip install -e .
export CLIENT_API_KEY=your_key_here
aitbc config set coordinator_url http://localhost:8000
aitbc client submit --prompt "What is AI?"
aitbc wallet balance
aitbc monitor dashboard
```

56
docs/cli-summary.md
View File

@@ -1,56 +0,0 @@
# AITBC CLI Enhancement Summary
## Overview
All CLI enhancement phases (0–5) are complete. The AITBC CLI provides a production-ready interface with 141/141 tests passing, 12 command groups, and 90+ subcommands.
## Architecture
- **Package**: `cli/aitbc_cli/` with modular commands
- **Framework**: Click + Rich for output formatting
- **Testing**: pytest with Click CliRunner, 141/141 passing
- **CI/CD**: `.github/workflows/cli-tests.yml` (Python 3.10/3.11/3.12)
## Command Groups
| Group | Subcommands |
|-------|-------------|
| **client** | submit, status, blocks, receipts, cancel, history, batch-submit, template, create-payment, get-payment, release-payment, refund-payment |
| **miner** | register, poll, mine, heartbeat, status, earnings, update-capabilities, deregister, jobs, concurrent-mine |
| **wallet** | balance, earn, spend, send, history, address, stats, stake, unstake, staking-info, create, list, switch, delete, backup, restore, info, request-payment, multisig-create, multisig-propose, multisig-sign, liquidity-stake, liquidity-unstake, rewards |
| **auth** | login, logout, token, status, refresh, keys (create/list/revoke), import-env |
| **blockchain** | blocks, block, transaction, status, sync-status, peers, info, supply, validators |
| **marketplace** | gpu (register/list/details/book/release), orders, pricing, reviews |
| **admin** | status, jobs, miners, analytics, logs, maintenance, audit-log |
| **config** | show, set, path, edit, reset, export, import, validate, environments, profiles, set-secret, get-secret |
| **monitor** | dashboard, metrics, alerts, history, webhooks, campaigns, campaign-stats |
| **simulate** | init, user (create/list/balance/fund), workflow, load-test, scenario, results, reset |
| **governance** | propose, vote, list, result |
| **plugin** | install, uninstall, list, toggle |
## Global Options
- `--output table|json|yaml` — Output format
- `--url URL` — Override coordinator URL
- `--api-key KEY` — Override API key
- `-v|-vv|-vvv` — Verbosity levels
- `--debug` — Debug mode
- `--config-file PATH` — Custom config file
## Installation
```bash
cd /home/oib/windsurf/aitbc
pip install -e .
```
## Key Features
- Rich output formatting (table/JSON/YAML)
- Retry with exponential backoff
- Progress bars for long-running operations
- Interactive prompts for destructive operations
- Multi-wallet support with staking and multi-sig
- Encrypted configuration secrets
- Audit logging
- Plugin system for custom commands
- Real-time monitoring dashboard
- Webhook notifications
- Batch job submission from CSV/JSON
- Job templates for repeated tasks
- Shell completion and man pages

305
docs/client-documentation.md
View File

@@ -1,305 +0,0 @@
# Client Documentation - AITBC
Use AITBC for AI/ML Workloads: Access secure, private, and verifiable AI/ML computation on the decentralized network
> ✅ **Now Available: CLI Wrapper Tool**
>
> Submit jobs, check status, and verify receipts with our new bash CLI wrapper. Supporting 13+ Ollama models with real-time blockchain verification!
## Key Features
- **Privacy First** - Your data and models remain confidential with zero-knowledge proofs and secure enclaves
- **Verifiable Results** - Every computation is cryptographically verified on the blockchain for trust and transparency
- **Fast & Efficient** - Access thousands of GPUs worldwide with sub-second response times
## Getting Started
Start using AITBC in minutes with our simple client SDK or web interface.
### Quick Start Options
- **CLI Wrapper Tool**: ✅ NEW - Unified bash script for job management
- **Web Interface**: No installation required
- **Python SDK**: For AI/ML developers
- **JavaScript SDK**: For web applications
- **REST API**: For any platform
### CLI Wrapper Tool (Recommended)
#### Submit an Inference Job
Use the bash CLI wrapper for easy job submission:
```bash
# Submit job with CLI wrapper
./scripts/aitbc-cli.sh submit inference \
--prompt "What is machine learning?" \
--model llama3.2:latest
# Check job status
./scripts/aitbc-cli.sh status <job_id>
# View receipt with payment details
./scripts/aitbc-cli.sh receipts --job-id <job_id>
```
> **Available Models:** llama3.2, mistral, deepseek-r1:14b, gemma3, qwen2.5-coder, and 8+ more via Ollama integration. Processing time: 11-25 seconds. Rate: 0.02 AITBC per GPU second.
### Web Interface (Fastest)
1. **Visit the Marketplace**
- Go to [aitbc.bubuit.net/marketplace](https://aitbc.bubuit.net/marketplace)
2. **Connect Your Wallet**
- Connect MetaMask or create a new AITBC wallet
3. **Submit Your Job**
- Upload your data or model, select parameters, and submit
4. **Get Results**
- Receive verified results with cryptographic proof
## Popular Use Cases
### AI Inference ✅ LIVE
Run inference on pre-trained models including LLama, Mistral, DeepSeek, and custom models via Ollama
- Text generation (13+ models)
- Code generation (DeepSeek, Qwen)
- Translation (Qwen2.5-translator)
- Real-time processing (11-25s)
### Model Training
Train and fine-tune models on your data with privacy guarantees
- Fine-tuning LLMs
- Custom model training
- Federated learning
- Transfer learning
### Data Analysis
Process large datasets with confidential computing
- Statistical analysis
- Pattern recognition
- Predictive modeling
- Data visualization
### Secure Computation
Run sensitive computations with end-to-end encryption
- Financial modeling
- Healthcare analytics
- Legal document processing
- Proprietary algorithms
## SDK Examples
### Python SDK
```python
# Install the SDK
pip install aitbc
# Initialize client
from aitbc import AITBCClient
client = AITBCClient(api_key="your-api-key")
# Run inference
result = client.inference(
model="gpt-4",
prompt="Explain quantum computing",
max_tokens=500,
temperature=0.7
)
print(result.text)
# Verify the receipt
is_valid = client.verify_receipt(result.receipt_id)
print(f"Verified: {is_valid}")
```
### JavaScript SDK
```javascript
// Install the SDK
npm install @aitbc/client
// Initialize client
import { AITBCClient } from '@aitbc/client';
const client = new AITBCClient({
apiKey: 'your-api-key',
network: 'mainnet'
});
// Run inference
const result = await client.inference({
model: 'stable-diffusion',
prompt: 'A futuristic city',
steps: 50,
cfg_scale: 7.5
});
// Download the image
await client.downloadImage(result.imageId, './output.png');
// Verify computation
const verified = await client.verify(result.receiptId);
console.log('Computation verified:', verified);
```
### REST API
```bash
# Submit a job
curl -X POST https://aitbc.bubuit.net/api/v1/jobs \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"type": "inference",
"model": "gpt-4",
"input": {
"prompt": "Hello, AITBC!",
"max_tokens": 100
},
"privacy": {
"confidential": true,
"zk_proof": true
}
}'
# Check job status
curl -X GET https://aitbc.bubuit.net/api/v1/jobs/JOB_ID \
-H "Authorization: Bearer YOUR_TOKEN"
```
## Pricing
Flexible pricing options for every use case
### Pay-per-use
- **$0.01/1K tokens**
- No minimum commitment
- Pay only for what you use
- All models available
- Basic support
### Professional
- **$99/month**
- $500 included credits
- Priority processing
- Advanced models
- Email support
- API access
### Enterprise
- **Custom**
- Unlimited usage
- Dedicated resources
- Custom models
- 24/7 support
- SLA guarantee
## Privacy & Security
> **Your data is never stored or exposed** - All computations are performed in secure enclaves with zero-knowledge proof verification.
### Privacy Features
- **End-to-end encryption** - Your data is encrypted before leaving your device
- **Zero-knowledge proofs** - Prove computation without revealing inputs
- **Secure enclaves** - Computations run in isolated, verified environments
- **No data retention** - Providers cannot access or store your data
- **Audit trails** - Full transparency on blockchain
### Compliance
- GDPR compliant
- SOC 2 Type II certified
- HIPAA eligible
- ISO 27001 certified
## Best Practices
### Optimizing Performance
- Use appropriate model sizes for your task
- Batch requests when possible
- Enable caching for repeated queries
- Choose the right privacy level for your needs
- Monitor your usage and costs
### Security Tips
- Keep your API keys secure
- Use environment variables for credentials
- Enable two-factor authentication
- Regularly rotate your keys
- Use VPN for additional privacy
### Cost Optimization
- Start with smaller models for testing
- Use streaming for long responses
- Set appropriate limits and timeouts
- Monitor token usage
- Consider subscription plans for regular use
## Support & Resources
### Getting Help
- **Documentation**: [Full API reference](full-documentation.html)
- **Community**: [Join our Discord](https://discord.gg/aitbc)
- **Email**: [aitbc@bubuit.net](mailto:aitbc@bubuit.net)
- **Status**: [System status](https://status.aitbc.bubuit.net)
### Tutorials
- [Getting Started with AI Inference](#)
- [Building a Chat Application](#)
- [Image Generation Guide](#)
- [Privacy-Preserving ML](#)
- [API Integration Best Practices](#)
### Examples
- [GitHub Repository](#)
- [Code Examples](#)
- [Sample Applications](#)
- [SDK Documentation](#)
## Frequently Asked Questions
> **Question not answered?** Contact us at [aitbc@bubuit.net](mailto:aitbc@bubuit.net)
### General
- **How do I get started?** - Sign up for an account, connect your wallet, and submit your first job through the web interface or API.
- **What models are available?** - We support GPT-3.5/4, Claude, Llama, Stable Diffusion, and many custom models.
- **Can I use my own model?** - Yes, you can upload and run private models with full confidentiality.
### Privacy
- **Is my data private?** - Absolutely. Your data is encrypted and never exposed to providers.
- **How do ZK proofs work?** - They prove computation was done correctly without revealing inputs.
- **Can you see my prompts?** - No, prompts are encrypted and processed in secure enclaves.
### Technical
- **What's the response time?** - Most jobs complete in 1-5 seconds depending on complexity.
- **Do you support streaming?** - Yes, streaming is available for real-time applications.
- **Can I run batch jobs?** - Yes, batch processing is supported for large workloads.
### Billing
- **How am I billed?** - Pay-per-use or monthly subscription options available.
- **Can I set spending limits?** - Yes, you can set daily/monthly limits in your dashboard.
- **Do you offer refunds?** - Yes, we offer refunds for service issues within 30 days.
---
© 2025 AITBC. All rights reserved.

40
docs/currentTask.md
View File

@@ -1,40 +0,0 @@
# Current Task
No active task. All recent work documented in `done.md`.
## Last Completed (2026-02-13)
### Critical Security Fixes
- ✅ Fixed hardcoded secrets (JWT, PostgreSQL credentials)
- ✅ Unified database sessions (storage.SessionDep)
- ✅ Closed authentication gaps in exchange API
- ✅ Tightened CORS defaults across all services
- ✅ Enhanced wallet encryption (Fernet, PBKDF2)
- ✅ Fixed CI import error (requests → httpx)
- ✅ Deployed to Site A (aitbc.bubuit.net)
- ✅ Site B no action needed (blockchain node only)
### Previous (2026-02-12)
- ✅ Persistent GPU marketplace (SQLModel) — see `done.md`
- ✅ CLI integration tests (24 tests) — see `done.md`
- ✅ Coordinator billing stubs (21 tests) — see `done.md`
- ✅ Documentation updated (README, roadmap, done, structure, components, files, coordinator-api)
## Test Summary
| Suite | Tests | Source |
|-------|-------|--------|
| Blockchain node | 50 | `tests/test_blockchain_nodes.py` |
| ZK integration | 8 | `tests/test_zk_integration.py` |
| CLI unit | 141 | `tests/cli/test_*.py` (9 files) |
| CLI integration | 24 | `tests/cli/test_cli_integration.py` |
| Billing | 21 | `apps/coordinator-api/tests/test_billing.py` |
| GPU marketplace | 22 | `apps/coordinator-api/tests/test_gpu_marketplace.py` |
## Environment
- **Local testnet**: localhost blockchain nodes (ports 8081, 8082)
- **Production**: `ssh aitbc-cascade` — same codebase, single environment
- **Remote node**: `ssh ns3-root` → Site C (aitbc.keisanki.net)
- See `infrastructure.md` for full topology

18
docs/currentissue.md
View File

@@ -1,18 +0,0 @@
# Current Issues
*No current issues to report.*
---
## Usage Guidelines
When tracking a new issue:
1. Add a new section with a descriptive title
2. Include the date and current status
3. Describe the issue, affected components, and any fixes attempted
4. Update status as progress is made
5. Once resolved, move this file to `docs/issues/` with a machine-readable name
## Recent Resolved Issues
See `docs/issues/` for resolved issues and their solutions.

111
docs/developer/api/coordinator/authentication.md
View File

@@ -1,111 +0,0 @@
---
title: API Authentication
description: Understanding authentication for the Coordinator API
---
# API Authentication
All Coordinator API endpoints require authentication using API keys.
## Getting Started
1. Sign up at [AITBC Dashboard](https://dashboard.aitbc.io)
2. Generate an API key
3. Include the key in your requests
## Authentication Methods
### HTTP Header (Recommended)
```http
X-API-Key: your_api_key_here
```
### Query Parameter
```http
GET /v1/jobs?api_key=your_api_key_here
```
## Example Requests
### cURL
```bash
curl -X GET https://aitbc.bubuit.net/api/v1/jobs \
-H "X-API-Key: your_api_key_here"
```
### Python
```python
import requests
headers = {
"X-API-Key": "your_api_key_here"
}
response = requests.get(
"https://aitbc.bubuit.net/api/v1/jobs",
headers=headers
)
```
### JavaScript
```javascript
const headers = {
"X-API-Key": "your_api_key_here"
};
fetch("https://aitbc.bubuit.net/api/v1/jobs", {
headers: headers
})
.then(response => response.json())
.then(data => console.log(data));
```
## Security Best Practices
- Never expose API keys in client-side code
- Use environment variables in production
- Rotate keys regularly
- Monitor API usage
- Use HTTPS for all requests
## Rate Limits
API requests are rate-limited based on your plan:
- Free: 60 requests/minute
- Pro: 600 requests/minute
- Enterprise: 6000 requests/minute
Rate limit headers are included in responses:
```http
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1640995200
```
## Error Handling
```json
{
"error": {
"code": "INVALID_API_KEY",
"message": "The provided API key is invalid"
}
}
```
## Key Management
### View Your Keys
Visit the [Dashboard](https://dashboard.aitbc.io/api-keys)
### Revoke a Key
```bash
curl -X DELETE https://aitbc.bubuit.net/api/v1/api-keys/{key_id} \
-H "X-API-Key: your_master_key"
```
### Regenerate a Key
```bash
curl -X POST https://aitbc.bubuit.net/api/v1/api-keys/{key_id}/regenerate \
-H "X-API-Key: your_master_key"
```

580
docs/developer/api/coordinator/endpoints.md
View File

@@ -1,580 +0,0 @@
---
title: API Endpoints
description: Complete list of Coordinator API endpoints
---
# API Endpoints
## Jobs
### Create Job
```http
POST /v1/jobs
```
Create a new AI job.
**Request Body:**
```json
{
"name": "image-classification",
"type": "ai-inference",
"model": {
"type": "python",
"entrypoint": "model.py",
"requirements": ["numpy", "torch"]
},
"input": {
"type": "image",
"format": "jpeg"
},
"output": {
"type": "json"
},
"resources": {
"cpu": "1000m",
"memory": "2Gi",
"gpu": "1"
},
"pricing": {
"max_cost": "0.10"
}
}
```
**Response:**
```json
{
"job_id": "job_1234567890",
"status": "submitted",
"created_at": "2024-01-01T12:00:00Z",
"estimated_completion": "2024-01-01T12:05:00Z"
}
```
### Get Job Status
```http
GET /v1/jobs/{job_id}
```
Retrieve the current status of a job.
**Response:**
```json
{
"job_id": "job_1234567890",
"status": "running",
"progress": 75,
"created_at": "2024-01-01T12:00:00Z",
"started_at": "2024-01-01T12:01:00Z",
"estimated_completion": "2024-01-01T12:05:00Z",
"miner_id": "miner_1234567890"
}
```
### List Jobs
```http
GET /v1/jobs
```
List all jobs with optional filtering.
**Query Parameters:**
- `status` (string): Filter by status (submitted, running, completed, failed)
- `type` (string): Filter by job type
- `limit` (integer): Maximum number of jobs to return (default: 50)
- `offset` (integer): Number of jobs to skip (default: 0)
**Response:**
```json
{
"jobs": [
{
"job_id": "job_1234567890",
"status": "completed",
"type": "ai-inference",
"created_at": "2024-01-01T12:00:00Z"
}
],
"total": 1,
"limit": 50,
"offset": 0
}
```
### Cancel Job
```http
DELETE /v1/jobs/{job_id}
```
Cancel a running or submitted job.
**Response:**
```json
{
"job_id": "job_1234567890",
"status": "cancelled",
"cancelled_at": "2024-01-01T12:03:00Z"
}
```
### Get Job Results
```http
GET /v1/jobs/{job_id}/results
```
Retrieve the results of a completed job.
**Response:**
```json
{
"job_id": "job_1234567890",
"status": "completed",
"results": {
"prediction": "cat",
"confidence": 0.95,
"processing_time": 1.23
},
"completed_at": "2024-01-01T12:04:00Z"
}
```
## Marketplace
### Create Offer
```http
POST /v1/marketplace/offers
```
Create a new marketplace offer for job execution.
**Request Body:**
```json
{
"job_type": "image-classification",
"price": "0.001",
"max_jobs": 10,
"requirements": {
"min_gpu_memory": "4Gi",
"min_cpu": "2000m"
},
"duration": 3600
}
```
**Response:**
```json
{
"offer_id": "offer_1234567890",
"miner_id": "miner_1234567890",
"status": "active",
"created_at": "2024-01-01T12:00:00Z"
}
```
### List Offers
```http
GET /v1/marketplace/offers
```
List all active marketplace offers.
**Query Parameters:**
- `job_type` (string): Filter by job type
- `max_price` (string): Maximum price filter
- `limit` (integer): Maximum number of offers (default: 50)
**Response:**
```json
{
"offers": [
{
"offer_id": "offer_1234567890",
"miner_id": "miner_1234567890",
"job_type": "image-classification",
"price": "0.001",
"reputation": 4.8
}
]
}
```
### Accept Offer
```http
POST /v1/marketplace/offers/{offer_id}/accept
```
Accept a marketplace offer for job execution.
**Request Body:**
```json
{
"job_id": "job_1234567890",
"bid_price": "0.001"
}
```
**Response:**
```json
{
"transaction_id": "tx_1234567890",
"status": "pending",
"created_at": "2024-01-01T12:00:00Z"
}
```
## Receipts
### Get Receipt
```http
GET /v1/receipts/{job_id}
```
Retrieve the receipt for a completed job.
**Response:**
```json
{
"receipt_id": "receipt_1234567890",
"job_id": "job_1234567890",
"miner_id": "miner_1234567890",
"signature": {
"sig": "base64_signature",
"public_key": "base64_public_key"
},
"attestations": [
{
"type": "completion",
"timestamp": "2024-01-01T12:04:00Z",
"signature": "base64_attestation"
}
],
"created_at": "2024-01-01T12:04:00Z"
}
```
### Verify Receipt
```http
POST /v1/receipts/verify
```
Verify the authenticity of a receipt.
**Request Body:**
```json
{
"receipt": {
"receipt_id": "receipt_1234567890",
"signature": {
"sig": "base64_signature",
"public_key": "base64_public_key"
}
}
}
```
**Response:**
```json
{
"valid": true,
"miner_signature_valid": true,
"coordinator_attestations": 2,
"verified_at": "2024-01-01T12:05:00Z"
}
```
## Analytics
### Get Marketplace Stats
```http
GET /v1/marketplace/stats
```
Retrieve marketplace statistics.
**Response:**
```json
{
"total_jobs": 10000,
"active_jobs": 150,
"completed_jobs": 9800,
"failed_jobs": 50,
"average_completion_time": 120.5,
"total_volume": "1500.50",
"active_miners": 500
}
```
### Get Miner Stats
```http
GET /v1/miners/{miner_id}/stats
```
Retrieve statistics for a specific miner.
**Response:**
```json
{
"miner_id": "miner_1234567890",
"reputation": 4.8,
"total_jobs": 500,
"success_rate": 0.98,
"average_completion_time": 115.2,
"total_earned": "125.50",
"active_since": "2024-01-01T00:00:00Z"
}
```
## Health
### Health Check
```http
GET /v1/health
```
Production base URL is `https://aitbc.bubuit.net/api`, so the full health URL is:
```http
GET /api/v1/health
```
Check the health status of the coordinator service.
**Response:**
```json
{
"status": "ok",
"version": "1.0.0",
"environment": "production",
"timestamp": "2024-01-01T12:00:00Z",
"services": {
"database": "healthy",
"blockchain": "healthy",
"marketplace": "healthy"
}
}
```
## WebSocket API
### Real-time Updates
```
WSS /ws
```
Connect to receive real-time updates about jobs and marketplace events.
**Message Types:**
- `job_update`: Job status changes
- `marketplace_update`: New offers or transactions
- `receipt_created`: New receipts generated
**Example Message:**
```json
{
"type": "job_update",
"data": {
"job_id": "job_1234567890",
"status": "completed",
"timestamp": "2024-01-01T12:04:00Z"
}
}
```
## Error Codes
| Code | Description | HTTP Status |
|------|-------------|-------------|
| `INVALID_JOB_TYPE` | Unsupported job type | 400 |
| `INSUFFICIENT_BALANCE` | Not enough funds in wallet | 402 |
| `JOB_NOT_FOUND` | Job does not exist | 404 |
| `JOB_ALREADY_COMPLETED` | Cannot modify completed job | 409 |
| `OFFER_NOT_AVAILABLE` | Offer is no longer available | 410 |
| `RATE_LIMIT_EXCEEDED` | Too many requests | 429 |
| `INTERNAL_ERROR` | Server error | 500 |
## SDK Examples
### Python
```python
from aitbc import AITBCClient
client = AITBCClient(api_key="your_key")
# Create a job
job = client.jobs.create({
"name": "my-job",
"type": "ai-inference",
...
})
# Get results
results = client.jobs.get_results(job["job_id"])
```
### JavaScript
```javascript
import { AITBCClient } from '@aitbc/client';
const client = new AITBCClient({ apiKey: 'your_key' });
// Create a job
const job = await client.jobs.create({
name: 'my-job',
type: 'ai-inference',
...
});
// Get results
const results = await client.jobs.getResults(job.jobId);
```
## Services
### Whisper Transcription
```http
POST /v1/services/whisper/transcribe
```
Transcribe audio file using Whisper.
**Request Body:**
```json
{
"audio_url": "https://example.com/audio.mp3",
"model": "base",
"language": "en",
"task": "transcribe"
}
```
### Stable Diffusion Generation
```http
POST /v1/services/stable-diffusion/generate
```
Generate images from text prompts.
**Request Body:**
```json
{
"prompt": "A beautiful sunset over mountains",
"model": "stable-diffusion-1.5",
"size": "1024x1024",
"num_images": 1,
"steps": 20
}
```
### LLM Inference
```http
POST /v1/services/llm/inference
```
Run inference on language models.
**Request Body:**
```json
{
"model": "llama-7b",
"prompt": "Explain quantum computing",
"max_tokens": 256,
"temperature": 0.7
}
```
### Video Transcoding
```http
POST /v1/services/ffmpeg/transcode
```
Transcode video files.
**Request Body:**
```json
{
"input_url": "https://example.com/video.mp4",
"output_format": "mp4",
"codec": "h264",
"resolution": "1920x1080"
}
```
### 3D Rendering
```http
POST /v1/services/blender/render
```
Render 3D scenes with Blender.
**Request Body:**
```json
{
"blend_file_url": "https://example.com/scene.blend",
"engine": "cycles",
"resolution_x": 1920,
"resolution_y": 1080,
"samples": 128
}
```
## Service Registry
### List All Services
```http
GET /v1/registry/services
```
List all available GPU services with optional filtering.
**Query Parameters:**
- `category` (optional): Filter by service category
- `search` (optional): Search by name, description, or tags
### Get Service Definition
```http
GET /v1/registry/services/{service_id}
```
Get detailed definition for a specific service.
### Get Service Schema
```http
GET /v1/registry/services/{service_id}/schema
```
Get JSON schema for service input parameters.
### Get Service Requirements
```http
GET /v1/registry/services/{service_id}/requirements
```
Get hardware requirements for a service.
### Validate Service Request
```http
POST /v1/registry/services/validate
```
Validate a service request against the service schema.
**Request Body:**
```json
{
"service_id": "llm_inference",
"request_data": {
"model": "llama-7b",
"prompt": "Hello world",
"max_tokens": 256
}
}
```
**Response:**
```json
{
"valid": true,
"errors": [],
"warnings": []
}
```

79
docs/developer/api/coordinator/openapi.md
View File

@@ -1,79 +0,0 @@
---
title: OpenAPI Specification
description: Complete OpenAPI specification for the Coordinator API
---
# OpenAPI Specification
The complete OpenAPI 3.0 specification for the AITBC Coordinator API is available below.
## Interactive Documentation
- [Swagger UI](https://aitbc.bubuit.net/api/docs) - Interactive API explorer
- [ReDoc](https://aitbc.bubuit.net/api/redoc) - Alternative documentation view
## Download Specification
- [JSON Format](openapi.json) - Raw OpenAPI JSON
- [YAML Format](openapi.yaml) - OpenAPI YAML format
## Key Endpoints
### Jobs
- `POST /v1/jobs` - Create a new job
- `GET /v1/jobs/{job_id}` - Get job details
- `GET /v1/jobs` - List jobs
- `DELETE /v1/jobs/{job_id}` - Cancel job
- `GET /v1/jobs/{job_id}/results` - Get job results
### Marketplace
- `POST /v1/marketplace/offers` - Create offer
- `GET /v1/marketplace/offers` - List offers
- `POST /v1/marketplace/offers/{offer_id}/accept` - Accept offer
### Receipts
- `GET /v1/receipts/{job_id}` - Get receipt
- `POST /v1/receipts/verify` - Verify receipt
### Analytics
- `GET /v1/marketplace/stats` - Get marketplace statistics
- `GET /v1/miners/{miner_id}/stats` - Get miner statistics
## Authentication
All endpoints require authentication via the `X-API-Key` header.
## Rate Limits
API requests are rate-limited based on your subscription plan.
## WebSocket API
Real-time updates available at:
- WebSocket: `wss://aitbc.bubuit.net/ws`
- Message types: job_update, marketplace_update, receipt_created
## Code Generation
Use the OpenAPI spec to generate client libraries:
```bash
# OpenAPI Generator
openapi-generator-cli generate -i openapi.json -g python -o ./client/
# Or use the online generator at https://openapi-generator.tech/
```
## SDK Integration
The OpenAPI spec is integrated into our official SDKs:
- [Python SDK](../../developer-guide/sdks/python.md)
- [JavaScript SDK](../../developer-guide/sdks/javascript.md)
## Support
For API support:
- 📖 [API Documentation](endpoints.md)
- 🐛 [Report Issues](https://github.com/aitbc/issues)
- 💬 [Discord](https://discord.gg/aitbc)
- 📧 [api-support@aitbc.io](mailto:api-support@aitbc.io)

140
docs/developer/api/coordinator/overview.md
View File

@@ -1,140 +0,0 @@
---
title: Coordinator API Overview
description: Introduction to the AITBC Coordinator API
---
# Coordinator API Overview
The Coordinator API is the central service of the AITBC platform, responsible for job management, marketplace operations, and coordination between various components.
## Base URL
```
Production: https://aitbc.bubuit.net/api
Staging: https://staging-api.aitbc.io
Development: http://localhost:8011
```
## Authentication
All API endpoints require authentication using an API key. Include the API key in the request header:
```http
X-API-Key: your_api_key_here
```
Get your API key from the [AITBC Dashboard](https://dashboard.aitbc.io).
## Core Concepts
### Jobs
Jobs are the primary unit of work in AITBC. They represent AI computations that need to be executed.
```json
{
"job_id": "job_1234567890",
"type": "ai-inference",
"status": "running",
"created_at": "2024-01-01T12:00:00Z",
"estimated_completion": "2024-01-01T12:05:00Z"
}
```
### Marketplace
The marketplace connects job creators with miners who can execute the jobs.
```json
{
"offer_id": "offer_1234567890",
"job_type": "image-classification",
"price": "0.001",
"miner_id": "miner_1234567890"
}
```
### Receipts
Receipts provide cryptographic proof of job execution and results.
```json
{
"receipt_id": "receipt_1234567890",
"job_id": "job_1234567890",
"signature": {
"sig": "base64_signature",
"public_key": "base64_public_key"
}
}
```
## Rate Limits
API requests are rate-limited to ensure fair usage:
| Plan | Requests per minute | Burst |
|------|---------------------|-------|
| Free | 60 | 10 |
| Pro | 600 | 100 |
| Enterprise | 6000 | 1000 |
## Error Handling
The API uses standard HTTP status codes and returns detailed error messages:
```json
{
"error": {
"code": "INVALID_API_KEY",
"message": "The provided API key is invalid",
"details": {
"request_id": "req_1234567890"
}
}
}
```
Common error codes:
- `400 Bad Request` - Invalid request parameters
- `401 Unauthorized` - Invalid or missing API key
- `403 Forbidden` - Insufficient permissions
- `404 Not Found` - Resource not found
- `429 Too Many Requests` - Rate limit exceeded
- `500 Internal Server Error` - Server error
## SDK Support
Official SDKs are available for:
- [Python](../../developer-guide/sdks/python.md)
- [JavaScript/TypeScript](../../developer-guide/sdks/javascript.md)
## WebSocket API
Real-time updates are available through WebSocket connections:
```javascript
const ws = new WebSocket('wss://aitbc.bubuit.net/ws');
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
console.log('Job update:', data);
};
```
## OpenAPI Specification
The complete OpenAPI 3.0 specification is available:
- [View in Swagger UI](https://aitbc.bubuit.net/api/docs)
- [Download JSON](openapi.md)
## Getting Started
1. [Get an API key](https://dashboard.aitbc.io/api-keys)
2. [Review authentication](authentication.md)
3. [Explore endpoints](endpoints.md)
4. [Check examples](../../developer-guide/examples.md)
## Support
- 📖 [Documentation](../../)
- 💬 [Discord](https://discord.gg/aitbc)
- 🐛 [Report Issues](https://github.com/aitbc/issues)
- 📧 [api-support@aitbc.io](mailto:api-support@aitbc.io)

47
docs/developer/index.md
View File

@@ -1,47 +0,0 @@
# AITBC Developer Documentation
Welcome to the AITBC developer documentation. This section contains resources for building on AITBC.
## Getting Started
- [Overview](overview.md) - Developer platform overview
- [Setup](setup.md) - Development environment setup
- [Contributing](contributing.md) - How to contribute to AITBC
## API Documentation
- [API Overview](api/overview.md) - REST API introduction
- [Authentication](api/authentication.md) - API authentication guide
- [Endpoints](api/endpoints.md) - Available API endpoints
- [OpenAPI Spec](api/openapi.md) - OpenAPI specification
## SDKs
- [Python SDK](sdks/python.md) - Python SDK documentation
- [JavaScript SDK](sdks/javascript.md) - JavaScript SDK documentation
## Tutorials & Examples
- [Examples](examples.md) - Code examples and tutorials
- [API Authentication](api-authentication.md) - Authentication examples
## Architecture
- [Architecture Guide](../reference/architecture/) - System architecture documentation
- [Design Patterns](../reference/architecture/) - Common patterns and best practices
## Testing
- [Testing Guide](../guides/WINDSURF_TESTING_GUIDE.md) - Comprehensive testing with Windsurf
- [Test Setup](../guides/WINDSURF_TEST_SETUP.md) - Quick testing setup
- [Test Examples](../examples/) - Test code examples
## Deployment
- [Deployment Guide](../operator/deployment/) - How to deploy AITBC applications
- [CI/CD](../operator/deployment/) - Continuous integration and deployment
## Reference
- [Glossary](../reference/glossary.md) - Terms and definitions
- [FAQ](../user-guide/faq.md) - Frequently asked questions

477
docs/developer/integration/partner-integration.md
View File

@@ -1,477 +0,0 @@
# Partner Integration Guide
This guide helps third-party services integrate with the AITBC platform for explorers, analytics, and other services.
## Overview
AITBC provides multiple integration points for partners:
- REST APIs for real-time data
- WebSocket streams for live updates
- Export endpoints for bulk data
- Webhook notifications for events
## Getting Started
### 1. Register Your Application
Register your service to get API credentials:
```bash
curl -X POST https://aitbc.bubuit.net/api/v1/partners/register \
-H "Content-Type: application/json" \
-d '{
"name": "Your Service Name",
"description": "Brief description of your service",
"website": "https://yourservice.com",
"contact": "contact@yourservice.com",
"integration_type": "explorer"
}'
```
**Response:**
```json
{
"partner_id": "partner-uuid",
"api_key": "aitbc_xxxxxxxxxxxx",
"api_secret": "secret_xxxxxxxxxxxx",
"rate_limit": {
"requests_per_minute": 1000,
"requests_per_hour": 50000
}
}
```
### 2. Authenticate Requests
Use your API credentials for authenticated requests:
```bash
curl -H "Authorization: Bearer aitbc_xxxxxxxxxxxx" \
https://aitbc.bubuit.net/api/explorer/blocks
```
## API Endpoints
### Blockchain Data
#### Get Latest Blocks
```http
GET /api/explorer/blocks?limit={limit}&offset={offset}
```
**Response:**
```json
{
"blocks": [
{
"hash": "0x123...",
"height": 1000000,
"timestamp": "2025-12-28T18:00:00Z",
"proposer": "0xabc...",
"transaction_count": 150,
"gas_used": "15000000",
"size": 1024000
}
],
"total": 1000000
}
```
#### Get Block Details
```http
GET /api/explorer/blocks/{block_hash}
```
#### Get Transaction
```http
GET /api/explorer/transactions/{tx_hash}
```
#### Get Address Details
```http
GET /api/explorer/addresses/{address}?transactions={true|false}
```
### Marketplace Data
#### Get Active Offers
```http
GET /api/v1/marketplace/offers?status=active&limit={limit}
```
#### Get Bid History
```http
GET /api/v1/marketplace/bids?offer_id={offer_id}
```
#### Get Service Categories
```http
GET /api/v1/marketplace/services/categories
```
### Analytics Data
#### Get Network Stats
```http
GET /api/v1/analytics/network/stats
```
**Response:**
```json
{
"total_blocks": 1000000,
"total_transactions": 50000000,
"active_addresses": 10000,
"network_hashrate": 1500000000000,
"average_block_time": 5.2,
"marketplace_volume": {
"24h": "1500000",
"7d": "10000000",
"30d": "40000000"
}
}
```
#### Get Historical Data
```http
GET /api/v1/analytics/historical?metric={metric}&period={period}&start={timestamp}&end={timestamp}
```
**Metrics:**
- `block_count`
- `transaction_count`
- `active_addresses`
- `marketplace_volume`
- `gas_price`
**Periods:**
- `1h`, `1d`, `1w`, `1m`
## WebSocket Streams
Connect to the WebSocket for real-time updates:
```javascript
const ws = new WebSocket('wss://aitbc.bubuit.net/ws');
// Authenticate
ws.send(JSON.stringify({
type: 'auth',
api_key: 'aitbc_xxxxxxxxxxxx'
}));
// Subscribe to blocks
ws.send(JSON.stringify({
type: 'subscribe',
channel: 'blocks'
}));
// Subscribe to transactions
ws.send(JSON.stringify({
type: 'subscribe',
channel: 'transactions',
filters: {
to_address: '0xabc...'
}
}));
// Handle messages
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
console.log(data);
};
```
### Available Channels
- `blocks` - New blocks
- `transactions` - New transactions
- `marketplace_offers` - New marketplace offers
- `marketplace_bids` - New bids
- `governance` - Governance proposals and votes
## Bulk Data Export
### Export Blocks
```http
POST /api/v1/export/blocks
```
**Request:**
```json
{
"start_block": 900000,
"end_block": 1000000,
"format": "json",
"compression": "gzip"
}
```
**Response:**
```json
{
"export_id": "export-uuid",
"estimated_size": "500MB",
"download_url": "https://aitbc.bubuit.net/api/v1/export/download/export-uuid"
}
```
### Export Transactions
```http
POST /api/v1/export/transactions
```
## Webhooks
Configure webhooks to receive event notifications:
```bash
curl -X POST https://aitbc.bubuit.net/api/v1/webhooks \
-H "Authorization: Bearer aitbc_xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"url": "https://yourservice.com/webhook",
"events": ["block.created", "transaction.confirmed"],
"secret": "your_webhook_secret"
}'
```
**Webhook Payload:**
```json
{
"event": "block.created",
"timestamp": "2025-12-28T18:00:00Z",
"data": {
"block": {
"hash": "0x123...",
"height": 1000000,
"proposer": "0xabc..."
}
},
"signature": "sha256_signature"
}
```
Verify webhook signatures:
```javascript
const crypto = require('crypto');
function verifyWebhook(payload, signature, secret) {
const expected = crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expected)
);
}
```
## Rate Limits
API requests are rate-limited based on your partner tier:
| Tier | Requests/Minute | Requests/Hour | Features |
|------|----------------|--------------|----------|
| Basic | 100 | 5,000 | Public data |
| Pro | 1,000 | 50,000 | + WebSocket |
| Enterprise | 10,000 | 500,000 | + Bulk export |
Rate limit headers are included in responses:
```
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640692800
```
## SDKs and Libraries
### Python SDK
```python
from aitbc_sdk import AITBCClient
client = AITBCClient(
api_key="aitbc_xxxxxxxxxxxx",
base_url="https://aitbc.bubuit.net/api/v1"
)
# Get latest block
block = client.blocks.get_latest()
print(f"Latest block: {block.height}")
# Stream transactions
for tx in client.stream.transactions():
print(f"New tx: {tx.hash}")
```
### JavaScript SDK
```javascript
import { AITBCClient } from 'aitbc-sdk-js';
const client = new AITBCClient({
apiKey: 'aitbc_xxxxxxxxxxxx',
baseUrl: 'https://aitbc.bubuit.net/api/v1'
});
// Get network stats
const stats = await client.analytics.getNetworkStats();
console.log('Network stats:', stats);
// Subscribe to blocks
client.subscribe('blocks', (block) => {
console.log('New block:', block);
});
```
## Explorer Integration Guide
### Display Blocks
```html
<div class="block-list">
{% for block in blocks %}
<div class="block-item">
<a href="/block/{{ block.hash }}">
Block #{{ block.height }}
</a>
<span class="timestamp">{{ block.timestamp }}</span>
<span class="proposer">{{ block.proposer }}</span>
</div>
{% endfor %}
</div>
```
### Transaction Details
```javascript
async function showTransaction(txHash) {
const tx = await client.transactions.get(txHash);
document.getElementById('tx-hash').textContent = tx.hash;
document.getElementById('tx-status').textContent = tx.status;
document.getElementById('tx-from').textContent = tx.from_address;
document.getElementById('tx-to').textContent = tx.to_address;
document.getElementById('tx-amount').textContent = tx.amount;
document.getElementById('tx-gas').textContent = tx.gas_used;
// Show events
const events = await client.transactions.getEvents(txHash);
renderEvents(events);
}
```
### Address Activity
```javascript
async function loadAddress(address) {
const [balance, transactions, tokens] = await Promise.all([
client.addresses.getBalance(address),
client.addresses.getTransactions(address),
client.addresses.getTokens(address)
]);
updateBalance(balance);
renderTransactions(transactions);
renderTokens(tokens);
}
```
## Analytics Integration
### Custom Dashboards
```python
import plotly.graph_objects as go
from aitbc_sdk import AITBCClient
client = AITBCClient(api_key="your_key")
# Get historical data
data = client.analytics.get_historical(
metric='transaction_count',
period='1d',
start='2025-01-01',
end='2025-12-28'
)
# Create chart
fig = go.Figure()
fig.add_trace(go.Scatter(
x=data.timestamps,
y=data.values,
mode='lines',
name='Transactions per Day'
))
fig.show()
```
### Real-time Monitoring
```javascript
const client = new AITBCClient({ apiKey: 'your_key' });
// Monitor network health
client.subscribe('blocks', (block) => {
const blockTime = calculateBlockTime(block);
updateBlockTimeMetric(blockTime);
if (blockTime > 10) {
alert('Block time is high!');
}
});
// Monitor marketplace activity
client.subscribe('marketplace_bids', (bid) => {
updateBidChart(bid);
checkForAnomalies(bid);
});
```
## Best Practices
1. **Caching**: Cache frequently accessed data
2. **Pagination**: Use pagination for large datasets
3. **Error Handling**: Implement proper error handling
4. **Rate Limiting**: Respect rate limits and implement backoff
5. **Security**: Keep API keys secure and use HTTPS
6. **Webhooks**: Verify webhook signatures
7. **Monitoring**: Monitor your API usage and performance
## Support
For integration support:
- Documentation: https://aitbc.bubuit.net/docs/
- API Reference: https://aitbc.bubuit.net/api/v1/docs
- Email: partners@aitbc.io
- Discord: https://discord.gg/aitbc
## Example Implementations
### Block Explorer
- GitHub: https://github.com/aitbc/explorer-example
- Demo: https://explorer.aitbc-example.com
### Analytics Platform
- GitHub: https://github.com/aitbc/analytics-example
- Demo: https://analytics.aitbc-example.com
### Mobile App
- GitHub: https://github.com/aitbc/mobile-example
- iOS: https://apps.apple.com/aitbc-wallet
- Android: https://play.google.com/aitbc-wallet
## Changelog
### v1.2.0 (2025-12-28)
- Added governance endpoints
- Improved WebSocket reliability
- New analytics metrics
### v1.1.0 (2025-12-15)
- Added bulk export API
- Webhook support
- Python SDK improvements
### v1.0.0 (2025-12-01)
- Initial release
- REST API v1
- WebSocket streams
- JavaScript SDK

128
docs/developer/integration/skills-framework.md
View File

@@ -1,128 +0,0 @@
# Cascade Skills Framework
## Overview
The Cascade Skills Framework provides a powerful way to automate complex, multi-step workflows in the AITBC project. Skills bundle together scripts, templates, documentation, and procedures that Cascade can intelligently invoke to execute tasks consistently.
## Skills Directory Structure
```
.windsurf/skills/
├── deploy-production/ # Production deployment workflow
│ ├── SKILL.md # Skill definition and documentation
│ ├── pre-deploy-checks.sh # Pre-deployment validation script
│ ├── environment-template.env # Production environment template
│ ├── rollback-steps.md # Emergency rollback procedures
│ └── health-check.py # Post-deployment health verification
│
└── blockchain-operations/ # Blockchain node management
├── SKILL.md # Skill definition and documentation
├── node-health.sh # Node health monitoring script
├── tx-tracer.py # Transaction debugging tool
├── mining-optimize.sh # GPU mining optimization script
├── sync-monitor.py # Real-time sync monitoring
└── network-diag.py # Network diagnostics tool
```
## Using Skills
### Automatic Invocation
Skills are automatically invoked when Cascade detects relevant keywords or context:
- "deploy production" → triggers deploy-production skill
- "check node status" → triggers blockchain-operations skill
- "debug transaction" → triggers blockchain-operations skill
- "optimize mining" → triggers blockchain-operations skill
### Manual Invocation
You can manually invoke skills by mentioning them directly:
- "Use the deploy-production skill"
- "Run blockchain-operations skill"
## Creating New Skills
1. Create a new directory under `.windsurf/skills/<skill-name>/`
2. Add a `SKILL.md` file with YAML frontmatter:
```yaml
---
name: skill-name
description: Brief description of the skill
version: 1.0.0
author: Cascade
tags: [tag1, tag2, tag3]
---
```
3. Add supporting files (scripts, templates, documentation)
4. Test the skill functionality
5. Commit to repository
## Skill Components
### Required
- **SKILL.md** - Main skill definition with frontmatter
### Optional (but recommended)
- Shell scripts for automation
- Python scripts for complex operations
- Configuration templates
- Documentation files
- Test scripts
## Best Practices
1. **Keep skills focused** on a specific domain or workflow
2. **Include comprehensive documentation** in SKILL.md
3. **Add error handling** to all scripts
4. **Use logging** for debugging and audit trails
5. **Include rollback procedures** for destructive operations
6. **Test thoroughly** before deploying
7. **Version your skills** using semantic versioning
## Example Skill: Deploy-Production
The deploy-production skill demonstrates best practices:
- Comprehensive pre-deployment checks
- Environment configuration template
- Detailed rollback procedures
- Post-deployment health verification
- Clear documentation and usage examples
## Integration with AITBC
Skills integrate seamlessly with AITBC components:
- Coordinator API interactions
- Blockchain node management
- Mining operations
- Exchange and marketplace functions
- Wallet daemon operations
## Recent Success Stories
### Ollama GPU Inference Testing (2026-01-24)
Using the blockchain-operations skill with Ollama testing enhancements:
- Executed end-to-end GPU inference workflow testing
- Fixed coordinator API bug (missing _coerce_float function)
- Verified complete job lifecycle from submission to receipt generation
- Documented comprehensive testing scenarios and automation scripts
- Achieved successful job completion with proper payment calculations
### Service Maintenance (2026-01-21)
Using the blockchain-operations skill framework:
- Successfully diagnosed and fixed all failing AITBC services
- Resolved duplicate service conflicts
- Implemented SSH access for automated management
- Restored full functionality to 7 core services
### Production Deployment (2025-01-19)
Using the deploy-production skill:
- Automated deployment validation
- Environment configuration management
- Health check automation
- Rollback procedure documentation
## Future Enhancements
- Skill marketplace for sharing community skills
- Skill dependencies and composition
- Skill versioning and updates
- Skill testing framework
- Skill analytics and usage tracking

Some files were not shown because too many files have changed in this diff Show More