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

```

Browse Source 
chore: remove obsolete files and add Solidity build artifacts to .gitignore

- Add ignore patterns for Solidity build artifacts (typechain-types, artifacts, cache)
- Remove unused exchange mock API server (api/exchange_mock_api.py)
- Remove obsolete client-web README placeholder
- Remove deprecated marketplace-ui HTML implementation
```
This commit is contained in:
oib
2026-01-24 15:46:23 +01:00
parent 9b9c5beb23
commit 55ced77928
195 changed files with 951 additions and 30090 deletions
Download Patch File Download Diff File Expand all files Collapse all files

55
docs/reference/components/blockchain_node.md Normal file
View File

@@ -0,0 +1,55 @@
# Blockchain Node – Task Breakdown
## Status (2025-12-22)
- **Stage 1**: ✅ **DEPLOYED** - Blockchain Node successfully deployed on host with RPC API accessible
- SQLModel-based blockchain with PoA consensus implemented
- RPC API running on port 9080 (proxied via /rpc/)
- Mock coordinator on port 8090 (proxied via /v1/)
- Devnet scripts and observability hooks implemented
- Note: SQLModel/SQLAlchemy compatibility issues remain (low priority)
## Stage 1 (MVP) - COMPLETED
- **Project Scaffolding**
- ✅ Create `apps/blockchain-node/src/` module layout (`types.py`, `state.py`, `blocks.py`, `mempool.py`, `consensus.py`, `rpc.py`, `p2p.py`, `receipts.py`, `settings.py`).
- ✅ Add `requirements.txt` with FastAPI, SQLModel, websockets, orjson, python-dotenv.
- ✅ Provide `.env.example` with `CHAIN_ID`, `DB_PATH`, bind addresses, proposer key.
- **State & Persistence**
- ✅ Implement SQLModel tables for blocks, transactions, accounts, receipts, peers, params.
- ✅ Set up database initialization and genesis loading.
- ✅ Provide migration or reset script under `scripts/`.
- **RPC Layer**
- ✅ Build FastAPI app exposing `/rpc/*` endpoints (sendTx, getTx, getBlock, getHead, getBalance, submitReceipt, metrics).
- ✅ Implement admin endpoints for devnet (`mintFaucet`, `paramSet`, `peers/add`).
- **Consensus & Block Production**
- ✅ Implement PoA proposer loop producing blocks at fixed interval.
- ✅ Integrate mempool selection, receipt validation, and block broadcasting.
- ✅ Add basic P2P gossip (websocket) for blocks/txs.
- **Receipts & Minting**
- ✅ Wire `receipts.py` to coordinator attestation mock.
- ✅ Mint tokens to miners based on compute_units with configurable ratios.
- **Devnet Tooling**
- ✅ Provide `scripts/devnet_up.sh` launching bootstrap node and mocks.
- ✅ Document curl commands for faucet, transfer, receipt submission.
## Production Deployment Details
- **Host**: Running on host machine (GPU access required)
- **Service**: systemd services for blockchain-node, blockchain-rpc, mock-coordinator
- **Ports**: 9080 (RPC), 8090 (Mock Coordinator)
- **Proxy**: nginx routes /rpc/ and /v1/ to host services
- **Access**: https://aitbc.bubuit.net/rpc/ for blockchain RPC
- **Database**: SQLite with SQLModel ORM
- **Issues**: SQLModel/SQLAlchemy compatibility (low priority)
## Stage 2+ - IN PROGRESS
- 🔄 Upgrade consensus to compute-backed proof (CBP) with work score weighting.
- 🔄 Introduce staking/slashing, replace SQLite with PostgreSQL, add snapshots/fast sync.
- 🔄 Implement light client support and metrics dashboard.

84
docs/reference/components/coordinator_api.md Normal file
View File

@@ -0,0 +1,84 @@
# Coordinator API – Task Breakdown
## Status (2026-01-24)
- **Stage 1 delivery**: ✅ **DEPLOYED** - Coordinator API deployed in production behind https://aitbc.bubuit.net/api/
- FastAPI service running in Incus container on port 8000
- Health endpoint operational: `/api/v1/health` returns `{"status":"ok","env":"dev"}`
- nginx proxy configured at `/api/` (so `/api/v1/*` routes to the container service)
- Explorer API available via nginx at `/api/explorer/*` (backend: `/v1/explorer/*`)
- Users API available via `/api/v1/users/*` (compat: `/api/users/*` for Exchange)
- **Stage 2 delivery**: ✅ **DEPLOYED** - All import and syntax errors fixed (2025-12-28)
- Fixed SQLModel import issues across the codebase
- Resolved missing module dependencies
- Database initialization working correctly with all tables created
- **Recent Bug Fixes (2026-01-24)**:
- ✅ Fixed missing `_coerce_float()` helper function in receipt service causing 500 errors
- ✅ Receipt generation now works correctly for all job completions
- ✅ Deployed fix to production incus container via SSH
- ✅ Result submission endpoint returns 200 OK with valid receipts
- **Testing & tooling**: Pytest suites cover job scheduling, miner flows, and receipt verification; the shared CI script `scripts/ci/run_python_tests.sh` executes these tests in GitHub Actions.
- **Documentation**: `docs/run.md` and `apps/coordinator-api/README.md` describe configuration for `RECEIPT_SIGNING_KEY_HEX` and `RECEIPT_ATTESTATION_KEY_HEX` plus the receipt history API.
- **Service APIs**: Implemented specific service endpoints for common GPU workloads (Whisper, Stable Diffusion, LLM inference, FFmpeg, Blender) with typed schemas and validation.
- **Service Registry**: Created dynamic service registry framework supporting 30+ GPU services across 6 categories (AI/ML, Media Processing, Scientific Computing, Data Analytics, Gaming, Development Tools).
## Stage 1 (MVP) - COMPLETED
- **Project Setup**
- ✅ Initialize FastAPI app under `apps/coordinator-api/src/app/` with `main.py`, `config.py`, `deps.py`.
- ✅ Add `.env.example` covering host/port, database URL, API key lists, rate limit configuration.
- ✅ Create `pyproject.toml` listing FastAPI, uvicorn, pydantic, SQL driver, httpx, redis (optional).
- **Models & Persistence**
- ✅ Design Pydantic schemas for jobs, miners, constraints, state transitions (`models.py`).
- ✅ Implement DB layer (`db.py`) using SQLite (or Postgres) with tables for jobs, miners, sessions, worker sessions.
- ✅ Provide migrations or schema creation script.
- **Business Logic**
- ✅ Implement `queue.py` and `matching.py` for job scheduling.
- ✅ Create state machine utilities (`states.py`) for job transitions.
- ✅ Add settlement stubs in `settlement.py` for future token accounting.
- **Routers**
- ✅ Build `/v1/jobs` endpoints (submit, get status, get result, cancel) with idempotency support.
- ✅ Build `/v1/miners` endpoints (register, heartbeat, poll, result, fail, drain).
- ✅ Build `/v1/admin` endpoints (stats, job listing, miner listing) with admin auth.
- ✅ Build `/v1/services` endpoints for specific GPU workloads:
- `/v1/services/whisper/transcribe` - Audio transcription
- `/v1/services/stable-diffusion/generate` - Image generation
- `/v1/services/llm/inference` - Text generation
- `/v1/services/ffmpeg/transcode` - Video transcoding
- `/v1/services/blender/render` - 3D rendering
- ✅ Build `/v1/registry` endpoints for dynamic service management:
- `/v1/registry/services` - List all available services
- `/v1/registry/services/{id}` - Get service definition
- `/v1/registry/services/{id}/schema` - Get JSON schema
- `/v1/registry/services/{id}/requirements` - Get hardware requirements
- Optionally add WebSocket endpoints under `ws/` for streaming updates.
- **Receipts & Attestations**
- ✅ Persist signed receipts (latest + history), expose `/v1/jobs/{job_id}/receipt(s)` endpoints, and attach optional coordinator attestations when `RECEIPT_ATTESTATION_KEY_HEX` is configured.
- **Auth & Rate Limiting**
- ✅ Implement dependencies in `deps.py` to validate API keys and optional HMAC signatures.
- ✅ Add rate limiting (e.g., `slowapi`) per key.
- **Testing & Examples**
- ✅ Create `.http` files or pytest suites for client/miner flows.
- ✅ Document curl examples and quickstart instructions in `apps/coordinator-api/README.md`.
## Production Deployment Details
- **Container**: Incus container 'aitbc' at `/opt/coordinator-api/`
- **Service**: systemd service `coordinator-api.service` enabled and running
- **Port**: 8000 (internal), proxied via nginx at `/api/` (including `/api/v1/*`)
- **Dependencies**: Virtual environment with FastAPI, uvicorn, pydantic installed
- **Access**: https://aitbc.bubuit.net/api/v1/health for health check
- **Note**: Explorer + Users routes are enabled in production (see `/api/explorer/*` and `/api/v1/users/*`).
## Stage 2+ - IN PROGRESS
- 🔄 Integrate with blockchain receipts for settlement triggers.
- 🔄 Add Redis-backed queues for scalability.
- 🔄 Implement metrics and tracing (Prometheus/OpenTelemetry).
- 🔄 Support multi-region coordinators with pool hub integration.

59
docs/reference/components/explorer_web.md Normal file
View File

@@ -0,0 +1,59 @@
# Explorer Web – Task Breakdown
## Status (2025-12-30)
- **Stage 1**: ✅ **DEPLOYED** - Explorer Web successfully deployed in production at https://aitbc.bubuit.net/explorer/
- All pages implemented with mock data integration, responsive design, and live data toggle
- Genesis block (height 0) properly displayed
- Mock/live data toggle functional
- nginx proxy configured at `/explorer/` route
- **Stage 2**: ✅ Completed - Live mode validated against coordinator endpoints with Playwright e2e tests.
- **Stage 3**: ✅ Completed - JavaScript error fixes deployed (2025-12-30)
- Fixed "can't access property 'length', t is undefined" error on page load
- Updated fetchMock function to return correct data structure
- Added defensive null checks across all page init functions
## Stage 1 (MVP) - COMPLETED
- **Structure & Assets**
- ✅ Populate `apps/explorer-web/public/` with `index.html` and all page scaffolds.
- ✅ Add base stylesheets (`public/css/base.css`, `public/css/layout.css`, `public/css/theme.css`).
- ✅ Include logo and icon assets under `public/assets/`.
- **TypeScript Modules**
- ✅ Provide configuration and data helpers (`src/config.ts`, `src/lib/mockData.ts`, `src/lib/models.ts`).
- ✅ Add shared store/utilities module for cross-page state.
- ✅ Implement core page controllers and components under `src/pages/` and `src/components/` (overview, blocks, transactions, addresses, receipts, header/footer, data mode toggle).
- **Mock Data**
- ✅ Provide mock JSON fixtures under `public/mock/`.
- ✅ Enable mock/live mode toggle via `getDataMode()` and `<data-mode-toggle>` components.
- **Interaction & UX**
- ✅ Implement search box detection for block numbers, hashes, and addresses.
- ✅ Add pagination or infinite scroll for block and transaction tables.
- ✅ Expand responsive polish beyond overview cards (tablet/mobile grid, table hover states).
- **Live Mode Integration**
- ✅ Hit live coordinator endpoints via nginx (`/api/explorer/blocks`, `/api/explorer/transactions`, `/api/explorer/addresses`, `/api/explorer/receipts`) via `getDataMode() === "live"`.
- ✅ Add fallbacks + error surfacing for partial/failed live responses.
- ✅ Implement Playwright e2e tests for live mode functionality.
- **Documentation**
- ✅ Update `apps/explorer-web/README.md` with build/run instructions and API assumptions.
- ✅ Capture coordinator API + CORS considerations in README deployment notes.
## Production Deployment Details
- **Container**: Incus container 'aitbc' at `/var/www/aitbc.bubuit.net/explorer/`
- **Build**: Vite + TypeScript build process
- **Port**: Static files served by nginx
- **Access**: https://aitbc.bubuit.net/explorer/
- **Features**: Genesis block display, mock/live toggle, responsive design
- **Mock Data**: Blocks.json with proper `{items: [...]}` structure
## Stage 2+ - IN PROGRESS
- 🔄 Integrate WebSocket streams for live head and mempool updates.
- 🔄 Add token balances and ABI decoding when supported by blockchain node.
- 🔄 Provide export-to-CSV functionality and light/dark theme toggle.

60
docs/reference/components/marketplace_web.md Normal file
View File

