# AITBC Full Documentation

Complete technical documentation for the AI Training & Blockchain Computing platform

# Introduction

AITBC (AI Training & Blockchain Computing) is a decentralized platform that combines artificial intelligence and blockchain technology to create a trustless marketplace for AI/ML workloads. The platform enables secure, private, and verifiable computation while maintaining transparency through blockchain technology.

## Key Features

- Decentralized Marketplace: Connect AI service providers with consumers in a trustless environment
- Confidential Computing: Zero-knowledge proofs and secure enclaves protect sensitive data
- High Performance: Sharding and rollups achieve 100,000+ TPS with sub-second finality
- Privacy-Preserving: Advanced cryptography ensures data confidentiality
- Token Economics: Sustainable incentives for all participants
- Autonomous Agents: AI agents can participate as marketplace providers

## Use Cases

#### Healthcare AI

Secure medical image analysis, drug discovery, and patient data processing while maintaining HIPAA compliance through confidential computing.

#### Financial Services

Fraud detection, risk assessment, and algorithmic trading with verifiable computation and audit trails.

#### Scientific Research

Collaborative research with data privacy, reproducible results, and fair attribution through blockchain verification.

# Architecture

## Core Components

graph TB A[Client] --> B[Coordinator API] B --> C[Blockchain Node] B --> D[GPU Providers] C --> E[Consensus Engine] C --> F[Smart Contracts] D --> G[ZK Proofs] F --> H[Receipt Storage]

### Blockchain Node

The blockchain node implements a hybrid Proof of Authority/Proof of Stake consensus mechanism with three operational modes:

- FAST Mode: 100-200ms finality, up to 50,000 TPS
- BALANCED Mode: 500ms-1s finality, up to 20,000 TPS
- SECURE Mode: 2-5s finality, up to 10,000 TPS

### Coordinator API

The coordinator serves as the central hub for marketplace operations:

- Job scheduling and management
- Receipt verification and storage
- Provider registration and reputation tracking
- Multi-tenant support with isolation
- Real-time metrics and analytics

### GPU Service Provider

Decentralized compute providers offer various AI/ML services:

- Model inference (text, image, audio, video)
- Model training and fine-tuning
- Data preprocessing and augmentation
- Result verification with ZK proofs
- Cross-chain compatibility

## Data Flow

sequenceDiagram participant C as Client participant API as Coordinator API participant P as Provider participant BC as Blockchain C->>API: Submit Job Request API->>API: Validate & Match Provider API->>P: Forward Job P->>P: Execute Computation P->>P: Generate ZK Proof P->>API: Submit Results + Proof API->>API: Verify Proof API->>BC: Store Receipt BC->>C: Notify Completion C->>API: Retrieve Results

## Consensus Mechanism

The hybrid consensus combines the speed of Proof of Authority with the decentralization of Proof of Stake:

### Mode Selection Algorithm

    def determine_mode(network_metrics):
        load = network_metrics.utilization
        auth_availability = network_metrics.authority_uptime
        stake_participation = network_metrics.stake_ratio

        if load < 0.3 and auth_availability > 0.9:
            return ConsensusMode.FAST
        elif load > 0.7 or stake_participation > 0.8:
            return ConsensusMode.SECURE
        else:
            return ConsensusMode.BALANCED

### Validator Selection

#### Authority-Only Selection

- VRF-based random selection from 21 authorities
- 100ms block time
- 2/3 signature threshold

#### Hybrid Selection

- 70% authority, 30% staker selection
- 500ms block time
- 2/3 authority + 1/3 stake threshold

#### Stake-Weighted Selection

- Full stake-weighted selection
- 2s block time
- 2/3 stake threshold

# Installation

## Prerequisites

System Requirements:

- Linux (Ubuntu 20.04+) or macOS (10.15+)
- 16GB RAM minimum (32GB recommended)
- 100GB free storage
- Docker 20.10+ and Docker Compose
- Node.js 16+ (for frontend development)
- Python 3.8+ (for backend development)
- Go 1.19+ (for blockchain node)

## Quick Start

### Option 1: Docker Compose (Recommended)

    # Clone the repository
    git clone https://github.com/oib/AITBC.git
    cd aitbc

    # Copy environment configuration
    cp .env.example .env
    # Edit .env with your settings

    # Start all services
    docker-compose up -d

    # Check status
    docker-compose ps

### Option 2: Manual Installation

    # Install dependencies
    ./scripts/install-dependencies.sh

    # Build blockchain node
    make build-node

    # Build coordinator
    make build-coordinator

    # Initialize database
    ./scripts/init-db.sh

    # Start services
    ./scripts/start-all.sh

## Configuration

### Environment Variables

Variable | Description | Default
--- | --- | ---
AITBC_NETWORK | Network mode (dev/test/main) | dev
AITBC_CHAIN_ID | Blockchain chain ID | 1337
AITBC_CONSENSUS_MODE | Consensus mode | BALANCED
AITBC_DB_URL | Database connection string | postgresql://localhost/aitbc
AITBC_REDIS_URL | Redis connection string | redis://localhost:6379

### Node Configuration

    # config/node.toml
    [network]
    listen_addr = "0.0.0.0:30303"
    discovery_addr = "0.0.0.0:30304"

    [consensus]
    mode = "BALANCED"
    validator_count = 21
    stake_minimum = 1000

    [storage]
    data_dir = "/var/lib/aitbc"
    prune = true
    prune_threshold = "100GB"

# APIs

## Coordinator API

### Authentication

