docs: simplify README to focus on core value proposition and remove obsolete trade-exchange HTML
- Rewrite README overview to emphasize decentralized GPU marketplace concept over technical implementation details - Condense architecture section from detailed component listing to high-level flow diagram - Remove directory structure table and consolidate documentation links - Streamline quick start section by removing redundant deployment/test instructions - Delete unused `apps/trade-exchange/index
This commit is contained in:
oib
181
README.md
181
README.md
@@ -4,165 +4,50 @@ Decentralized GPU compute marketplace with blockchain-based job coordination, Ol
|
||||
|
||||
[](LICENSE)
|
||||
|
||||
## Overview
|
||||
## The Idea
|
||||
|
||||
AITBC is a full-stack blockchain platform that connects GPU compute providers (miners) with AI workload consumers (clients) through a decentralized marketplace. The system handles job submission, miner matching, GPU inference execution, cryptographic receipt generation, and on-chain payment settlement.
|
||||
AITBC creates a decentralized marketplace where GPU providers can earn tokens by running AI inference workloads, while clients pay for compute access through a transparent blockchain system. The platform eliminates centralized cloud providers by using cryptographic proofs and smart contracts to ensure fair payment and verifiable computation.
|
||||
|
||||
**Key capabilities:**
|
||||
- **Blockchain nodes** — PoA consensus, gossip relay, WebSocket RPC
|
||||
- **Coordinator API** — Job lifecycle, miner registry, GPU marketplace, payments, billing, governance
|
||||
- **GPU mining** — Ollama-based LLM inference with host GPU passthrough
|
||||
- **Wallet daemon** — Balance tracking, receipt verification, ledger management
|
||||
- **Trade exchange** — Bitcoin/AITBC trading with order book and price ticker
|
||||
- **ZK circuits** — Zero-knowledge receipt verification (Circom/snarkjs)
|
||||
- **Browser wallet** — Firefox extension for AITBC transactions
|
||||
- **Explorer** — Real-time blockchain explorer (blocks, transactions, addresses, receipts)
|
||||
## Technical Overview
|
||||
|
||||
## Architecture
|
||||
**Core Components:**
|
||||
- **Blockchain Layer** — Proof-of-Authority consensus with transaction receipts
|
||||
- **Coordinator API** — Job marketplace, miner registry, and payment processing
|
||||
- **GPU Mining** — Ollama-based inference with zero-knowledge receipt generation
|
||||
- **Wallet System** — Token management and receipt verification
|
||||
- **Exchange Platform** — Bitcoin/AITBC trading with order matching
|
||||
|
||||
**Key Innovations:**
|
||||
- Zero-knowledge proofs for verifiable computation receipts
|
||||
- GPU marketplace with capability-based matching
|
||||
- Cryptographic payment settlement without trusted intermediaries
|
||||
- Open-source alternative to centralized AI cloud services
|
||||
|
||||
## Architecture Flow
|
||||
|
||||
```
|
||||
Client ──► Coordinator API ──► Pool Hub ──► Miner (GPU/Ollama)
|
||||
│ │
|
||||
▼ ▼
|
||||
Marketplace ZK Receipt
|
||||
│ │
|
||||
▼ ▼
|
||||
Wallet Daemon ◄──── Blockchain Nodes ◄─── Settlement
|
||||
│
|
||||
▼
|
||||
Trade Exchange
|
||||
Clients submit jobs → Coordinator matches miners → GPU inference executes →
|
||||
ZK receipts generated → Blockchain records payments → Tokens transferred
|
||||
```
|
||||
|
||||
## Directory Structure
|
||||
## Technology Stack
|
||||
|
||||
```
|
||||
aitbc/
|
||||
├── apps/ # Core microservices
|
||||
│ ├── blockchain-node/ # PoA blockchain node (FastAPI + gossip)
|
||||
│ ├── coordinator-api/ # Job coordination API (FastAPI)
|
||||
│ ├── explorer-web/ # Blockchain explorer (TypeScript + Vite)
|
||||
│ ├── marketplace-web/ # GPU marketplace frontend (TypeScript + Vite)
|
||||
│ ├── pool-hub/ # Mining pool management (FastAPI + Redis)
|
||||
│ ├── trade-exchange/ # BTC/AITBC exchange (FastAPI + WebSocket)
|
||||
│ ├── wallet-daemon/ # Wallet service (FastAPI)
|
||||
│ └── zk-circuits/ # ZK proof circuits (Circom)
|
||||
├── cli/ # CLI tools (12 command groups, 90+ subcommands)
|
||||
├── contracts/ # Solidity smart contracts
|
||||
├── docs/ # Documentation (10 numbered sections)
|
||||
├── extensions/ # Browser extensions (Firefox wallet)
|
||||
├── infra/ # Infrastructure (nginx, k8s, helm, terraform)
|
||||
├── packages/ # Shared libraries
|
||||
│ ├── py/aitbc-crypto/ # Cryptographic primitives
|
||||
│ ├── py/aitbc-sdk/ # Python SDK
|
||||
│ └── solidity/aitbc-token/# ERC-20 token contract
|
||||
├── plugins/ollama/ # Ollama LLM integration
|
||||
├── scripts/ # All scripts, organized by purpose
|
||||
│ ├── blockchain/ # Genesis, proposer, mock chain
|
||||
│ ├── ci/ # CI/CD pipeline
|
||||
│ ├── dev/ # Dev tools, local services
|
||||
│ ├── examples/ # Usage examples and simulations
|
||||
│ ├── ops/ # Coordinator proxy, tunnels
|
||||
│ └── test/ # Integration and verification
|
||||
├── systemd/ # Systemd service units
|
||||
├── tests/ # Test suites (unit, integration, e2e, security, CLI)
|
||||
└── website/ # Public website and HTML documentation
|
||||
```
|
||||
|
||||
See [docs/README.md](docs/README.md) for the full documentation index.
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Python 3.11+
|
||||
- Node.js 18+ (for web apps and ZK circuits)
|
||||
- PostgreSQL (optional, SQLite for development)
|
||||
- Ollama (for GPU inference)
|
||||
|
||||
### Run Services Locally
|
||||
|
||||
```bash
|
||||
# Start all services
|
||||
./scripts/dev_services.sh
|
||||
|
||||
# Or start individually
|
||||
cd apps/coordinator-api && uvicorn app.main:app --port 8000
|
||||
cd apps/blockchain-node && python -m aitbc_chain.main
|
||||
cd apps/wallet-daemon && uvicorn app.main:app --port 8002
|
||||
```
|
||||
|
||||
### Run Tests
|
||||
|
||||
```bash
|
||||
# CLI tests (141 unit + 24 integration)
|
||||
pytest tests/cli/
|
||||
|
||||
# Coordinator API tests (billing + GPU marketplace)
|
||||
pytest apps/coordinator-api/tests/
|
||||
|
||||
# Blockchain node tests
|
||||
pytest tests/test_blockchain_nodes.py
|
||||
|
||||
# All tests together (208 passing)
|
||||
pytest apps/coordinator-api/tests/ tests/cli/
|
||||
```
|
||||
|
||||
### CLI Usage
|
||||
|
||||
```bash
|
||||
pip install -e .
|
||||
|
||||
# Submit a job
|
||||
aitbc client submit --type inference --prompt "Hello world"
|
||||
|
||||
# Register as a miner
|
||||
aitbc miner register --gpu RTX4090
|
||||
|
||||
# GPU marketplace
|
||||
aitbc marketplace gpu list
|
||||
aitbc marketplace gpu book <gpu_id> --hours 1
|
||||
|
||||
# Wallet and governance
|
||||
aitbc wallet balance
|
||||
aitbc governance propose --type parameter_change --title "Update fee"
|
||||
```
|
||||
|
||||
## Deployment
|
||||
|
||||
Services run in an Incus container with systemd units. See `systemd/` for service definitions and `scripts/deploy/` for deployment automation.
|
||||
|
||||
```bash
|
||||
# Deploy to container
|
||||
./scripts/deploy/deploy-to-container.sh
|
||||
|
||||
# Deploy blockchain nodes
|
||||
./scripts/deploy/deploy-blockchain.sh
|
||||
```
|
||||
|
||||
## Test Results
|
||||
|
||||
| Suite | Tests | Source |
|
||||
|-------|-------|--------|
|
||||
| Blockchain node | 50 | `tests/test_blockchain_nodes.py` |
|
||||
| ZK integration | 8 | `tests/test_zk_integration.py` |
|
||||
| CLI unit tests | 141 | `tests/cli/test_*.py` (9 files) |
|
||||
| CLI integration | 24 | `tests/cli/test_cli_integration.py` |
|
||||
| Billing | 21 | `apps/coordinator-api/tests/test_billing.py` |
|
||||
| GPU marketplace | 22 | `apps/coordinator-api/tests/test_gpu_marketplace.py` |
|
||||
- **Backend**: FastAPI, PostgreSQL, Redis, systemd services
|
||||
- **Blockchain**: Python-based nodes with PoA consensus
|
||||
- **AI Inference**: Ollama with GPU passthrough
|
||||
- **Cryptography**: Circom ZK circuits, Solidity smart contracts
|
||||
- **Frontend**: TypeScript, Vite, React components
|
||||
- **Infrastructure**: Incus containers, nginx reverse proxy
|
||||
|
||||
## Documentation
|
||||
|
||||
| Section | Path | Description |
|
||||
|---------|------|-------------|
|
||||
| Getting Started | [docs/0_getting_started/](docs/0_getting_started/) | Intro, installation, CLI usage |
|
||||
| Clients | [docs/2_clients/](docs/2_clients/) | Job submission, wallet, pricing, API |
|
||||
| Miners | [docs/3_miners/](docs/3_miners/) | GPU setup, registration, earnings |
|
||||
| Blockchain | [docs/4_blockchain/](docs/4_blockchain/) | Node operation, configuration |
|
||||
| Reference | [docs/5_reference/](docs/5_reference/) | CLI reference, architecture specs |
|
||||
| Architecture | [docs/6_architecture/](docs/6_architecture/) | System flow, component details |
|
||||
| Deployment | [docs/7_deployment/](docs/7_deployment/) | Remote deployment, backups |
|
||||
| Development | [docs/8_development/](docs/8_development/) | Setup, contributing, examples |
|
||||
| Security | [docs/9_security/](docs/9_security/) | Security architecture, audit |
|
||||
| Section | Path | Focus |
|
||||
|---------|------|-------|
|
||||
| Getting Started | [docs/0_getting_started/](docs/0_getting_started/) | Installation & basic usage |
|
||||
| Clients | [docs/2_clients/](docs/2_clients/) | Job submission & payments |
|
||||
| Miners | [docs/3_miners/](docs/3_miners/) | GPU setup & earnings |
|
||||
| Architecture | [docs/6_architecture/](docs/6_architecture/) | System design & flow |
|
||||
| Development | [docs/8_development/](docs/8_development/) | Contributing & setup |
|
||||
|
||||
## License
|
||||
|
||||
|
||||
Reference in New Issue
Block a user