@@ -0,0 +1,60 @@
# Marketplace Web – Task Breakdown
## Status (2025-12-30)
- **Stage 1**: ✅ **DEPLOYED** - Marketplace Web successfully deployed in production at https://aitbc.bubuit.net/marketplace/
- Vite + TypeScript project with API layer, auth scaffolding, and mock/live data toggle
- Offer list, bid form, stats cards implemented
- Mock data fixtures with API abstraction
- nginx proxy configured at `/marketplace/` route
- **Stage 2**: ✅ Completed - Connected to coordinator endpoints with feature flags for live mode rollout.
## Stage 1 (MVP) - COMPLETED
- **Project Initialization**
- ✅ Scaffold Vite + TypeScript project under `apps/marketplace-web/`.
- ✅ Define `package.json`, `tsconfig.json`, `vite.config.ts`, and `.env.example` with `VITE_API_BASE`, `VITE_FEATURE_WALLET`.
- ✅ Configure ESLint/Prettier presets.
- **API Layer**
- ✅ Implement `src/api/http.ts` for base fetch wrapper with mock vs real toggle.
- ✅ Create `src/api/marketplace.ts` with typed functions for offers, bids, stats, wallet.
- ✅ Provide mock JSON files under `public/mock/` for development.
- **State Management**
- ✅ Implement lightweight store in `src/lib/api.ts` with pub/sub and caching.
- ✅ Define shared TypeScript interfaces in `src/lib/types.ts`.
- **Views & Components**
- ✅ Build router in `src/main.ts` and bootstrap application.
- ✅ Implement views: offer list, bid form, stats cards.
- ✅ Create components with validation and responsive design.
- ✅ Add filters (region, hardware, price, latency).
- **Styling & UX**
- ✅ Create CSS system implementing design and responsive layout.
- ✅ Ensure accessibility: semantic HTML, focus states, keyboard navigation.
- ✅ Add toast notifications and form validation messaging.
- **Authentication**
- ✅ Implement auth/session scaffolding in `src/lib/auth.ts`.
- ✅ Add feature flags for marketplace actions.
- **Documentation**
- ✅ Update `apps/marketplace-web/README.md` with instructions for dev/build, mock API usage, and configuration.
## Production Deployment Details
- **Container**: Incus container 'aitbc' at `/var/www/aitbc.bubuit.net/marketplace/`
- **Build**: Vite + TypeScript build process
- **Port**: Static files served by nginx
- **Access**: https://aitbc.bubuit.net/marketplace/
- **Features**: Offer list, bid form, stats cards, responsive design
- **Mock Data**: JSON fixtures in `public/mock/` directory
## Stage 2+ - IN PROGRESS
- 🔄 Integrate real coordinator/pool hub endpoints and authentication.
- 🔄 Add WebSocket updates for live offer/pricing changes.
- 🔄 Implement i18n support with dictionaries in `public/i18n/`.
- 🔄 Add Vitest test suite for utilities and API modules.

42
docs/reference/components/miner.md Normal file
View File

@@ -0,0 +1,42 @@
# Miner (Host Ops) – Task Breakdown
## Status (2025-12-22)
- **Stage 1**: ✅ **IMPLEMENTED** - Infrastructure scripts and runtime behavior validated through `apps/miner-node/` control loop; host installer/systemd automation implemented.
## Stage 1 (MVP) - COMPLETED
- **Installer & Scripts**
- ✅ Finalize `/root/scripts/aitbc-miner/install_miner.sh` to install dependencies, create venv, deploy systemd unit.
- ✅ Implement `/root/scripts/aitbc-miner/miner.sh` main loop (poll, run job, submit proof) as per bootstrap spec.
- ✅ Ensure scripts detect GPU availability and switch between CUDA/CPU modes.
- **Configuration**
- ✅ Define `/etc/aitbc/miner.conf` with environment-style keys (COORD_URL, WALLET_ADDR, API_KEY, MINER_ID, WORK_DIR, intervals).
- ✅ Document configuration editing steps and permission requirements.
- **Systemd & Logging**
- ✅ Install `aitbc-miner.service` unit with restart policy, log path, and hardening flags.
- ✅ Provide optional logrotate config under `configs/systemd/` or `configs/security/`.
- **Mock Coordinator Integration**
- ✅ Supply FastAPI mock coordinator (`mock_coordinator.py`) for local smoke testing.
- ✅ Document curl or httpie commands to validate miner registration and proof submission.
- **Documentation**
- ✅ Update `apps/miner-node/README.md` (ops section) and create runbooks under `docs/runbooks/` once available.
- ✅ Add troubleshooting steps (GPU check, heartbeat failures, log locations).
## Implementation Status
- **Location**: `/root/scripts/aitbc-miner/` and `apps/miner-node/`
- **Features**: Installer scripts, systemd service, configuration management
- **Runtime**: Poll, execute jobs, submit proofs with GPU/CPU detection
- **Integration**: Mock coordinator for local testing
- **Deployment**: Ready for host deployment with systemd automation
## Stage 2+ - IN PROGRESS
- 🔄 Harden systemd service with `ProtectSystem`, `ProtectHome`, `NoNewPrivileges` and consider non-root user.
- 🔄 Add metrics integration (Prometheus exporters, GPU telemetry).
- 🔄 Automate zero-downtime updates with rolling restart instructions.

80
docs/reference/components/miner_node.md Normal file
View File

@@ -0,0 +1,80 @@
# Miner Node – Task Breakdown
## Status (2026-01-24)
- **Stage 1**: ✅ **IMPLEMENTED** - Core miner package (`apps/miner-node/src/aitbc_miner/`) provides registration, heartbeat, polling, and result submission flows with CLI/Python runners. Basic telemetry and tests exist.
- **Host GPU Miner**: ✅ **DEPLOYED** - Real GPU miner (`gpu_miner_host.py`) running on host with RTX 4060 Ti, Ollama integration, and systemd service. Successfully processes jobs and generates receipts with payment amounts.
## Recent Updates (2026-01-24)
### Host GPU Miner Deployment
- ✅ Deployed real GPU miner on host with NVIDIA RTX 4060 Ti (16GB)
- ✅ Integrated Ollama for LLM inference across 13+ models
- ✅ Configured systemd service (`aitbc-host-gpu-miner.service`)
- ✅ Fixed miner ID configuration (REDACTED_MINER_KEY)
- ✅ Enhanced logging with flush handlers for systemd journal visibility
- ✅ Verified end-to-end workflow: job polling → Ollama inference → result submission → receipt generation
### Performance Metrics
- Processing time: ~11-25 seconds per inference job
- GPU utilization: 7-20% during processing
- Token processing: 200+ tokens per job
- Payment calculation: 11.846 gpu_seconds @ 0.02 AITBC = 0.23692 AITBC
- Receipt signature: Ed25519 cryptographic signing
### Integration Points
- Coordinator API: http://127.0.0.1:18000 (via Incus proxy)
- Miner ID: REDACTED_MINER_KEY
- Heartbeat interval: 15 seconds
- Job polling: 3-second intervals
- Result submission: JSON with metrics and execution details
## Stage 1 (MVP) - COMPLETED
- **Package Skeleton**
- ✅ Create Python package `aitbc_miner` with modules: `main.py`, `config.py`, `agent.py`, `probe.py`, `queue.py`, `runners/cli.py`, `runners/python.py`, `util/{fs.py, limits.py, log.py}`.
- ✅ Add `pyproject.toml` or `requirements.txt` listing httpx, pydantic, pyyaml, psutil, uvloop (optional).
- **Configuration & Loading**
- ✅ Implement YAML config parser supporting environment overrides (auth token, coordinator URL, heartbeat intervals, resource limits).
- ✅ Provide `.env.example` or sample `config.yaml` in `apps/miner-node/`.
- **Capability Probe**
- ✅ Collect CPU cores, memory, disk space, GPU info (nvidia-smi), runner availability.
- ✅ Send capability payload to coordinator upon registration.
- **Agent Control Loop**
- ✅ Implement async tasks for registration, heartbeat with backoff, job pulling/acking, job execution, result upload.
- ✅ Manage workspace directories under `/var/lib/aitbc/miner/jobs/<job-id>/` with state persistence for crash recovery.
- **Runners**
- ✅ CLI runner validating commands against allowlist definitions (`/etc/aitbc/miner/allowlist.d/`).
- ✅ Python runner importing trusted modules from configured paths.
- ✅ Enforce resource limits (nice, ionice, ulimit) and capture logs/metrics.
- **Result Handling**
- ✅ Implement artifact upload via multipart requests and finalize job state with coordinator.
- ✅ Support failure reporting with detailed error codes (E_DENY, E_OOM, E_TIMEOUT, etc.).
- **Telemetry & Health**
- ✅ Emit structured JSON logs; optionally expose `/healthz` endpoint.
- ✅ Track metrics: running jobs, queue length, VRAM free, CPU load.
- **Testing**
- ✅ Provide unit tests for config loader, allowlist validator, capability probe.
- ✅ Add integration test hitting `mock_coordinator.py` from bootstrap docs.
## Implementation Status
- **Location**: `apps/miner-node/src/aitbc_miner/`
- **Features**: Registration, heartbeat, job polling, result submission
- **Runners**: CLI and Python runners with allowlist validation
- **Resource Management**: CPU, memory, disk, GPU monitoring
- **Deployment**: Ready for deployment with coordinator integration
## Stage 2+ - IN PROGRESS
- 🔄 Implement multi-slot scheduling (GPU vs CPU) with cgroup integration.
- 🔄 Add Redis-backed queue for job retries and persistent metrics export.
- 🔄 Support secure secret handling (tmpfs, hardware tokens) and network egress policies.

64
docs/reference/components/pool_hub.md Normal file
View File

@@ -0,0 +1,64 @@
# Pool Hub – Task Breakdown
## Status (2025-12-22)
- **Stage 1**: ✅ **IMPLEMENTED** - FastAPI service implemented with miner registry, scoring engine, and Redis/PostgreSQL backing stores. Service configuration API and UI added for GPU providers to select which services to offer.
- **Service Configuration**: ✅ Implemented dynamic service configuration allowing miners to enable/disable specific GPU services, set pricing, and define capabilities.
## Stage 1 (MVP) - COMPLETED
- **Project Setup**
- ✅ Initialize FastAPI project under `apps/pool-hub/src/app/` with `main.py`, `deps.py`, `registry.py`, `scoring.py`, and router modules (`miners.py`, `match.py`, `admin.py`, `health.py`).
- ✅ Add `.env.example` defining bind host/port, DB DSN, Redis URL, coordinator shared secret, session TTLs.
- ✅ Configure dependencies: FastAPI, uvicorn, pydantic-settings, SQLAlchemy/SQLModel, psycopg (or sqlite), redis, prometheus-client.
- **Data Layer**
- ✅ Implement PostgreSQL schema for miners, miner status, feedback, price overrides as outlined in bootstrap doc.
- ✅ Provide migrations or DDL scripts under `apps/pool-hub/migrations/`.
- **Registry & Scoring**
- ✅ Build in-memory registry (with optional Redis backing) storing miner capabilities, health, and pricing.
- ✅ Implement scoring function weighing capability fit, price, latency, trust, and load.
- **API Endpoints**
- ✅ `POST /v1/miners/register` exchanging API key for session token, storing capability profile.
- ✅ `POST /v1/miners/update` and `WS /v1/miners/heartbeat` for status updates.
- ✅ `POST /v1/match` returning top K candidates for coordinator requests with explain string.
- ✅ `POST /v1/feedback` to adjust trust and metrics.
- ✅ `GET /v1/health` and `GET /v1/metrics` for observability.
- ✅ Service Configuration endpoints:
- `GET /v1/services/` - List all service configurations for miner
- `GET /v1/services/{type}` - Get specific service configuration
- `POST /v1/services/{type}` - Create/update service configuration
- `PATCH /v1/services/{type}` - Partial update
- `DELETE /v1/services/{type}` - Delete configuration
- `GET /v1/services/templates/{type}` - Get default templates
- `POST /v1/services/validate/{type}` - Validate against hardware
- ✅ UI endpoint:
- `GET /services` - Service configuration web interface
- ✅ Optional admin listing endpoint guarded by shared secret.
- **Rate Limiting & Security**
- ✅ Enforce coordinator shared secret on `/v1/match`.
- ✅ Add rate limits to registration and match endpoints.
- ✅ Consider IP allowlist and TLS termination guidance.
- **Testing & Tooling**
- ✅ Unit tests for scoring module, registry updates, and feedback adjustments.
- ✅ Integration test simulating miners registering, updating, and matching.
- ✅ Provide CLI scripts to seed mock miners for development.
## Implementation Status
- **Location**: `apps/pool-hub/src/app/`
- **Features**: Miner registry, scoring engine, service configuration, UI
- **Database**: PostgreSQL with Redis backing
- **API**: REST endpoints with WebSocket heartbeat support
- **Security**: Coordinator shared secret, rate limiting
- **Deployment**: Ready for deployment with systemd service
## Stage 2+ - IN PROGRESS
- 🔄 Introduce WebSocket streaming of match suggestions and commands.
- 🔄 Add redis-based lease management, multi-region routing, and attested capability manifests.
- 🔄 Integrate marketplace pricing data and blockchain settlement hooks.

258
docs/reference/components/trade_exchange.md Normal file
View File

