oib/aitbc
1
0
Fork 0
Code Issues Pull Requests Actions 6 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/`