All API requests require authentication using JWT tokens:

    curl -X POST http://localhost:8080/api/v1/auth/login \
      -H "Content-Type: application/json" \
      -d '{"address": "0x...", "signature": "0x..."}'

### Endpoints

Job Management

    # Create a job
    POST /api/v1/jobs
    {
      "type": "inference",
      "model_id": "gpt-4",
      "input_data": "Hello, world!",
      "requirements": {
        "max_tokens": 100,
        "temperature": 0.7
      }
    }

    # Get job status
    GET /api/v1/jobs/{job_id}

    # List jobs
    GET /api/v1/jobs?status=pending&limit=10

    # Cancel a job
    DELETE /api/v1/jobs/{job_id}

Receipt Verification

    # Verify a receipt
    POST /api/v1/receipts/verify
    {
      "receipt_id": "0x...",
      "proof": "0x...",
      "public_inputs": ["0x..."]
    }

    # Get receipt details
    GET /api/v1/receipts/{receipt_id}

## Blockchain API

### JSON-RPC Endpoints

    # Get latest block
    curl -X POST http://localhost:8545 \
      -H "Content-Type: application/json" \
      -d '{"jsonrpc":"2.0","method":"eth_getBlockByNumber","params":["latest", false],"id":1}'

    # Send transaction
    curl -X POST http://localhost:8545 \
      -H "Content-Type: application/json" \
      -d '{"jsonrpc":"2.0","method":"eth_sendRawTransaction","params":["0x..."],"id":1}'

### WebSocket Subscriptions

    # Subscribe to new blocks
    ws://localhost:8545

    {"jsonrpc":"2.0","id":1,"method":"eth_subscribe","params":["newHeads"]}

## Wallet API

### Wallet Operations

    # Create wallet
    POST /api/v1/wallet/create
    {
      "password": "secure-password",
      "mnemonic_language": "english"
    }

    # Unlock wallet
    POST /api/v1/wallet/unlock
    {
      "wallet_id": "wallet-uuid",
      "password": "secure-password"
    }

    # Sign transaction
    POST /api/v1/wallet/sign
    {
      "wallet_id": "wallet-uuid",
      "transaction": "0x..."
    }

# Development

## Building

### Prerequisites

    # Install build dependencies
    sudo apt-get install build-essential libssl-dev

    # Install Rust (for blockchain node)
    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
    source ~/.cargo/env

    # Install Go
    wget https://go.dev/dl/go1.19.linux-amd64.tar.gz
    sudo tar -C /usr/local -xzf go1.19.linux-amd64.tar.gz

### Build Components

    # Build blockchain node
    cd blockchain-node
    cargo build --release

    # Build coordinator
    cd coordinator-api
    go build -o bin/coordinator

    # Build wallet daemon
    cd wallet-daemon
    go build -o bin/wallet

    # Build frontend
    cd marketplace-web
    npm install
    npm run build

## Testing

### Unit Tests

    # Run all tests
    make test

    # Run specific package tests
    make test-unit PACKAGE=coordinator

    # Run with coverage
    make test-coverage

### Integration Tests

    # Start test environment
    docker-compose -f docker-compose.test.yml up -d

    # Run integration tests
    make test-integration

    # Clean up
    docker-compose -f docker-compose.test.yml down -v

### Load Testing

    # Install Locust
    pip install locust

    # Run load tests
    locust -f tests/load/locustfile.py --host=http://localhost:8080

## Contributing

We welcome contributions! Please see our contributing guide for details.

### Development Workflow

1. Fork the repository on Gitea
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

### Code Style

Rust

    # Format code
    cargo fmt

    # Run linter
    cargo clippy -- -D warnings

    # Run audit
    cargo audit

Go

    # Format code
    go fmt ./...

    # Run linter
    golangci-lint run

    # Run security check
    gosec ./...

# Security

## Threat Model

Our comprehensive threat model covers:

- Privacy attacks and mitigations
- Consensus security
- Smart contract vulnerabilities
- Network-level attacks
- Economic attacks

See the full threat modeling document for detailed analysis.

## Security Audits

Completed Audits:

- Trail of Bits (2024) - Smart Contracts
- CertiK (2024) - Protocol Security
- OpenZeppelin (2023) - Token Economics

## Bug Bounty Program

We offer rewards up to $100,000 for critical vulnerabilities:

- Critical: $50,000 - $100,000
- High: $10,000 - $50,000
- Medium: $1,000 - $10,000
- Low: $100 - $1,000

Report vulnerabilities at: andreas.fleckl@bubuit.net

# Reference

## Glossary

Term | Definition
--- | ---
ZK Proof | Zero-knowledge proof enabling verification without revealing inputs
Receipt | Cryptographic proof of computation completion
Provider | Node offering AI/ML computation services
Coordinator | Central service managing marketplace operations

## Frequently Asked Questions

### General

#### What blockchain does AITBC use?

AITBC implements its own blockchain with a hybrid consensus mechanism, but supports cross-chain interoperability with Ethereum, Polygon, and BSC.

#### How are transactions verified?

Through a combination of zero-knowledge proofs for privacy and traditional blockchain validation for transparency.

### Technical

#### What programming languages are used?

- Rust for blockchain node
- Go for coordinator and wallet
- TypeScript/React for frontend
- Python for AI/ML components

#### How can I run a node?

See the installation guide for detailed instructions on running a full node, validator node, or GPU provider.

## Support

Get help through:

- Documentation: Full Documentation
- Community: Discord
- Issues: GitHub Issues
- Email: andreas.fleckl@bubuit.net