@@ -0,0 +1,258 @@
# Trade Exchange Documentation
## Overview
The AITBC Trade Exchange is a web platform that allows users to buy AITBC tokens using Bitcoin. It features a modern, responsive interface with user authentication, wallet management, and real-time trading capabilities.
## Features
### Bitcoin Wallet Integration
- **Payment Gateway**: Buy AITBC tokens with Bitcoin
- **QR Code Support**: Mobile-friendly payment QR codes
- **Real-time Monitoring**: Automatic payment confirmation tracking
- **Exchange Rate**: 1 BTC = 100,000 AITBC (configurable)
### User Management
- **Wallet-based Authentication**: No passwords required
- **Individual Accounts**: Each user has a unique wallet and balance
- **Session Security**: 24-hour token-based sessions
- **Profile Management**: View transaction history and account details
### Trading Interface
- **Live Prices**: Real-time exchange rate updates
- **Payment Tracking**: Monitor Bitcoin payments and AITBC credits
- **Transaction History**: Complete record of all trades
- **Mobile Responsive**: Works on all devices
## Getting Started
### 1. Access the Exchange
Visit: https://aitbc.bubuit.net/Exchange/
### 2. Connect Your Wallet
1. Click "Connect Wallet" in the navigation
2. A unique wallet address is generated
3. Your user account is created automatically
### 3. Buy AITBC Tokens
1. Navigate to the Trade section
2. Enter the amount of AITBC you want to buy
3. The Bitcoin equivalent is calculated
4. Click "Create Payment Request"
5. Send Bitcoin to the provided address
6. Wait for confirmation (1 confirmation needed)
7. AITBC tokens are credited to your wallet
## API Reference
### User Management
#### Login/Register
```http
POST /api/users/login
{
"wallet_address": "aitbc1abc123..."
}
```
Canonical route (same backend, without compatibility proxy):
```http
POST /api/v1/users/login
{
"wallet_address": "aitbc1abc123..."
}
```
#### Get User Profile
```http
GET /api/users/me
Headers: X-Session-Token: <token>
```
Canonical route:
```http
GET /api/v1/users/users/me
Headers: X-Session-Token: <token>
```
#### Get User Balance
```http
GET /api/users/{user_id}/balance
Headers: X-Session-Token: <token>
```
Canonical route:
```http
GET /api/v1/users/users/{user_id}/balance
Headers: X-Session-Token: <token>
```
#### Logout
```http
POST /api/users/logout
Headers: X-Session-Token: <token>
```
Canonical route:
```http
POST /api/v1/users/logout
Headers: X-Session-Token: <token>
```
### Exchange Operations
#### Create Payment Request
```http
POST /api/exchange/create-payment
{
"user_id": "uuid",
"aitbc_amount": 1000,
"btc_amount": 0.01
}
Headers: X-Session-Token: <token>
```
#### Check Payment Status
```http
GET /api/exchange/payment-status/{payment_id}
```
#### Get Exchange Rates
```http
GET /api/exchange/rates
```
## Configuration
### Bitcoin Settings
- **Network**: Bitcoin Testnet (for demo)
- **Confirmations Required**: 1
- **Payment Timeout**: 1 hour
- **Main Address**: tb1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh
### Exchange Settings
- **Rate**: 1 BTC = 100,000 AITBC
- **Fee**: 0.5% transaction fee
- **Min Payment**: 0.0001 BTC
- **Max Payment**: 10 BTC
## Security
### Authentication
- **Session Tokens**: SHA-256 hashed tokens
- **Expiry**: 24 hours automatic timeout
- **Storage**: Server-side session management
### Privacy
- **User Isolation**: Each user has private data
- **No Tracking**: No personal data collected
- **GDPR Compliant**: Minimal data retention
## Development
### Frontend Stack
- **HTML5**: Semantic markup
- **CSS3**: TailwindCSS for styling
- **JavaScript**: Vanilla JS with Axios
- **Lucide Icons**: Modern icon library
### Backend Stack
- **FastAPI**: Python web framework
- **SQLModel**: Database ORM
- **SQLite**: Development database
- **Pydantic**: Data validation
### File Structure
```
apps/trade-exchange/
├── index.html # Main application
├── bitcoin-wallet.py # Bitcoin integration
└── README.md # Setup instructions
apps/coordinator-api/src/app/
├── routers/
│ ├── users.py # User management
│ └── exchange.py # Exchange operations
├── domain/
│ └── user.py # User models
└── schemas.py # API schemas
```
## Deployment
### Production
- **URL**: https://aitbc.bubuit.net/Exchange/
- **SSL**: Fully configured
- **CDN**: Nginx static serving
- **API**: /api/v1/* endpoints
### Environment Variables
```bash
BITCOIN_TESTNET=true
BITCOIN_ADDRESS=tb1q...
BTC_TO_AITBC_RATE=100000
MIN_CONFIRMATIONS=1
```
## Testing
### Testnet Bitcoin
Get free testnet Bitcoin from:
- https://testnet-faucet.mempool.co/
- https://coinfaucet.eu/en/btc-testnet/
### Demo Mode
- No real Bitcoin required
- Simulated payments for testing
- Auto-generated wallet addresses
## Troubleshooting
### Common Issues
**Payment Not Showing**
- Check transaction has 1 confirmation
- Verify correct amount sent
- Refresh the page
**Can't Connect Wallet**
- Check JavaScript is enabled
- Clear browser cache
- Try a different browser
**Balance Incorrect**
- Wait for blockchain sync
- Check transaction history
- Contact support
### Logs
Check application logs:
```bash
journalctl -u aitbc-coordinator -f
```
## Future Enhancements
### Planned Features
- [ ] MetaMask wallet support
- [ ] Advanced trading charts
- [ ] Limit orders
- [ ] Mobile app
- [ ] Multi-currency support
### Technical Improvements
- [ ] Redis session storage
- [ ] PostgreSQL database
- [ ] Microservices architecture
- [ ] WebSocket real-time updates
## Support
For help or questions:
- **Documentation**: https://aitbc.bubuit.net/docs/
- **API Docs**: https://aitbc.bubuit.net/api/docs
- **Admin Panel**: https://aitbc.bubuit.net/admin/stats
## License
This project is part of the AITBC ecosystem. See the main repository for license information.

53
docs/reference/components/wallet_daemon.md Normal file
View File

@@ -0,0 +1,53 @@
# Wallet Daemon – Task Breakdown
## Status (2025-12-22)
- **Stage 1**: ✅ **DEPLOYED** - Wallet Daemon successfully deployed in production at https://aitbc.bubuit.net/wallet/
- FastAPI application running in Incus container on port 8002
- Encrypted keystore with Argon2id + XChaCha20-Poly1305 implemented
- REST and JSON-RPC APIs operational
- Mock ledger with SQLite backend functional
- Receipt verification using aitbc_sdk integrated
- nginx proxy configured at /wallet/ route
## Stage 1 (MVP) - COMPLETED
- **Project Setup**
- ✅ Initialize FastAPI application under `apps/wallet-daemon/src/app/` with `main.py`, `settings.py`, `api_rest.py`, `api_jsonrpc.py`.
- ✅ Create crypto and keystore modules implementing Argon2id key derivation and XChaCha20-Poly1305 encryption.
- ✅ Add dependencies: FastAPI, uvicorn, argon2-cffi, pynacl, aitbc-sdk, aitbc-crypto, pydantic-settings.
- **Keystore & Security**
- ✅ Implement encrypted wallet file format storing metadata, salt, nonce, ciphertext.
- ✅ Provide REST endpoints to create/import wallets, unlock/lock, derive accounts.
- ✅ Enforce unlock TTL and in-memory zeroization of sensitive data.
- **REST & JSON-RPC APIs**
- ✅ Implement REST routes: wallet lifecycle, account derivation, signing (message/tx/receipt), mock ledger endpoints.
- ✅ Mirror functionality via JSON-RPC under `/rpc`.
- ✅ Authentication token header enforcement and rate limits on signing operations.
- **Mock Ledger**
- ✅ Implement SQLite-backed ledger with balances and transfers for local testing.
- ✅ Provide REST endpoints to query balances and submit transfers.
- **Documentation & Examples**
- ✅ Update deployment documentation with systemd service and nginx proxy configuration.
- ✅ Document production endpoints and API access via https://aitbc.bubuit.net/wallet/
- **Receipts**
- ✅ Integrate `ReceiptVerifierService` consuming `CoordinatorReceiptClient` to fetch and validate receipts (miner + coordinator signatures).
## Production Deployment Details
- **Container**: Incus container 'aitbc' at `/opt/wallet-daemon/`
- **Service**: systemd service `wallet-daemon.service` enabled and running
- **Port**: 8002 (internal), proxied via nginx at `/wallet/`
- **Dependencies**: Virtual environment with all required packages installed
- **Access**: https://aitbc.bubuit.net/wallet/docs for API documentation
## Stage 2+ - IN PROGRESS
- Add ChainAdapter interface targeting real blockchain node RPC.
- 🔄 Implement mock adapter first, followed by AITBC node adapter.
- Support hardware-backed signing (YubiKey/PKCS#11) and multi-curve support gating.
- Introduce webhook retry/backoff logic and structured logging with request IDs.

270
docs/reference/components/zk-applications.md Normal file
View File

@@ -0,0 +1,270 @@
# Zero-Knowledge Applications in AITBC
This document describes the Zero-Knowledge (ZK) proof capabilities implemented in the AITBC platform.
## Overview
AITBC now supports privacy-preserving operations through ZK-SNARKs, allowing users to prove computations, membership, and other properties without revealing sensitive information.
## Available ZK Features
### 1. Identity Commitments
Create privacy-preserving identity commitments that allow you to prove you're a valid user without revealing your identity.
**Endpoint**: `POST /api/zk/identity/commit`
**Request**:
```json
{
"salt": "optional_random_string"
}
```
**Response**:
```json
{
"commitment": "hash_of_identity_and_salt",
"salt": "used_salt",
"user_id": "user_identifier",
"created_at": "2025-12-28T17:50:00Z"
}
```
### 2. Stealth Addresses
Generate one-time payment addresses for enhanced privacy in transactions.
**Endpoint**: `POST /api/zk/stealth/address`
**Parameters**:
- `recipient_public_key` (query): The recipient's public key
**Response**:
```json
{
"stealth_address": "0x27b224d39bb988620a1447eb4bce6fc629e15331",
"shared_secret_hash": "b9919ff990cd8793aa587cf5fd800efb997b6dcd...",
"ephemeral_key": "ca8acd0ae4a9372cdaeef7eb3ac7eb10",
"view_key": "0x5f7de2cc364f7c8d64ce1051c97a1ba6028f83d9"
}
```
### 3. Private Receipt Attestation
Create receipts that prove computation occurred without revealing the actual computation details.
**Endpoint**: `POST /api/zk/receipt/attest`
**Parameters**:
- `job_id` (query): Identifier of the computation job
- `user_address` (query): Address of the user requesting computation
- `computation_result` (query): Hash of the computation result
- `privacy_level` (query): "basic", "medium", or "maximum"
**Response**:
```json
{
"job_id": "job_123",
"user_address": "0xabcdef",
"commitment": "a6a8598788c066115dcc8ca35032dc60b89f2e138...",
"privacy_level": "basic",
"timestamp": "2025-12-28T17:51:26.758953",
"verified": true
}
```
### 4. Group Membership Proofs
Prove membership in a group (miners, clients, developers) without revealing your identity.
**Endpoint**: `POST /api/zk/membership/verify`
**Request**:
```json
{
"group_id": "miners",
"nullifier": "unique_64_char_string",
"proof": "zk_snark_proof_string"
}
```
### 5. Private Bidding
Submit bids to marketplace auctions without revealing the bid amount.
**Endpoint**: `POST /api/zk/marketplace/private-bid`
**Request**:
```json
{
"auction_id": "auction_123",
"bid_commitment": "hash_of_bid_and_salt",
"proof": "proof_that_bid_is_in_valid_range"
}
```
### 6. Computation Proofs
Verify that AI computations were performed correctly without revealing the inputs.
**Endpoint**: `POST /api/zk/computation/verify`
**Request**:
```json
{
"job_id": "job_456",
"result_hash": "hash_of_computation_result",
"proof_of_execution": "zk_snark_proof",
"public_inputs": {}
}
```
## Anonymity Sets
View available anonymity sets for privacy operations:
**Endpoint**: `GET /api/zk/anonymity/sets`
**Response**:
```json
{
"sets": {
"miners": {
"size": 100,
"description": "Registered GPU miners",
"type": "merkle_tree"
},
"clients": {
"size": 500,
"description": "Active clients",
"type": "merkle_tree"
},
"transactions": {
"size": 1000,
"description": "Recent transactions",
"type": "ring_signature"
}
},
"min_anonymity": 3,
"recommended_sets": ["miners", "clients"]
}
```
## Technical Implementation
### Circuit Compilation
The ZK circuits are compiled using:
- **Circom**: v2.2.3
- **Circomlib**: For standard circuit components
- **SnarkJS**: For trusted setup and proof generation
### Trusted Setup
A complete trusted setup ceremony has been performed:
1. Powers of Tau ceremony with 2^12 powers
2. Phase 2 preparation for specific circuits
3. Groth16 proving keys generated
4. Verification keys exported
### Circuit Files
The following circuit files are deployed:
- `receipt_simple_0001.zkey`: Proving key for receipt circuit
- `receipt_simple.wasm`: WASM witness generator
- `verification_key.json`: Verification key for on-chain verification
### Privacy Levels
1. **Basic**: Hash-based commitments (no ZK-SNARKs)
2. **Medium**: Simple ZK proofs with limited constraints
3. **Maximum**: Full ZK-SNARKs with complete privacy
## Security Considerations
1. **Trusted Setup**: The trusted setup was performed with proper entropy and multiple contributions
2. **Randomness**: All operations use cryptographically secure random number generation
3. **Nullifiers**: Prevent double-spending and replay attacks
4. **Verification**: All proofs can be verified on-chain or off-chain
## Future Enhancements
1. **Additional Circuits**: Membership and bid range circuits to be compiled
2. **Recursive Proofs**: Enable proof composition for complex operations
3. **On-Chain Verification**: Deploy verification contracts to blockchain
4. **Hardware Acceleration**: GPU acceleration for proof generation
## API Status
Check the current status of ZK features:
**Endpoint**: `GET /api/zk/status`
This endpoint returns detailed information about:
- Which ZK features are active
- Circuit compilation status
- Available proof types
- Next steps for implementation
## Integration Guide
To integrate ZK proofs in your application:
1. **Generate Proof**: Use the appropriate endpoint to generate a proof
2. **Submit Proof**: Include the proof in your transaction or API call
3. **Verify Proof**: The system will automatically verify the proof
4. **Privacy**: Your sensitive data remains private throughout the process
## Examples
### Private Marketplace Bid
```javascript
// 1. Create bid commitment
const bidAmount = 100;
const salt = generateRandomSalt();
const commitment = hash(bidAmount + salt);
// 2. Generate ZK proof that bid is within range
const proof = await generateBidRangeProof(bidAmount, salt);
// 3. Submit private bid
const response = await fetch('/api/zk/marketplace/private-bid', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
auction_id: 'auction_123',
bid_commitment: commitment,
proof: proof
})
});
```
### Stealth Address Payment
```javascript
// 1. Generate stealth address for recipient
const response = await fetch(
'/api/zk/stealth/address?recipient_public_key=0x123...',
{ method: 'POST' }
);
const { stealth_address, view_key } = await response.json();
// 2. Send payment to stealth address
await sendTransaction({
to: stealth_address,
amount: 1000
});
// 3. Recipient can view funds using view_key
const balance = await viewStealthAddressBalance(view_key);
```
## Support
For questions about ZK applications:
- Check the API documentation at `/docs/`
- Review the status endpoint at `/api/zk/status`
- Examine the circuit source code in `apps/zk-circuits/`

205
docs/reference/done.md
View File

@@ -1,205 +0,0 @@
# Completed Bootstrap Tasks
## Repository Initialization
- Scaffolded core monorepo directories reflected in `docs/bootstrap/dirs.md`.
- Added top-level config files: `.editorconfig`, `.gitignore`, `LICENSE`, and root `README.md`.
- Created Windsurf workspace metadata under `windsurf/`.
## Documentation
- Authored `docs/roadmap.md` capturing staged development targets.
- Added README placeholders for primary apps under `apps/` to outline purpose and setup notes.
## Coordinator API
- Implemented SQLModel-backed job persistence and service layer in `apps/coordinator-api/src/app/`.
- Wired client, miner, and admin routers to coordinator services (job lifecycle, scheduling, stats).
- Added initial pytest coverage under `apps/coordinator-api/tests/test_jobs.py`.
- Added signed receipt generation, persistence (`Job.receipt`, `JobReceipt` history table), retrieval endpoints, telemetry metrics, and optional coordinator attestations.
- Persisted historical receipts via `JobReceipt`; exposed `/v1/jobs/{job_id}/receipts` endpoint and integrated canonical serialization.
- Documented receipt attestation configuration (`RECEIPT_ATTESTATION_KEY_HEX`) in `docs/run.md` and coordinator README.
## Miner Node
- Created coordinator client, control loop, and capability/backoff utilities in `apps/miner-node/src/aitbc_miner/`.
- Implemented CLI/Python runners and execution pipeline with result reporting.
- Added starter tests for runners in `apps/miner-node/tests/test_runners.py`.
## Blockchain Node
- Added websocket fan-out, disconnect cleanup, and load-test coverage in `apps/blockchain-node/tests/test_websocket.py`, ensuring gossip topics deliver reliably to multiple subscribers.
## Directory Preparation
- Established scaffolds for Python and JavaScript packages in `packages/py/` and `packages/js/`.
- Seeded example project directories under `examples/` for quickstart clients and receipt verification.
- Added `examples/receipts-sign-verify/fetch_and_verify.py` demonstrating coordinator receipt fetching + verification using Python SDK.
## Python SDK
- Created `packages/py/aitbc-sdk/` with coordinator receipt client and verification helpers consuming `aitbc_crypto` utilities.
- Added pytest coverage under `packages/py/aitbc-sdk/tests/test_receipts.py` validating miner/coordinator signature checks and client behavior.
## Wallet Daemon
- Added `apps/wallet-daemon/src/app/receipts/service.py` providing `ReceiptVerifierService` that fetches and validates receipts via `aitbc_sdk`.
- Created unit tests under `apps/wallet-daemon/tests/test_receipts.py` verifying service behavior.
- Implemented wallet SDK receipt ingestion + attestation surfacing in `packages/py/aitbc-sdk/src/receipts.py`, including pagination client, signature verification, and failure diagnostics with full pytest coverage.
- Hardened REST API by wiring dependency overrides in `apps/wallet-daemon/tests/test_wallet_api.py`, expanding workflow coverage (create/list/unlock/sign) and enforcing structured password policy errors consumed in CI.
## Explorer Web
- Initialized a Vite + TypeScript scaffold in `apps/explorer-web/` with `vite.config.ts`, `tsconfig.json`, and placeholder `src/main.ts` content.
- Installed frontend dependencies locally to unblock editor tooling and TypeScript type resolution.
- Implemented `overview` page stats rendering backed by mock block/transaction/receipt fetchers, including robust empty-state handling and TypeScript type fixes.
## Pool Hub
- Implemented FastAPI service scaffolding with Redis/PostgreSQL-backed repositories, match/health/metrics endpoints, and Prometheus instrumentation (`apps/pool-hub/src/poolhub/`).
- Added Alembic migrations (`apps/pool-hub/migrations/`) and async integration tests covering repositories and endpoints (`apps/pool-hub/tests/`).
## Solidity Token
- Implemented attested minting logic in `packages/solidity/aitbc-token/contracts/AIToken.sol` using `AccessControl` role gates and ECDSA signature recovery.
- Added Hardhat unit tests in `packages/solidity/aitbc-token/test/aitoken.test.ts` covering successful minting, replay prevention, and invalid attestor signatures.
- Configured project TypeScript settings via `packages/solidity/aitbc-token/tsconfig.json` to align Hardhat, Node, and Mocha typings for the contract test suite.
## JavaScript SDK
- Delivered fetch-based client wrapper with TypeScript definitions and Vitest coverage under `packages/js/aitbc-sdk/`.
## Blockchain Node Enhancements
- Added comprehensive WebSocket tests for blocks and transactions streams including multi-subscriber and high-volume scenarios.
- Extended PoA consensus with per-proposer block metrics and rotation tracking.
- Added latest block interval gauge and RPC error spike alerting.
- Enhanced observability with Grafana dashboards for blockchain node and coordinator overview.
- Implemented marketplace endpoints in coordinator API with explorer and marketplace routers.
- Added mock coordinator integration with enhanced telemetry capabilities.
- Created comprehensive observability documentation and alerting rules.
## Explorer Web Production Readiness
- Implemented Playwright end-to-end tests for live mode functionality.
- Enhanced responsive design with improved CSS layout system.
- Added comprehensive error handling and fallback mechanisms for live API responses.
- Integrated live coordinator endpoints with proper data reconciliation.
## Marketplace Web Launch
- Completed auth/session scaffolding for marketplace actions.
- Implemented API abstraction layer with mock/live mode toggle.
- Connected mock listings and bids to coordinator data sources.
- Added feature flags for controlled live mode rollout.
## Cross-Chain Settlement
- Implemented cross-chain settlement hooks with external bridges.
- Created BridgeAdapter interface for LayerZero integration.
- Implemented BridgeManager for orchestration and retry logic.
- Added settlement storage and API endpoints.
- Created cross-chain settlement documentation.
## Python SDK Transport Abstraction
- Designed pluggable transport abstraction layer for multi-network support.
- Implemented base Transport interface with HTTP/WebSocket transports.
- Created MultiNetworkClient for managing multiple blockchain networks.
- Updated AITBCClient to use transport abstraction with backward compatibility.
- Added transport documentation and examples.
## GPU Service Provider Configuration
- Extended Miner model to include service configurations.
- Created service configuration API endpoints in pool-hub.
- Built HTML/JS UI for service provider configuration.
- Added service pricing configuration and capability validation.
- Implemented service selection for GPU providers.
## GPU Service Expansion
- Implemented dynamic service registry framework for 30+ GPU services.
- Created service definitions for 6 categories: AI/ML, Media Processing, Scientific Computing, Data Analytics, Gaming, Development Tools.
- Built comprehensive service registry API with validation and discovery.
- Added hardware requirement checking and pricing models.
- Updated roadmap with service expansion phase documentation.
## Stage 7 - GPU Service Expansion & Privacy Features
### GPU Service Infrastructure
- Create dynamic service registry with JSON schema validation
- Implement service provider configuration UI with dynamic service selection
- Create service definitions for AI/ML (LLM inference, image/video generation, speech recognition, computer vision, recommendation systems)
- Create service definitions for Media Processing (video transcoding, streaming, 3D rendering, image/audio processing)
- Create service definitions for Scientific Computing (molecular dynamics, weather modeling, financial modeling, physics simulation, bioinformatics)
- Create service definitions for Data Analytics (big data processing, real-time analytics, graph analytics, time series analysis)
- Create service definitions for Gaming & Entertainment (cloud gaming, asset baking, physics simulation, VR/AR rendering)
- Create service definitions for Development Tools (GPU compilation, model training, data processing, simulation testing, code generation)
- Implement service-specific validation and hardware requirement checking
### Privacy & Cryptography Features
- ✅ Research zk-proof-based receipt attestation and prototype a privacy-preserving settlement flow
- ✅ Implement Groth16 ZK circuit for receipt hash preimage proofs
- ✅ Create ZK proof generation service in coordinator API
- ✅ Implement on-chain verification contract (ZKReceiptVerifier.sol)
- ✅ Add confidential transaction support with opt-in ciphertext storage
- ✅ Implement HSM-backed key management (Azure Key Vault, AWS KMS, Software)
- ✅ Create hybrid encryption system (AES-256-GCM + X25519)
- ✅ Implement role-based access control with time restrictions
- ✅ Create tamper-evident audit logging with chain of hashes
- ✅ Publish comprehensive threat modeling with STRIDE analysis
- ✅ Update cross-chain settlement hooks for ZK proofs and privacy levels
### Enterprise Integration Features
- ✅ Deliver reference connectors for ERP/payment systems with Python SDK
- ✅ Implement Stripe payment connector with full charge/refund/subscription support
- ✅ Create enterprise-grade Python SDK with async support, dependency injection, metrics
- ✅ Build ERP connector base classes with plugin architecture for protocols
- ✅ Document comprehensive SLAs with uptime guarantees and support commitments
- ✅ Stand up multi-tenant coordinator infrastructure with per-tenant isolation
- ✅ Implement tenant management service with lifecycle operations
- ✅ Create tenant context middleware for automatic tenant identification
- ✅ Build resource quota enforcement with Redis-backed caching
- ✅ Create usage tracking and billing metrics with tiered pricing
- ✅ Launch ecosystem certification program with SDK conformance testing
- ✅ Define Bronze/Silver/Gold certification tiers with clear requirements
- ✅ Build language-agnostic test suite with OpenAPI contract validation
- ✅ Implement security validation framework with dependency scanning
- ✅ Design public registry API for partner/SDK discovery
- ✅ Validate certification system with Stripe connector certification
### Community & Governance Features
- ✅ Establish open RFC process with clear stages and review criteria
- ✅ Create governance website with documentation and navigation
- ✅ Set up community call schedule with multiple call types
- ✅ Design RFC template and GitHub PR template for submissions
- ✅ Implement benevolent dictator model with sunset clause
- ✅ Create hybrid governance structure (GitHub + Discord + Website)
- ✅ Document participation guidelines and code of conduct
- ✅ Establish transparency and accountability processes
### Ecosystem Growth Initiatives
- ✅ Create hackathon organization framework with quarterly themes and bounty board
- ✅ Design grant program with hybrid approach (micro-grants + strategic grants)
- ✅ Build marketplace extension SDK with cookiecutter templates
- ✅ Create analytics tooling for ecosystem metrics and KPI tracking
- ✅ Track ecosystem KPIs (active marketplaces, cross-chain volume) and feed them into quarterly strategy reviews
- ✅ Establish judging criteria with ecosystem impact weighting
- ✅ Create sponsor partnership framework with tiered benefits
- ✅ Design retroactive grants for proven projects
- ✅ Implement milestone-based disbursement for accountability
### Stage 8 - Frontier R&D & Global Expansion
- ✅ Launch research consortium framework with governance model and membership tiers
- ✅ Develop hybrid PoA/PoS consensus research plan with 12-month implementation timeline
- ✅ Create scaling research plan for sharding and rollups (100K+ TPS target)
- ✅ Design ZK applications research plan for privacy-preserving AI
- ✅ Create governance research plan with liquid democracy and AI assistance
- ✅ Develop economic models research plan with sustainable tokenomics
- ✅ Implement hybrid consensus prototype demonstrating dynamic mode switching
- ✅ Create executive summary for consortium recruitment
- ✅ Prototype sharding architecture with beacon chain coordination
- ✅ Implement ZK-rollup prototype for transaction batching
- ⏳ Set up consortium legal structure and operational infrastructure
- ⏳ Recruit founding members from industry and academia

333
docs/reference/governance/governance.md Normal file
View File

@@ -0,0 +1,333 @@
# Governance Module
The AITBC governance module enables decentralized decision-making through proposal voting and parameter changes.
## Overview
The governance system allows AITBC token holders to:
- Create proposals for protocol changes
- Vote on active proposals
- Execute approved proposals
- Track governance history
## API Endpoints
### Get Governance Parameters
Retrieve current governance system parameters.
```http
GET /api/v1/governance/parameters
```
**Response:**
```json
{
"min_proposal_voting_power": 1000,
"max_proposal_title_length": 200,
"max_proposal_description_length": 5000,
"default_voting_period_days": 7,
"max_voting_period_days": 30,
"min_quorum_threshold": 0.01,
"max_quorum_threshold": 1.0,
"min_approval_threshold": 0.01,
"max_approval_threshold": 1.0,
"execution_delay_hours": 24
}
```
### List Proposals
Get a list of governance proposals.
```http
GET /api/v1/governance/proposals?status={status}&limit={limit}&offset={offset}
```
**Query Parameters:**
- `status` (optional): Filter by proposal status (`active`, `passed`, `rejected`, `executed`)
- `limit` (optional): Number of proposals to return (default: 20)
- `offset` (optional): Number of proposals to skip (default: 0)
**Response:**
```json
[
{
"id": "proposal-uuid",
"title": "Proposal Title",
"description": "Description of the proposal",
"type": "parameter_change",
"target": {},
"proposer": "user-address",
"status": "active",
"created_at": "2025-12-28T18:00:00Z",
"voting_deadline": "2025-12-28T18:00:00Z",
"quorum_threshold": 0.1,
"approval_threshold": 0.5,
"current_quorum": 0.15,
"current_approval": 0.75,
"votes_for": 150,
"votes_against": 50,
"votes_abstain": 10,
"total_voting_power": 1000000
}
]
```
### Create Proposal
Create a new governance proposal.
```http
POST /api/v1/governance/proposals
```
**Request Body:**
```json
{
"title": "Reduce Transaction Fees",
"description": "This proposal suggests reducing transaction fees...",
"type": "parameter_change",
"target": {
"fee_percentage": "0.05"
},
"voting_period": 7,
"quorum_threshold": 0.1,
"approval_threshold": 0.5
}
```
**Fields:**
- `title`: Proposal title (10-200 characters)
- `description`: Detailed description (50-5000 characters)
- `type`: Proposal type (`parameter_change`, `protocol_upgrade`, `fund_allocation`, `policy_change`)
- `target`: Target configuration for the proposal
- `voting_period`: Voting period in days (1-30)
- `quorum_threshold`: Minimum participation percentage (0.01-1.0)
- `approval_threshold`: Minimum approval percentage (0.01-1.0)
### Get Proposal
Get details of a specific proposal.
```http
GET /api/v1/governance/proposals/{proposal_id}
```
### Submit Vote
Submit a vote on a proposal.
```http
POST /api/v1/governance/vote
```
**Request Body:**
```json
{
"proposal_id": "proposal-uuid",
"vote": "for",
"reason": "I support this change because..."
}
```
**Fields:**
- `proposal_id`: ID of the proposal to vote on
- `vote`: Vote option (`for`, `against`, `abstain`)
- `reason` (optional): Reason for the vote (max 500 characters)
### Get Voting Power
Check a user's voting power.
```http
GET /api/v1/governance/voting-power/{user_id}
```
**Response:**
```json
{
"user_id": "user-address",
"voting_power": 10000
}
```
### Execute Proposal
Execute an approved proposal.
```http
POST /api/v1/governance/execute/{proposal_id}
```
**Note:** Proposals can only be executed after:
1. Voting period has ended
2. Quorum threshold is met
3. Approval threshold is met
4. 24-hour execution delay has passed
## Proposal Types
### Parameter Change
Modify system parameters like fees, limits, or thresholds.
**Example Target:**
```json
{
"transaction_fee": "0.05",
"min_stake_amount": "1000",
"max_block_size": "2000"
}
```
### Protocol Upgrade
Initiate a protocol upgrade with version changes.
**Example Target:**
```json
{
"version": "1.2.0",
"upgrade_type": "hard_fork",
"activation_block": 1000000,
"changes": {
"new_features": ["feature1", "feature2"],
"breaking_changes": ["change1"]
}
}
```
### Fund Allocation
Allocate funds from the treasury.
**Example Target:**
```json
{
"amount": "1000000",
"recipient": "0x123...",
"purpose": "Ecosystem development fund",
"milestones": [
{
"description": "Phase 1 development",
"amount": "500000",
"deadline": "2025-06-30"
}
]
}
```
### Policy Change
Update governance or operational policies.
**Example Target:**
```json
{
"policy_name": "voting_period",
"new_value": "14 days",
"rationale": "Longer voting period for better participation"
}
```
## Voting Process
1. **Proposal Creation**: Any user with sufficient voting power can create a proposal
2. **Voting Period**: Token holders vote during the specified voting period
3. **Quorum Check**: Minimum participation must be met
4. **Approval Check**: Minimum approval ratio must be met
5. **Execution Delay**: 24-hour delay before execution
6. **Execution**: Approved changes are implemented
## Database Schema
### GovernanceProposal
- `id`: Unique proposal identifier
- `title`: Proposal title
- `description`: Detailed description
- `type`: Proposal type
- `target`: Target configuration (JSON)
- `proposer`: Address of the proposer
- `status`: Current status
- `created_at`: Creation timestamp
- `voting_deadline`: End of voting period
- `quorum_threshold`: Minimum participation required
- `approval_threshold`: Minimum approval required
- `executed_at`: Execution timestamp
- `rejection_reason`: Reason for rejection
### ProposalVote
- `id`: Unique vote identifier
- `proposal_id`: Reference to proposal
- `voter_id`: Address of the voter
- `vote`: Vote choice (for/against/abstain)
- `voting_power`: Power at time of vote
- `reason`: Vote reason
- `voted_at`: Vote timestamp
### TreasuryTransaction
- `id`: Unique transaction identifier
- `proposal_id`: Reference to proposal
- `from_address`: Source address
- `to_address`: Destination address
- `amount`: Transfer amount
- `status`: Transaction status
- `transaction_hash`: Blockchain hash
## Security Considerations
1. **Voting Power**: Based on AITBC token holdings
2. **Double Voting**: Prevented by tracking voter addresses
3. **Execution Delay**: Prevents rush decisions
4. **Quorum Requirements**: Ensures sufficient participation
5. **Proposal Thresholds**: Prevents spam proposals
## Integration Guide
### Frontend Integration
```javascript
// Fetch proposals
const response = await fetch('/api/v1/governance/proposals');
const proposals = await response.json();
// Submit vote
await fetch('/api/v1/governance/vote', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
proposal_id: 'uuid',
vote: 'for',
reason: 'Support this proposal'
})
});
```
### Smart Contract Integration
The governance system can be integrated with smart contracts for:
- On-chain voting
- Automatic execution
- Treasury management
- Parameter enforcement
## Best Practices
1. **Clear Proposals**: Provide detailed descriptions and rationales
2. **Reasonable Thresholds**: Set achievable quorum and approval thresholds
3. **Community Discussion**: Use forums for proposal discussion
4. **Gradual Changes**: Implement major changes in phases
5. **Monitoring**: Track proposal outcomes and system impact
## Future Enhancements
1. **Delegated Voting**: Allow users to delegate voting power
2. **Quadratic Voting**: Implement more sophisticated voting mechanisms
3. **Time-locked Voting**: Lock tokens for voting power boosts
4. **Multi-sig Execution**: Require multiple signatures for execution
5. **Proposal Templates**: Standardize proposal formats
## Support
For governance-related questions:
- Check the API documentation
- Review proposal history
- Contact the governance team
- Participate in community discussions

204
docs/reference/governance/roadmap-retrospective-template.md Normal file
View File

@@ -0,0 +1,204 @@
# AITBC Roadmap Retrospective - [Period]
**Date**: [Date]
**Period**: [e.g., H1 2024, H2 2024]
**Authors**: AITBC Core Team
## Executive Summary
[Brief 2-3 sentence summary of the period's achievements and challenges]
## KPI Performance Review
### Key Metrics
| KPI | Target | Actual | Status | Notes |
|-----|--------|--------|--------|-------|
| Active Marketplaces | [target] | [actual] | ✅/⚠️/❌ | [comments] |
| Cross-Chain Volume | [target] | [actual] | ✅/⚠️/❌ | [comments] |
| Active Developers | [target] | [actual] | ✅/⚠️/❌ | [comments] |
| TVL (Total Value Locked) | [target] | [actual] | ✅/⚠️/❌ | [comments] |
| Transaction Volume | [target] | [actual] | ✅/⚠️/❌ | [comments] |
### Performance Analysis
#### Achievements
- [List 3-5 major achievements]
- [Include metrics and impact]
#### Challenges
- [List 2-3 key challenges]
- [Include root causes if known]
#### Learnings
- [Key insights from the period]
- [What worked well]
- [What didn't work as expected]
## Roadmap Progress
### Completed Items
#### Stage 7 - Community & Governance
- ✅ [Item] - [Date completed] - [Brief description]
- ✅ [Item] - [Date completed] - [Brief description]
#### Stage 8 - Frontier R&D & Global Expansion
- ✅ [Item] - [Date completed] - [Brief description]
- ✅ [Item] - [Date completed] - [Brief description]
### In Progress Items
#### [Stage Name]
- ⏳ [Item] - [Progress %] - [ETA] - [Blockers if any]
- ⏳ [Item] - [Progress %] - [ETA] - [Blockers if any]
### Delayed Items
#### [Stage Name]
- ⏸️ [Item] - [Original date] → [New date] - [Reason for delay]
- ⏸️ [Item] - [Original date] → [New date] - [Reason for delay]
### New Items Added
- 🆕 [Item] - [Added date] - [Priority] - [Rationale]
## Ecosystem Health
### Developer Ecosystem
- **New Developers**: [number]
- **Active Projects**: [number]
- **GitHub Stars**: [number]
- **Community Engagement**: [description]
### User Adoption
- **Active Users**: [number]
- **Transaction Growth**: [percentage]
- **Geographic Distribution**: [key regions]
### Partner Ecosystem
- **New Partners**: [number]
- **Integration Status**: [description]
- **Success Stories**: [1-2 examples]
## Technical Achievements
### Major Releases
- [Release Name] - [Date] - [Key features]
- [Release Name] - [Date] - [Key features]
### Research Outcomes
- [Paper/Prototype] - [Status] - [Impact]
- [Research Area] - [Findings] - [Next steps]
### Infrastructure Improvements
- [Improvement] - [Impact] - [Metrics]
## Community & Governance
### Governance Participation
- **Proposal Submissions**: [number]
- **Voting Turnout**: [percentage]
- **Community Discussions**: [key topics]
### Community Initiatives
- [Initiative] - [Participation] - [Outcomes]
- [Initiative] - [Participation] - [Outcomes]
### Events & Activities
- [Event] - [Attendance] - [Feedback]
- [Event] - [Attendance] - [Feedback]
## Financial Overview
### Treasury Status
- **Balance**: [amount]
- **Burn Rate**: [amount/month]
- **Runway**: [months]
### Grant Program
- **Grants Awarded**: [number]
- **Total Amount**: [amount]
- **Success Rate**: [percentage]
## Risk Assessment
### Technical Risks
- [Risk] - [Probability] - [Impact] - [Mitigation]
### Market Risks
- [Risk] - [Probability] - [Impact] - [Mitigation]
### Operational Risks
- [Risk] - [Probability] - [Impact] - [Mitigation]
## Next Period Goals
### Primary Objectives
1. [Objective] - [Success criteria]
2. [Objective] - [Success criteria]
3. [Objective] - [Success criteria]
### Key Initiatives
- [Initiative] - [Owner] - [Timeline]
- [Initiative] - [Owner] - [Timeline]
- [Initiative] - [Owner] - [Timeline]
### Resource Requirements
- **Team**: [needs]
- **Budget**: [amount]
- **Partnerships**: [requirements]
## Long-term Vision Updates
### Strategy Adjustments
- [Adjustment] - [Rationale] - [Expected impact]
### New Opportunities
- [Opportunity] - [Potential] - [Next steps]
### Timeline Revisions
- [Milestone] - [Original] → [Revised] - [Reason]
## Feedback & Suggestions
### Community Feedback
- [Summary of key feedback]
- [Action items]
### Partner Feedback
- [Summary of key feedback]
- [Action items]
### Internal Feedback
- [Summary of key feedback]
- [Action items]
## Appendices
### A. Detailed Metrics
[Additional charts and data]
### B. Project Timeline
[Visual timeline with dependencies]
### C. Risk Register
[Detailed risk matrix]
### D. Action Item Tracker
[List of action items with owners and due dates]
---
**Next Review Date**: [Date]
**Document Version**: [version]
**Distribution**: [list of recipients]
## Approval
| Role | Name | Signature | Date |
|------|------|-----------|------|
| Project Lead | | | |
| Tech Lead | | | |
| Community Lead | | | |
| Ecosystem Lead | | | |

271
docs/reference/governance/transparency-report-template.md Normal file
View File

@@ -0,0 +1,271 @@
# AITBC Annual Transparency Report - [Year]
**Published**: [Date]
**Reporting Period**: [Start Date] to [End Date]
**Prepared By**: AITBC Foundation
## Executive Summary
[2-3 paragraph summary of the year's achievements, challenges, and strategic direction]
## Mission & Vision Alignment
### Mission Progress
- [Progress towards decentralizing AI/ML marketplace]
- [Key metrics showing mission advancement]
- [Community impact stories]
### Vision Milestones
- [Technical milestones achieved]
- [Ecosystem growth metrics]
- [Strategic partnerships formed]
## Governance Transparency
### Governance Structure
- **Current Model**: [Description of governance model]
- **Decision Making Process**: [How decisions are made]
- **Community Participation**: [Governance participation metrics]
### Key Governance Actions
| Date | Action | Outcome | Community Feedback |
|------|--------|---------|-------------------|
| [Date] | [Proposal/Decision] | [Result] | [Summary] |
| [Date] | [Proposal/Decision] | [Result] | [Summary] |
### Treasury & Financial Transparency
- **Total Treasury**: [Amount] AITBC
- **Annual Expenditure**: [Amount] AITBC
- **Funding Sources**: [Breakdown]
- **Expense Categories**: [Breakdown]
#### Budget Allocation
| Category | Budgeted | Actual | Variance | Notes |
|----------|----------|--------|----------|-------|
| Development | [Amount] | [Amount] | [Amount] | [Explanation] |
| Operations | [Amount] | [Amount] | [Amount] | [Explanation] |
| Community | [Amount] | [Amount] | [Amount] | [Explanation] |
| Research | [Amount] | [Amount] | [Amount] | [Explanation] |
## Technical Development
### Protocol Updates
#### Major Releases
- [Version] - [Date] - [Key Features]
- [Version] - [Date] - [Key Features]
- [Version] - [Date] - [Key Features]
#### Research & Development
- **Research Papers Published**: [Number]
- **Prototypes Developed**: [Number]
- **Patents Filed**: [Number]
- **Open Source Contributions**: [Details]
### Security & Reliability
- **Security Audits**: [Number] completed
- **Critical Issues**: [Number] found and fixed
- **Uptime**: [Percentage]
- **Incidents**: [Number] with details
### Performance Metrics
| Metric | Target | Actual | Status |
|--------|--------|--------|--------|
| TPS | [Target] | [Actual] | ✅/⚠️/❌ |
| Block Time | [Target] | [Actual] | ✅/⚠️/❌ |
| Finality | [Target] | [Actual] | ✅/⚠️/❌ |
| Gas Efficiency | [Target] | [Actual] | ✅/⚠️/❌ |
## Ecosystem Health
### Network Statistics
- **Total Transactions**: [Number]
- **Active Addresses**: [Number]
- **Total Value Locked (TVL)**: [Amount]
- **Cross-Chain Volume**: [Amount]
- **Marketplaces**: [Number]
### Developer Ecosystem
- **Active Developers**: [Number]
- **Projects Built**: [Number]
- **GitHub Stars**: [Number]
- **Developer Grants Awarded**: [Number]
### Community Metrics
- **Community Members**: [Discord/Telegram/etc.]
- **Monthly Active Users**: [Number]
- **Social Media Engagement**: [Metrics]
- **Event Participation**: [Number of events, attendance]
### Geographic Distribution
| Region | Users | Developers | Partners | Growth |
|--------|-------|------------|----------|--------|
| North America | [Number] | [Number] | [Number] | [%] |
| Europe | [Number] | [Number] | [Number] | [%] |
| Asia Pacific | [Number] | [Number] | [Number] | [%] |
| Other | [Number] | [Number] | [Number] | [%] |
## Sustainability Metrics
### Environmental Impact
- **Energy Consumption**: [kWh/year]
- **Carbon Footprint**: [tCO2/year]
- **Renewable Energy Usage**: [Percentage]
- **Efficiency Improvements**: [Year-over-year change]
### Economic Sustainability
- **Revenue Streams**: [Breakdown]
- **Cost Optimization**: [Achievements]
- **Long-term Funding**: [Strategy]
- **Risk Management**: [Approach]
### Social Impact
- **Education Programs**: [Number of participants]
- **Accessibility Features**: [Improvements]
- **Inclusion Initiatives**: [Programs launched]
- **Community Benefits**: [Stories/examples]
## Partnerships & Collaborations
### Strategic Partners
| Partner | Type | Since | Key Achievements |
|---------|------|-------|-----------------|
| [Partner] | [Type] | [Year] | [Achievements] |
| [Partner] | [Type] | [Year] | [Achievements] |
### Academic Collaborations
- **University Partnerships**: [Number]
- **Research Projects**: [Number]
- **Student Programs**: [Participants]
- **Publications**: [Number]
### Industry Alliances
- **Consortium Members**: [Number]
- **Working Groups**: [Active groups]
- **Standardization Efforts**: [Contributions]
- **Joint Initiatives**: [Projects]
## Compliance & Legal
### Regulatory Compliance
- **Jurisdictions**: [Countries/regions of operation]
- **Licenses**: [Held licenses]
- **Compliance Programs**: [Active programs]
- **Audits**: [Results]
### Data Privacy
- **Privacy Policy Updates**: [Changes made]
- **Data Protection**: [Measures implemented]
- **User Rights**: [Enhancements]
- **Incidents**: [Any breaches/issues]
### Intellectual Property
- **Patents**: [Portfolio summary]
- **Trademarks**: [Registered marks]
- **Open Source**: [Licenses used]
- **Contributions**: [Policy]
## Risk Management
### Identified Risks
| Risk Category | Risk Level | Mitigation | Status |
|---------------|------------|------------|--------|
| Technical | [Level] | [Strategy] | [Status] |
| Market | [Level] | [Strategy] | [Status] |
| Regulatory | [Level] | [Strategy] | [Status] |
| Operational | [Level] | [Strategy] | [Status] |
### Incident Response
- **Security Incidents**: [Number] with details
- **Response Time**: [Average time]
- **Recovery Time**: [Average time]
- **Lessons Learned**: [Key takeaways]
## Community Feedback & Engagement
### Feedback Channels
- **Proposals Received**: [Number]
- **Community Votes**: [Number]
- **Feedback Implementation Rate**: [Percentage]
- **Response Time**: [Average time]
### Major Community Initiatives
- [Initiative 1] - [Participation] - [Outcome]
- [Initiative 2] - [Participation] - [Outcome]
- [Initiative 3] - [Participation] - [Outcome]
### Challenges & Concerns
- **Top Issues Raised**: [Summary]
- **Actions Taken**: [Responses]
- **Ongoing Concerns**: [Status]
## Future Outlook
### Next Year Goals
1. [Goal 1] - [Success criteria]
2. [Goal 2] - [Success criteria]
3. [Goal 3] - [Success criteria]
### Strategic Priorities
- [Priority 1] - [Rationale]
- [Priority 2] - [Rationale]
- [Priority 3] - [Rationale]
### Resource Allocation
- **Development**: [Planned investment]
- **Community**: [Planned investment]
- **Research**: [Planned investment]
- **Operations**: [Planned investment]
## Acknowledgments
### Contributors
- **Core Team**: [Number of contributors]
- **Community Contributors**: [Number]
- **Top Contributors**: [Recognition]
### Special Thanks
- [Individual/Organization 1]
- [Individual/Organization 2]
- [Individual/Organization 3]
## Appendices
### A. Detailed Financial Statements
[Link to detailed financial reports]
### B. Technical Specifications
[Link to technical documentation]
### C. Governance Records
[Link to governance documentation]
### D. Community Survey Results
[Key findings from community surveys]
### E. Third-Party Audits
[Links to audit reports]
---
## Contact & Verification
### Verification
- **Financial Audit**: [Auditor] - [Report link]
- **Technical Audit**: [Auditor] - [Report link]
- **Security Audit**: [Auditor] - [Report link]
### Contact Information
- **Transparency Questions**: transparency@aitbc.io
- **General Inquiries**: info@aitbc.io
- **Security Issues**: security@aitbc.io
- **Media Inquiries**: media@aitbc.io
### Document Information
- **Version**: [Version number]
- **Last Updated**: [Date]
- **Next Report Due**: [Date]
- **Archive**: [Link to past reports]
---
*This transparency report is published annually as part of AITBC's commitment to openness and accountability. All data presented is accurate to the best of our knowledge. For questions or clarifications, please contact us at transparency@aitbc.io.*

458
docs/reference/roadmap.md
View File

@@ -1,458 +0,0 @@
# AITBC Development Roadmap
This roadmap aggregates high-priority tasks derived from the bootstrap specifications in `docs/bootstrap/` and tracks progress across the monorepo. Update this document as milestones evolve.
## Stage 1 — Upcoming Focus Areas [COMPLETED: 2025-12-22]
- **Blockchain Node Foundations**
- ✅ Bootstrap module layout in `apps/blockchain-node/src/`.
- ✅ Implement SQLModel schemas and RPC stubs aligned with historical/attested receipts.
- **Explorer Web Enablement**
- ✅ Finish mock integration across all pages and polish styling + mock/live toggle.
- ✅ Begin wiring coordinator endpoints (e.g., `/v1/jobs/{job_id}/receipts`).
- **Marketplace Web Scaffolding**
- ✅ Scaffold Vite/vanilla frontends consuming coordinator receipt history endpoints and SDK examples.
- **Pool Hub Services**
- ✅ Initialize FastAPI project, scoring registry, and telemetry ingestion hooks leveraging coordinator/miner metrics.
- **CI Enhancements**
- ✅ Add blockchain-node tests once available and frontend build/lint checks to `.github/workflows/python-tests.yml` or follow-on workflows.
- ✅ Provide systemd unit + installer scripts under `scripts/` for streamlined deployment.
## Stage 2 — Core Services (MVP) [COMPLETED: 2025-12-22]
- **Coordinator API**
- ✅ Scaffold FastAPI project (`apps/coordinator-api/src/app/`).
- ✅ Implement job submission, status, result endpoints.
- ✅ Add miner registration, heartbeat, poll, result routes.
- ✅ Wire SQLite persistence for jobs, miners, receipts (historical `JobReceipt` table).
- ✅ Provide `.env.example`, `pyproject.toml`, and run scripts.
- ✅ Deploy minimal version in container with nginx proxy
- **Miner Node**
- ✅ Implement capability probe and control loop (register → heartbeat → fetch jobs).
- ✅ Build CLI and Python runners with sandboxed work dirs (result reporting stubbed to coordinator).
- **Blockchain Node**
- ✅ Define SQLModel schema for blocks, transactions, accounts, receipts (`apps/blockchain-node/src/aitbc_chain/models.py`).
- ✅ Harden schema parity across runtime + storage:
- Alembic baseline + follow-on migrations in `apps/blockchain-node/migrations/` now track the SQLModel schema (blocks, transactions, receipts, accounts).
- Added `Relationship` + `ForeignKey` wiring in `apps/blockchain-node/src/aitbc_chain/models.py` for block ↔ transaction ↔ receipt joins.
- Introduced hex/enum validation hooks via Pydantic validators to ensure hash integrity and safe persistence.
- ✅ Implement PoA proposer loop with block assembly (`apps/blockchain-node/src/aitbc_chain/consensus/poa.py`).
- ✅ Expose REST RPC endpoints for tx submission, balances, receipts (`apps/blockchain-node/src/aitbc_chain/rpc/router.py`).
- ✅ Deliver WebSocket RPC + P2P gossip layer:
- ✅ Stand up WebSocket subscription endpoints (`apps/blockchain-node/src/aitbc_chain/rpc/websocket.py`) mirroring REST payloads.
- ✅ Implement pub/sub transport for block + transaction gossip backed by an in-memory broker (Starlette `Broadcast` or Redis) with configurable fan-out.
- ✅ Add integration tests and load-test harness ensuring gossip convergence and back-pressure handling.
- ✅ Ship devnet scripts (`apps/blockchain-node/scripts/`).
- ✅ Add observability hooks (JSON logging, Prometheus metrics) and integrate coordinator mock into devnet tooling.
- ✅ Expand observability dashboards + miner mock integration:
- Build Grafana dashboards for consensus health (block intervals, proposer rotation) and RPC latency (`apps/blockchain-node/observability/`).
- Expose miner mock telemetry (job throughput, error rates) via shared Prometheus registry and ingest into blockchain-node dashboards.
- Add alerting rules (Prometheus `Alertmanager`) for stalled proposers, queue saturation, and miner mock disconnects.
- Wire coordinator mock into devnet tooling to simulate real-world load and validate observability hooks.
- **Receipt Schema**
- ✅ Finalize canonical JSON receipt format under `protocols/receipts/` (includes sample signed receipts).
- ✅ Implement signing/verification helpers in `packages/py/aitbc-crypto` (JS SDK pending).
- ✅ Translate `docs/bootstrap/aitbc_tech_plan.md` contract skeleton into Solidity project (`packages/solidity/aitbc-token/`).
- ✅ Add deployment/test scripts and document minting flow (`packages/solidity/aitbc-token/scripts/` and `docs/run.md`).
- **Wallet Daemon**
- ✅ Implement encrypted keystore (Argon2id + XChaCha20-Poly1305) via `KeystoreService`.
- ✅ Provide REST and JSON-RPC endpoints for wallet management and signing (`api_rest.py`, `api_jsonrpc.py`).
- ✅ Add mock ledger adapter with SQLite backend powering event history (`ledger_mock/`).
- ✅ Integrate Python receipt verification helpers (`aitbc_sdk`) and expose API/service utilities validating miner + coordinator signatures.
- ✅ Harden REST API workflows (create/list/unlock/sign) with structured password policy enforcement and deterministic pytest coverage in `apps/wallet-daemon/tests/test_wallet_api.py`.
- ✅ Implement Wallet SDK receipt ingestion + attestation surfacing:
- Added `/v1/jobs/{job_id}/receipts` client helpers with cursor pagination, retry/backoff, and summary reporting (`packages/py/aitbc-sdk/src/receipts.py`).
- Reused crypto helpers to validate miner and coordinator signatures, capturing per-key failure reasons for downstream UX.
- Surfaced aggregated attestation status (`ReceiptStatus`) and failure diagnostics for SDK + UI consumers; JS helper parity still planned.
## Stage 3 — Pool Hub & Marketplace [COMPLETED: 2025-12-22]
- **Pool Hub**
- ✅ Implement miner registry, scoring engine, and `/v1/match` API with Redis/PostgreSQL backing stores.
- ✅ Add observability endpoints (`/v1/health`, `/v1/metrics`) plus Prometheus instrumentation and integration tests.
- **Marketplace Web**
- ✅ Initialize Vite project with vanilla TypeScript (`apps/marketplace-web/`).
- ✅ Build offer list, bid form, and stats cards powered by mock data fixtures (`public/mock/`).
- ✅ Provide API abstraction toggling mock/live mode (`src/lib/api.ts`) and wire coordinator endpoints.
- ✅ Validate live mode against coordinator `/v1/marketplace/*` responses and add auth feature flags for rollout.
- ✅ Deploy to production at https://aitbc.bubuit.net/marketplace/
- **Explorer Web**
- ✅ Initialize Vite + TypeScript project scaffold (`apps/explorer-web/`).
- ✅ Add routed pages for overview, blocks, transactions, addresses, receipts.
- ✅ Seed mock datasets (`public/mock/`) and fetch helpers powering overview + blocks tables.
- ✅ Extend mock integrations to transactions, addresses, and receipts pages.
- ✅ Implement styling system, mock/live data toggle, and coordinator API wiring scaffold.
- ✅ Render overview stats from mock block/transaction/receipt summaries with graceful empty-state fallbacks.
- ✅ Validate live mode + responsive polish:
- Hit live coordinator endpoints via nginx (`/api/explorer/blocks`, `/api/explorer/transactions`, `/api/explorer/addresses`, `/api/explorer/receipts`) via `getDataMode() === "live"` and reconcile payloads with UI models.
- Add fallbacks + error surfacing for partial/failed live responses (toast + console diagnostics).
- Audit responsive breakpoints (`public/css/layout.css`) and adjust grid/typography for tablet + mobile; add regression checks in Percy/Playwright snapshots.
- ✅ Deploy to production at https://aitbc.bubuit.net/explorer/ with genesis block display
## Stage 4 — Observability & Production Polish
- **Observability & Telemetry**
- ✅ Build Grafana dashboards for PoA consensus health (block intervals, proposer rotation cadence) leveraging `poa_last_block_interval_seconds`, `poa_proposer_rotations_total`, and per-proposer counters.
- ✅ Surface RPC latency histograms/summaries for critical endpoints (`rpc_get_head`, `rpc_send_tx`, `rpc_submit_receipt`) and add Grafana panels with SLO thresholds.
- ✅ Ingest miner mock telemetry (job throughput, failure rate) into the shared Prometheus registry and wire panels/alerts that correlate miner health with consensus metrics.
- **Explorer Web (Live Mode)**
- ✅ Finalize live `getDataMode() === "live"` workflow: align API payload contracts, render loading/error states, and persist mock/live toggle preference.
- ✅ Expand responsive testing (tablet/mobile) and add automated visual regression snapshots prior to launch.
- ✅ Integrate Playwright smoke tests covering overview, blocks, and transactions pages in live mode.
- **Marketplace Web (Launch Readiness)**
- ✅ Connect mock listings/bids to coordinator data sources and provide feature flags for live mode rollout.
- ✅ Implement auth/session scaffolding for marketplace actions and document API assumptions in `apps/marketplace-web/README.md`.
- ✅ Add Grafana panels monitoring marketplace API throughput and error rates once endpoints are live.
- **Operational Hardening**
- ✅ Extend Alertmanager rules to cover RPC error spikes, proposer stalls, and miner disconnects using the new metrics.
- ✅ Document dashboard import + alert deployment steps in `docs/run.md` for operators.
- ✅ Prepare Stage 3 release checklist linking dashboards, alerts, and smoke tests prior to production cutover.
- ✅ Enable host GPU miner with coordinator proxy routing and systemd-backed coordinator service; add proxy health timer.
## Stage 5 — Scaling & Release Readiness
- **Infrastructure Scaling**
- ✅ Benchmark blockchain node throughput under sustained load; capture CPU/memory targets and suggest horizontal scaling thresholds.
- ✅ Build Terraform/Helm templates for dev/staging/prod environments, including Prometheus/Grafana bundles.
- ✅ Implement autoscaling policies for coordinator, miners, and marketplace services with synthetic traffic tests.
- **Reliability & Compliance**
- ✅ Formalize backup/restore procedures for PostgreSQL, Redis, and ledger storage with scheduled jobs.
- ✅ Complete security hardening review (TLS termination, API auth, secrets management) and document mitigations in `docs/security.md`.
- ✅ Add chaos testing scripts (network partition, coordinator outage) and track mean-time-to-recovery metrics.
- **Product Launch Checklist**
- ✅ Finalize public documentation (API references, onboarding guides) and publish to the docs portal.
- ✅ Coordinate beta release timeline, including user acceptance testing of explorer/marketplace live modes.
- ✅ Establish post-launch monitoring playbooks and on-call rotations.
## Stage 6 — Ecosystem Expansion
- **Cross-Chain & Interop**
- ✅ Prototype cross-chain settlement hooks leveraging external bridges; document integration patterns.
- ✅ Extend SDKs (Python/JS) with pluggable transport abstractions for multi-network support.
- 🔄 Evaluate third-party explorer/analytics integrations and publish partner onboarding guides.
- **Marketplace Growth**
- 🔄 Launch incentive programs (staking, liquidity mining) and expose telemetry dashboards tracking campaign performance.
- 🔄 Implement governance module (proposal voting, parameter changes) and add API/UX flows to explorer/marketplace.
- 🔄 Provide SLA-backed coordinator/pool hubs with capacity planning and billing instrumentation.
- **Developer Experience**
- ✅ Publish advanced tutorials (custom proposers, marketplace extensions) and maintain versioned API docs.
- 🔄 Integrate CI/CD pipelines with canary deployments and blue/green release automation.
- 🔄 Host quarterly architecture reviews capturing lessons learned and feeding into roadmap revisions.
## Stage 7 — Innovation & Ecosystem Services
- **GPU Service Expansion**
- ✅ Implement dynamic service registry framework for 30+ GPU-accelerated services
- ✅ Create service definitions for AI/ML (LLM inference, image/video generation, speech recognition, computer vision, recommendation systems)
- ✅ Create service definitions for Media Processing (video transcoding, streaming, 3D rendering, image/audio processing)
- ✅ Create service definitions for Scientific Computing (molecular dynamics, weather modeling, financial modeling, physics simulation, bioinformatics)
- ✅ Create service definitions for Data Analytics (big data processing, real-time analytics, graph analytics, time series analysis)
- ✅ Create service definitions for Gaming & Entertainment (cloud gaming, asset baking, physics simulation, VR/AR rendering)
- ✅ Create service definitions for Development Tools (GPU compilation, model training, data processing, simulation testing, code generation)
- ✅ Deploy service provider configuration UI with dynamic service selection
- ✅ Implement service-specific validation and hardware requirement checking
- **Advanced Cryptography & Privacy**
- ✅ Research zk-proof-based receipt attestation and prototype a privacy-preserving settlement flow.
- ✅ Add confidential transaction support with opt-in ciphertext storage and HSM-backed key management.
- ✅ Publish threat modeling updates and share mitigations with ecosystem partners.
- **Enterprise Integrations**
- ✅ Deliver reference connectors for ERP/payment systems and document SLA expectations.
- ✅ Stand up multi-tenant coordinator infrastructure with per-tenant isolation and billing metrics.
- ✅ Launch ecosystem certification program (SDK conformance, security best practices) with public registry.
- **Community & Governance**
- ✅ Establish open RFC process, publish governance website, and schedule regular community calls.
- ✅ Sponsor hackathons/accelerators and provide grants for marketplace extensions and analytics tooling.
- ✅ Track ecosystem KPIs (active marketplaces, cross-chain volume) and feed them into quarterly strategy reviews.
## Stage 8 — Frontier R&D & Global Expansion [COMPLETED: 2025-12-28]
- **Protocol Evolution**
- ✅ Launch research consortium exploring next-gen consensus (hybrid PoA/PoS) and finalize whitepapers.
- 🔄 Prototype sharding or rollup architectures to scale throughput beyond current limits.
- 🔄 Standardize interoperability specs with industry bodies and submit proposals for adoption.
- **Global Rollout**
- 🔄 Establish regional infrastructure hubs (multi-cloud) with localized compliance and data residency guarantees.
- 🔄 Partner with regulators/enterprises to pilot regulated marketplaces and publish compliance playbooks.
- 🔄 Expand localization (UI, documentation, support) covering top target markets.
- **Long-Term Sustainability**
- 🔄 Create sustainability fund for ecosystem maintenance, bug bounties, and community stewardship.
- 🔄 Define succession planning for core teams, including training programs and contributor pathways.
- 🔄 Publish bi-annual roadmap retrospectives assessing KPI alignment and revising long-term goals.
## Stage 9 — Moonshot Initiatives [COMPLETED: 2025-12-28]
- **Decentralized Infrastructure**
- 🔄 Transition coordinator/miner roles toward community-governed validator sets with incentive alignment.
- 🔄 Explore decentralized storage/backbone options (IPFS/Filecoin) for ledger and marketplace artifacts.
- 🔄 Prototype fully trustless marketplace settlement leveraging zero-knowledge rollups.
- **AI & Automation**
- 🔄 Integrate AI-driven monitoring/anomaly detection for proposer health, market liquidity, and fraud detection.
- 🔄 Automate incident response playbooks with ChatOps and policy engines.
- 🔄 Launch research into autonomous agent participation (AI agents bidding/offering in the marketplace) and governance implications.
- **Global Standards Leadership**
- 🔄 Chair industry working groups defining receipt/marketplace interoperability standards.
- 🔄 Publish annual transparency reports and sustainability metrics for stakeholders.
- 🔄 Engage with academia and open-source foundations to steward long-term protocol evolution.
### Stage 10 — Stewardship & Legacy Planning [COMPLETED: 2025-12-28]
- **Open Governance Maturity**
- 🔄 Transition roadmap ownership to community-elected councils with transparent voting and treasury controls.
- 🔄 Codify constitutional documents (mission, values, conflict resolution) and publish public charters.
- 🔄 Implement on-chain governance modules for protocol upgrades and ecosystem-wide decisions.
- **Educational & Outreach Programs**
- 🔄 Fund university partnerships, research chairs, and developer fellowships focused on decentralized marketplace tech.
- 🔄 Create certification tracks and mentorship programs for new validator/operators.
- 🔄 Launch annual global summit and publish proceedings to share best practices across partners.
- **Long-Term Preservation**
- 🔄 Archive protocol specs, governance records, and cultural artifacts in decentralized storage with redundancy.
- 🔄 Establish legal/organizational frameworks to ensure continuity across jurisdictions.
- 🔄 Develop end-of-life/transition plans for legacy components, documenting deprecation strategies and migration tooling.
## Shared Libraries & Examples
## Stage 11 — Trade Exchange & Token Economy [COMPLETED: 2025-12-28]
- **Bitcoin Wallet Integration**
- ✅ Implement Bitcoin payment gateway for AITBC token purchases
- ✅ Create payment request API with unique payment addresses
- ✅ Add QR code generation for mobile payments
- ✅ Implement real-time payment monitoring with blockchain API
- ✅ Configure exchange rate: 1 BTC = 100,000 AITBC
- **User Management System**
- ✅ Implement wallet-based authentication with session management
- ✅ Create individual user accounts with unique wallets
- ✅ Add user profile pages with transaction history
- ✅ Implement secure session tokens with 24-hour expiry
- ✅ Add login/logout functionality across all pages
- **Trade Exchange Platform**
- ✅ Build responsive trading interface with real-time price updates
- ✅ Integrate Bitcoin payment flow with QR code display
- ✅ Add payment status monitoring and confirmation handling
- ✅ Implement AITBC token minting upon payment confirmation
- ✅ Deploy to production at https://aitbc.bubuit.net/Exchange/
- **API Infrastructure**
- ✅ Add user management endpoints (/api/users/*)
- ✅ Implement exchange payment endpoints (/api/exchange/*)
- ✅ Add session-based authentication for protected routes
- ✅ Create transaction history and balance tracking APIs
- ✅ Fix all import and syntax errors in coordinator API
## Stage 13 — Explorer Live API & Reverse Proxy Fixes [COMPLETED: 2025-12-28]
- **Explorer Live API**
- ✅ Enable coordinator explorer routes at `/v1/explorer/*`.
- ✅ Expose nginx explorer proxy at `/api/explorer/*` (maps to backend `/v1/explorer/*`).
- ✅ Fix response schema mismatches (e.g., receipts response uses `jobId`).
- **Coordinator API Users/Login**
- ✅ Ensure `/v1/users/login` is registered and working.
- ✅ Fix missing SQLModel tables by initializing DB on startup (wallet/user tables created).
- **nginx Reverse Proxy Hardening**
- ✅ Fix `/api/v1/*` routing to avoid double `/v1` prefix.
- ✅ Add compatibility proxy for Exchange: `/api/users/*` → backend `/v1/users/*`.
## Stage 12 — Zero-Knowledge Proof Implementation [COMPLETED: 2025-12-28]
- **Circom Compiler Setup**
- ✅ Install Circom compiler v2.2.3 on production server
- ✅ Configure Node.js environment for ZK circuit compilation
- ✅ Install circomlib and required dependencies
- **ZK Circuit Development**
- ✅ Create receipt attestation circuit (receipt_simple.circom)
- ✅ Implement membership proof circuit template
- ✅ Implement bid range proof circuit template
- ✅ Compile circuits to R1CS, WASM, and symbolic files
- **Trusted Setup Ceremony**
- ✅ Perform Powers of Tau setup ceremony (2^12)
- ✅ Generate proving keys (zkey) for Groth16
- ✅ Export verification keys for on-chain verification
- ✅ Complete phase 2 preparation with contributions
- **ZK Applications API**
- ✅ Implement identity commitment endpoints
- ✅ Create stealth address generation service
- ✅ Add private receipt attestation API
- ✅ Implement group membership proof verification
- ✅ Add private bidding functionality
- ✅ Create computation proof verification
- ✅ Deploy to production at /api/zk/ endpoints
- **Integration & Deployment**
- ✅ Integrate ZK proof service with coordinator API
- ✅ Configure circuit files in production environment
- ✅ Enable ZK proof generation in coordinator service
- ✅ Update documentation with ZK capabilities
## Stage 14 — Explorer JavaScript Error Fixes [COMPLETED: 2025-12-30]
- **JavaScript Error Resolution**
- ✅ Fixed "can't access property 'length', t is undefined" error on Explorer page load
- ✅ Updated fetchMock function in mockData.ts to return correct structure with 'items' property
- ✅ Added defensive null checks in all page init functions (overview, blocks, transactions, addresses, receipts)
- ✅ Fixed TypeScript errors for null checks and missing properties
- ✅ Deployed fixes to production server (/var/www/aitbc.bubuit.net/explorer/)
- ✅ Configured mock data serving from correct path (/explorer/mock/)
## Stage 15 — Cascade Skills Framework [COMPLETED: 2025-01-19]
- **Skills Infrastructure**
- ✅ Implement Cascade skills framework for complex workflow automation
- ✅ Create skills directory structure at `.windsurf/skills/`
- ✅ Define skill metadata format with YAML frontmatter
- ✅ Add progressive disclosure for intelligent skill invocation
- **Deploy-Production Skill**
- ✅ Create comprehensive deployment workflow skill
- ✅ Implement pre-deployment validation script (disk, memory, services, SSL)
- ✅ Add environment template with all production variables
- ✅ Create rollback procedures with emergency steps
- ✅ Build health check script for post-deployment verification
- **Blockchain-Operations Skill**
- ✅ Create node health monitoring with peer analysis and sync status
- ✅ Implement transaction tracer for debugging and gas optimization
- ✅ Build GPU mining optimization script for NVIDIA/AMD cards
- ✅ Add real-time sync monitor with visual progress bar
- ✅ Create network diagnostics tool with connectivity analysis
- **Skills Integration**
- ✅ Enable automatic skill invocation based on context
- ✅ Add manual skill triggering with keyword detection
- ✅ Implement error handling and logging in all skills
- ✅ Create comprehensive documentation and usage examples
## Stage 16 — Service Maintenance & Optimization [COMPLETED: 2026-01-21]
- **Service Recovery**
- ✅ Diagnose and fix all failing AITBC container services
- ✅ Resolve duplicate service conflicts causing port binding errors
- ✅ Fix marketplace service implementation (missing server.py)
- ✅ Disable redundant services to prevent resource conflicts
- **System Administration**
- ✅ Configure passwordless SSH access for automation
- ✅ Create dedicated SSH keys for secure service management
- ✅ Document service dependencies and port mappings
- ✅ Establish service monitoring procedures
- **Service Status Verification**
- ✅ Verify all 7 core services running correctly
- ✅ Confirm proper nginx reverse proxy configuration
- ✅ Validate API endpoints accessibility
- ✅ Test service recovery procedures
## Stage 17 — Ollama GPU Inference & CLI Tooling [COMPLETED: 2026-01-24]
- **End-to-End Ollama Testing**
- ✅ Verify complete GPU inference workflow from job submission to receipt generation
- ✅ Test Ollama integration with multiple models (llama3.2, mistral, deepseek, etc.)
- ✅ Validate job lifecycle: QUEUED → RUNNING → COMPLETED
- ✅ Confirm receipt generation with accurate payment calculations
- ✅ Record transactions on blockchain with proper metadata
- **Coordinator API Bug Fixes**
- ✅ Fix missing `_coerce_float()` helper function causing 500 errors
- ✅ Deploy fix to production incus container via SSH
- ✅ Verify result submission returns 200 OK with valid receipts
- ✅ Validate receipt payload structure and signature generation
- **Miner Configuration & Optimization**
- ✅ Fix miner ID mismatch (host-gpu-miner → REDACTED_MINER_KEY)
- ✅ Enhance logging with explicit flush handlers for systemd journal
- ✅ Configure unbuffered Python logging environment variables
- ✅ Create systemd service unit with proper environment configuration
- **CLI Tooling Development**
- ✅ Create unified bash CLI wrapper (`scripts/aitbc-cli.sh`)
- ✅ Implement commands: submit, status, browser, blocks, receipts, cancel
- ✅ Add admin commands: admin-miners, admin-jobs, admin-stats
- ✅ Support environment variable overrides for URL and API keys
- ✅ Make script executable and document usage patterns
- **Blockchain-Operations Skill Enhancement**
- ✅ Add comprehensive Ollama testing scenarios to skill
- ✅ Create detailed test documentation (`ollama-test-scenario.md`)
- ✅ Document common issues and troubleshooting procedures
- ✅ Add performance metrics and expected results
- ✅ Include end-to-end automation script template
- **Documentation Updates**
- ✅ Update localhost testing scenario with CLI wrapper usage
- ✅ Convert examples to use localhost URLs (127.0.0.1)
- ✅ Add host user paths and quick start commands
- ✅ Document complete workflow from setup to verification
- ✅ Update skill documentation with testing scenarios
## Stage 18 — Repository Reorganization & CSS Consolidation [COMPLETED: 2026-01-24]
- **Root Level Cleanup**
- ✅ Move 60+ loose files from root to proper directories
- ✅ Organize deployment scripts into `scripts/deploy/`
- ✅ Organize GPU miner files into `scripts/gpu/`
- ✅ Organize test/verify files into `scripts/test/`
- ✅ Organize service management scripts into `scripts/service/`
- ✅ Move systemd services to `systemd/`
- ✅ Move nginx configs to `infra/nginx/`
- ✅ Move dashboards to `website/dashboards/`
- **Website/Docs Folder Structure**
- ✅ Establish `/website/docs/` as source for HTML documentation
- ✅ Create shared CSS file (`css/docs.css`) with 1232 lines
- ✅ Create theme toggle JavaScript (`js/theme.js`)
- ✅ Migrate all HTML files to use external CSS (45-66% size reduction)
- ✅ Clean `/docs/` folder to only contain mkdocs markdown files
- **Documentation Styling Fixes**
- ✅ Fix dark theme background consistency across all docs pages
- ✅ Add dark theme support to `full-documentation.html`
- ✅ Fix Quick Start section cascade styling in docs-miners.html
- ✅ Fix SDK Examples cascade indentation in docs-clients.html
- ✅ Fix malformed `</code-block>` tags across all docs
- ✅ Update API endpoint example to use Python/FastAPI
- **Path Reference Updates**
- ✅ Update systemd service file with new `scripts/gpu/gpu_miner_host.py` path
- ✅ Update skill documentation with new file locations
- ✅ Update localhost-testing-scenario.md with correct paths
- ✅ Update gpu_miner_host_wrapper.sh with new path
- **Repository Maintenance**
- ✅ Expand .gitignore from 39 to 145 lines with organized sections
- ✅ Add project-specific ignore rules for coordinator, explorer, GPU miner
- ✅ Document final folder structure in done.md
the canonical checklist during implementation. Mark completed tasks with ✅ and add dates or links to relevant PRs as development progresses.

95
docs/reference/specs/receipt-spec.md Normal file
View File

@@ -0,0 +1,95 @@
# AITBC Receipt Specification (Draft)
## Overview
This document defines the canonical schema and serialization rules for receipts generated by the AITBC network after miners complete compute jobs. Receipts serve as tamper-evident evidence tying compute usage to token minting events.
## Receipt Fields
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `version` | string | yes | Receipt schema version (e.g., `"1.0"`). |
| `receipt_id` | string | yes | Unique identifier for this receipt. SHOULD be globally unique (UUID or hash). |
| `job_id` | string | yes | Identifier of the coordinator job this receipt references. |
| `provider` | string | yes | Miner address/account that executed the job. |
| `client` | string | yes | Client address/account that requested the job. |
| `units` | number | yes | Compute units earned by the miner (token minting basis). |
| `unit_type` | string | yes | Unit denomination (e.g., `"gpu_seconds"`, `"token_ops"`). |
| `price` | number | optional | Price paid by the client for the job (same unit as `units` if applicable). |
| `model` | string | optional | Model or workload identifier (e.g., `"runwayml/stable-diffusion-v1-5"`). |
| `prompt_hash` | string | optional | Hash of user prompt or workload input to preserve privacy. |
| `started_at` | integer | yes | Unix timestamp (seconds) when the job started. |
| `completed_at` | integer | yes | Unix timestamp when the job completed. |
| `duration_ms` | integer | optional | Milliseconds elapsed during execution. |
| `artifact_hash` | string | optional | SHA-256 hash of the result artifact(s). |
| `coordinator_id` | string | optional | Coordinator identifier if multiple coordinators exist. |
| `nonce` | string | optional | Unique nonce to prevent replay/double minting. |
| `chain_id` | integer | optional | Target chain/network identifier. |
| `metadata` | object | optional | Arbitrary key/value pairs for future extensions. |
| `signature` | object | conditional | Signature object (see below). |
### Signature Object
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `alg` | string | yes | Signature algorithm (e.g., `"Ed25519"`, `"secp256k1"`). |
| `key_id` | string | yes | Identifier of signing key (e.g., `"miner-ed25519-2025-09"`). |
| `sig` | string | yes | Base64url-encoded signature over the canonical receipt bytes. |
Receipts SHOULD be signed by either the miner, coordinator attester, or both depending on trust model. Multiple signatures can be supported by storing them in `metadata.signatures` array.
## Canonical Serialization
1. Construct a JSON object containing all fields except `signature`.
2. Remove any fields with null/undefined values.
3. Sort keys lexicographically at each object level.
4. Serialize using UTF-8 without whitespace (RFC 8785 style).
5. Compute hash as `sha256(serialized_json)` for Ed25519 signing.
6. Attach `signature` object containing algorithm, key ID, and base64url signature over the hash.
## Validation Rules
- `completed_at >= started_at`.
- `units >= 0` and `price >= 0` when present.
- `signature.alg` MUST be one of the network approved algorithms (initially `Ed25519`).
- `chain_id` SHOULD match the target blockchain network when provided.
- Reject receipts older than network-defined retention period.
## Example Receipt (unsigned)
```json
{
"version": "1.0",
"receipt_id": "rcpt-20250926-000123",
"job_id": "job-abc123",
"provider": "ait1minerxyz...",
"client": "ait1clientabc...",
"units": 1.9,
"unit_type": "gpu_seconds",
"price": 4.2,
"model": "runwayml/stable-diffusion-v1-5",
"prompt_hash": "sha256:cf1f...",
"started_at": 1695720000,
"completed_at": 1695720002,
"artifact_hash": "sha256:deadbeef...",
"coordinator_id": "coord-eu-west-1",
"nonce": "b7f3d10b",
"chain_id": 12345
}
```
Signed form includes:
```json
"signature": {
"alg": "Ed25519",
"key_id": "miner-ed25519-2025-09",
"sig": "Fql0..."
}
```
## Future Extensions
- Multi-signature receipts (miner + coordinator attestations).
- ZK-proof metadata for privacy-preserving verification.
- On-chain receipt anchors with Merkle proofs.