Files
aitbc/website/docs/full-documentation.html
oib 07f3a87328 docs: restructure website, optimize HTML, gitignore private files
Website docs (website/docs/):
- Delete 6 stale -md.html duplicates
- Rename docs-clients/miners/developers → clients/miners/developers.html
- Unify header/nav across all 15 pages (new .site-header pattern)
- Fix 34 dead href=# links with real targets
- Upgrade Font Awesome v4→v6 in index.html
- Replace search stub with live client-side search (15-page index)
- Extract all inline CSS into shared docs.css (+630 lines)
- Extract inline theme JS into shared theme.js
- Strip inline style= attributes from 10+ pages
- Add .announce-banner, .source-links, .search-results CSS classes
- Add Markdown Source links to clients/miners/developers pages
- Update components.html title to Architecture & Components
- Move browser-wallet.html to website/wallet/, leave redirect
- Update all dates to February 2026

Website root:
- Delete 6 root-level duplicate HTML files (160KB saved)
- Rewire index.html and 404.html links

Root README.md:
- Fix 8 broken doc links to new numbered folder structure
- Update copyright to 2026

.gitignore + .example files:
- Gitignore private files: .aitbc.yaml, .env, deploy scripts,
  GPU scripts, service scripts, infra configs, .windsurf/, website README
- Create 7 .example files for GitHub users with sanitized templates
- Untrack 47 previously committed private files

Live server:
- Push all website files to aitbc-cascade:/var/www/html/
- Clean stale admin.html and index.nginx-debian.html
2026-02-13 23:18:52 +01:00

