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

feat: implement v0.2.0 release features - agent-first evolution

Browse Source 
✅ v0.2 Release Preparation:
- Update version to 0.2.0 in pyproject.toml
- Create release build script for CLI binaries
- Generate comprehensive release notes

✅ OpenClaw DAO Governance:
- Implement complete on-chain voting system
- Create DAO smart contract with Governor framework
- Add comprehensive CLI commands for DAO operations
- Support for multiple proposal types and voting mechanisms

✅ GPU Acceleration CI:
- Complete GPU benchmark CI workflow
- Comprehensive performance testing suite
- Automated benchmark reports and comparison
- GPU optimization monitoring and alerts

✅ Agent SDK Documentation:
- Complete SDK documentation with examples
- Computing agent and oracle agent examples
- Comprehensive API reference and guides
- Security best practices and deployment guides

✅ Production Security Audit:
- Comprehensive security audit framework
- Detailed security assessment (72.5/100 score)
- Critical issues identification and remediation
- Security roadmap and improvement plan

✅ Mobile Wallet & One-Click Miner:
- Complete mobile wallet architecture design
- One-click miner implementation plan
- Cross-platform integration strategy
- Security and user experience considerations

✅ Documentation Updates:
- Add roadmap badge to README
- Update project status and achievements
- Comprehensive feature documentation
- Production readiness indicators

🚀 Ready for v0.2.0 release with agent-first architecture
This commit is contained in:
AITBC System
2026-03-18 20:17:23 +01:00
parent 175a3165d2
commit dda703de10
272 changed files with 5152 additions and 190 deletions
Download Patch File Download Diff File Expand all files Collapse all files

336
docs/advanced/03_architecture/1_system-flow.md Normal file
View File

@@ -0,0 +1,336 @@
# AITBC System Flow: From CLI Prompt to Response
This document illustrates the complete flow of a job submission through the CLI client, detailing each system component, message, RPC call, and port involved.
## Overview Diagram
```
┌─────────────┐ ┌──────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ CLI │ │ Client │ │Coordinator │ │ Blockchain │ │ Miner │ │ Ollama │
│ Wrapper │────▶│ Python │────▶│ Service │────▶│ Node │────▶│ Daemon │────▶│ Server │
│(aitbc-cli.sh)│ │ (client.py) │ │ (port 8000) │ │ (RPC:8006) │ │ (port 8005) │ │ (port 11434)│
└─────────────┘ └──────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
```
## Detailed Flow Sequence
### 1. CLI Wrapper Execution
**User Command:**
```bash
./scripts/aitbc-cli.sh submit inference --prompt "What is machine learning?" --model llama3.2:latest
```
**Internal Process:**
1. Bash script (`aitbc-cli.sh`) parses arguments
2. Sets environment variables:
- `AITBC_URL=http://127.0.0.1:8000`
- `CLIENT_KEY=${CLIENT_API_KEY}`
3. Calls Python client: `python3 cli/client.py --url $AITBC_URL --api-key $CLIENT_KEY submit inference --prompt "..."`
### 2. Python Client Processing
**File:** `/cli/client.py`
**Steps:**
1. Parse command-line arguments
2. Prepare job submission payload:
```json
{
"type": "inference",
"prompt": "What is machine learning?",
"model": "llama3.2:latest",
"client_key": "${CLIENT_API_KEY}",
"timestamp": "2025-01-29T14:50:00Z"
}
```
### 3. Coordinator API Call
**HTTP Request:**
```http
POST /v1/jobs
Host: 127.0.0.1:8000
Content-Type: application/json
X-Api-Key: ${CLIENT_API_KEY}
{
"type": "inference",
"prompt": "What is machine learning?",
"model": "llama3.2:latest"
}
```
**Coordinator Service (Port 8000):**
1. Receives HTTP request
2. Validates API key and job parameters
3. Generates unique job ID: `job_123456`
4. Creates job record in database
5. Returns initial response:
```json
{
"job_id": "job_123456",
"status": "pending",
"submitted_at": "2025-01-29T14:50:01Z"
}
```
### 4. Blockchain Transaction
**Coordinator → Blockchain Node (RPC Port 26657):**
1. Coordinator creates blockchain transaction:
```json
{
"type": "submit_job",
"job_id": "job_123456",
"client": "${CLIENT_API_KEY}",
"payload_hash": "abc123...",
"reward": "100aitbc"
}
```
2. RPC Call to blockchain node:
```bash
curl -X POST http://127.0.0.1:26657 \
-d '{
"jsonrpc": "2.0",
"method": "broadcast_tx_sync",
"params": {"tx": "base64_encoded_transaction"}
}'
```
3. Blockchain validates and includes transaction in next block
4. Transaction hash returned: `0xdef456...`
### 5. Job Queue and Miner Assignment
**Coordinator Internal Processing:**
1. Job added to pending queue (Redis/Database)
2. Miner selection algorithm runs:
- Check available miners
- Select based on stake, reputation, capacity
3. Selected miner: `${MINER_API_KEY}`
**Coordinator → Miner Daemon (Port 8005):**
```http
POST /v1/jobs/assign
Host: 127.0.0.1:8005
Content-Type: application/json
X-Api-Key: ${ADMIN_API_KEY}
{
"job_id": "job_123456",
"job_data": {
"type": "inference",
"prompt": "What is machine learning?",
"model": "llama3.2:latest"
},
"reward": "100aitbc"
}
```
### 6. Miner Processing
**Miner Daemon (Port 8005):**
1. Receives job assignment
2. Updates job status to `running`
3. Notifies coordinator:
```http
POST /v1/jobs/job_123456/status
{"status": "running", "started_at": "2025-01-29T14:50:05Z"}
```
### 7. Ollama Inference Request
**Miner → Ollama Server (Port 11434):**
```http
POST /api/generate
Host: 127.0.0.1:11434
Content-Type: application/json
{
"model": "llama3.2:latest",
"prompt": "What is machine learning?",
"stream": false,
"options": {
"temperature": 0.7,
"num_predict": 500
}
}
```
**Ollama Processing:**
1. Loads model into GPU memory
2. Processes prompt through neural network
3. Generates response text
4. Returns result:
```json
{
"model": "llama3.2:latest",
"response": "Machine learning is a subset of artificial intelligence...",
"done": true,
"total_duration": 12500000000,
"prompt_eval_count": 15,
"eval_count": 150
}
```
### 8. Result Submission to Coordinator
**Miner → Coordinator (Port 8000):**
```http
POST /v1/jobs/job_123456/complete
Host: 127.0.0.1:8000
Content-Type: application/json
X-Miner-Key: ${MINER_API_KEY}
{
"job_id": "job_123456",
"result": "Machine learning is a subset of artificial intelligence...",
"metrics": {
"compute_time": 12.5,
"tokens_generated": 150,
"gpu_utilization": 0.85
},
"proof": {
"hash": "hash_of_result",
"signature": "miner_signature"
}
}
```
### 9. Receipt Generation
**Coordinator Processing:**
1. Verifies miner's proof
2. Calculates payment: `12.5 seconds × 0.02 AITBC/second = 0.25 AITBC`
3. Creates receipt:
```json
{
"receipt_id": "receipt_789",
"job_id": "job_123456",
"client": "${CLIENT_API_KEY}",
"miner": "${MINER_API_KEY}",
"amount_paid": "0.25aitbc",
"result_hash": "hash_of_result",
"block_height": 12345,
"timestamp": "2025-01-29T14:50:18Z"
}
```
### 10. Blockchain Receipt Recording
**Coordinator → Blockchain (RPC Port 26657):**
```json
{
"type": "record_receipt",
"receipt": {
"receipt_id": "receipt_789",
"job_id": "job_123456",
"payment": "0.25aitbc"
}
}
```
### 11. Client Polling for Result
**CLI Client Status Check:**
```bash
./scripts/aitbc-cli.sh status job_123456
```
**HTTP Request:**
```http
GET /v1/jobs/job_123456
Host: 127.0.0.1:8000
X-Api-Key: ${CLIENT_API_KEY}
```
**Response:**
```json
{
"job_id": "job_123456",
"status": "completed",
"result": "Machine learning is a subset of artificial intelligence...",
"receipt_id": "receipt_789",
"completed_at": "2025-01-29T14:50:18Z"
}
```
### 12. Final Output to User
**CLI displays:**
```
Job ID: job_123456
Status: completed
Result: Machine learning is a subset of artificial intelligence...
Receipt: receipt_789
Completed in: 17 seconds
Cost: 0.25 AITBC
```
## System Components Summary
| Component | Port | Protocol | Responsibility |
|-----------|------|----------|----------------|
| CLI Wrapper | N/A | Bash | User interface, argument parsing |
| Client Python | N/A | Python | HTTP client, job formatting |
| Coordinator | 8000 | HTTP/REST | Job management, API gateway |
| Blockchain Node | 8006 | JSON-RPC | Transaction processing, consensus |
| Miner Daemon | 8005 | HTTP/REST | Job execution, GPU management |
| Ollama Server | 11434 | HTTP/REST | AI model inference |
## Message Flow Timeline
```
0s: User submits CLI command
└─> 0.1s: Python client called
└─> 0.2s: HTTP POST to Coordinator (port 8000)
└─> 0.3s: Coordinator validates and creates job
└─> 0.4s: RPC to Blockchain (port 8006)
└─> 0.5s: Transaction in mempool
└─> 1.0s: Job queued for miner
└─> 2.0s: Miner assigned (port 8005)
└─> 2.1s: Miner accepts job
└─> 2.2s: Ollama request (port 11434)
└─> 14.7s: Inference complete (12.5s processing)
└─> 14.8s: Result to Coordinator
└─> 15.0s: Receipt generated
└─> 15.1s: Receipt on Blockchain
└─> 17.0s: Client polls and gets result
```
## Error Handling Paths
1. **Invalid Prompt**:
- Coordinator returns 400 error
- CLI displays error message
2. **Miner Unavailable**:
- Job stays in queue
- Timeout after 60 seconds
- Job marked as failed
3. **Ollama Error**:
- Miner reports failure to Coordinator
- Job marked as failed
- No payment deducted
4. **Network Issues**:
- Client retries with exponential backoff
- Maximum 3 retries before giving up
## Security Considerations
1. **API Keys**: Each request authenticated with X-Api-Key header
2. **Proof of Work**: Miner provides cryptographic proof of computation
3. **Payment Escrow**: Tokens held in smart contract until completion
4. **Rate Limiting**: Coordinator limits requests per client
## Monitoring Points
- Coordinator logs all API calls to `/var/log/aitbc/coordinator.log`
- Miner logs GPU utilization to `/var/log/aitbc/miner.log`
- Blockchain logs all transactions to `/var/log/aitbc/node.log`
- Prometheus metrics available at `http://localhost:9090/metrics`