665 lines
30 KiB
HTML

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Full Documentation - AITBC</title>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/all.min.css">
<link rel="stylesheet" href="css/docs.css">
</head>
<body>
<!-- Header -->
<header class="site-header">
<div class="container">
<div class="header-inner">
<a href="/" class="brand">
<i class="fas fa-cube"></i>
<span>AITBC</span>
</a>
<nav class="header-nav">
<a href="/">Home</a>
<a href="/explorer/">Explorer</a>
<a href="/Exchange/">Exchange</a>
<a href="/docs/index.html" class="active">Docs</a>
<button id="theme-toggle" class="theme-toggle" title="Toggle theme"><i class="fas fa-sun"></i></button>
</nav>
</div>
</div>
</header>
<!-- Main Content -->
<main>
<div class="container">
<div class="doc-header">
<h1>AITBC Full Documentation</h1>
<p>Complete technical documentation for the AI Training & Blockchain Computing platform</p>
</div>
<div class="doc-grid">
<!-- Sidebar -->
<aside class="sidebar">
<h3>Table of Contents</h3>
<ul>
<li><a href="#introduction">Introduction</a></li>
<li><a href="#architecture">Architecture</a>
<ul>
<li><a href="#core-components" class="sub-item">Core Components</a></li>
<li><a href="#data-flow" class="sub-item">Data Flow</a></li>
<li><a href="#consensus" class="sub-item">Consensus Mechanism</a></li>
</ul>
</li>
<li><a href="#installation">Installation</a>
<ul>
<li><a href="#prerequisites" class="sub-item">Prerequisites</a></li>
<li><a href="#quick-start" class="sub-item">Quick Start</a></li>
<li><a href="#configuration" class="sub-item">Configuration</a></li>
</ul>
</li>
<li><a href="#apis">APIs</a>
<ul>
<li><a href="#coordinator-api" class="sub-item">Coordinator API</a></li>
<li><a href="#blockchain-api" class="sub-item">Blockchain API</a></li>
<li><a href="#wallet-api" class="sub-item">Wallet API</a></li>
</ul>
</li>
<li><a href="#development">Development</a>
<ul>
<li><a href="#building" class="sub-item">Building</a></li>
<li><a href="#testing" class="sub-item">Testing</a></li>
<li><a href="#contributing" class="sub-item">Contributing</a></li>
</ul>
</li>
<li><a href="#security">Security</a>
<ul>
<li><a href="#threat-model" class="sub-item">Threat Model</a></li>
<li><a href="#audits" class="sub-item">Audits</a></li>
<li><a href="#bug-bounty" class="sub-item">Bug Bounty</a></li>
</ul>
</li>
<li><a href="#reference">Reference</a>
<ul>
<li><a href="#glossary" class="sub-item">Glossary</a></li>
<li><a href="#faq" class="sub-item">FAQ</a></li>
<li><a href="#support" class="sub-item">Support</a></li>
</ul>
</li>
</ul>
<h3 style="margin-top: 2rem;">Markdown Docs</h3>
<ul>
<li><a href="https://github.com/oib/AITBC/tree/main/docs/0_getting_started" target="_blank" class="sub-item">0 Getting Started</a></li>
<li><a href="https://github.com/oib/AITBC/tree/main/docs/1_project" target="_blank" class="sub-item">1 Project</a></li>
<li><a href="https://github.com/oib/AITBC/tree/main/docs/2_clients" target="_blank" class="sub-item">2 Clients</a></li>
<li><a href="https://github.com/oib/AITBC/tree/main/docs/3_miners" target="_blank" class="sub-item">3 Miners</a></li>
<li><a href="https://github.com/oib/AITBC/tree/main/docs/4_blockchain" target="_blank" class="sub-item">4 Blockchain</a></li>
<li><a href="https://github.com/oib/AITBC/tree/main/docs/5_reference" target="_blank" class="sub-item">5 Reference</a></li>
<li><a href="https://github.com/oib/AITBC/tree/main/docs/6_architecture" target="_blank" class="sub-item">6 Architecture</a></li>
<li><a href="https://github.com/oib/AITBC/tree/main/docs/7_deployment" target="_blank" class="sub-item">7 Deployment</a></li>
<li><a href="https://github.com/oib/AITBC/tree/main/docs/8_development" target="_blank" class="sub-item">8 Development</a></li>
<li><a href="https://github.com/oib/AITBC/tree/main/docs/9_security" target="_blank" class="sub-item">9 Security</a></li>
</ul>
</aside>
<!-- Content -->
<div class="content">
<section id="introduction">
<h1>Introduction</h1>
<p>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.</p>
<h2>Key Features</h2>
<ul>
<li><strong>Decentralized Marketplace</strong>: Connect AI service providers with consumers in a trustless environment</li>
<li><strong>Confidential Computing</strong>: Zero-knowledge proofs and secure enclaves protect sensitive data</li>
<li><strong>High Performance</strong>: Sharding and rollups achieve 100,000+ TPS with sub-second finality</li>
<li><strong>Privacy-Preserving</strong>: Advanced cryptography ensures data confidentiality</li>
<li><strong>Token Economics</strong>: Sustainable incentives for all participants</li>
<li><strong>Autonomous Agents</strong>: AI agents can participate as marketplace providers</li>
</ul>
<h2>Use Cases</h2>
<div class="tabs">
<div class="tab-buttons">
<button class="tab-button active" onclick="switchTab('healthcare')">Healthcare</button>
<button class="tab-button" onclick="switchTab('finance')">Finance</button>
<button class="tab-button" onclick="switchTab('research')">Research</button>
</div>
<div id="healthcare" class="tab-content active">
<h4>Healthcare AI</h4>
<p>Secure medical image analysis, drug discovery, and patient data processing while maintaining HIPAA compliance through confidential computing.</p>
</div>
<div id="finance" class="tab-content">
<h4>Financial Services</h4>
<p>Fraud detection, risk assessment, and algorithmic trading with verifiable computation and audit trails.</p>
</div>
<div id="research" class="tab-content">
<h4>Scientific Research</h4>
<p>Collaborative research with data privacy, reproducible results, and fair attribution through blockchain verification.</p>
</div>
</div>
</section>
<section id="architecture">
<h1>Architecture</h1>
<h2 id="core-components">Core Components</h2>
<div class="mermaid">
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]
</div>
<h3>Blockchain Node</h3>
<p>The blockchain node implements a hybrid Proof of Authority/Proof of Stake consensus mechanism with three operational modes:</p>
<ul>
<li><strong>FAST Mode</strong>: 100-200ms finality, up to 50,000 TPS</li>
<li><strong>BALANCED Mode</strong>: 500ms-1s finality, up to 20,000 TPS</li>
<li><strong>SECURE Mode</strong>: 2-5s finality, up to 10,000 TPS</li>
</ul>
<h3>Coordinator API</h3>
<p>The coordinator serves as the central hub for marketplace operations:</p>
<ul>
<li>Job scheduling and management</li>
<li>Receipt verification and storage</li>
<li>Provider registration and reputation tracking</li>
<li>Multi-tenant support with isolation</li>
<li>Real-time metrics and analytics</li>
</ul>
<h3>GPU Service Provider</h3>
<p>Decentralized compute providers offer various AI/ML services:</p>
<ul>
<li>Model inference (text, image, audio, video)</li>
<li>Model training and fine-tuning</li>
<li>Data preprocessing and augmentation</li>
<li>Result verification with ZK proofs</li>
<li>Cross-chain compatibility</li>
</ul>
<h2 id="data-flow">Data Flow</h2>
<div class="mermaid">
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
</div>
<h2 id="consensus">Consensus Mechanism</h2>
<p>The hybrid consensus combines the speed of Proof of Authority with the decentralization of Proof of Stake:</p>
<h3>Mode Selection Algorithm</h3>
<pre><code>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</code></pre>
<h3>Validator Selection</h3>
<div class="tabs">
<div class="tab-buttons">
<button class="tab-button active" onclick="switchTab('fast-mode')">FAST Mode</button>
<button class="tab-button" onclick="switchTab('balanced-mode')">BALANCED Mode</button>
<button class="tab-button" onclick="switchTab('secure-mode')">SECURE Mode</button>
</div>
<div id="fast-mode" class="tab-content active">
<h4>Authority-Only Selection</h4>
<ul>
<li>VRF-based random selection from 21 authorities</li>
<li>100ms block time</li>
<li>2/3 signature threshold</li>
</ul>
</div>
<div id="balanced-mode" class="tab-content">
<h4>Hybrid Selection</h4>
<ul>
<li>70% authority, 30% staker selection</li>
<li>500ms block time</li>
<li>2/3 authority + 1/3 stake threshold</li>
</ul>
</div>
<div id="secure-mode" class="tab-content">
<h4>Stake-Weighted Selection</h4>
<ul>
<li>Full stake-weighted selection</li>
<li>2s block time</li>
<li>2/3 stake threshold</li>
</ul>
</div>
</div>
</section>
<section id="installation">
<h1>Installation</h1>
<h2 id="prerequisites">Prerequisites</h2>
<div class="alert alert-info">
<strong>System Requirements:</strong>
<ul>
<li>Linux (Ubuntu 20.04+) or macOS (10.15+)</li>
<li>16GB RAM minimum (32GB recommended)</li>
<li>100GB free storage</li>
<li>Docker 20.10+ and Docker Compose</li>
<li>Node.js 16+ (for frontend development)</li>
<li>Python 3.8+ (for backend development)</li>
<li>Go 1.19+ (for blockchain node)</li>
</ul>
</div>
<h2 id="quick-start">Quick Start</h2>
<h3>Option 1: Docker Compose (Recommended)</h3>
<pre><code># 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</code></pre>
<h3>Option 2: Manual Installation</h3>
<pre><code># 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</code></pre>
<h2 id="configuration">Configuration</h2>
<h3>Environment Variables</h3>
<table>
<tr>
<th>Variable</th>
<th>Description</th>
<th>Default</th>
</tr>
<tr>
<td>AITBC_NETWORK</td>
<td>Network mode (dev/test/main)</td>
<td>dev</td>
</tr>
<tr>
<td>AITBC_CHAIN_ID</td>
<td>Blockchain chain ID</td>
<td>1337</td>
</tr>
<tr>
<td>AITBC_CONSENSUS_MODE</td>
<td>Consensus mode</td>
<td>BALANCED</td>
</tr>
<tr>
<td>AITBC_DB_URL</td>
<td>Database connection string</td>
<td>postgresql://localhost/aitbc</td>
</tr>
<tr>
<td>AITBC_REDIS_URL</td>
<td>Redis connection string</td>
<td>redis://localhost:6379</td>
</tr>
</table>
<h3>Node Configuration</h3>
<pre><code># 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"</code></pre>
</section>
<section id="apis">
<h1>APIs</h1>
<h2 id="coordinator-api">Coordinator API</h2>
<h3>Authentication</h3>
<p>All API requests require authentication using JWT tokens:</p>
<pre><code>curl -X POST http://localhost:8080/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{"address": "0x...", "signature": "0x..."}'</code></pre>
<h3>Endpoints</h3>
<div class="code-group">
<div class="code-group-header">Job Management</div>
<div class="code-group-content">
<pre><code># 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}</code></pre>
</div>
</div>
<div class="code-group">
<div class="code-group-header">Receipt Verification</div>
<div class="code-group-content">
<pre><code># 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}</code></pre>
</div>
</div>
<h2 id="blockchain-api">Blockchain API</h2>
<h3>JSON-RPC Endpoints</h3>
<pre><code># 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}'</code></pre>
<h3>WebSocket Subscriptions</h3>
<pre><code># Subscribe to new blocks
ws://localhost:8545
{"jsonrpc":"2.0","id":1,"method":"eth_subscribe","params":["newHeads"]}</code></pre>
<h2 id="wallet-api">Wallet API</h2>
<h3>Wallet Operations</h3>
<pre><code># 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..."
}</code></pre>
</section>
<section id="development">
<h1>Development</h1>
<h2 id="building">Building</h2>
<h3>Prerequisites</h3>
<pre><code># 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</code></pre>
<h3>Build Components</h3>
<pre><code># 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</code></pre>
<h2 id="testing">Testing</h2>
<h3>Unit Tests</h3>
<pre><code># Run all tests
make test
# Run specific package tests
make test-unit PACKAGE=coordinator
# Run with coverage
make test-coverage</code></pre>
<h3>Integration Tests</h3>
<pre><code># 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</code></pre>
<h3>Load Testing</h3>
<pre><code># Install Locust
pip install locust
# Run load tests
locust -f tests/load/locustfile.py --host=http://localhost:8080</code></pre>
<h2 id="contributing">Contributing</h2>
<p>We welcome contributions! Please see our contributing guide for details.</p>
<h3>Development Workflow</h3>
<ol>
<li>Fork the repository on Gitea</li>
<li>Create a feature branch</li>
<li>Make your changes</li>
<li>Add tests for new functionality</li>
<li>Ensure all tests pass</li>
<li>Submit a pull request</li>
</ol>
<h3>Code Style</h3>
<div class="code-group">
<div class="code-group-header">Rust</div>
<div class="code-group-content">
<pre><code># Format code
cargo fmt
# Run linter
cargo clippy -- -D warnings
# Run audit
cargo audit</code></pre>
</div>
</div>
<div class="code-group">
<div class="code-group-header">Go</div>
<div class="code-group-content">
<pre><code># Format code
go fmt ./...
# Run linter
golangci-lint run
# Run security check
gosec ./...</code></pre>
</div>
</div>
</section>
<section id="security">
<h1>Security</h1>
<h2 id="threat-model">Threat Model</h2>
<p>Our comprehensive threat model covers:</p>
<ul>
<li>Privacy attacks and mitigations</li>
<li>Consensus security</li>
<li>Smart contract vulnerabilities</li>
<li>Network-level attacks</li>
<li>Economic attacks</li>
</ul>
<p>See the full threat modeling document for detailed analysis.</p>
<h2 id="audits">Security Audits</h2>
<div class="alert alert-success">
<strong>Completed Audits:</strong>
<ul>
<li>Trail of Bits (2024) - Smart Contracts</li>
<li>CertiK (2024) - Protocol Security</li>
<li>OpenZeppelin (2023) - Token Economics</li>
</ul>
</div>
<h2 id="bug-bounty">Bug Bounty Program</h2>
<p>We offer rewards up to $100,000 for critical vulnerabilities:</p>
<ul>
<li>Critical: $50,000 - $100,000</li>
<li>High: $10,000 - $50,000</li>
<li>Medium: $1,000 - $10,000</li>
<li>Low: $100 - $1,000</li>
</ul>
<p>Report vulnerabilities at: <a href="mailto:aitbc@bubuit.net">aitbc@bubuit.net</a></p>
</section>
<section id="reference">
<h1>Reference</h1>
<h2 id="glossary">Glossary</h2>
<table>
<tr>
<th>Term</th>
<th>Definition</th>
</tr>
<tr>
<td>ZK Proof</td>
<td>Zero-knowledge proof enabling verification without revealing inputs</td>
</tr>
<tr>
<td>Receipt</td>
<td>Cryptographic proof of computation completion</td>
</tr>
<tr>
<td>Provider</td>
<td>Node offering AI/ML computation services</td>
</tr>
<tr>
<td>Coordinator</td>
<td>Central service managing marketplace operations</td>
</tr>
</table>
<h2 id="faq">Frequently Asked Questions</h2>
<h3>General</h3>
<h4>What blockchain does AITBC use?</h4>
<p>AITBC implements its own blockchain with a hybrid consensus mechanism, but supports cross-chain interoperability with Ethereum, Polygon, and BSC.</p>
<h4>How are transactions verified?</h4>
<p>Through a combination of zero-knowledge proofs for privacy and traditional blockchain validation for transparency.</p>
<h3>Technical</h3>
<h4>What programming languages are used?</h4>
<ul>
<li>Rust for blockchain node</li>
<li>Go for coordinator and wallet</li>
<li>TypeScript/React for frontend</li>
<li>Python for AI/ML components</li>
</ul>
<h4>How can I run a node?</h4>
<p>See the installation guide for detailed instructions on running a full node, validator node, or GPU provider.</p>
<h2 id="support">Support</h2>
<p>Get help through:</p>
<ul>
<li>Documentation: <a href="full-documentation.html">Full Documentation</a></li>
<li>Community: <a href="https://discord.gg/aitbc">Discord</a></li>
<li>Issues: <a href="https://github.com/oib/AITBC/issues">GitHub Issues</a></li>
<li>Email: <a href="mailto:aitbc@bubuit.net">aitbc@bubuit.net</a></li>
</ul>
</section>
</div>
</div>
</div>
</main>
<!-- Footer -->
<footer>
<div class="container">
<p>&copy; 2026 AITBC. All rights reserved.</p>
</div>
</footer>
<script src="/js/mermaid.min.js"></script>
<script src="/js/mermaid-init.js"></script>
<script src="js/theme.js"></script>
</body>
</html>