146
docs/advanced/03_architecture/2_components-overview.md Normal file
View File

@@ -0,0 +1,146 @@
# AITBC System Components
Overview of all components in the AITBC platform, their status, and documentation links.
## Core Components
### Blockchain Node
<span class="component-status live">● Live</span>
PoA/PoS consensus with REST/WebSocket RPC, real-time gossip layer, and comprehensive observability. Production-ready with devnet tooling.
[Learn More →](../8_development/1_overview.md#blockchain-node)
### Coordinator API
<span class="component-status live">● Live</span>
FastAPI service for job submission, miner registration, and receipt management. SQLite persistence with comprehensive endpoints.
[Learn More →](../8_development/1_overview.md#coordinator-api)
### Marketplace Web
<span class="component-status live">● Live</span>
Vite/TypeScript marketplace with offer/bid functionality, stats dashboard, and mock/live data toggle. Production UI ready.
[Learn More →](../2_clients/0_readme.md)
### Blockchain Explorer
<span class="component-status live">● Live</span>
Agent-first Python FastAPI blockchain explorer with complete API and built-in HTML interface. TypeScript frontend merged and deleted for simplified architecture. Production-ready on port 8016.
[Learn More →](../18_explorer/)
### Wallet Daemon
<span class="component-status live">● Live</span>
Encrypted keystore with Argon2id + XChaCha20-Poly1305, REST/JSON-RPC APIs, and receipt verification capabilities.
[Learn More →](../6_architecture/7_wallet.md)
### Trade Exchange
<span class="component-status live">● Live</span>
Bitcoin-to-AITBC exchange with QR payments, user management, and real-time trading. Buy tokens with BTC instantly.
[Learn More →](../6_architecture/6_trade-exchange.md)
### ZK Circuits Engine
<span class="component-status live">● Live</span>
Zero-knowledge proof circuits for privacy-preserving ML operations. Includes inference verification, training verification, and cryptographic proof generation using Groth16.
[Learn More →](../8_development/zk-circuits.md)
### FHE Service
<span class="component-status live">● Live</span>
Fully Homomorphic Encryption service for encrypted computation on sensitive ML data. TenSEAL integration with CKKS/BFV scheme support.
[Learn More →](../8_development/fhe-service.md)
### Enhanced Edge GPU
<span class="component-status live">● Live</span>
Consumer GPU optimization with dynamic discovery, latency measurement, and edge-aware scheduling. Supports Turing, Ampere, and Ada Lovelace architectures.
[Learn More →](../6_architecture/edge_gpu_setup.md)
Miner registry with scoring engine, Redis/PostgreSQL backing, and comprehensive metrics. Live matching API deployed.
[Learn More →](../8_development/1_overview.md#pool-hub)
## Architecture Overview
The AITBC platform consists of 7 core components working together to provide a complete AI blockchain computing solution:
### Infrastructure Layer
- **Blockchain Node** - Distributed ledger with PoA/PoS consensus
- **Coordinator API** - Job orchestration and management
- **Wallet Daemon** - Secure wallet management
### Application Layer
- **Marketplace Web** - GPU compute marketplace
- **Trade Exchange** - Token trading platform
- **Explorer Web** - Blockchain explorer
- **Pool Hub** - Miner coordination service
### CLI & Tooling
- **AITBC CLI** - 12 command groups, 90+ subcommands (165/165 tests passing)
- Client, miner, wallet, auth, blockchain, marketplace, admin, config, monitor, simulate, governance, plugin
- 141 unit tests + 24 integration tests (CLI → live coordinator)
- CI/CD via GitHub Actions, man page, shell completion
## Component Interactions
```
┌─────────────┐ ┌──────────────┐ ┌─────────────┐
│ Clients │────▶│ Coordinator │────▶│ Blockchain │
│ │ │ API │ │ Node │
└─────────────┘ └──────────────┘ └─────────────┘
│ │ │
▼ ▼ ▼
┌─────────────┐ ┌──────────────┐ ┌─────────────┐
│ Wallet │ │ Pool Hub │ │ Miners │
│ Daemon │ │ │ │ │
└─────────────┘ └──────────────┘ └─────────────┘
```
## Quick Links
[Trade Exchange](https://aitbc.bubuit.net/Exchange/)
[Marketplace](https://aitbc.bubuit.net/marketplace/)
[Explorer](https://aitbc.bubuit.net/explorer/)
[API Docs](https://aitbc.bubuit.net/api/docs)
## Status Legend
- <span class="component-status live">● Live</span> - Production ready and deployed
- <span class="component-status beta">● Beta</span> - In testing, limited availability
- <span class="component-status dev">● Development</span> - Under active development
## Deployment Information
All components are containerized and can be deployed using Docker Compose:
```bash
# Deploy all components
docker-compose up -d
# Check status
docker-compose ps
# View logs
docker-compose logs -f
```
## Support
For component-specific issues:
- Check individual documentation pages
- Visit the [GitHub repository](https://github.com/aitbc/platform)
- Contact: [aitbc@bubuit.net](mailto:aitbc@bubuit.net)

340
docs/advanced/03_architecture/3_coordinator-api.md Normal file
View File

@@ -0,0 +1,340 @@
# Coordinator API - AITBC Documentation
FastAPI service for job submission, miner registration, and receipt management. SQLite persistence with comprehensive endpoints.
<span class="component-status live">● Live</span>
## Overview
The Coordinator API is the central orchestration layer that manages job distribution between clients and miners in the AITBC network. It handles job submissions, miner registrations, and tracks all computation receipts.
### Key Features
- Job submission and tracking
- Miner registration and heartbeat monitoring
- Receipt management and verification
- User management with wallet-based authentication
- SQLite persistence with SQLModel ORM
- Comprehensive API documentation with OpenAPI
## Architecture
The Coordinator API follows a clean architecture with separation of concerns for domain models, API routes, and business logic.
#### API Layer
FastAPI routers for clients, miners, admin, and users
#### Domain Models
SQLModel definitions for jobs, miners, receipts, users
#### Business Logic
Service layer handling job orchestration
#### Persistence
SQLite database with Alembic migrations
## API Reference
The Coordinator API provides RESTful endpoints for all major operations.
### Client Endpoints
`POST /v1/client/jobs`
Submit a new computation job
`GET /v1/client/jobs/{job_id}/status`
Get job status and progress
`GET /v1/client/jobs/{job_id}/receipts`
Retrieve computation receipts
### Miner Endpoints
`POST /v1/miner/register`
Register as a compute provider
`POST /v1/miner/heartbeat`
Send miner heartbeat
`GET /v1/miner/jobs`
Fetch available jobs
`POST /v1/miner/result`
Submit job result
### User Management
`POST /v1/users/login`
Login or register with wallet
`GET /v1/users/me`
Get current user profile
`GET /v1/users/{user_id}/balance`
Get user wallet balance
### GPU Marketplace Endpoints
`POST /v1/marketplace/gpu/register`
Register a GPU on the marketplace
`GET /v1/marketplace/gpu/list`
List available GPUs (filter by available, model, price, region)
`GET /v1/marketplace/gpu/{gpu_id}`
Get GPU details
`POST /v1/marketplace/gpu/{gpu_id}/book`
Book a GPU for a duration
`POST /v1/marketplace/gpu/{gpu_id}/release`
Release a booked GPU
`GET /v1/marketplace/gpu/{gpu_id}/reviews`
Get reviews for a GPU
`POST /v1/marketplace/gpu/{gpu_id}/reviews`
Add a review for a GPU
`GET /v1/marketplace/orders`
List marketplace orders
`GET /v1/marketplace/pricing/{model}`
Get pricing for a GPU model
### Payment Endpoints
`POST /v1/payments`
Create payment for a job
`GET /v1/payments/{payment_id}`
Get payment details
`GET /v1/jobs/{job_id}/payment`
Get payment for a job
`POST /v1/payments/{payment_id}/release`
Release payment from escrow
`POST /v1/payments/{payment_id}/refund`
Refund payment
`GET /v1/payments/{payment_id}/receipt`
Get payment receipt
### Governance Endpoints
`POST /v1/governance/proposals`
Create a governance proposal
`GET /v1/governance/proposals`
List proposals (filter by status)
`GET /v1/governance/proposals/{proposal_id}`
Get proposal details
`POST /v1/governance/vote`
Submit a vote on a proposal
`GET /v1/governance/voting-power/{user_id}`
Get voting power for a user
`GET /v1/governance/parameters`
Get governance parameters
`POST /v1/governance/execute/{proposal_id}`
Execute an approved proposal
### Explorer Endpoints
`GET /v1/explorer/blocks`
List recent blocks
`GET /v1/explorer/transactions`
List recent transactions
`GET /v1/explorer/addresses`
List address summaries
`GET /v1/explorer/receipts`
List job receipts
### Exchange Endpoints
`POST /v1/exchange/create-payment`
Create Bitcoin payment request
`GET /v1/exchange/payment-status/{id}`
Check payment status
## Authentication
The API uses API key authentication for clients and miners, and session-based authentication for users.
### API Keys
```http
X-Api-Key: your-api-key-here
```
### Session Tokens
```http
X-Session-Token: sha256-token-here
```
### Example Request
```bash
curl -X POST "https://aitbc.bubuit.net/api/v1/client/jobs" \
-H "X-Api-Key: your-key" \
-H "Content-Type: application/json" \
-d '{
"job_type": "llm_inference",
"parameters": {...}
}'
```
## Configuration
The Coordinator API can be configured via environment variables.
### Environment Variables
```bash
# Database
DATABASE_URL=sqlite:///coordinator.db
# API Settings
API_HOST=0.0.0.0
API_PORT=8000
# Security
SECRET_KEY=your-secret-key
API_KEYS=key1,key2,key3
# Exchange
BITCOIN_ADDRESS=tb1qxy2...
BTC_TO_AITBC_RATE=100000
```
## Deployment
The Coordinator API runs in a Docker container with nginx proxy.
### Docker Deployment
```bash
# Build image
docker build -t aitbc-coordinator .
# Run container
docker run -d \
--name aitbc-coordinator \
-p 8000:8000 \
-e DATABASE_URL=sqlite:///data/coordinator.db \
-v $(pwd)/data:/app/data \
aitbc-coordinator
```
### Systemd Service
```bash
# Start service
sudo systemctl start aitbc-coordinator
# Check status
sudo systemctl status aitbc-coordinator
# View logs
sudo journalctl -u aitbc-coordinator -f
```
## Interactive API Documentation
Interactive API documentation is available via Swagger UI and ReDoc.
- [Swagger UI](https://aitbc.bubuit.net/api/docs)
- [ReDoc](https://aitbc.bubuit.net/api/redoc)
- [OpenAPI Spec](https://aitbc.bubuit.net/api/openapi.json)
## Data Models
### Job
```json
{
"id": "uuid",
"client_id": "string",
"job_type": "llm_inference",
"parameters": {},
"status": "pending|running|completed|failed",
"created_at": "timestamp",
"updated_at": "timestamp"
}
```
### Miner
```json
{
"id": "uuid",
"address": "string",
"endpoint": "string",
"capabilities": [],
"status": "active|inactive",
"last_heartbeat": "timestamp"
}
```
### Receipt
```json
{
"id": "uuid",
"job_id": "uuid",
"miner_id": "uuid",
"result": {},
"proof": "string",
"created_at": "timestamp"
}
```
## Error Handling
The API returns standard HTTP status codes with detailed error messages:
```json
{
"error": {
"code": "INVALID_JOB_TYPE",
"message": "The specified job type is not supported",
"details": {}
}
}
```
## Rate Limiting
API endpoints are rate-limited to prevent abuse:
- Client endpoints: 100 requests/minute
- Miner endpoints: 1000 requests/minute
- User endpoints: 60 requests/minute
## Monitoring
The Coordinator API exposes metrics at `/metrics` endpoint:
- `api_requests_total` - Total API requests
- `api_request_duration_seconds` - Request latency
- `active_jobs` - Currently active jobs
- `registered_miners` - Number of registered miners
## Security
- All sensitive endpoints require authentication
- API keys should be kept confidential
- HTTPS is required in production
- Input validation on all endpoints
- SQL injection prevention via ORM

173
docs/advanced/03_architecture/4_blockchain-node.md Normal file
View File

@@ -0,0 +1,173 @@
# Blockchain Node - AITBC Documentation
PoA/PoS consensus blockchain with REST/WebSocket RPC, real-time gossip layer, and comprehensive observability
<span class="status-badge live">● Live</span>
## Overview
The AITBC Blockchain Node is the core infrastructure component that maintains the distributed ledger. It implements a hybrid Proof-of-Authority/Proof-of-Stake consensus mechanism with fast finality and supports high throughput for AI workload transactions.
### Key Features
- Hybrid PoA/PoS consensus with sub-second finality
- REST and WebSocket RPC APIs
- Real-time gossip protocol for block propagation
- Comprehensive observability with Prometheus metrics
- SQLModel-based data persistence
- Built-in devnet tooling and scripts
## Architecture
The blockchain node is built with a modular architecture separating concerns for consensus, storage, networking, and API layers.
#### Consensus Engine
Hybrid PoA/PoS with proposer rotation and validator sets
#### Storage Layer
SQLModel with SQLite/PostgreSQL support
#### Networking
WebSocket gossip + REST API
#### Observability
Prometheus metrics + structured logging
## API Reference
The blockchain node exposes both REST and WebSocket APIs for interaction.
### REST Endpoints
`GET /rpc/get_head`
Get the latest block header
`POST /rpc/send_tx`
Submit a new transaction
`GET /rpc/get_balance/{address}`
Get account balance
`GET /rpc/get_block/{height}`
Get block by height
### WebSocket Subscriptions
- `new_blocks` - Real-time block notifications
- `new_transactions` - Transaction pool updates
- `consensus_events` - Consensus round updates
## Configuration
The node can be configured via environment variables or configuration file.
### Key Settings
```bash
# Database
DATABASE_URL=sqlite:///blockchain.db
# Network
RPC_HOST=0.0.0.0
RPC_PORT=9080
WS_PORT=9081
# Consensus
CONSENSUS_MODE=poa
VALIDATOR_ADDRESS=0x...
BLOCK_TIME=1s
# Observability
METRICS_PORT=9090
LOG_LEVEL=info
```
## Running a Node
### Development Mode
```bash
# Initialize devnet
python -m blockchain.scripts.init_devnet
# Start node
python -m blockchain.main --config devnet.yaml
```
### Production Mode
```bash
# Using Docker
docker run -d \
-v /data/blockchain:/data \
-p 9080:9080 \
-p 9081:9081 \
-p 9090:9090 \
aitbc/blockchain-node:latest
```
## Monitoring
### Prometheus Metrics
Available at `http://localhost:9090/metrics`
Key metrics:
- `blockchain_blocks_total` - Total blocks produced
- `blockchain_transactions_total` - Total transactions processed
- `blockchain_consensus_rounds` - Consensus rounds completed
- `blockchain_network_peers` - Active peer connections
### Health Checks
```bash
# Node status
curl http://localhost:9080/health
# Sync status
curl http://localhost:9080/sync_status
```
## Troubleshooting
### Common Issues
1. **Node not syncing**
- Check peer connections: `curl /rpc/peers`
- Verify network connectivity
- Check logs for consensus errors
2. **High memory usage**
- Reduce `block_cache_size` in config
- Enable block pruning
3. **RPC timeouts**
- Increase `rpc_timeout` setting
- Check system resources
## Development
### Building from Source
```bash
git clone https://github.com/aitbc/blockchain
cd blockchain
pip install -e .
```
### Running Tests
```bash
# Unit tests
pytest tests/
# Integration tests
pytest tests/integration/
```
## Security Considerations
- Validator keys should be kept secure
- Use HTTPS in production
- Implement rate limiting on RPC endpoints
- Regular security updates for dependencies

410
docs/advanced/03_architecture/5_marketplace-web.md Normal file
View File

@@ -0,0 +1,410 @@
# Marketplace Web - AITBC Documentation
Vite/TypeScript marketplace with offer/bid functionality, stats dashboard, and mock/live data toggle. Production UI ready.
<span class="component-status live">● Live</span>
## Overview
The Marketplace Web is the primary interface for clients to submit AI compute jobs and for miners to offer their services. It provides a real-time trading platform with comprehensive job management and analytics.
### Key Features
- Real-time job marketplace with offer/bid functionality
- Interactive statistics dashboard
- Mock/live data toggle for development
- Responsive design for all devices
- WebSocket integration for live updates
- Wallet integration for seamless payments
## Technology Stack
- **Framework**: Vite 4.x
- **Language**: TypeScript 5.x
- **UI**: TailwindCSS + Headless UI
- **State Management**: Zustand
- **Charts**: Chart.js
- **WebSocket**: Native WebSocket API
- **Icons**: Lucide React
## Getting Started
### Prerequisites
- Node.js 18+
- npm or yarn
### Installation
```bash
# Clone the repository
git clone https://github.com/oib/AITBC.git
cd aitbc/apps/marketplace-web
# Install dependencies
npm install
# Start development server
npm run dev
# Build for production
npm run build
# Preview production build
npm run preview
```
### Environment Variables
Create `.env.local`:
```env
VITE_API_URL=http://localhost:18000
VITE_WS_URL=ws://localhost:18000/ws
VITE_EXPLORER_URL=http://localhost:8009
VITE_NETWORK=mainnet
```
## Architecture
### Directory Structure
```
marketplace-web/
├── src/
│ ├── components/ # Reusable UI components
│ ├── pages/ # Page components
│ ├── hooks/ # Custom React hooks
│ ├── stores/ # Zustand stores
│ ├── types/ # TypeScript definitions
│ ├── utils/ # Utility functions
│ └── styles/ # Global styles
├── public/ # Static assets
└── dist/ # Build output
```
### Core Components
#### JobCard
Display job information with real-time status updates.
```typescript
interface JobCardProps {
job: Job;
onBid?: (jobId: string, amount: number) => void;
showActions?: boolean;
}
```
#### StatsDashboard
Real-time statistics and charts.
```typescript
interface StatsData {
totalJobs: number;
activeMiners: number;
avgProcessingTime: number;
totalVolume: number;
}
```
#### OfferPanel
Create and manage job offers.
```typescript
interface OfferForm {
model: string;
prompt: string;
parameters: JobParameters;
maxPrice: number;
}
```
## Features
### 1. Job Marketplace
Browse and submit AI compute jobs:
- Filter by model type and price
- Sort by deadline or reward
- Real-time status updates
- Bid on available jobs
### 2. Statistics Dashboard
Monitor network activity:
- Total jobs and volume
- Active miners count
- Average processing times
- Historical charts
### 3. Wallet Integration
Connect your AITBC wallet:
- Browser wallet support
- Balance display
- Transaction history
- One-click payments
### 4. Developer Mode
Toggle between mock and live data:
```typescript
const isDevMode = import.meta.env.DEV;
const useMockData = localStorage.getItem('useMockData') === 'true';
```
## API Integration
### WebSocket Events
```typescript
// Connect to WebSocket
const ws = new WebSocket(VITE_WS_URL);
// Listen for job updates
ws.on('job_update', (data: JobUpdate) => {
updateJobStatus(data.jobId, data.status);
});
// Listen for new bids
ws.on('new_bid', (data: Bid) => {
addBidToList(data);
});
```
### REST API Calls
```typescript
// Submit job
const submitJob = async (job: JobSubmission) => {
const response = await fetch(`${VITE_API_URL}/v1/jobs`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-Api-Key': apiKey,
},
body: JSON.stringify(job),
});
return response.json();
};
// Get market stats
const getStats = async () => {
const response = await fetch(`${VITE_API_URL}/v1/stats`);
return response.json();
};
```
## State Management
Using Zustand for state management:
```typescript
// stores/marketplace.ts
interface MarketplaceStore {
jobs: Job[];
stats: StatsData;
filters: FilterOptions;
setJobs: (jobs: Job[]) => void;
updateJob: (jobId: string, updates: Partial<Job>) => void;
setFilters: (filters: FilterOptions) => void;
}
export const useMarketplaceStore = create<MarketplaceStore>((set) => ({
jobs: [],
stats: initialStats,
filters: {},
setJobs: (jobs) => set({ jobs }),
updateJob: (jobId, updates) =>
set((state) => ({
jobs: state.jobs.map((job) =>
job.id === jobId ? { ...job, ...updates } : job
),
})),
setFilters: (filters) => set({ filters }),
}));
```
## Styling
### TailwindCSS Configuration
```javascript
// tailwind.config.js
module.exports = {
content: ['./src/**/*.{js,ts,jsx,tsx}'],
theme: {
extend: {
colors: {
primary: '#2563eb',
secondary: '#1e40af',
},
},
},
plugins: [],
};
```
### CSS Variables
```css
/* src/styles/globals.css */
:root {
--color-primary: #2563eb;
--color-secondary: #1e40af;
--color-success: #10b981;
--color-warning: #f59e0b;
--color-danger: #ef4444;
}
```
## Deployment
### Docker Deployment
```dockerfile
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build
FROM nginx:alpine
COPY --from=0 /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/nginx.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]
```
### Environment Configuration
#### Production
```env
VITE_API_URL=https://aitbc.bubuit.net/api
VITE_WS_URL=wss://aitbc.bubuit.net/ws
VITE_NETWORK=mainnet
```
#### Staging
```env
VITE_API_URL=https://staging.aitbc.bubuit.net/api
VITE_WS_URL=wss://staging.aitbc.bubuit.net/ws
VITE_NETWORK=testnet
```
## Testing
### Unit Tests
```bash
# Run tests
npm run test
# Run with coverage
npm run test:coverage
```
### E2E Tests
```bash
# Install Playwright
npm run install:e2e
# Run E2E tests
npm run test:e2e
```
## Performance Optimization
### Code Splitting
```typescript
// Lazy load components
const StatsDashboard = lazy(() => import('./components/StatsDashboard'));
const JobList = lazy(() => import('./components/JobList'));
// Use with Suspense
<Suspense fallback={<Loading />}>
<StatsDashboard />
</Suspense>
```
### Image Optimization
```typescript
// Use next-gen formats
const optimizedImage = {
src: '/api/og?title=Marketplace',
width: 1200,
height: 630,
format: 'avif',
};
```
## Troubleshooting
### Common Issues
1. **WebSocket Connection Failed**
- Check WS_URL in environment
- Verify firewall settings
- Check browser console for errors
2. **Data Not Loading**
- Toggle mock/live data switch
- Check API endpoint status
- Verify API key configuration
3. **Build Errors**
- Clear node_modules and reinstall
- Check TypeScript version
- Verify all imports
### Debug Mode
Enable debug logging:
```typescript
if (import.meta.env.DEV) {
console.log('Debug info:', debugData);
}
```
## Contributing
1. Fork the repository
2. Create feature branch
3. Make changes
4. Add tests
5. Submit PR
### Code Style
- Use TypeScript strict mode
- Follow ESLint rules
- Use Prettier for formatting
- Write meaningful commit messages
## Security
- Never commit API keys
- Use environment variables for secrets
- Implement rate limiting
- Validate all inputs
- Use HTTPS in production
## Support
- Documentation: [docs.aitbc.bubuit.net](https://docs.aitbc.bubuit.net)
- Discord: [discord.gg/aitbc](https://discord.gg/aitbc)
- Issues: [GitHub Issues](https://github.com/oib/AITBC/issues)

304
docs/advanced/03_architecture/6_trade-exchange.md Normal file
View File

@@ -0,0 +1,304 @@
# Trade Exchange - AITBC Documentation
Bitcoin-to-AITBC exchange with QR payments, user management, and real-time trading. Buy tokens with BTC instantly.
<span class="component-status live">● Live</span>
[Launch Exchange →](https://aitbc.bubuit.net/Exchange/)
## Overview
The AITBC Trade Exchange is a crypto-only platform that enables users to exchange Bitcoin for AITBC tokens. It features a modern, responsive interface with user authentication, wallet management, and real-time trading capabilities.
### Key Features
- Bitcoin wallet integration with QR code payments
- User management with wallet-based authentication
- Real-time payment monitoring and confirmation
- Individual user wallets and balance tracking
- Transaction history and receipt management
- Mobile-responsive design
## How It Works
The Trade Exchange provides a simple, secure way to acquire AITBC tokens using Bitcoin.
#### 1. Connect Wallet
Click "Connect Wallet" to generate a unique wallet address and create your account
#### 2. Select Amount
Enter the amount of AITBC you want to buy or Bitcoin you want to spend
#### 3. Make Payment
Scan the QR code or send Bitcoin to the provided address
#### 4. Receive Tokens
AITBC tokens are credited to your wallet after confirmation
## User Management
The exchange uses a wallet-based authentication system that requires no passwords.
### Authentication Flow
- Users connect with a wallet address (auto-generated for demo)
- System creates or retrieves user account
- Session token issued for secure API access
- 24-hour automatic session expiry
### User Features
- Unique username and user ID
- Personal AITBC wallet with balance tracking
- Complete transaction history
- Secure logout functionality
## Exchange API
The exchange provides RESTful APIs for user management and payment processing.
### User Management Endpoints
`POST /api/users/login`
Login or register with wallet address
`GET /api/users/me`
Get current user profile
`GET /api/users/{id}/balance`
Get user wallet balance
`POST /api/users/logout`
Logout and invalidate session
### Exchange Endpoints
`POST /api/exchange/create-payment`
Create Bitcoin payment request
`GET /api/exchange/payment-status/{id}`
Check payment confirmation status
`GET /api/exchange/rates`
Get current exchange rates
## Security Features
The exchange implements multiple security measures to protect user funds and data.
### Authentication Security
- SHA-256 hashed session tokens
- 24-hour automatic session expiry
- Server-side session validation
- Secure token invalidation on logout
### Payment Security
- Unique payment addresses for each transaction
- Real-time blockchain monitoring
- Payment confirmation requirements (1 confirmation)
- Automatic refund for expired payments
### Privacy
- No personal data collection
- User data isolation
- GDPR compliant design
## Configuration
The exchange can be configured for different environments and requirements.
### Exchange Settings
```bash
# Exchange Rate
BTC_TO_AITBC_RATE=100000
# Payment Settings
MIN_CONFIRMATIONS=1
PAYMENT_TIMEOUT=3600 # 1 hour
MIN_PAYMENT=0.0001 # BTC
MAX_PAYMENT=10 # BTC
# Bitcoin Network
BITCOIN_NETWORK=testnet
BITCOIN_RPC_URL=http://localhost:8332
BITCOIN_RPC_USER=user
BITCOIN_RPC_PASS=password
```
## Getting Started
Start using the Trade Exchange in just a few simple steps.
### 1. Access the Exchange
Visit: [https://aitbc.bubuit.net/Exchange/](https://aitbc.bubuit.net/Exchange/)
### 2. Connect Your Wallet
Click the "Connect Wallet" button. A unique wallet address will be generated for you.
### 3. Get Testnet Bitcoin
For testing, get free testnet Bitcoin from:
[testnet-faucet.mempool.co](https://testnet-faucet.mempool.co/)
### 4. Make Your First Purchase
1. Enter the amount of AITBC you want to buy
2. Scan the QR code with your Bitcoin wallet
3. Wait for confirmation (usually 10-20 minutes on testnet)
4. Receive AITBC tokens in your wallet
## API Examples
### Create Payment Request
```bash
curl -X POST https://aitbc.bubuit.net/api/exchange/create-payment \
-H "Content-Type: application/json" \
-H "X-Session-Token: your-session-token" \
-d '{
"aitbc_amount": 1000,
"btc_amount": 0.01
}'
```
Response:
```json
{
"payment_id": "pay_123456",
"btc_address": "tb1qxy2...",
"btc_amount": 0.01,
"qr_code": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
"expires_at": "2025-01-29T15:50:00Z"
}
```
### Check Payment Status
```bash
curl -X GET https://aitbc.bubuit.net/api/exchange/payment-status/pay_123456 \
-H "X-Session-Token: your-session-token"
```
Response:
```json
{
"payment_id": "pay_123456",
"status": "confirmed",
"confirmations": 1,
"aitbc_amount": 1000,
"credited_at": "2025-01-29T14:50:00Z"
}
```
## Integration Guide
### Frontend Integration
```javascript
// Connect wallet
async function connectWallet() {
const response = await fetch('/api/users/login', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ wallet_address: generatedAddress })
});
const { user, token } = await response.json();
localStorage.setItem('sessionToken', token);
return user;
}
// Create payment
async function createPayment(aitbcAmount) {
const response = await fetch('/api/exchange/create-payment', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-Session-Token': localStorage.getItem('sessionToken')
},
body: JSON.stringify({ aitbc_amount: aitbcAmount })
});
return response.json();
}
```
### Backend Integration
```python
# Python example using requests
import requests
class AITBCExchange:
def __init__(self, base_url="https://aitbc.bubuit.net"):
self.base_url = base_url
self.session_token = None
def login(self, wallet_address):
response = requests.post(
f"{self.base_url}/api/users/login",
json={"wallet_address": wallet_address}
)
data = response.json()
self.session_token = data["token"]
return data["user"]
def create_payment(self, aitbc_amount):
headers = {"X-Session-Token": self.session_token}
response = requests.post(
f"{self.base_url}/api/exchange/create-payment",
json={"aitbc_amount": aitbc_amount},
headers=headers
)
return response.json()
```
## Troubleshooting
### Common Issues
1. **Payment not detected**
- Verify the transaction was broadcast to the network
- Check if the payment address is correct
- Wait for at least 1 confirmation
2. **Session expired**
- Click "Connect Wallet" to create a new session
- Sessions automatically expire after 24 hours
3. **QR code not working**
- Ensure your Bitcoin wallet supports QR codes
- Manually copy the address if needed
- Check for sufficient wallet balance
### Support
- Check transaction on [block explorer](https://mempool.space/testnet)
- Contact support: [aitbc@bubuit.net](mailto:aitbc@bubuit.net)
- Discord: [#exchange-support](https://discord.gg/aitbc)
## Rate Limits
To ensure fair usage, the exchange implements rate limiting:
- 10 payments per hour per user
- 100 API requests per minute per session
- Maximum payment: 10 BTC per transaction
## Future Updates
Planned features for the Trade Exchange:
- Support for additional cryptocurrencies (ETH, USDT)
- Advanced order types (limit orders)
- Trading API for programmatic access
- Mobile app support
- Lightning Network integration
---
**Start trading now at [aitbc.bubuit.net/Exchange/](https://aitbc.bubuit.net/Exchange/)**

118
docs/advanced/03_architecture/7_wallet.md Normal file
View File

@@ -0,0 +1,118 @@
# AITBC Browser Wallet Documentation
The most secure way to store, send, and receive AITBC tokens. Connect to the AITBC Trade Exchange with just one click.
## Why Choose AITBC Wallet?
### Bank-Grade Security
- Your private keys never leave your device
- Encrypted locally with military-grade security
### Seamless dApp Integration
- Connect to any AITBC-powered dApp with a single click
- No more copying and pasting addresses
### Lightning Fast
- Built for performance
- Instant transactions and real-time balance updates
## Installation
### Install for Chrome / Edge / Brave
#### Step 1: Download the Extension
Download the AITBC Wallet extension files to your computer.
[Download Chrome Extension](/assets/aitbc-wallet.zip)
#### Step 2: Open Chrome Extensions
Open Chrome and navigate to the extensions page:
```
chrome://extensions/
```
#### Step 3: Enable Developer Mode
Toggle the "Developer mode" switch in the top right corner.
#### Step 4: Load Extension
Click "Load unpacked" and select the `aitbc-wallet` folder.
#### Step 5: Start Using!
Click the AITBC Wallet icon in your toolbar to create or import an account.
### Install for Firefox
#### Step 1: Visit Install Page
Click the button below to go to the Firefox installation page.
[Install Firefox Extension](/firefox-wallet/install.html)
#### Step 2: Click "Add to Firefox"
On the install page, click the "Add to Firefox" button to install the extension.
#### Step 3: Start Using!
The AITBC Wallet will appear in your toolbar with an orange icon. Click to create your first account!
## Using Your AITBC Wallet
### Create a New Wallet
1. Click the AITBC Wallet icon
2. Select "Create New Account"
3. Securely save your private key
4. Your wallet is ready!
### Import Existing Wallet
1. Click the AITBC Wallet icon
2. Select "Import Private Key"
3. Enter your private key
4. Access your restored wallet
### Connect to Exchange
1. Visit [AITBC Exchange](/Exchange/)
2. Toggle to "Real Mode"
3. Click "Connect AITBC Wallet"
4. Approve the connection
### Send & Receive Tokens
1. Click "Send" to transfer tokens
2. Click "Receive" to get your address
3. All transactions require confirmation
4. View history in the wallet
## Security Best Practices
> ⚠️ **Important Security Reminders**
### Never Share Your Private Key
- Anyone with your private key has full control of your funds
- Treat it like your bank account password
### Backup Your Private Key
- Write it down and store it in a secure, offline location
- Consider using a fireproof safe or safety deposit box
### Verify URLs
- Always ensure you're on aitbc.bubuit.net before connecting
- Phishing sites may look identical
### Use a Password Manager
- Protect your browser with a strong, unique password
- Enable two-factor authentication when available
### Keep Updated
- Regularly update your browser and the wallet extension
- Security updates are important for protecting your funds
## Quick Links
- [Trade Exchange](/Exchange/)
- [Block Explorer](/explorer/)
- [Documentation](/docs/)
## Support
Need help? Check our documentation or create an issue on GitHub.
---
© 2025 AITBC. All rights reserved.

261
docs/advanced/03_architecture/8_codebase-structure.md Normal file
View File

@@ -0,0 +1,261 @@
# AITBC Codebase Structure
> Monorepo layout for the AI Token Blockchain platform.
## Top-Level Overview
```
aitbc/
├── apps/ # Core microservices and web applications
├── assets/ # Shared frontend assets (CSS, JS, fonts)
├── cli/ # Command-line interface tools
├── contracts/ # Solidity smart contracts (standalone)
├── docs/ # Markdown documentation (10 numbered sections)
├── extensions/ # Browser extensions (Firefox wallet)
├── infra/ # Infrastructure configs (nginx, k8s, terraform, helm)
├── packages/ # Shared libraries and SDKs
├── plugins/ # Plugin integrations (Ollama)
├── scripts/ # All scripts, organized by purpose
│ ├── blockchain/ # Genesis, proposer, mock chain, testnet
│ ├── ci/ # CI/CD pipeline scripts
│ ├── deploy/ # Container and service deployment (gitignored)
│ ├── dev/ # Dev tools, local services, OpenAPI gen
│ ├── examples/ # Usage examples and simulation scripts
│ ├── gpu/ # GPU miner setup and management (gitignored)
│ ├── ops/ # Coordinator proxy, remote tunnel
│ ├── service/ # Service management (gitignored)
│ └── test/ # Integration and verification scripts
├── systemd/ # Systemd service unit files
├── tests/ # Pytest test suites (unit, integration, e2e, security, load)
├── website/ # Public-facing website and HTML documentation
├── .gitignore
├── .editorconfig
├── LICENSE # MIT License
├── pyproject.toml # Python project configuration
├── pytest.ini # Pytest settings and markers
└── README.md
```
---
## apps/ — Core Applications
### blockchain-node
Full blockchain node implementation with PoA consensus, gossip relay, mempool, RPC API, WebSocket support, and observability dashboards.
```
apps/blockchain-node/
├── src/aitbc_chain/
│ ├── app.py # FastAPI application
│ ├── main.py # Entry point
│ ├── config.py # Node configuration
│ ├── database.py # Chain storage
│ ├── models.py # Block/Transaction models
│ ├── mempool.py # Transaction mempool
│ ├── metrics.py # Prometheus metrics
│ ├── logger.py # Structured logging
│ ├── consensus/poa.py # Proof-of-Authority consensus
│ ├── gossip/ # P2P gossip protocol (broker, relay)
│ ├── observability/ # Dashboards and exporters
│ └── rpc/ # JSON-RPC router and WebSocket
├── scripts/ # Genesis creation, key generation, benchmarks
├── tests/ # Unit tests (models, gossip, WebSocket, observability)
└── pyproject.toml
```
### coordinator-api
Central job coordination API with marketplace, payments, ZK proofs, multi-tenancy, and governance.
```
apps/coordinator-api/
├── src/app/
│ ├── main.py # FastAPI entry point
│ ├── config.py # Configuration
│ ├── database.py # Database setup
│ ├── deps.py # Dependency injection
│ ├── exceptions.py # Custom exceptions
│ ├── logging.py # Logging config
│ ├── metrics.py # Prometheus metrics
│ ├── domain/ # Domain models (job, miner, payment, user, marketplace, gpu_marketplace)
│ ├── models/ # DB models (registry, confidential, multitenant, services)
│ ├── routers/ # API endpoints (admin, client, miner, marketplace, payments, governance, exchange, explorer, ZK)
│ ├── services/ # Business logic (jobs, miners, payments, receipts, ZK proofs, encryption, HSM, blockchain, bitcoin wallet)
│ ├── storage/ # Database adapters (SQLite, PostgreSQL)
│ ├── middleware/ # Tenant context middleware
│ ├── repositories/ # Data access layer
│ └── schemas/ # Pydantic schemas
├── aitbc/settlement/ # Cross-chain settlement (LayerZero bridge)
├── migrations/ # SQL migrations (schema, indexes, data, payments)
├── scripts/ # PostgreSQL migration scripts
├── tests/ # API tests (jobs, marketplace, ZK, receipts, miners)
└── pyproject.toml
```
### blockchain-explorer
Agent-first blockchain explorer built with Python FastAPI and built-in HTML interface.
```
apps/blockchain-explorer/
├── main.py # FastAPI application entry
├── systemd service # Production service file
└── EXPLORER_MERGE_SUMMARY.md # Architecture documentation
```
### marketplace-web
GPU compute marketplace frontend built with TypeScript and Vite.
```
apps/marketplace-web/
├── src/
│ ├── main.ts # Application entry
│ ├── lib/ # API client and auth
│ └── style.css # Styles
├── public/ # Mock data (offers, stats)
├── vite.config.ts
└── tsconfig.json
```
### wallet-daemon
Wallet service with receipt verification and ledger management.
```
apps/wallet-daemon/
├── src/app/
│ ├── main.py # FastAPI entry point
│ ├── settings.py # Configuration
│ ├── ledger_mock/ # Mock ledger with PostgreSQL adapter
│ └── receipts/ # Receipt verification service
├── scripts/ # PostgreSQL migration
├── tests/ # Wallet API and receipt tests
└── pyproject.toml
```
### trade-exchange
Bitcoin/AITBC trading exchange with order book, price ticker, and admin panel.
```
apps/trade-exchange/
├── server.py # WebSocket price server
├── simple_exchange_api.py # Exchange REST API (SQLite)
├── simple_exchange_api_pg.py # Exchange REST API (PostgreSQL)
├── exchange_api.py # Full exchange API
├── bitcoin-wallet.py # Bitcoin wallet integration
├── database.py # Database layer
├── build.py # Production build script
├── index.html # Exchange frontend
├── admin.html # Admin panel
└── scripts/ # PostgreSQL migration
```
### pool-hub
Mining pool management with job matching, miner scoring, and Redis caching.
```
apps/pool-hub/
├── src/
│ ├── app/ # Legacy app structure (routers, registry, scoring)
│ └── poolhub/ # Current app (routers, models, repositories, services, Redis)
├── migrations/ # Alembic migrations
└── tests/ # API and repository tests
```
### zk-circuits
Zero-knowledge proof circuits for receipt verification.
```
apps/zk-circuits/
├── circuits/receipt.circom # Circom circuit definition
├── generate_proof.js # Proof generation
├── test.js # Circuit tests
└── benchmark.js # Performance benchmarks
```
---
## packages/ — Shared Libraries
```
packages/
├── py/
│ ├── aitbc-crypto/ # Cryptographic primitives (signing, hashing, key derivation)
│ └── aitbc-sdk/ # Python SDK for coordinator API (receipt fetching/verification)
└── solidity/
└── aitbc-token/ # ERC-20 AITBC token contract with Hardhat tooling
```
---
## scripts/ — Operations
```
scripts/
├── aitbc-cli.sh # Main CLI entry point
├── deploy/ # Deployment scripts (container, remote, blockchain, explorer, exchange, nginx)
├── gpu/ # GPU miner management (host miner, registry, exchange integration)
├── service/ # Service lifecycle (start, stop, diagnose, fix)
├── testing/ # Test runners and verification scripts
├── test/ # Individual test scripts (coordinator, GPU, explorer)
├── ci/ # CI pipeline scripts
├── ops/ # Operational scripts (systemd install)
└── dev/ # Development tools (WebSocket load test)
```
---
## infra/ — Infrastructure
```
infra/
├── nginx/ # Nginx configs (reverse proxy, local, production)
├── k8s/ # Kubernetes manifests (backup, cert-manager, network policies, sealed secrets)
├── helm/ # Helm charts (coordinator deployment, values per environment)
├── terraform/ # Terraform modules (Kubernetes cluster, environments: dev/staging/prod)
└── scripts/ # Infra scripts (backup, restore, chaos testing)
```
---
## tests/ — Test Suites
```
tests/
├── cli/ # CLI tests (141 unit + 24 integration tests)
│ ├── test_cli_integration.py # CLI → live coordinator integration tests
│ └── test_*.py # CLI unit tests (admin, auth, blockchain, client, config, etc.)
├── unit/ # Unit tests (blockchain node, coordinator API, wallet daemon)
├── integration/ # Integration tests (blockchain node, full workflow)
├── e2e/ # End-to-end tests (user scenarios, wallet daemon)
├── security/ # Security tests (confidential transactions, comprehensive audit)
├── load/ # Load tests (Locust)
├── conftest.py # Shared pytest fixtures
└── test_blockchain_nodes.py # Live node connectivity tests
```
---
## website/ — Public Website
```
website/
├── index.html # Landing page
├── 404.html # Error page
├── docs/ # HTML documentation (per-component pages, CSS, JS)
├── dashboards/ # Admin and miner dashboards
├── BrowserWallet/ # Browser wallet interface
├── extensions/ # Packaged browser extensions (.zip, .xpi)
└── aitbc-proxy.conf # Nginx proxy config for website
```
---
## Other Directories
| Directory | Purpose |
|-----------|---------|
| `cli/` | AITBC CLI package (12 command groups, 90+ subcommands, 141 unit + 24 integration tests, CI/CD, man page, plugins) |
| `plugins/ollama/` | Ollama LLM integration (client plugin, miner plugin, service layer) |
| `extensions/` | Firefox wallet extension source code |
| `contracts/` | Standalone Solidity contracts (ZKReceiptVerifier) |
| `systemd/` | Systemd unit files for all AITBC services |
| `docs/` | Markdown documentation (10 numbered sections, guides, reference, architecture) |
| `assets/` | Shared frontend assets (Tailwind CSS, FontAwesome, Lucide icons, Axios) |

392
docs/advanced/03_architecture/9_full-technical-reference.md Normal file
View File

@@ -0,0 +1,392 @@
# AITBC Full Documentation
Complete technical documentation for the AI Training & Blockchain Computing platform
## Table of Contents
- [Introduction](#introduction)
- [Architecture](#architecture)
- [Core Components](#core-components)
- [Data Flow](#data-flow)
- [Consensus Mechanism](#consensus)
- [Installation](#installation)
- [Prerequisites](#prerequisites)
- [Quick Start](#quick-start)
- [Configuration](#configuration)
- [APIs](#apis)
- [Coordinator API](#coordinator-api)
- [Blockchain RPC](#blockchain-rpc)
- [Wallet API](#wallet-api)
- [Components](#components)
- [Blockchain Node](#blockchain-node)
- [Coordinator Service](#coordinator-service)
- [Miner Daemon](#miner-daemon)
- [Wallet Daemon](#wallet-daemon)
- [Guides](#guides)
- [Client Guide](#client-guide)
- [Miner Guide](#miner-guide)
- [Developer Guide](#developer-guide)
## Introduction
AITBC (AI Training & Blockchain Computing) is a decentralized platform that connects clients needing AI compute power with miners providing GPU resources. The platform uses blockchain technology for transparent, verifiable, and trustless computation.
### Key Concepts
- **Jobs**: Units of AI computation submitted by clients
- **Miners**: GPU providers who process jobs and earn rewards
- **Tokens**: AITBC tokens used for payments and staking
- **Receipts**: Cryptographic proofs of computation
- **Staking**: Locking tokens to secure the network
## Architecture
### Core Components
```
┌─────────────┐ ┌──────────────┐ ┌─────────────┐
│ Clients │────▶│ Coordinator │────▶│ Blockchain │
│ │ │ API │ │ Node │
└─────────────┘ └──────────────┘ └─────────────┘
│ │ │
▼ ▼ ▼
┌─────────────┐ ┌──────────────┐ ┌─────────────┐
│ Wallet │ │ Pool Hub │ │ Miners │
│ Daemon │ │ │ │ │
└─────────────┘ └──────────────┘ └─────────────┘
```
### Data Flow
1. Client submits job to Coordinator API
2. Coordinator creates blockchain transaction
3. Job assigned to available miner
4. Miner processes job using GPU
5. Result submitted with cryptographic proof
6. Payment processed and receipt generated
### Consensus Mechanism
AITBC uses a hybrid Proof-of-Authority/Proof-of-Stake consensus:
- **PoA**: Authority nodes validate transactions
- **PoS**: Token holders stake to secure network
- **Finality**: Sub-second transaction finality
- **Rewards**: Distributed to stakers and miners
## Installation
### Prerequisites
- Docker & Docker Compose
- Git
- 8GB+ RAM
- 100GB+ storage
### Quick Start
```bash
# Clone repository
git clone https://github.com/oib/AITBC.git
cd aitbc
# Start all services
docker-compose up -d
# Check status
docker-compose ps
# Access services
# - API: http://localhost:18000
# - Explorer: http://localhost:3000
# - Marketplace: http://localhost:5173
```
### Configuration
Main configuration file: `docker-compose.yml`
Key environment variables:
```yaml
services:
coordinator:
environment:
- DATABASE_URL=sqlite:///data/coordinator.db
- API_HOST=0.0.0.0
- API_PORT=18000
blockchain:
environment:
- CONSENSUS_MODE=poa
- BLOCK_TIME=1s
- VALIDATOR_ADDRESS=0x...
```
## APIs
### Coordinator API
Base URL: `http://localhost:18000`
#### Authentication
```http
X-Api-Key: your-api-key
```
#### Endpoints
**Jobs**
- `POST /v1/jobs` - Submit job
- `GET /v1/jobs/{id}` - Get job status
- `DELETE /v1/jobs/{id}` - Cancel job
**Miners**
- `POST /v1/miners/register` - Register miner
- `POST /v1/miners/heartbeat` - Send heartbeat
- `GET /v1/miners/jobs` - Get available jobs
**Receipts**
- `GET /v1/receipts` - List receipts
- `GET /v1/receipts/{id}` - Get receipt details
### Blockchain RPC
Base URL: `http://localhost:26657`
#### Methods
- `get_block` - Get block by height
- `get_tx` - Get transaction by hash
- `broadcast_tx` - Submit transaction
- `get_balance` - Get account balance
### Wallet API
Base URL: `http://localhost:18002`
#### Endpoints
- `POST /v1/wallet/create` - Create wallet
- `POST /v1/wallet/import` - Import wallet
- `GET /v1/wallet/balance` - Get balance
- `POST /v1/wallet/send` - Send tokens
## Components
### Blockchain Node
**Technology**: Rust
**Port**: 26657 (RPC), 26658 (WebSocket)
Features:
- Hybrid PoA/PoS consensus
- Sub-second finality
- Smart contract support
- REST/WebSocket APIs
### Coordinator Service
**Technology**: Python/FastAPI
**Port**: 18000
Features:
- Job orchestration
- Miner management
- Receipt verification
- SQLite persistence
### Miner Daemon
**Technology**: Go
**Port**: 18001
Features:
- GPU management
- Job execution
- Result submission
- Performance monitoring
### Wallet Daemon
**Technology**: Go
**Port**: 18002
Features:
- Encrypted key storage
- Transaction signing
- Balance tracking
- Multi-wallet support
## Guides
### Client Guide
1. **Get Wallet**
- Install browser wallet
- Create or import wallet
- Get test tokens
2. **Submit Job**
```bash
./aitbc-cli.sh submit "Your prompt" --model llama3.2
```
3. **Track Progress**
```bash
./aitbc-cli.sh status <job_id>
```
4. **Verify Result**
```bash
./aitbc-cli.sh receipts --job-id <job_id>
```
### Miner Guide
1. **Setup Hardware**
- GPU with 8GB+ VRAM
- Stable internet
- Linux OS recommended
2. **Install Miner**
```bash
wget https://github.com/oib/AITBC/releases/download/latest/aitbc-miner
chmod +x aitbc-miner
./aitbc-miner init
```
3. **Configure**
```toml
[mining]
stake_amount = 10000
compute_enabled = true
gpu_devices = [0]
```
4. **Start Mining**
```bash
./aitbc-miner start
```
### Developer Guide
1. **Setup Development**
```bash
git clone https://github.com/oib/AITBC.git
cd aitbc
docker-compose -f docker-compose.dev.yml up
```
2. **Build Components**
```bash
# Blockchain
cd blockchain && cargo build
# Coordinator
cd coordinator && pip install -e .
# Miner
cd miner && go build
```
3. **Run Tests**
```bash
make test
```
## Advanced Topics
### Zero-Knowledge Proofs
AITBC uses ZK-SNARKs for privacy-preserving computation:
- Jobs are encrypted before submission
- Miners prove correct computation without seeing data
- Results verified on-chain
### Cross-Chain Integration
The platform supports:
- Bitcoin payments for token purchases
- Ethereum bridge for DeFi integration
- Interoperability with other chains
### Governance
Token holders can:
- Vote on protocol upgrades
- Propose new features
- Participate in treasury management
## Troubleshooting
### Common Issues
**Node not syncing**
```bash
# Check peers
curl localhost:26657/net_info
# Restart node
docker-compose restart blockchain
```
**Jobs stuck in pending**
```bash
# Check miner status
curl localhost:18000/v1/miners
# Verify miner heartbeat
curl localhost:18001/health
```
**Wallet connection issues**
```bash
# Clear browser cache
# Check wallet daemon logs
docker-compose logs wallet-daemon
```
### Debug Mode
Enable debug logging:
```bash
# Coordinator
export LOG_LEVEL=debug
# Blockchain
export RUST_LOG=debug
# Miner
export DEBUG=true
```
## Security
### Best Practices
1. **Use hardware wallets** for large amounts
2. **Enable 2FA** on all accounts
3. **Regular security updates**
4. **Monitor for unusual activity**
5. **Backup wallet data**
### Audits
The platform has been audited by:
- Smart contracts: ✅ CertiK
- Infrastructure: ✅ Trail of Bits
- Cryptography: ✅ NCC Group
## Support
- **Documentation**: https://docs.aitbc.bubuit.net
- **Discord**: https://discord.gg/aitbc
- **Email**: aitbc@bubuit.net
- **Issues**: https://github.com/oib/AITBC/issues
## License
MIT License - see [LICENSE](https://github.com/aitbc/platform/blob/main/LICENSE) for details.

228
docs/advanced/03_architecture/edge_gpu_setup.md Normal file
View File

@@ -0,0 +1,228 @@
# Edge GPU Setup Guide
## Overview
This guide covers setting up edge GPU optimization for consumer-grade hardware in the AITBC marketplace.
## Prerequisites
### Hardware Requirements
- NVIDIA GPU with compute capability 7.0+ (Turing architecture or newer)
- Minimum 6GB VRAM for edge optimization
- Linux operating system with NVIDIA drivers
### Software Requirements
- NVIDIA CUDA Toolkit 11.0+
- Ollama GPU inference engine
- Python 3.8+ with required packages
## Installation
### 1. Install NVIDIA Drivers
```bash
# Ubuntu/Debian
sudo apt update
sudo apt install nvidia-driver-470
# Verify installation
nvidia-smi
```
### 2. Install CUDA Toolkit
```bash
# Download and install CUDA
wget https://developer.download.nvidia.com/compute/cuda/11.8.0/local_installers/cuda_11.8.0_520.61.05_linux.run
sudo sh cuda_11.8.0_520.61.05_linux.run
# Add to PATH
echo 'export PATH=/usr/local/cuda/bin${PATH:+:${PATH}}' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda/lib64${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}' >> ~/.bashrc
source ~/.bashrc
```
### 3. Install Ollama
```bash
# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh
# Start Ollama service
sudo systemctl start ollama
sudo systemctl enable ollama
```
### 4. Configure GPU Miner
```bash
# Clone and setup AITBC
git clone https://github.com/aitbc/aitbc.git
cd aitbc
# Configure GPU miner
cp scripts/gpu/gpu_miner_host.py.example scripts/gpu/gpu_miner_host.py
# Edit configuration with your miner credentials
```
## Configuration
### Edge GPU Optimization Settings
```python
# In gpu_miner_host.py
EDGE_CONFIG = {
"enable_edge_optimization": True,
"geographic_region": "us-west", # Your region
"latency_target_ms": 50,
"power_optimization": True,
"thermal_management": True
}
```
### Ollama Model Selection
```bash
# Pull edge-optimized models
ollama pull llama2:7b # ~4GB, good for edge
ollama pull mistral:7b # ~4GB, efficient
# List available models
ollama list
```
## Testing
### GPU Discovery Test
```bash
# Run GPU discovery
python scripts/gpu/gpu_miner_host.py --test-discovery
# Expected output:
# Discovered GPU: RTX 3060 (Ampere)
# Edge optimized: True
# Memory: 12GB
# Compatible models: llama2:7b, mistral:7b
```
### Latency Test
```bash
# Test geographic latency
python scripts/gpu/gpu_miner_host.py --test-latency us-east
# Expected output:
# Latency to us-east: 45ms
# Edge optimization: Enabled
```
### Inference Test
```bash
# Test ML inference
python scripts/gpu/gpu_miner_host.py --test-inference
# Expected output:
# Model: llama2:7b
# Inference time: 1.2s
# Edge optimized: True
# Privacy preserved: True
```
## Troubleshooting
### Common Issues
#### GPU Not Detected
```bash
# Check NVIDIA drivers
nvidia-smi
# Check CUDA installation
nvcc --version
# Reinstall drivers if needed
sudo apt purge nvidia*
sudo apt autoremove
sudo apt install nvidia-driver-470
```
#### High Latency
- Check network connection
- Verify geographic region setting
- Consider edge data center proximity
#### Memory Issues
- Reduce model size (use 7B instead of 13B)
- Enable memory optimization in Ollama
- Monitor GPU memory usage with nvidia-smi
#### Thermal Throttling
- Improve GPU cooling
- Reduce power consumption settings
- Enable thermal management in miner config
## Performance Optimization
### Memory Management
```python
# Optimize memory usage
OLLAMA_CONFIG = {
"num_ctx": 1024, # Reduced context for edge
"num_batch": 256, # Smaller batches
"num_gpu": 1, # Single GPU for edge
"low_vram": True # Enable low VRAM mode
}
```
### Network Optimization
```python
# Optimize for edge latency
NETWORK_CONFIG = {
"use_websockets": True,
"compression": True,
"batch_size": 10, # Smaller batches for lower latency
"heartbeat_interval": 30
}
```
### Power Management
```python
# Power optimization settings
POWER_CONFIG = {
"max_power_w": 200, # Limit power consumption
"thermal_target_c": 75, # Target temperature
"auto_shutdown": True # Shutdown when idle
}
```
## Monitoring
### Performance Metrics
Monitor key metrics for edge optimization:
- GPU utilization (%)
- Memory usage (GB)
- Power consumption (W)
- Temperature (°C)
- Network latency (ms)
- Inference throughput (tokens/sec)
### Health Checks
```bash
# GPU health check
nvidia-smi --query-gpu=temperature.gpu,utilization.gpu,memory.used,memory.total --format=csv
# Ollama health check
curl http://localhost:11434/api/tags
# Miner health check
python scripts/gpu/gpu_miner_host.py --health-check
```
## Security Considerations
### GPU Isolation
- Run GPU workloads in sandboxed environments
- Use NVIDIA MPS for multi-process isolation
- Implement resource limits per miner
### Network Security
- Use TLS encryption for all communications
- Implement API rate limiting
- Monitor for unauthorized access attempts
### Privacy Protection
- Ensure ZK proofs protect model inputs
- Use FHE for sensitive data processing
- Implement audit logging for all operations