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

chore: standardize configuration, logging, and error handling across blockchain node and coordinator API

Browse Source 
- Add infrastructure.md and workflow files to .gitignore to prevent sensitive info leaks
- Change blockchain node mempool backend default from memory to database for persistence
- Refactor blockchain node logger with StructuredLogFormatter and AuditLogger (consistent with coordinator)
- Add structured logging fields: service, module, function, line number
- Unify coordinator config with Database
This commit is contained in:
oib
2026-02-13 22:39:43 +01:00
parent 0cbd2b507c
commit 06e48ef34b
196 changed files with 4660 additions and 20090 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
.gitignore vendored
View File

@@ -184,3 +184,12 @@ scripts/gpu/*.local.py
# Deployment secrets # Deployment secrets
scripts/deploy/*.secret.* scripts/deploy/*.secret.*
infra/nginx/*.local.conf infra/nginx/*.local.conf
# ===================
# Documentation
# ===================
# Infrastructure docs (contains sensitive network info)
docs/infrastructure.md
# Workflow files (personal, change frequently)
docs/1_project/3_currenttask.md
docs/1_project/4_currentissue.md

2
apps/blockchain-node/src/aitbc_chain/config.py
View File

@@ -32,7 +32,7 @@ class ChainSettings(BaseSettings):
min_fee: int = 0 # Minimum fee to accept into mempool min_fee: int = 0 # Minimum fee to accept into mempool
# Mempool settings # Mempool settings
mempool_backend: str = "memory" # "memory" or "database" mempool_backend: str = "database" # "database" or "memory" (database recommended for persistence)
mempool_max_size: int = 10_000 mempool_max_size: int = 10_000
mempool_eviction_interval: int = 60 # seconds mempool_eviction_interval: int = 60 # seconds

62
apps/blockchain-node/src/aitbc_chain/logger.py
View File

@@ -1,13 +1,16 @@
from __future__ import annotations from __future__ import annotations
import logging import logging
import sys
from datetime import datetime from datetime import datetime
from typing import Any, Optional from typing import Any, Optional
import json import json
class JsonFormatter(logging.Formatter): class StructuredLogFormatter(logging.Formatter):
"""Custom JSON formatter for structured logging - consistent with coordinator API."""
RESERVED = { RESERVED = {
"name", "name",
"msg", "msg",
@@ -34,8 +37,12 @@ class JsonFormatter(logging.Formatter):
def format(self, record: logging.LogRecord) -> str: # type: ignore[override] def format(self, record: logging.LogRecord) -> str: # type: ignore[override]
payload: dict[str, Any] = { payload: dict[str, Any] = {
"timestamp": datetime.utcnow().isoformat() + "Z", "timestamp": datetime.utcnow().isoformat() + "Z",
"service": "aitbc-blockchain-node",
"level": record.levelname, "level": record.levelname,
"logger": record.name, "logger": record.name,
"module": record.module,
"function": record.funcName,
"line": record.lineno,
"message": record.getMessage(), "message": record.getMessage(),
} }
@@ -45,27 +52,66 @@ class JsonFormatter(logging.Formatter):
payload[key] = value payload[key] = value
if record.exc_info: if record.exc_info:
payload["exc_info"] = self.formatException(record.exc_info) payload["exception"] = self.formatException(record.exc_info)
if record.stack_info: if record.stack_info:
payload["stack"] = record.stack_info payload["stack"] = record.stack_info
return json.dumps(payload, default=str) return json.dumps(payload, default=str)
def configure_logging(level: Optional[str] = None) -> None: class AuditLogger:
"""Audit logger for tracking sensitive operations - consistent with coordinator API."""
def __init__(self, logger: logging.Logger):
self.logger = logger
def log(self, action: str, user_id: Optional[str] = None, resource_id: Optional[str] = None,
details: Optional[dict] = None, success: bool = True) -> None:
"""Log an audit event."""
self.logger.info(
"audit_event",
extra={
"audit": {
"action": action,
"user_id": user_id,
"resource_id": resource_id,
"details": details or {},
"success": success
}
}
)
def configure_logging(level: Optional[str] = None, json_format: bool = True) -> None:
"""Configure structured logging for the blockchain node."""
log_level = getattr(logging, (level or "INFO").upper(), logging.INFO) log_level = getattr(logging, (level or "INFO").upper(), logging.INFO)
root = logging.getLogger() root = logging.getLogger()
if root.handlers: root.handlers.clear()
return
if json_format:
handler = logging.StreamHandler(sys.stdout)
formatter = StructuredLogFormatter()
handler.setFormatter(formatter)
else:
handler = logging.StreamHandler(sys.stdout)
handler.setFormatter(
logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
)
handler = logging.StreamHandler()
formatter = JsonFormatter()
handler.setFormatter(formatter)
root.addHandler(handler) root.addHandler(handler)
root.setLevel(log_level) root.setLevel(log_level)
logging.getLogger('uvicorn').setLevel(log_level)
logging.getLogger('uvicorn.access').setLevel(log_level)
def get_logger(name: str) -> logging.Logger: def get_logger(name: str) -> logging.Logger:
"""Get a logger instance."""
if not logging.getLogger().handlers: if not logging.getLogger().handlers:
configure_logging() configure_logging()
return logging.getLogger(name) return logging.getLogger(name)
def get_audit_logger(name: str = "audit") -> AuditLogger:
"""Get an audit logger instance."""
return AuditLogger(get_logger(name))

108
apps/coordinator-api/src/app/config.py
View File

@@ -1,39 +1,83 @@
"""
Unified configuration for AITBC Coordinator API
Provides environment-based adapter selection and consolidated settings.
"""
from pydantic_settings import BaseSettings, SettingsConfigDict from pydantic_settings import BaseSettings, SettingsConfigDict
from typing import List, Optional from typing import List, Optional
from pathlib import Path from pathlib import Path
import os import os
class Settings(BaseSettings): class DatabaseConfig(BaseSettings):
model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8", case_sensitive=False) """Database configuration with adapter selection."""
adapter: str = "sqlite" # sqlite, postgresql
url: Optional[str] = None
pool_size: int = 10
max_overflow: int = 20
pool_pre_ping: bool = True
@property
def effective_url(self) -> str:
"""Get the effective database URL."""
if self.url:
return self.url
# Auto-generate SQLite URL based on environment
if self.adapter == "sqlite":
project_root = self._find_project_root()
db_path = project_root / "data" / "coordinator.db"
db_path.parent.mkdir(parents=True, exist_ok=True)
return f"sqlite:///{db_path}"
elif self.adapter == "postgresql":
return "postgresql://localhost:5432/aitbc_coordinator"
return "sqlite:///:memory:"
@staticmethod
def _find_project_root() -> Path:
"""Find project root by looking for .git directory."""
current = Path(__file__).resolve()
while current.parent != current:
if (current / ".git").exists():
return current
current = current.parent
return Path(__file__).resolve().parents[3]
class Config:
env_file = ".env"
env_file_encoding = "utf-8"
case_sensitive = False
class Settings(BaseSettings):
"""Unified application settings with environment-based configuration."""
model_config = SettingsConfigDict(
env_file=".env",
env_file_encoding="utf-8",
case_sensitive=False,
extra="allow"
)
# Environment
app_env: str = "dev" app_env: str = "dev"
app_host: str = "127.0.0.1" app_host: str = "127.0.0.1"
app_port: int = 8011 app_port: int = 8011
# Use absolute path to avoid database duplicates in different working directories # Database
@property database: DatabaseConfig = DatabaseConfig()
def database_url(self) -> str:
# Find project root by looking for .git directory
current = Path(__file__).resolve()
while current.parent != current:
if (current / ".git").exists():
project_root = current
break
current = current.parent
else:
# Fallback to relative path if .git not found
project_root = Path(__file__).resolve().parents[3]
db_path = project_root / "data" / "coordinator.db"
db_path.parent.mkdir(parents=True, exist_ok=True)
return f"sqlite:///{db_path}"
# API Keys
client_api_keys: List[str] = [] client_api_keys: List[str] = []
miner_api_keys: List[str] = [] miner_api_keys: List[str] = []
admin_api_keys: List[str] = [] admin_api_keys: List[str] = []
# Security
hmac_secret: Optional[str] = None hmac_secret: Optional[str] = None
jwt_secret: Optional[str] = None
jwt_algorithm: str = "HS256"
jwt_expiration_hours: int = 24
# CORS
allow_origins: List[str] = [ allow_origins: List[str] = [
"http://localhost:3000", "http://localhost:3000",
"http://localhost:8080", "http://localhost:8080",
@@ -41,15 +85,41 @@ class Settings(BaseSettings):
"http://localhost:8011" "http://localhost:8011"
] ]
# Job Configuration
job_ttl_seconds: int = 900 job_ttl_seconds: int = 900
heartbeat_interval_seconds: int = 10 heartbeat_interval_seconds: int = 10
heartbeat_timeout_seconds: int = 30 heartbeat_timeout_seconds: int = 30
# Rate Limiting
rate_limit_requests: int = 60 rate_limit_requests: int = 60
rate_limit_window_seconds: int = 60 rate_limit_window_seconds: int = 60
# Receipt Signing
receipt_signing_key_hex: Optional[str] = None receipt_signing_key_hex: Optional[str] = None
receipt_attestation_key_hex: Optional[str] = None receipt_attestation_key_hex: Optional[str] = None
# Logging
log_level: str = "INFO"
log_format: str = "json" # json or text
# Mempool
mempool_backend: str = "database" # database, memory
def validate_secrets(self) -> None:
"""Validate that all required secrets are provided."""
if self.app_env == "production":
if not self.jwt_secret:
raise ValueError("JWT_SECRET environment variable is required in production")
if self.jwt_secret == "change-me-in-production":
raise ValueError("JWT_SECRET must be changed from default value")
@property
def database_url(self) -> str:
"""Get the database URL (backward compatibility)."""
return self.database.effective_url
settings = Settings() settings = Settings()
# Validate secrets on import
settings.validate_secrets()

21
apps/coordinator-api/src/app/deps.py
View File

@@ -1,10 +1,19 @@
from typing import Callable, Annotated """
Dependency injection module for AITBC Coordinator API
Provides unified dependency injection using storage.SessionDep.
"""
from typing import Callable
from fastapi import Depends, Header, HTTPException from fastapi import Depends, Header, HTTPException
from .config import settings from .config import settings
from .storage import SessionDep
class APIKeyValidator: class APIKeyValidator:
"""Validator for API key authentication."""
def __init__(self, allowed_keys: list[str]): def __init__(self, allowed_keys: list[str]):
self.allowed_keys = {key.strip() for key in allowed_keys if key} self.allowed_keys = {key.strip() for key in allowed_keys if key}
@@ -15,12 +24,22 @@ class APIKeyValidator:
def require_client_key() -> Callable[[str | None], str]: def require_client_key() -> Callable[[str | None], str]:
"""Dependency for client API key authentication."""
return APIKeyValidator(settings.client_api_keys) return APIKeyValidator(settings.client_api_keys)
def require_miner_key() -> Callable[[str | None], str]: def require_miner_key() -> Callable[[str | None], str]:
"""Dependency for miner API key authentication."""
return APIKeyValidator(settings.miner_api_keys) return APIKeyValidator(settings.miner_api_keys)
def require_admin_key() -> Callable[[str | None], str]: def require_admin_key() -> Callable[[str | None], str]:
"""Dependency for admin API key authentication."""
return APIKeyValidator(settings.admin_api_keys) return APIKeyValidator(settings.admin_api_keys)
# Legacy aliases for backward compatibility
def get_session():
"""Legacy alias - use SessionDep instead."""
from .storage import get_session
return get_session()

198
apps/coordinator-api/src/app/exceptions.py
View File

@@ -1,83 +1,249 @@
""" """
Exception classes for AITBC coordinator Exception classes and error response schemas for AITBC coordinator
Provides structured error responses for consistent API error handling.
""" """
from datetime import datetime
from typing import Any, Dict, Optional, List
from pydantic import BaseModel, Field
class ErrorDetail(BaseModel):
"""Detailed error information."""
field: Optional[str] = Field(None, description="Field that caused the error")
message: str = Field(..., description="Error message")
code: Optional[str] = Field(None, description="Error code for programmatic handling")
class ErrorResponse(BaseModel):
"""Standardized error response for all API errors."""
error: Dict[str, Any] = Field(..., description="Error information")
timestamp: str = Field(default_factory=lambda: datetime.utcnow().isoformat() + "Z")
request_id: Optional[str] = Field(None, description="Request ID for tracing")
class Config:
json_schema_extra = {
"example": {
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid input data",
"status": 422,
"details": [
{"field": "email", "message": "Invalid email format", "code": "invalid_format"}
]
},
"timestamp": "2026-02-13T21:00:00Z",
"request_id": "req_abc123"
}
}
class AITBCError(Exception): class AITBCError(Exception):
"""Base exception for all AITBC errors""" """Base exception for all AITBC errors"""
pass error_code: str = "INTERNAL_ERROR"
status_code: int = 500
def to_response(self, request_id: Optional[str] = None) -> ErrorResponse:
"""Convert exception to standardized error response."""
return ErrorResponse(
error={
"code": self.error_code,
"message": str(self),
"status": self.status_code,
"details": []
},
request_id=request_id
)
class AuthenticationError(AITBCError): class AuthenticationError(AITBCError):
"""Raised when authentication fails""" """Raised when authentication fails"""
pass error_code: str = "AUTHENTICATION_ERROR"
status_code: int = 401
def __init__(self, message: str = "Authentication failed"):
super().__init__(message)
class AuthorizationError(AITBCError):
"""Raised when authorization fails"""
error_code: str = "AUTHORIZATION_ERROR"
status_code: int = 403
def __init__(self, message: str = "Not authorized to perform this action"):
super().__init__(message)
class RateLimitError(AITBCError): class RateLimitError(AITBCError):
"""Raised when rate limit is exceeded""" """Raised when rate limit is exceeded"""
def __init__(self, message: str, retry_after: int = None): error_code: str = "RATE_LIMIT_EXCEEDED"
status_code: int = 429
def __init__(self, message: str = "Rate limit exceeded", retry_after: int = 60):
super().__init__(message) super().__init__(message)
self.retry_after = retry_after self.retry_after = retry_after
def to_response(self, request_id: Optional[str] = None) -> ErrorResponse:
return ErrorResponse(
error={
"code": self.error_code,
"message": str(self),
"status": self.status_code,
"details": [{"retry_after": self.retry_after}]
},
request_id=request_id
)
class APIError(AITBCError): class APIError(AITBCError):
"""Raised when API request fails""" """Raised when API request fails"""
error_code: str = "API_ERROR"
status_code: int = 500
def __init__(self, message: str, status_code: int = None, response: dict = None): def __init__(self, message: str, status_code: int = None, response: dict = None):
super().__init__(message) super().__init__(message)
self.status_code = status_code self.status_code = status_code or self.status_code
self.response = response self.response = response
class ConfigurationError(AITBCError): class ConfigurationError(AITBCError):
"""Raised when configuration is invalid""" """Raised when configuration is invalid"""
pass error_code: str = "CONFIGURATION_ERROR"
status_code: int = 500
def __init__(self, message: str = "Invalid configuration"):
super().__init__(message)
class ConnectorError(AITBCError): class ConnectorError(AITBCError):
"""Raised when connector operation fails""" """Raised when connector operation fails"""
pass error_code: str = "CONNECTOR_ERROR"
status_code: int = 502
def __init__(self, message: str = "Connector operation failed"):
super().__init__(message)
class PaymentError(ConnectorError): class PaymentError(ConnectorError):
"""Raised when payment operation fails""" """Raised when payment operation fails"""
pass error_code: str = "PAYMENT_ERROR"
status_code: int = 402
def __init__(self, message: str = "Payment operation failed"):
super().__init__(message)
class ValidationError(AITBCError): class ValidationError(AITBCError):
"""Raised when data validation fails""" """Raised when data validation fails"""
pass error_code: str = "VALIDATION_ERROR"
status_code: int = 422
def __init__(self, message: str = "Validation failed", details: List[ErrorDetail] = None):
super().__init__(message)
self.details = details or []
def to_response(self, request_id: Optional[str] = None) -> ErrorResponse:
return ErrorResponse(
error={
"code": self.error_code,
"message": str(self),
"status": self.status_code,
"details": [{"field": d.field, "message": d.message, "code": d.code} for d in self.details]
},
request_id=request_id
)
class WebhookError(AITBCError): class WebhookError(AITBCError):
"""Raised when webhook processing fails""" """Raised when webhook processing fails"""
pass error_code: str = "WEBHOOK_ERROR"
status_code: int = 500
def __init__(self, message: str = "Webhook processing failed"):
super().__init__(message)
class ERPError(ConnectorError): class ERPError(ConnectorError):
"""Raised when ERP operation fails""" """Raised when ERP operation fails"""
pass error_code: str = "ERP_ERROR"
status_code: int = 502
def __init__(self, message: str = "ERP operation failed"):
super().__init__(message)
class SyncError(ConnectorError): class SyncError(ConnectorError):
"""Raised when synchronization fails""" """Raised when synchronization fails"""
pass error_code: str = "SYNC_ERROR"
status_code: int = 500
def __init__(self, message: str = "Synchronization failed"):
super().__init__(message)
class TimeoutError(AITBCError): class TimeoutError(AITBCError):
"""Raised when operation times out""" """Raised when operation times out"""
pass error_code: str = "TIMEOUT_ERROR"
status_code: int = 504
def __init__(self, message: str = "Operation timed out"):
super().__init__(message)
class TenantError(ConnectorError): class TenantError(ConnectorError):
"""Raised when tenant operation fails""" """Raised when tenant operation fails"""
pass error_code: str = "TENANT_ERROR"
status_code: int = 400
def __init__(self, message: str = "Tenant operation failed"):
super().__init__(message)
class QuotaExceededError(ConnectorError): class QuotaExceededError(ConnectorError):
"""Raised when resource quota is exceeded""" """Raised when resource quota is exceeded"""
pass error_code: str = "QUOTA_EXCEEDED"
status_code: int = 429
def __init__(self, message: str = "Quota exceeded", limit: int = None):
super().__init__(message)
self.limit = limit
def to_response(self, request_id: Optional[str] = None) -> ErrorResponse:
details = [{"limit": self.limit}] if self.limit else []
return ErrorResponse(
error={
"code": self.error_code,
"message": str(self),
"status": self.status_code,
"details": details
},
request_id=request_id
)
class BillingError(ConnectorError): class BillingError(ConnectorError):
"""Raised when billing operation fails""" """Raised when billing operation fails"""
pass error_code: str = "BILLING_ERROR"
status_code: int = 402
def __init__(self, message: str = "Billing operation failed"):
super().__init__(message)
class NotFoundError(AITBCError):
"""Raised when a resource is not found"""
error_code: str = "NOT_FOUND"
status_code: int = 404
def __init__(self, message: str = "Resource not found"):
super().__init__(message)
class ConflictError(AITBCError):
"""Raised when there's a conflict (e.g., duplicate resource)"""
error_code: str = "CONFLICT"
status_code: int = 409
def __init__(self, message: str = "Resource conflict"):
super().__init__(message)

90
apps/coordinator-api/src/app/logging.py
View File

@@ -1,19 +1,90 @@
""" """
Logging configuration for the AITBC Coordinator API Logging configuration for the AITBC Coordinator API
Provides structured JSON logging for better observability and log parsing.
""" """
import logging import logging
import sys import sys
from typing import Any, Dict import json
from datetime import datetime
from typing import Any, Dict, Optional
from pythonjsonlogger import jsonlogger
def setup_logging(level: str = "INFO") -> None: class StructuredLogFormatter(jsonlogger.JsonFormatter):
"""Custom JSON formatter for structured logging."""
def add_fields(self, log_record: Dict[str, Any], record: logging.LogRecord, message_dict: Dict[str, Any]) -> None:
super().add_fields(log_record, record, message_dict)
log_record['timestamp'] = datetime.utcnow().isoformat() + 'Z'
log_record['service'] = 'aitbc-coordinator-api'
log_record['level'] = record.levelname
log_record['logger'] = record.name
log_record['module'] = record.module
log_record['function'] = record.funcName
log_record['line'] = record.lineno
if record.exc_info:
log_record['exception'] = self.format_exception(record.exc_info)
@staticmethod
def format_exception(exc_info) -> Optional[Dict[str, Any]]:
"""Format exception info for JSON output."""
if exc_info is None:
return None
import traceback
return {
'type': exc_info[0].__name__ if exc_info[0] else None,
'message': str(exc_info[1]) if exc_info[1] else None,
'traceback': traceback.format_exception(*exc_info) if exc_info[0] else None
}
class AuditLogger:
"""Audit logger for tracking sensitive operations."""
def __init__(self, logger: logging.Logger):
self.logger = logger
def log(self, action: str, user_id: Optional[str] = None, resource_id: Optional[str] = None,
details: Optional[Dict[str, Any]] = None, success: bool = True) -> None:
"""Log an audit event."""
self.logger.info(
"audit_event",
extra={
'audit': {
'action': action,
'user_id': user_id,
'resource_id': resource_id,
'details': details or {},
'success': success
}
}
)
def setup_logging(level: str = "INFO", json_format: bool = True) -> None:
"""Setup structured logging for the application.""" """Setup structured logging for the application."""
logging.basicConfig( root_logger = logging.getLogger()
level=getattr(logging, level.upper()), root_logger.handlers.clear()
format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
handlers=[logging.StreamHandler(sys.stdout)] if json_format:
) handler = logging.StreamHandler(sys.stdout)
handler.setFormatter(StructuredLogFormatter(
'%(timestamp)s %(level)s %(message)s'
))
else:
handler = logging.StreamHandler(sys.stdout)
handler.setFormatter(
logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
)
root_logger.addHandler(handler)
root_logger.setLevel(getattr(logging, level.upper()))
logging.getLogger('uvicorn').setLevel(level)
logging.getLogger('uvicorn.access').setLevel(level)
def get_logger(name: str) -> logging.Logger: def get_logger(name: str) -> logging.Logger:
@@ -21,5 +92,10 @@ def get_logger(name: str) -> logging.Logger:
return logging.getLogger(name) return logging.getLogger(name)
def get_audit_logger(name: str = "audit") -> AuditLogger:
"""Get an audit logger instance."""
return AuditLogger(get_logger(name))
# Initialize default logging on import # Initialize default logging on import
setup_logging() setup_logging()

78
apps/coordinator-api/src/app/main.py
View File

@@ -1,5 +1,7 @@
from fastapi import FastAPI from fastapi import FastAPI, Request
from fastapi.middleware.cors import CORSMiddleware from fastapi.middleware.cors import CORSMiddleware
from fastapi.responses import JSONResponse
from fastapi.exceptions import RequestValidationError
from prometheus_client import make_asgi_app from prometheus_client import make_asgi_app
from .config import settings from .config import settings
@@ -21,6 +23,11 @@ from .routers import (
from .routers.governance import router as governance from .routers.governance import router as governance
from .routers.partners import router as partners from .routers.partners import router as partners
from .storage.models_governance import GovernanceProposal, ProposalVote, TreasuryTransaction, GovernanceParameter from .storage.models_governance import GovernanceProposal, ProposalVote, TreasuryTransaction, GovernanceParameter
from .exceptions import AITBCError, ErrorResponse
from .logging import get_logger
logger = get_logger(__name__)
def create_app() -> FastAPI: def create_app() -> FastAPI:
@@ -28,6 +35,19 @@ def create_app() -> FastAPI:
title="AITBC Coordinator API", title="AITBC Coordinator API",
version="0.1.0", version="0.1.0",
description="Stage 1 coordinator service handling job orchestration between clients and miners.", description="Stage 1 coordinator service handling job orchestration between clients and miners.",
docs_url="/docs",
redoc_url="/redoc",
openapi_url="/openapi.json",
openapi_tags=[
{"name": "health", "description": "Health check endpoints"},
{"name": "client", "description": "Client operations"},
{"name": "miner", "description": "Miner operations"},
{"name": "admin", "description": "Admin operations"},
{"name": "marketplace", "description": "GPU Marketplace"},
{"name": "exchange", "description": "Exchange operations"},
{"name": "governance", "description": "Governance operations"},
{"name": "zk", "description": "Zero-Knowledge proofs"},
]
) )
# Create database tables # Create database tables
@@ -60,10 +80,66 @@ def create_app() -> FastAPI:
metrics_app = make_asgi_app() metrics_app = make_asgi_app()
app.mount("/metrics", metrics_app) app.mount("/metrics", metrics_app)
@app.exception_handler(AITBCError)
async def aitbc_error_handler(request: Request, exc: AITBCError) -> JSONResponse:
"""Handle AITBC exceptions with structured error responses."""
request_id = request.headers.get("X-Request-ID")
response = exc.to_response(request_id)
return JSONResponse(
status_code=response.error["status"],
content=response.model_dump()
)
@app.exception_handler(RequestValidationError)
async def validation_error_handler(request: Request, exc: RequestValidationError) -> JSONResponse:
"""Handle FastAPI validation errors with structured error responses."""
request_id = request.headers.get("X-Request-ID")
details = []
for error in exc.errors():
details.append({
"field": ".".join(str(loc) for loc in error["loc"]),
"message": error["msg"],
"code": error["type"]
})
error_response = ErrorResponse(
error={
"code": "VALIDATION_ERROR",
"message": "Request validation failed",
"status": 422,
"details": details
},
request_id=request_id
)
return JSONResponse(
status_code=422,
content=error_response.model_dump()
)
@app.get("/v1/health", tags=["health"], summary="Service healthcheck") @app.get("/v1/health", tags=["health"], summary="Service healthcheck")
async def health() -> dict[str, str]: async def health() -> dict[str, str]:
return {"status": "ok", "env": settings.app_env} return {"status": "ok", "env": settings.app_env}
@app.get("/health/live", tags=["health"], summary="Liveness probe")
async def liveness() -> dict[str, str]:
return {"status": "alive"}
@app.get("/health/ready", tags=["health"], summary="Readiness probe")
async def readiness() -> dict[str, str]:
# Check database connectivity
try:
from .storage import get_engine
engine = get_engine()
with engine.connect() as conn:
conn.execute("SELECT 1")
return {"status": "ready", "database": "connected"}
except Exception as e:
logger.error("Readiness check failed", extra={"error": str(e)})
return JSONResponse(
status_code=503,
content={"status": "not ready", "error": str(e)}
)
return app return app

34
apps/coordinator-api/src/app/storage/db.py
View File

@@ -1,3 +1,9 @@
"""
Database storage module for AITBC Coordinator API
Provides unified database session management with connection pooling.
"""
from __future__ import annotations from __future__ import annotations
from contextlib import contextmanager from contextlib import contextmanager
@@ -5,6 +11,7 @@ from typing import Annotated, Generator
from fastapi import Depends from fastapi import Depends
from sqlalchemy.engine import Engine from sqlalchemy.engine import Engine
from sqlalchemy.pool import QueuePool
from sqlmodel import Session, SQLModel, create_engine from sqlmodel import Session, SQLModel, create_engine
from ..config import settings from ..config import settings
@@ -15,27 +22,48 @@ _engine: Engine | None = None
def get_engine() -> Engine: def get_engine() -> Engine:
"""Get or create the database engine with connection pooling."""
global _engine global _engine
if _engine is None: if _engine is None:
connect_args = {"check_same_thread": False} if settings.database_url.startswith("sqlite") else {} db_config = settings.database
_engine = create_engine(settings.database_url, echo=False, connect_args=connect_args) connect_args = {"check_same_thread": False} if "sqlite" in db_config.effective_url else {}
_engine = create_engine(
db_config.effective_url,
echo=False,
connect_args=connect_args,
poolclass=QueuePool if "postgresql" in db_config.effective_url else None,
pool_size=db_config.pool_size,
max_overflow=db_config.max_overflow,
pool_pre_ping=db_config.pool_pre_ping,
)
return _engine return _engine
def init_db() -> None: def init_db() -> None:
"""Initialize database tables."""
engine = get_engine() engine = get_engine()
SQLModel.metadata.create_all(engine) SQLModel.metadata.create_all(engine)
@contextmanager @contextmanager
def session_scope() -> Generator[Session, None, None]: def session_scope() -> Generator[Session, None, None]:
"""Context manager for database sessions."""
engine = get_engine() engine = get_engine()
with Session(engine) as session: session = Session(engine)
try:
yield session yield session
session.commit()
except Exception:
session.rollback()
raise
finally:
session.close()
def get_session() -> Generator[Session, None, None]: def get_session() -> Generator[Session, None, None]:
"""Get a database session (for FastAPI dependency)."""
with session_scope() as session: with session_scope() as session:
yield session yield session

47
docs/0_getting_started/1_intro.md Normal file
View File

@@ -0,0 +1,47 @@
# What is AITBC?
AITBC is a decentralized GPU computing platform that connects AI workloads with GPU providers through a blockchain-coordinated marketplace.
| Role | What you do |
|------|-------------|
| **Client** | Rent GPU power, submit AI/ML jobs, pay with AITBC tokens |
| **Miner** | Provide GPU resources, process jobs, earn AITBC tokens |
| **Node Operator** | Run blockchain infrastructure, validate transactions |
## Key Components
| Component | Purpose |
|-----------|---------|
| Coordinator API | Job orchestration, miner matching, receipt management |
| Blockchain Node | PoA consensus, transaction ledger, token transfers |
| Marketplace Web | GPU offer/bid UI, stats dashboard |
| Trade Exchange | BTC-to-AITBC trading, QR payments |
| Wallet | Key management, staking, multi-sig support |
| CLI | 90+ commands across 12 groups for all roles |
## Quick Start by Role
**Clients** → [2_clients/1_quick-start.md](../2_clients/1_quick-start.md)
```bash
pip install -e .
aitbc config set coordinator_url http://localhost:8000
aitbc client submit --prompt "What is AI?"
```
**Miners** → [3_miners/1_quick-start.md](../3_miners/1_quick-start.md)
```bash
aitbc miner register --name my-gpu --gpu a100 --count 1
aitbc miner poll
```
**Node Operators** → [4_blockchain/1_quick-start.md](../4_blockchain/1_quick-start.md)
```bash
aitbc-node init --chain-id ait-devnet
aitbc-node start
```
## Next Steps
- [2_installation.md](./2_installation.md) — Install all components
- [3_cli.md](./3_cli.md) — Full CLI usage guide
- [../README.md](../README.md) — Documentation navigation

71
docs/0_getting_started/2_installation.md Normal file
View File

@@ -0,0 +1,71 @@
# Installation
## Prerequisites
- Python 3.10+
- Git
- (Optional) PostgreSQL 14+ for production
- (Optional) NVIDIA GPU + CUDA for mining
## Monorepo Install
```bash
git clone https://github.com/oib/AITBC.git
cd aitbc
python -m venv .venv && source .venv/bin/activate
pip install -e .
```
This installs the CLI, coordinator API, and blockchain node from the monorepo.
## Environment Configuration
### Coordinator API
Create `apps/coordinator-api/.env`:
```env
JWT_SECRET=your-secret-key
DATABASE_URL=sqlite:///./data/coordinator.db # or postgresql://user:pass@localhost/aitbc
LOG_LEVEL=INFO
```
### Blockchain Node
Create `apps/blockchain-node/.env`:
```env
CHAIN_ID=ait-devnet
RPC_BIND_HOST=0.0.0.0
RPC_BIND_PORT=8080
MEMPOOL_BACKEND=database
```
## Systemd Services (Production)
```bash
sudo cp systemd/aitbc-*.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now aitbc-coordinator-api
sudo systemctl enable --now aitbc-blockchain-node-1
```
## Verify
```bash
systemctl status aitbc-coordinator-api
curl http://localhost:8000/v1/health
aitbc blockchain status
```
## Troubleshooting
| Problem | Fix |
|---------|-----|
| Port in use | `sudo lsof -i :8000` then `kill` the PID |
| DB corrupt | `rm -f data/coordinator.db && python -m app.storage init` |
| Module not found | Ensure venv is active: `source .venv/bin/activate` |
## Next Steps
- [3_cli.md](./3_cli.md) — CLI usage guide
- [../2_clients/1_quick-start.md](../2_clients/1_quick-start.md) — Client quick start
- [../3_miners/1_quick-start.md](../3_miners/1_quick-start.md) — Miner quick start

73
docs/0_getting_started/3_cli.md Normal file
View File

@@ -0,0 +1,73 @@
# CLI Usage
## Setup
```bash
pip install -e . # from monorepo root
aitbc config set coordinator_url http://localhost:8000
export AITBC_API_KEY=your-key # or use --api-key
```
## Global Options
| Option | Description |
|--------|-------------|
| `--url URL` | Coordinator API URL |
| `--api-key KEY` | API key for authentication |
| `--output table\|json\|yaml` | Output format |
| `-v / -vv / -vvv` | Verbosity level |
| `--debug` | Debug mode |
## Command Groups
| Group | Key commands |
|-------|-------------|
| `client` | `submit`, `status`, `list`, `cancel`, `download`, `batch-submit` |
| `miner` | `register`, `poll`, `mine`, `earnings`, `deregister` |
| `wallet` | `balance`, `send`, `stake`, `backup`, `multisig-create` |
| `auth` | `login`, `logout`, `token`, `keys` |
| `blockchain` | `status`, `blocks`, `transaction`, `validators` |
| `marketplace` | `gpu list`, `gpu book`, `orders`, `reviews` |
| `admin` | `status`, `jobs`, `miners`, `audit-log` |
| `config` | `set`, `show`, `profiles`, `secrets` |
| `monitor` | `dashboard`, `metrics`, `alerts`, `webhooks` |
| `simulate` | `workflow`, `load-test`, `scenario` |
## Client Workflow
```bash
aitbc wallet balance # check funds
aitbc client submit --prompt "What is AI?" # submit job
aitbc client status --job-id <JOB_ID> # check progress
aitbc client download --job-id <JOB_ID> --output ./ # get results
```
## Miner Workflow
```bash
aitbc miner register --name gpu-1 --gpu a100 --count 4
aitbc miner poll # start accepting jobs
aitbc wallet balance # check earnings
```
## Configuration
Config file: `~/.aitbc/config.yaml`
```yaml
coordinator_url: http://localhost:8000
api_key: your-api-key
output_format: table
log_level: INFO
```
## Troubleshooting
| Problem | Fix |
|---------|-----|
| Auth error | `export AITBC_API_KEY=your-key` or `aitbc auth login` |
| Connection refused | Check coordinator: `curl http://localhost:8000/v1/health` |
| Unknown command | Update CLI: `pip install -e .` from monorepo root |
## Full Reference
See [5_reference/1_cli-reference.md](../5_reference/1_cli-reference.md) for all 90+ commands with detailed options.

0
docs/files.md → docs/1_project/1_files.md
View File

142
docs/roadmap.md → docs/1_project/2_roadmap.md
View File

@@ -797,7 +797,147 @@ Current Status: Canonical receipt schema specification moved from `protocols/rec
- ✅ Site B (ns3): No action needed (blockchain node only) - ✅ Site B (ns3): No action needed (blockchain node only)
- ✅ Commit: `26edd70` - Changes committed and deployed - ✅ Commit: `26edd70` - Changes committed and deployed
## Recent Progress (2026-02-11) ## Recent Progress (2026-02-13) - Code Quality & Observability ✅ COMPLETE
### Structured Logging Implementation
- ✅ Added JSON structured logging to Coordinator API
- `StructuredLogFormatter` class for consistent log output
- Added `AuditLogger` class for tracking sensitive operations
- Configurable JSON/text format via settings
- ✅ Added JSON structured logging to Blockchain Node
- Consistent log format with Coordinator API
- Added `service` field for log parsing
- Added `get_audit_logger()` function
### Structured Error Responses
- ✅ Implemented standardized error responses across all APIs
- Added `ErrorResponse` and `ErrorDetail` Pydantic models
- All exceptions now have `error_code`, `status_code`, and `to_response()` method
- Added new exception types: `AuthorizationError`, `NotFoundError`, `ConflictError`
- Added exception handlers in main.py for consistent error formatting
### OpenAPI Documentation
- ✅ Enabled OpenAPI documentation with ReDoc
- Added `docs_url="/docs"`, `redoc_url="/redoc"`, `openapi_url="/openapi.json"`
- Added OpenAPI tags for all router groups (health, client, miner, admin, marketplace, exchange, governance, zk)
- Structured endpoint organization for better API discoverability
### Health Check Endpoints
- ✅ Added liveness and readiness probes
- `/health/live` - Simple alive check
- `/health/ready` - Database connectivity check
- Used by orchestrators for service health monitoring
### Unified Configuration
- ✅ Consolidated configuration with environment-based adapter selection
- Added `DatabaseConfig` class with adapter selection (sqlite/postgresql)
- Added connection pooling settings (`pool_size`, `max_overflow`, `pool_pre_ping`)
- Added `validate_secrets()` method for production environments
- Added `mempool_backend` configuration for persistence
- Backward compatible `database_url` property
### Connection Pooling
- ✅ Added database connection pooling
- `QueuePool` for PostgreSQL with configurable pool settings
- `pool_size=10`, `max_overflow=20`, `pool_pre_ping=True`
- Improved session scope with proper commit/rollback handling
- Better resource management under load
### Unified SessionDep
- ✅ Completed migration to unified `storage.SessionDep`
- All routers now use `SessionDep` dependency injection
- Removed legacy session code paths
- Consistent database session management across services
### DatabaseMempool Default
- ✅ Changed mempool backend to use database persistence by default
- `mempool_backend: str = "database"` (was "memory")
- Transaction persistence across restarts
- Better reliability for production deployments
### Systemd Service Standardization
- ✅ Standardized all service paths to `/opt/<service-name>` convention
- Updated 10 systemd service files:
- aitbc-coordinator-api.service
- aitbc-exchange-api.service
- aitbc-exchange-frontend.service
- aitbc-wallet.service
- aitbc-node.service
- aitbc-gpu-miner.service
- aitbc-gpu-miner-root.service
- aitbc-host-gpu-miner.service
- aitbc-gpu-registry.service
- aitbc-coordinator-proxy-health.service
- Consistent deployment paths across all services
## Upcoming Improvements (2026-02-14+)
### High Priority - Security & Stability
- **Redis-backed Rate Limiting**
- Replace in-memory rate limiter with Redis-backed implementation
- Support for distributed rate limiting across multiple instances
- Configurable limits per endpoint
- Status: Pending implementation
- **Request Validation Middleware**
- Add request size limits for all endpoints
- Input sanitization for all user inputs
- SQL injection and XSS prevention
- Status: Pending implementation
- **Audit Logging**
- Comprehensive audit logging for sensitive operations
- Track: API key usage, admin actions, configuration changes
- Integration with existing `AuditLogger` class
- Status: Pending implementation
### Medium Priority - Performance & Quality
- **Redis-backed Mempool (Production)**
- Add Redis adapter for mempool in production
- Support for distributed mempool across nodes
- Better persistence and recovery
- Status: Pending implementation
- **Async I/O Conversion**
- Convert blocking I/O operations to async where possible
- Use `aiohttp` or `httpx` async clients for external API calls
- Async database operations with SQLModel
- Status: Pending implementation
- **Custom Business Metrics**
- Add Prometheus metrics for business logic
- Track: jobs created, miners registered, payments processed
- Custom dashboards for operational visibility
- Status: Pending implementation
### Low Priority - Polish & Documentation
- **API Documentation Enhancement**
- Add detailed endpoint descriptions
- Include request/response examples
- Add code samples for common operations
- Status: Pending implementation
- **Architecture Diagrams**
- Create architecture diagrams for `docs/`
- Include data flow diagrams
- Service interaction diagrams
- Deployment architecture diagrams
- Status: Pending implementation
- **Operational Runbook**
- Create operational runbook for production
- Include: deployment procedures, troubleshooting guides
- Escalation procedures and contact information
- Status: Pending implementation
- **Chaos Engineering Tests**
- Add tests for service failures
- Test network partitions and recovery
- Simulate database outages
- Status: Pending implementation
### Git & Repository Hygiene ✅ COMPLETE ### Git & Repository Hygiene ✅ COMPLETE
- Renamed local `master` branch to `main` and set tracking to `github/main` - Renamed local `master` branch to `main` and set tracking to `github/main`

19
docs/done.md → docs/1_project/5_done.md
View File

@@ -619,3 +619,22 @@ This document tracks components that have been successfully deployed and are ope
- ✅ **Site A** (aitbc.bubuit.net): All security fixes deployed and active - ✅ **Site A** (aitbc.bubuit.net): All security fixes deployed and active
- ✅ **Site B** (ns3): No action needed - only blockchain node running - ✅ **Site B** (ns3): No action needed - only blockchain node running
- ✅ **Commit**: `26edd70` - All changes committed and deployed - ✅ **Commit**: `26edd70` - All changes committed and deployed
### Legacy Service Cleanup (2026-02-13)
- ✅ Removed legacy `aitbc-blockchain.service` running on port 9080
- ✅ Confirmed only 2 blockchain nodes running (ports 8081 and 8082)
- ✅ Both active nodes responding correctly to RPC requests
### Systemd Service Naming Standardization (2026-02-13)
- ✅ Renamed all services to use `aitbc-` prefix for consistency
- ✅ Site A updates:
- `blockchain-node.service` → `aitbc-blockchain-node-1.service`
- `blockchain-node-2.service` → `aitbc-blockchain-node-2.service`
- `blockchain-rpc.service` → `aitbc-blockchain-rpc-1.service`
- `blockchain-rpc-2.service` → `aitbc-blockchain-rpc-2.service`
- `coordinator-api.service` → `aitbc-coordinator-api.service`
- `exchange-mock-api.service` → `aitbc-exchange-mock-api.service`
- ✅ Site B updates:
- `blockchain-node.service` → `aitbc-blockchain-node-3.service`
- `blockchain-rpc.service` → `aitbc-blockchain-rpc-3.service`
- ✅ All services restarted and verified operational

0
docs/issues/2026-01-29_cross-site-sync-resolved.md → docs/1_project/6_cross-site-sync-resolved.md
View File

19
docs/2_clients/0_readme.md Normal file
View File

@@ -0,0 +1,19 @@
# Client Documentation
Rent GPU computing power for AI/ML workloads on the AITBC network.
## Reading Order
| # | File | What you learn |
|---|------|----------------|
| 1 | [1_quick-start.md](./1_quick-start.md) | Get running in 5 minutes |
| 2 | [2_job-submission.md](./2_job-submission.md) | Submit and configure jobs |
| 3 | [3_job-lifecycle.md](./3_job-lifecycle.md) | Track status, get results, view history, cancel |
| 4 | [4_wallet.md](./4_wallet.md) | Manage tokens and payments |
| 5 | [5_pricing-billing.md](./5_pricing-billing.md) | Understand costs and invoices |
| 6 | [6_api-reference.md](./6_api-reference.md) | REST API endpoints for integration |
## Related
- [CLI Guide](../0_getting_started/3_cli.md) — Command-line reference
- [Miner Docs](../3_miners/0_readme.md) — If you also want to provide GPU resources

38
docs/2_clients/1_quick-start.md Normal file
View File

@@ -0,0 +1,38 @@
# Client Quick Start
**5 minutes** — Install, configure, submit your first job.
## 1. Install & Configure
```bash
pip install -e . # from monorepo root
aitbc config set coordinator_url http://localhost:8000
export AITBC_API_KEY=your-key
```
## 2. Create Wallet
```bash
aitbc wallet create --name my-wallet
```
Save your seed phrase securely.
## 3. Submit a Job
```bash
aitbc client submit --prompt "Summarize this document" --input data.txt
```
## 4. Track & Download
```bash
aitbc client status --job-id <JOB_ID>
aitbc client download --job-id <JOB_ID> --output ./results
```
## Next
- [2_job-submission.md](./2_job-submission.md) — Advanced job options (GPU, priority, batch)
- [3_job-lifecycle.md](./3_job-lifecycle.md) — Status tracking, results, history
- [5_pricing-billing.md](./5_pricing-billing.md) — Cost structure

135
docs/2_clients/2_job-submission.md Normal file
View File

@@ -0,0 +1,135 @@
# Job Submission Guide
Submit compute jobs to the AITBC network.
## Basic Submission
```bash
aitbc client submit --model gpt2 --input data.txt --output results/
```
## Options Reference
| Option | Required | Description |
|--------|----------|-------------|
| `--model` | Yes | Model to run (e.g., gpt2, llama, stable-diffusion) |
| `--input` | Yes | Input file or data |
| `--output` | Yes | Output directory |
| `--gpu` | No | GPU requirements (v100, a100, rtx3090) |
| `--gpu-count` | No | Number of GPUs (default: 1) |
| `--timeout` | No | Job timeout in seconds (default: 3600) |
| `--priority` | No | Job priority (low, normal, high) |
## GPU Requirements
### Single GPU
```bash
aitbc client submit --model gpt2 --input data.txt --gpu v100
```
### Multiple GPUs
```bash
aitbc client submit --model llama --input data.txt --gpu a100 --gpu-count 4
```
### Specific GPU Type
```bash
aitbc client submit --model stable-diffusion --input data.txt --gpu rtx3090
```
## Input Methods
### File Input
```bash
aitbc client submit --model gpt2 --input ./data/training_data.txt
```
### Inline Input
```bash
aitbc client submit --model gpt2 --input "Hello, world!"
```
### URL Input
```bash
aitbc client submit --model gpt2 --input https://example.com/data.txt
```
## Output Options
### Local Directory
```bash
aitbc client submit --model gpt2 --input data.txt --output ./results
```
### S3 Compatible Storage
```bash
aitbc client submit --model gpt2 --input data.txt --output s3://my-bucket/results
```
## Job Priority
| Priority | Speed | Cost |
|----------|-------|------|
| low | Standard | 1x |
| normal | Fast | 1.5x |
| high | Priority | 2x |
## Examples
### Training Job
```bash
aitbc client submit \
--model llama \
--input ./training_data.csv \
--output ./model_weights \
--gpu a100 \
--gpu-count 4 \
--timeout 7200 \
--priority high
```
### Inference Job
```bash
aitbc client submit \
--model gpt2 \
--input ./prompts.txt \
--output ./outputs \
--gpu v100 \
--timeout 600
```
## Batch Jobs
Submit multiple jobs at once:
```bash
# Using a job file
aitbc client submit-batch --file jobs.yaml
```
Example `jobs.yaml`:
```yaml
jobs:
- model: gpt2
input: data1.txt
output: results1/
- model: gpt2
input: data2.txt
output: results2/
```
## Next
- [3_job-lifecycle.md](./3_job-lifecycle.md) — Status, results, history, cancellation
- [5_pricing-billing.md](./5_pricing-billing.md) — Cost structure and invoices

292
docs/2_clients/3_job-lifecycle.md Normal file
View File

@@ -0,0 +1,292 @@
# Job Status Guide
Understand job states and how to track progress.
## Job States
| State | Description | Actions |
|-------|-------------|---------|
| pending | Job queued, waiting for miner | Wait |
| assigned | Miner assigned, starting soon | Wait |
| running | Job executing | Monitor |
| completed | Job finished successfully | Download |
| failed | Job error occurred | Retry/Contact |
| canceled | Job cancelled by user | None |
## Check Status
### Using CLI
```bash
aitbc client status --job-id <JOB_ID>
```
### Using API
```python
import requests
response = requests.get(
"http://localhost:8000/v1/jobs/{job_id}",
headers={"X-Api-Key": "your-key"}
)
print(response.json())
```
## Status Response Example
```json
{
"job_id": "job_abc123",
"status": "running",
"progress": 45,
"miner_id": "miner_xyz789",
"created_at": "2026-02-13T10:00:00Z",
"started_at": "2026-02-13T10:01:00Z",
"estimated_completion": "2026-02-13T10:30:00Z"
}
```
## Progress Tracking
### Real-time Updates
```bash
aitbc client watch --job-id <JOB_ID>
```
### WebSocket Updates
```python
import websocket
def on_message(ws, message):
print(message)
ws = websocket.WebSocketApp(
"ws://localhost:8000/v1/jobs/ws",
on_message=on_message
)
ws.run_forever()
```
## State Transitions
```
pending → assigned → running → completed
↓ ↓ ↓
failed failed failed
↓ ↓ ↓
canceled canceled canceled
```
## Next Steps
- [Job Submission](./2_job-submission.md) - Submitting jobs
- [Results](./3_job-lifecycle.md) - Managing results
- [Job History](./3_job-lifecycle.md) - Viewing past jobs
---
Learn how to download and manage job results.
## Overview
Results are stored after job completion. This guide covers downloading and managing outputs.
## Download Results
### Using CLI
```bash
aitbc client download --job-id <JOB_ID> --output ./results
```
### Using API
```python
import requests
response = requests.get(
"http://localhost:8000/v1/jobs/{job_id}/download",
headers={"X-Api-Key": "your-key"}
)
with open("output.zip", "wb") as f:
f.write(response.content)
```
## Result Formats
| Format | Extension | Description |
|--------|-----------|-------------|
| JSON | `.json` | Structured data output |
| Text | `.txt` | Plain text output |
| Binary | `.bin` | Model weights, tensors |
| Archive | `.zip` | Multiple files |
## Result Contents
A typical result package includes:
```
job_<ID>/
├── output.json # Job metadata and status
├── result.txt # Main output
├── logs/ # Execution logs
│ ├── stdout.log
│ └── stderr.log
└── artifacts/ # Model files, etc.
└── model.bin
```
## Result Retention
| Plan | Retention |
|------|-----------|
| Free | 7 days |
| Pro | 30 days |
| Enterprise | 90 days |
## Sharing Results
### Generate Share Link
```bash
aitbc client share --job-id <JOB_ID>
```
### Set Expiration
```bash
aitbc client share --job-id <JOB_ID> --expires 7d
```
## Verify Results
### Check Integrity
```bash
aitbc client verify --job-id <JOB_ID>
```
### Compare Checksums
```bash
# Download checksum file
aitbc client download --job-id <JOB_ID> --checksum
# Verify
sha256sum -c output.sha256
```
## Delete Results
```bash
aitbc client delete --job-id <JOB_ID>
```
## Next Steps
- [Job Status](./3_job-lifecycle.md) - Understanding job states
- [Job Submission](./2_job-submission.md) - Submitting jobs
- [Billing](./5_pricing-billing.md) - Understanding charges
---
View and manage your past jobs.
## List All Jobs
```bash
aitbc client list
```
### Filter by Status
```bash
# Running jobs
aitbc client list --status running
# Completed jobs
aitbc client list --status completed
# Failed jobs
aitbc client list --status failed
```
### Filter by Date
```bash
# Last 7 days
aitbc client list --days 7
# Specific date range
aitbc client list --from 2026-01-01 --to 2026-01-31
```
## Job Details
```bash
aitbc client get --job-id <JOB_ID>
```
## Export History
```bash
# Export to JSON
aitbc client export --format json --output jobs.json
# Export to CSV
aitbc client export --format csv --output jobs.csv
```
## Statistics
```bash
aitbc client stats
```
Shows:
- Total jobs submitted
- Success rate
- Average completion time
- Total spent
## Next Steps
- [Job Status](./3_job-lifecycle.md) - Understanding job states
- [Job Cancellation](./3_job-lifecycle.md) - Canceling jobs
- [Billing](./5_pricing-billing.md) - Understanding charges
---
How to cancel jobs and manage running operations.
## Cancel a Job
```bash
aitbc client cancel --job-id <JOB_ID>
```
## Confirmation
```bash
aitbc client cancel --job-id <JOB_ID> --force
```
## Cancellation States
| State | Description |
|-------|-------------|
| canceling | Cancellation requested |
| canceled | Job successfully canceled |
| failed | Cancellation failed |
## Effects
- Job stops immediately
- Partial results may be available
- Charges apply for resources used
## Next Steps
- [Job Submission](./2_job-submission.md) - Submitting jobs
- [Job History](./3_job-lifecycle.md) - Viewing past jobs
- [Pricing](./5_pricing-billing.md) - Cost structure

78
docs/2_clients/4_wallet.md Normal file
View File

@@ -0,0 +1,78 @@
# Wallet Management
Manage your AITBC wallet and tokens.
## Create Wallet
```bash
aitbc wallet create --name my-wallet
```
Save the seed phrase securely!
## Import Wallet
```bash
aitbc wallet import --seed "your seed phrase words"
```
## View Balance
```bash
aitbc wallet balance
```
### Detailed Balance
```bash
aitbc wallet balance --detailed
```
Shows:
- Available balance
- Pending transactions
- Locked tokens
## Send Tokens
```bash
aitbc wallet send --to <ADDRESS> --amount 100
```
### With Memo
```bash
aitbc wallet send --to <ADDRESS> --amount 100 --memo "Payment for job"
```
## Transaction History
```bash
aitbc wallet history
```
### Filter
```bash
aitbc wallet history --type sent
aitbc wallet history --type received
```
## Security
### Backup Wallet
```bash
aitbc wallet export --output wallet.json
```
### Change Password
```bash
aitbc wallet change-password
```
## Next
- [5_pricing-billing.md](./5_pricing-billing.md) — Cost structure and invoices
- [CLI Guide](../0_getting_started/3_cli.md) — Full CLI reference

119
docs/2_clients/5_pricing-billing.md Normal file
View File

@@ -0,0 +1,119 @@
# Pricing & Costs
Understand the cost structure for using AITBC.
## Cost Structure
### Per-Job Pricing
| Resource | Unit | Price |
|----------|------|-------|
| GPU (V100) | per hour | 0.05 AITBC |
| GPU (A100) | per hour | 0.10 AITBC |
| GPU (RTX3090) | per hour | 0.03 AITBC |
| Storage | per GB/day | 0.001 AITBC |
### Priority Pricing
| Priority | Multiplier |
|----------|------------|
| Low | 0.8x |
| Normal | 1.0x |
| High | 1.5x |
| Urgent | 2.0x |
## Cost Examples
### Small Job (V100, 1 hour)
```
Base: 0.05 AITBC
Normal priority: 1.0x
Total: 0.05 AITBC
```
### Large Job (A100, 4 GPUs, 4 hours)
```
Base: 0.10 AITBC × 4 GPUs × 4 hours = 1.60 AITBC
High priority: 1.5x
Total: 2.40 AITBC
```
## Free Tier
- 10 GPU hours per month
- 1 GB storage
- Limited to V100 GPUs
## Enterprise Plans
| Feature | Basic | Pro | Enterprise |
|---------|-------|-----|------------|
| GPU hours/month | 100 | 500 | Unlimited |
| Priority | Normal | High | Urgent |
| Support | Email | 24/7 Chat | Dedicated |
| SLA | 99% | 99.9% | 99.99% |
## Next Steps
- [Billing](./5_pricing-billing.md) - Billing and invoices
- [Wallet](./4_wallet.md) - Managing your wallet
- [Job Submission](./2_job-submission.md) - Submitting jobs
---
Manage billing and view invoices.
## View Invoices
```bash
aitbc billing list
```
### Filter by Date
```bash
aitbc billing list --from 2026-01-01 --to 2026-01-31
```
### Download Invoice
```bash
aitbc billing download --invoice-id <INV_ID>
```
## Payment Methods
### Add Payment Method
```bash
aitbc billing add-card --number 4111111111111111 --expiry 12/26 --cvc 123
```
### Set Default
```bash
aitbc billing set-default --card-id <CARD_ID>
```
## Auto-Pay
```bash
# Enable auto-pay
aitbc billing auto-pay enable
# Disable auto-pay
aitbc billing auto-pay disable
```
## Billing Alerts
```bash
# Set spending limit
aitbc billing alert --limit 100 --email you@example.com
```
## Next Steps
- [Pricing](./5_pricing-billing.md) - Cost structure
- [Wallet](./4_wallet.md) - Managing your wallet
- [Job Submission](./2_job-submission.md) - Submitting jobs

124
docs/2_clients/6_api-reference.md Normal file
View File

@@ -0,0 +1,124 @@
# Client API Reference
REST API endpoints for client operations.
## Endpoints
### Submit Job
```
POST /v1/jobs
```
**Request Body:**
```json
{
"model": "gpt2",
"input": "string or file_id",
"output_config": {
"destination": "local or s3://bucket/path",
"format": "json"
},
"requirements": {
"gpu_type": "v100",
"gpu_count": 1,
"min_vram_gb": 16
},
"priority": "normal",
"timeout_seconds": 3600
}
```
**Response:**
```json
{
"job_id": "job_abc123",
"estimated_cost": 0.05,
"estimated_time_seconds": 600
}
```
### Get Job Status
```
GET /v1/jobs/{job_id}
```
**Response:**
```json
{
"job_id": "job_abc123",
"status": "running",
"progress": 45,
"miner_id": "miner_xyz789",
"created_at": "2026-02-13T10:00:00Z",
"started_at": "2026-02-13T10:01:00Z",
"completed_at": null,
"result": null
}
```
### List Jobs
```
GET /v1/jobs?status=running&limit=10
```
**Response:**
```json
{
"jobs": [
{
"job_id": "job_abc123",
"status": "running",
"model": "gpt2"
}
],
"total": 1,
"has_more": false
}
```
### Cancel Job
```
DELETE /v1/jobs/{job_id}
```
### Download Results
```
GET /v1/jobs/{job_id}/download
```
### Get Job History
```
GET /v1/jobs/history?from=2026-01-01&to=2026-01-31
```
## Error Codes
| Code | Description |
|------|-------------|
| 400 | Invalid request |
| 401 | Unauthorized |
| 404 | Job not found |
| 422 | Validation error |
| 429 | Rate limited |
| 500 | Server error |
## Rate Limits
- 60 requests/minute
- 1000 requests/hour
## Next
- [1_quick-start.md](./1_quick-start.md) — Get started quickly
- [2_job-submission.md](./2_job-submission.md) — CLI-based job submission
- [CLI Guide](../0_getting_started/3_cli.md) — Full CLI reference

20
docs/3_miners/0_readme.md Normal file
View File

@@ -0,0 +1,20 @@
# Miner Documentation
Provide GPU resources to the AITBC network and earn tokens.
## Reading Order
| # | File | What you learn |
|---|------|----------------|
| 1 | [1_quick-start.md](./1_quick-start.md) | Get mining in 5 minutes |
| 2 | [2_registration.md](./2_registration.md) | Register GPU with the network |
| 3 | [3_job-management.md](./3_job-management.md) | Accept and complete jobs |
| 4 | [4_earnings.md](./4_earnings.md) | Track and withdraw earnings |
| 5 | [5_gpu-setup.md](./5_gpu-setup.md) | GPU drivers, CUDA, optimization |
| 6 | [6_monitoring.md](./6_monitoring.md) | Dashboards, alerts, health checks |
| 7 | [7_api-miner.md](./7_api-miner.md) | REST API endpoints for integration |
## Related
- [CLI Guide](../0_getting_started/3_cli.md) — Command-line reference
- [Client Docs](../2_clients/0_readme.md) — If you also want to submit jobs

37
docs/3_miners/1_quick-start.md Normal file
View File

@@ -0,0 +1,37 @@
# Miner Quick Start
**5 minutes** — Register your GPU and start earning AITBC tokens.
## Prerequisites
- NVIDIA GPU with 16GB+ VRAM (V100, A100, RTX 3090+)
- Python 3.10+, CUDA drivers installed
- 50GB+ storage, stable internet
## 1. Install & Configure
```bash
pip install -e . # from monorepo root
aitbc config set coordinator_url http://localhost:8000
export AITBC_API_KEY=your-key
```
## 2. Register & Start
```bash
aitbc miner register --name my-gpu --gpu v100 --count 1
aitbc miner poll # start accepting jobs
```
## 3. Verify
```bash
aitbc miner status # GPU status + earnings
aitbc wallet balance # check token balance
```
## Next
- [2_registration.md](./2_registration.md) — Advanced registration options
- [3_job-management.md](./3_job-management.md) — Job acceptance and completion
- [5_gpu-setup.md](./5_gpu-setup.md) — GPU driver and CUDA setup

80
docs/3_miners/2_registration.md Normal file
View File

@@ -0,0 +1,80 @@
# Miner Registration
Register your miner with the AITBC network.
## Requirements
### Hardware Requirements
| Resource | Minimum | Recommended |
|----------|---------|-------------|
| GPU VRAM | 8GB | 16GB+ |
| RAM | 16GB | 32GB+ |
| Storage | 50GB | 100GB+ |
| Bandwidth | 10 Mbps | 100 Mbps |
### Supported GPUs
- NVIDIA V100 (16GB/32GB)
- NVIDIA A100 (40GB/80GB)
- NVIDIA RTX 3090 (24GB)
- NVIDIA RTX 4090 (24GB)
## Registration
### Basic Registration
```bash
aitbc miner register --name my-miner --gpu v100 --count 1
```
### Advanced Registration
```bash
aitbc miner register \
--name my-miner \
--gpu a100 \
--count 4 \
--location us-east \
--price 0.10 \
--max-concurrent 4
```
### Flags Reference
| Flag | Description |
|------|-------------|
| `--name` | Miner name |
| `--gpu` | GPU type (v100, a100, rtx3090, rtx4090) |
| `--count` | Number of GPUs |
| `--location` | Geographic location |
| `--price` | Price per GPU/hour in AITBC |
| `--max-concurrent` | Maximum concurrent jobs |
## Verification
```bash
aitbc miner status
```
Shows:
- Registration status
- GPU availability
- Current jobs
## Update Registration
```bash
aitbc miner update --price 0.12 --max-concurrent 8
```
## De-register
```bash
aitbc miner deregister --confirm
```
## Next
- [Job Management](./3_job-management.md) — Job management
- [Earnings](./4_earnings.md) — Earnings tracking
- [GPU Setup](./5_gpu-setup.md) — GPU configuration

96
docs/3_miners/3_job-management.md Normal file
View File

@@ -0,0 +1,96 @@
# Job Management
Accept and complete jobs on the AITBC network.
## Overview
Jobs are assigned to miners based on GPU availability, price, and reputation.
## Accept Jobs
### Manual Acceptance
```bash
aitbc miner jobs --available
aitbc miner accept --job-id <JOB_ID>
```
### Auto-Accept
```bash
aitbc miner auto-accept enable --max-concurrent 4
```
### Auto-Accept Settings
```bash
# Set GPU requirements
aitbc miner auto-accept --gpu v100 --gpu-count 1-4
# Set price range
aitbc miner auto-accept --min-price 0.08 --max-price 0.12
```
## Job States
| State | Description |
|-------|-------------|
| assigned | Job assigned, waiting to start |
| starting | Preparing environment |
| running | Executing job |
| uploading | Uploading results |
| completed | Job finished successfully |
| failed | Job error occurred |
## Monitor Jobs
### Check Status
```bash
aitbc miner job-status --job-id <JOB_ID>
```
### Watch Progress
```bash
aitbc miner watch --job-id <JOB_ID>
```
### List Active Jobs
```bash
aitbc miner jobs --active
```
## Complete Jobs
### Manual Completion
```bash
aitbc miner complete --job-id <JOB_ID>
```
### Upload Results
```bash
aitbc miner upload --job-id <JOB_ID> --path ./results
```
## Handle Failures
### Retry Job
```bash
aitbc miner retry --job-id <JOB_ID>
```
### Report Issue
```bash
aitbc miner report --job-id <JOB_ID> --reason "gpu-error"
```
## Next
- [Earnings](./4_earnings.md) — Earnings tracking
- [GPU Setup](./5_gpu-setup.md) — GPU configuration
- [Monitoring](./6_monitoring.md) - Monitor your miner

66
docs/3_miners/4_earnings.md Normal file
View File

@@ -0,0 +1,66 @@
# Earnings & Payouts
Track and manage your mining earnings.
## Earnings Overview
```bash
aitbc miner earnings
```
Shows:
- Total earned
- Pending balance
- Last payout
## Earnings Breakdown
| Source | Description |
|--------|-------------|
| job_completion | Payment for completed jobs |
| bonus | Performance bonuses |
| referral | Referral rewards |
## Payout Schedule
| Plan | Schedule | Minimum |
|------|----------|---------|
| Automatic | Daily | 10 AITBC |
| Manual | On request | 1 AITBC |
## Request Payout
```bash
aitbc wallet withdraw --amount 100 --address <WALLET_ADDRESS>
```
## Earnings History
```bash
aitbc miner earnings --history --days 30
```
## Performance Metrics
```bash
aitbc miner stats
```
Shows:
- Success rate
- Average completion time
- Total jobs completed
- Earnings per GPU/hour
## Tax Reporting
```bash
aitbc miner earnings --export --year 2026
```
Export for tax purposes.
## Next
- [Job Management](./3_job-management.md) — Job management
- [Monitoring](./6_monitoring.md) - Monitor your miner
- [GPU Setup](./5_gpu-setup.md) — GPU configuration

111
docs/3_miners/5_gpu-setup.md Normal file
View File

@@ -0,0 +1,111 @@
# GPU Setup & Configuration
Configure and optimize your GPU setup for mining.
## Prerequisites
### Driver Installation
```bash
# Ubuntu/Debian
sudo apt install nvidia-driver-535
# Verify installation
nvidia-smi
```
### CUDA Installation
```bash
# Download CUDA from NVIDIA
wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb
sudo apt-get update
sudo apt-get install cuda-toolkit-12-3
```
## Configuration
### Miner Config
Create `~/.aitbc/miner.yaml`:
```yaml
gpu:
type: v100
count: 1
cuda_devices: 0
performance:
max_memory_percent: 90
max_gpu_temp: 80
power_limit: 250
jobs:
max_concurrent: 4
timeout_grace: 300
```
### Environment Variables
```bash
export CUDA_VISIBLE_DEVICES=0
export NVIDIA_VISIBLE_DEVICES=all
export AITBC_GPU_MEMORY_LIMIT=0.9
```
## Optimization
### Memory Settings
```yaml
performance:
tensor_cores: true
fp16: true # Use half precision
max_memory_percent: 90
```
### Thermal Management
```yaml
thermal:
target_temp: 70
max_temp: 85
fan_curve:
- temp: 50
fan: 30
- temp: 70
fan: 60
- temp: 85
fan: 100
```
## Troubleshooting
### GPU Not Detected
```bash
# Check driver
nvidia-smi
# Check CUDA
nvcc --version
# Restart miner
aitbc miner restart
```
### Temperature Issues
```bash
# Monitor temperature
nvidia-smi -l 1
# Check cooling
ipmitool sdr list | grep Temp
```
## Next
- [Quick Start](./1_quick-start.md) — Get started
- [Monitoring](./6_monitoring.md) - Monitor your miner
- [Job Management](./3_job-management.md) — Job management

110
docs/3_miners/6_monitoring.md Normal file
View File

@@ -0,0 +1,110 @@
# Monitoring & Alerts
Monitor your miner performance and set up alerts.
## Real-time Monitoring
### Dashboard
```bash
aitbc miner dashboard
```
Shows:
- GPU utilization
- Memory usage
- Temperature
- Active jobs
- Earnings rate
### CLI Stats
```bash
aitbc miner stats
```
### Prometheus Metrics
```bash
# Enable metrics endpoint
aitbc miner metrics --port 9090
```
Available at: http://localhost:9090/metrics
## Alert Configuration
### Set Alerts
```bash
# GPU temperature alert
aitbc miner alert --metric temp --threshold 85 --action notify
# Memory usage alert
aitbc miner alert --metric memory --threshold 90 --action throttle
# Job failure alert
aitbc miner alert --metric failures --threshold 3 --action pause
```
### Alert Types
| Type | Description |
|------|-------------|
| temp | GPU temperature |
| memory | GPU memory usage |
| utilization | GPU utilization |
| jobs | Job success/failure rate |
| earnings | Earnings below threshold |
### Alert Actions
| Action | Description |
|--------|-------------|
| notify | Send notification |
| throttle | Reduce job acceptance |
| pause | Stop accepting jobs |
| restart | Restart miner |
## Log Management
### View Logs
```bash
# Recent logs
aitbc miner logs --tail 100
# Filter by level
aitbc miner logs --level error
# Filter by job
aitbc miner logs --job-id <JOB_ID>
```
### Log Rotation
```bash
# Configure log rotation
aitbc miner logs --rotate --max-size 100MB --keep 5
```
## Health Checks
```bash
# Run health check
aitbc miner health
# Detailed health report
aitbc miner health --detailed
```
Shows:
- GPU health
- Driver status
- Network connectivity
- Storage availability
## Next
- [Quick Start](./1_quick-start.md) — Get started
- [GPU Setup](./5_gpu-setup.md) — GPU configuration
- [Job Management](./3_job-management.md) — Job management

141
docs/3_miners/7_api-miner.md Normal file
View File

@@ -0,0 +1,141 @@
# Miner API Reference
Complete API reference for miner operations.
## Endpoints
### Register Miner
```
POST /v1/miners
```
**Request Body:**
```json
{
"name": "my-miner",
"gpu_type": "v100",
"gpu_count": 1,
"location": "us-east",
"price_per_hour": 0.05,
"max_concurrent": 4
}
```
**Response:**
```json
{
"miner_id": "miner_xyz789",
"api_key": "key_abc123",
"status": "pending"
}
```
### Update Miner
```
PUT /v1/miners/{miner_id}
```
### Heartbeat
```
POST /v1/miners/{miner_id}/heartbeat
```
**Response:**
```json
{
"status": "ok",
"jobs_assigned": 0,
"queue_length": 5
}
```
### List Available Jobs
```
GET /v1/miners/{miner_id}/jobs/available
```
**Response:**
```json
{
"jobs": [
{
"job_id": "job_abc123",
"model": "gpt2",
"gpu_type": "v100",
"gpu_count": 1,
"estimated_time": 600,
"price": 0.05
}
]
}
```
### Accept Job
```
POST /v1/miners/{miner_id}/jobs/{job_id}/accept
```
### Complete Job
```
POST /v1/miners/{miner_id}/jobs/{job_id}/complete
```
**Request Body:**
```json
{
"result_hash": "sha256:abc123...",
"metrics": {
"execution_time_seconds": 600,
"gpu_time_seconds": 600
}
}
```
### Get Miner Stats
```
GET /v1/miners/{miner_id}/stats
```
**Response:**
```json
{
"total_jobs": 100,
"success_rate": 0.98,
"average_completion_time": 600,
"earnings": 50.5,
"earnings_per_gpu_hour": 0.05
}
```
## Error Codes
| Code | Description |
|------|-------------|
| 400 | Invalid request |
| 401 | Unauthorized |
| 404 | Miner/job not found |
| 409 | Job already assigned |
| 422 | Validation error |
## Rate Limits
- 60 requests/minute
- 10 job operations/minute
## Next
- [Quick Start](./1_quick-start.md) — Get started
- [Job Management](./3_job-management.md) — Job management
- [Monitoring](./6_monitoring.md) - Monitor your miner

23
docs/4_blockchain/0_readme.md Normal file
View File

@@ -0,0 +1,23 @@
# Blockchain Node Documentation
Run a blockchain node: validate transactions, produce blocks, maintain the AITBC ledger.
## Reading Order
| # | File | What you learn |
|---|------|----------------|
| 1 | [1_quick-start.md](./1_quick-start.md) | Get a node running in 10 minutes |
| 2 | [2_configuration.md](./2_configuration.md) | Node, RPC, P2P, mempool settings |
| 3 | [3_operations.md](./3_operations.md) | Start/stop, sync, peers, backups |
| 4 | [4_consensus.md](./4_consensus.md) | PoA consensus mechanism |
| 5 | [5_validator.md](./5_validator.md) | Become a validator, duties, rewards |
| 6 | [6_networking.md](./6_networking.md) | Firewall, NAT, bootstrap nodes |
| 7 | [7_monitoring.md](./7_monitoring.md) | Prometheus, dashboards, alerts |
| 8 | [8_troubleshooting.md](./8_troubleshooting.md) | Common issues and fixes |
| 9 | [9_upgrades.md](./9_upgrades.md) | Version upgrades, rollback |
| 10 | [10_api-blockchain.md](./10_api-blockchain.md) | RPC and WebSocket API reference |
## Related
- [Installation](../0_getting_started/2_installation.md) — Install all components
- [CLI Guide](../0_getting_started/3_cli.md) — `aitbc blockchain` commands

202
docs/4_blockchain/10_api-blockchain.md Normal file
View File

@@ -0,0 +1,202 @@
# Blockchain API Reference
Complete API reference for blockchain node operations.
## RPC Endpoints
### Get Block
```
GET /rpc/block/{height}
```
**Response:**
```json
{
"block": {
"header": {
"height": 100,
"timestamp": "2026-02-13T10:00:00Z",
"proposer": "ait-devnet-proposer-1",
"parent_hash": "0xabc123...",
"state_root": "0xdef456...",
"tx_root": "0xghi789..."
},
"transactions": [...],
"receipts": [...]
},
"block_id": "0xjkl012..."
}
```
### Get Transaction
```
GET /rpc/tx/{tx_hash}
```
**Response:**
```json
{
"tx": {
"hash": "0xabc123...",
"type": "transfer",
"from": "0x1234...",
"to": "0x5678...",
"value": 100,
"gas": 21000,
"data": "0x..."
},
"height": 100,
"index": 0
}
```
### Submit Transaction
```
POST /rpc/broadcast_tx_commit
```
**Request Body:**
```json
{
"tx": "0xabc123...",
"type": "transfer",
"from": "0x1234...",
"to": "0x5678...",
"value": 100,
"data": "0x..."
}
```
**Response:**
```json
{
"tx_response": {
"code": 0,
"data": "0x...",
"log": "success",
"hash": "0xabc123..."
},
"height": 100,
"index": 0
}
```
### Get Status
```
GET /rpc/status
```
**Response:**
```json
{
"node_info": {
"protocol_version": "v0.1.0",
"network": "ait-devnet",
"node_id": "12D3KooW...",
"listen_addr": "tcp://0.0.0.0:7070"
},
"sync_info": {
"latest_block_height": 1000,
"catching_up": false,
"earliest_block_height": 1
},
"validator_info": {
"voting_power": 1000,
"proposer": true
}
}
```
### Get Mempool
```
GET /rpc/mempool
```
**Response:**
```json
{
"size": 50,
"txs": [
{
"hash": "0xabc123...",
"fee": 0.001,
"size": 200
}
]
}
```
## WebSocket Endpoints
### Subscribe to Blocks
```
WS /rpc/block
```
**Message:**
```json
{
"type": "new_block",
"data": {
"height": 1001,
"hash": "0x...",
"proposer": "ait-devnet-proposer-1"
}
}
```
### Subscribe to Transactions
```
WS /rpc/tx
```
**Message:**
```json
{
"type": "new_tx",
"data": {
"hash": "0xabc123...",
"type": "transfer",
"from": "0x1234...",
"to": "0x5678...",
"value": 100
}
}
```
## Error Codes
| Code | Description |
|------|-------------|
| 0 | Success |
| 1 | Internal error |
| 2 | Invalid transaction |
| 3 | Invalid request |
| 4 | Not found |
| 5 | Conflict |
## Rate Limits
- 1000 requests/minute for RPC
- 100 requests/minute for writes
- 10 connections per IP
## Next
- [Quick Start](./1_quick-start.md) — Get started
- [Configuration](./2_configuration.md) - Configure your node
- [Operations](./3_operations.md) — Day-to-day ops

54
docs/4_blockchain/1_quick-start.md Normal file
View File

@@ -0,0 +1,54 @@
# Node Quick Start
**10 minutes** — Install, configure, and sync a blockchain node.
## Prerequisites
| Resource | Minimum |
|----------|---------|
| CPU | 4 cores |
| RAM | 16 GB |
| Storage | 100 GB SSD |
| Network | 100 Mbps stable |
## 1. Install
```bash
cd /home/oib/windsurf/aitbc
python -m venv .venv && source .venv/bin/activate
pip install -e .
```
## 2. Initialize & Configure
```bash
aitbc-chain init --name my-node --network ait-devnet
```
Edit `~/.aitbc/chain.yaml`:
```yaml
node:
name: my-node
data_dir: ./data
rpc:
bind_host: 0.0.0.0
bind_port: 8080
p2p:
bind_port: 7070
bootstrap_nodes:
- /dns4/node-1.aitbc.com/tcp/7070/p2p/...
```
## 3. Start & Verify
```bash
aitbc-chain start
aitbc-chain status # node info + sync progress
curl http://localhost:8080/rpc/health # RPC health check
```
## Next
- [2_configuration.md](./2_configuration.md) — Full config reference
- [3_operations.md](./3_operations.md) — Day-to-day ops
- [7_monitoring.md](./7_monitoring.md) — Prometheus + dashboards

87
docs/4_blockchain/2_configuration.md Normal file
View File

@@ -0,0 +1,87 @@
# Blockchain Node Configuration
Configure your blockchain node for optimal performance.
## Configuration File
Location: `~/.aitbc/chain.yaml`
## Node Configuration
```yaml
node:
name: my-node
network: ait-devnet # or ait-mainnet
data_dir: /opt/blockchain-node/data
log_level: info
```
## RPC Configuration
```yaml
rpc:
enabled: true
bind_host: 0.0.0.0
bind_port: 8080
cors_origins:
- http://localhost:3000
- http://localhost:8000
rate_limit: 1000 # requests per minute
```
## P2P Configuration
```yaml
p2p:
enabled: true
bind_host: 0.0.0.0
bind_port: 7070
bootstrap_nodes:
- /dns4/node-1.aitbc.com/tcp/7070/p2p/...
max_peers: 50
min_peers: 5
```
## Mempool Configuration
```yaml
mempool:
backend: database # or memory
max_size: 10000
min_fee: 0
eviction_interval: 60
```
## Database Configuration
```yaml
database:
adapter: postgresql # or sqlite
url: postgresql://user:pass@localhost/aitbc_chain
pool_size: 10
max_overflow: 20
```
## Validator Configuration
```yaml
validator:
enabled: true
key: <VALIDATOR_PRIVATE_KEY>
block_time: 2 # seconds
max_block_size: 1000000 # bytes
max_txs_per_block: 500
```
## Environment Variables
```bash
export AITBC_CHAIN_DATA_DIR=/opt/blockchain-node/data
export AITBC_CHAIN_RPC_PORT=8080
export AITBC_CHAIN_P2P_PORT=7070
```
## Next
- [Quick Start](./1_quick-start.md) — Get started
- [Operations](./3_operations.md) — Day-to-day ops
- [Consensus](./4_consensus.md) — Consensus mechanism

102
docs/4_blockchain/3_operations.md Normal file
View File

@@ -0,0 +1,102 @@
# Node Operations
Day-to-day operations for blockchain nodes.
## Starting the Node
```bash
# Start in foreground (for testing)
aitbc-chain start
# Start as daemon
aitbc-chain start --daemon
# Start with custom config
aitbc-chain start --config /path/to/config.yaml
```
## Stopping the Node
```bash
# Graceful shutdown
aitbc-chain stop
# Force stop
aitbc-chain stop --force
```
## Node Status
```bash
aitbc-chain status
```
Shows:
- Block height
- Peers connected
- Mempool size
- Last block time
## Checking Sync Status
```bash
aitbc-chain sync-status
```
Shows:
- Current height
- Target height
- Sync progress percentage
- Estimated time to sync
## Managing Peers
### List Peers
```bash
aitbc-chain peers list
```
### Add Peer
```bash
aitbc-chain peers add /dns4/new-node.example.com/tcp/7070/p2p/...
```
### Remove Peer
```bash
aitbc-chain peers remove <PEER_ID>
```
## Backup & Restore
### Backup Data
```bash
aitbc-chain backup --output /backup/chain-backup.tar.gz
```
### Restore Data
```bash
aitbc-chain restore --input /backup/chain-backup.tar.gz
```
## Log Management
```bash
# View logs
aitbc-chain logs --tail 100
# Filter by level
aitbc-chain logs --level error
# Export logs
aitbc-chain logs --export /var/log/aitbc-chain.log
```
## Next
- [Quick Start](./1_quick-start.md) — Get started
- [Configuration](./2_configuration.md) - Configure your node
- [Consensus](./4_consensus.md) — Consensus mechanism

65
docs/4_blockchain/4_consensus.md Normal file
View File

@@ -0,0 +1,65 @@
# Consensus Mechanism
Understand AITBC's proof-of-authority consensus mechanism.
## Overview
AITBC uses a Proof-of-Authority (PoA) consensus mechanism with:
- Fixed block time: 2 seconds
- Authority set of validated proposers
- Transaction finality on each block
## Block Production
### Proposer Selection
Proposers take turns producing blocks in a round-robin fashion. Each proposer gets a fixed time slot.
### Block Structure
```json
{
"header": {
"height": 100,
"timestamp": "2026-02-13T10:00:00Z",
"proposer": "ait-devnet-proposer-1",
"parent_hash": "0xabc123...",
"state_root": "0xdef456...",
"tx_root": "0xghi789..."
},
"transactions": [...],
"receipts": [...]
}
```
## Consensus Rules
1. **Block Time**: 2 seconds minimum
2. **Block Size**: 1 MB maximum
3. **Transactions**: 500 maximum per block
4. **Fee**: Minimum 0 (configurable)
## Validator Requirements
| Requirement | Value |
|-------------|-------|
| Uptime | 99% minimum |
| Latency | < 100ms to peers |
| Stake | 1000 AITBC |
## Fork Selection
Longest chain rule applies:
- Validators always extend the longest known chain
- Reorgs occur only on conflicting blocks within the last 10 blocks
## Finality
Blocks are considered final after:
- 1 confirmation for normal transactions
- 3 confirmations for high-value transactions
## Next
- [Quick Start](./1_quick-start.md) — Get started
- [Validator Operations](./5_validator.md) - Validator guide
- [Networking](./6_networking.md) - P2P networking

95
docs/4_blockchain/5_validator.md Normal file
View File

@@ -0,0 +1,95 @@
# Validator Operations
Guide for running a validator node in the AITBC network.
## Becoming a Validator
### Requirements
| Requirement | Value |
|-------------|-------|
| Stake | 1000 AITBC |
| Node uptime | 99%+ |
| Technical capability | Must run node 24/7 |
| Geographic distribution | One per region preferred |
### Registration
```bash
aitbc-chain validator register --stake 1000
```
### Activate Validator Status
```bash
aitbc-chain validator activate
```
## Validator Duties
### Block Production
Validators take turns producing blocks:
- Round-robin selection
- Fixed 2-second block time
- Missed blocks result in reduced rewards
### Transaction Validation
- Verify transaction signatures
- Check sender balance
- Validate smart contract execution
### Network Participation
- Maintain P2P connections
- Propagate blocks to peers
- Participate in consensus votes
## Validator Rewards
### Block Rewards
| Block Position | Reward |
|----------------|--------|
| Proposer | 1 AITBC |
| Validator (any) | 0.1 AITBC |
### Performance Bonuses
- 100% uptime: 1.5x multiplier
- 99-100% uptime: 1.2x multiplier
- <99% uptime: 1.0x multiplier
## Validator Monitoring
```bash
# Check validator status
aitbc-chain validator status
# View performance metrics
aitbc-chain validator metrics
# Check missed blocks
aitbc-chain validator missed-blocks
```
## Validator Slashing
### Slashing Conditions
| Violation | Penalty |
|-----------|---------|
| Double signing | 5% stake |
| Extended downtime | 1% stake |
| Invalid block | 2% stake |
### Recovery
- Partial slashing can be recovered
- Full slashing requires re-registration
## Next
- [Quick Start](./1_quick-start.md) — Get started
- [Consensus](./4_consensus.md) — Consensus mechanism
- [Monitoring](./7_monitoring.md) — Monitoring

107
docs/4_blockchain/6_networking.md Normal file
View File

@@ -0,0 +1,107 @@
# Networking Configuration
Configure P2P networking for your blockchain node.
## Network Settings
### Firewall Configuration
```bash
# Allow P2P port
sudo ufw allow 7070/tcp
# Allow RPC port
sudo ufw allow 8080/tcp
# Allow from specific IPs
sudo ufw allow from 10.0.0.0/8 to any port 8080
```
### Port Forwarding
If behind a NAT, configure port forwarding:
- External port 7070 → Internal IP:7070
- External port 8080 → Internal IP:8080
## Bootstrap Nodes
### Default Bootstrap Nodes
```yaml
p2p:
bootstrap_nodes:
- /dns4/node-1.aitbc.com/tcp/7070/p2p/12D3KooW...
- /dns4/node-2.aitbc.com/tcp/7070/p2p/12D3KooW...
- /dns4/node-3.aitbc.com/tcp/7070/p2p/12D3KooW...
```
### Adding Custom Bootstrap Nodes
```bash
aitbc-chain p2p add-bootstrap /dns4/my-node.example.com/tcp/7070/p2p/...
```
## Peer Management
### Connection Limits
```yaml
p2p:
max_peers: 50
min_peers: 5
outbound_peers: 10
inbound_peers: 40
```
### Peer Scoring
Nodes are scored based on:
- Latency
- Availability
- Protocol compliance
- Block propagation speed
## NAT Traversal
### Supported Methods
| Method | Description |
|--------|-------------|
| AutoNAT | Automatic NAT detection |
| Hole Punching | UDP hole punching |
| Relay | TURN relay fallback |
### Configuration
```yaml
p2p:
nat:
enabled: true
method: auto # auto, hole_punching, relay
external_ip: 203.0.113.1
```
## Troubleshooting
### Check Connectivity
```bash
aitbc-chain p2p check-connectivity
```
### List Active Connections
```bash
aitbc-chain p2p connections
```
### Debug Mode
```bash
aitbc-chain start --log-level debug
```
## Next
- [Quick Start](./1_quick-start.md) — Get started
- [Configuration](./2_configuration.md) - Configure your node
- [Operations](./3_operations.md) — Day-to-day ops

89
docs/4_blockchain/7_monitoring.md Normal file
View File

@@ -0,0 +1,89 @@
# Node Monitoring
Monitor your blockchain node performance and health.
## Dashboard
```bash
aitbc-chain dashboard
```
Shows:
- Block height
- Peers connected
- Mempool size
- CPU/Memory/GPU usage
- Network traffic
## Prometheus Metrics
```bash
# Enable metrics
aitbc-chain metrics --port 9090
```
Available metrics:
- `aitbc_block_height` - Current block height
- `aitbc_peers_count` - Number of connected peers
- `aitbc_mempool_size` - Transactions in mempool
- `aitbc_block_production_time` - Block production time
- `aitbc_cpu_usage` - CPU utilization
- `aitbc_memory_usage` - Memory utilization
## Alert Configuration
### Set Alerts
```bash
# Low peers alert
aitbc-chain alert --metric peers --threshold 3 --action notify
# High mempool alert
aitbc-chain alert --metric mempool --threshold 5000 --action notify
# Sync delay alert
aitbc-chain alert --metric sync_delay --threshold 100 --action notify
```
### Alert Actions
| Action | Description |
|--------|-------------|
| notify | Send notification |
| restart | Restart node |
| pause | Pause block production |
## Log Monitoring
```bash
# Real-time logs
aitbc-chain logs --tail
# Search logs
aitbc-chain logs --grep "error" --since "1h"
# Export logs
aitbc-chain logs --export /var/log/aitbc-chain/
```
## Health Checks
```bash
# Run health check
aitbc-chain health
# Detailed report
aitbc-chain health --detailed
```
Checks:
- Disk space
- Memory
- P2P connectivity
- RPC availability
- Database sync
## Next
- [Quick Start](./1_quick-start.md) — Get started
- [Configuration](./2_configuration.md) - Configure your node
- [Operations](./3_operations.md) — Day-to-day ops

153
docs/4_blockchain/8_troubleshooting.md Normal file
View File

@@ -0,0 +1,153 @@
# Troubleshooting
Common issues and solutions for blockchain nodes.
## Common Issues
### Node Won't Start
```bash
# Check logs
tail -f ~/.aitbc/logs/chain.log
# Common causes:
# - Port already in use
# - Corrupted database
# - Invalid configuration
```
**Solutions:**
```bash
# Kill existing process
sudo lsof -i :8080
sudo kill $(sudo lsof -t -i :8080)
# Reset database
rm -rf ~/.aitbc/data/chain.db
aitbc-chain init
# Validate config
aitbc-chain validate-config
```
### Sync Stuck
```bash
# Check sync status
aitbc-chain sync-status
# Force sync from scratch
aitbc-chain reset --hard
# Check peer connectivity
aitbc-chain p2p connections
```
**Solutions:**
```bash
# Add more peers
aitbc-chain p2p add-bootstrap /dns4/new-peer.example.com/tcp/7070/p2p/...
# Clear peer database
rm -rf ~/.aitbc/data/peers.db
# Restart with fresh sync
aitbc-chain start --sync-mode full
```
### P2P Connection Issues
```bash
# Check connectivity
aitbc-chain p2p check-connectivity
# Test port forwarding
curl http://localhost:8080/rpc/net_info
```
**Solutions:**
```bash
# Open firewall
sudo ufw allow 7070/tcp
sudo ufw allow 8080/tcp
# Check NAT configuration
aitbc-chain p2p nat-status
# Use relay mode
aitbc-chain start --p2p-relay-enabled
```
### High Memory Usage
```bash
# Check memory usage
htop | grep aitbc-chain
# Check database size
du -sh ~/.aitbc/data/
```
**Solutions:**
```bash
# Prune old data
aitbc-chain prune --keep-blocks 10000
# Reduce peer count
# Edit config: max_peers: 25
# Enable compression
aitbc-chain start --db-compression
```
### RPC Not Responding
```bash
# Check RPC status
curl http://localhost:8080/rpc/health
# Check if RPC is enabled
aitbc-chain status | grep RPC
```
**Solutions:**
```bash
# Restart with RPC enabled
aitbc-chain start --rpc-enabled
# Check CORS settings
# Edit config: rpc.cors_origins
# Increase rate limits
# Edit config: rpc.rate_limit: 2000
```
## Diagnostic Commands
```bash
# Full system check
aitbc-chain doctor
# Network diagnostics
aitbc-chain diagnose network
# Database diagnostics
aitbc-chain diagnose database
# Log analysis
aitbc-chain logs --analyze
```
## Getting Help
```bash
# Generate debug report
aitbc-chain debug-report > debug.txt
# Share on Discord or GitHub Issues
```
## Next
- [Quick Start](./1_quick-start.md) — Get started
- [Configuration](./2_configuration.md) - Configure your node
- [Operations](./3_operations.md) — Day-to-day ops

77
docs/4_blockchain/9_upgrades.md Normal file
View File

@@ -0,0 +1,77 @@
# Node Upgrades
Guide for upgrading your blockchain node.
## Upgrade Process
### Check Current Version
```bash
aitbc-chain version
```
### Check for Updates
```bash
aitbc-chain check-update
```
### Upgrade Steps
```bash
# 1. Backup data
aitbc-chain backup --output /backup/chain-$(date +%Y%m%d).tar.gz
# 2. Stop node gracefully
aitbc-chain stop
# 3. Upgrade software
pip install --upgrade aitbc-chain
# 4. Review migration notes
cat CHANGELOG.md
# 5. Start node
aitbc-chain start
```
## Version-Specific Upgrades
### v0.1.0 → v0.2.0
```bash
# Database migration required
aitbc-chain migrate --from v0.1.0
```
### v0.2.0 → v0.3.0
```bash
# Configuration changes
aitbc-chain migrate-config --from v0.2.0
```
## Rollback Procedure
```bash
# If issues occur, rollback
pip install aitbc-chain==0.1.0
# Restore from backup
aitbc-chain restore --input /backup/chain-YYYYMMDD.tar.gz
# Start old version
aitbc-chain start
```
## Upgrade Notifications
```bash
# Enable upgrade alerts
aitbc-chain alert --metric upgrade_available --action notify
```
## Next
- [Quick Start](./1_quick-start.md) — Get started
- [Operations](./3_operations.md) — Day-to-day ops
- [Monitoring](./7_monitoring.md) — Monitoring

28
docs/5_reference/0_index.md Normal file
View File

@@ -0,0 +1,28 @@
# Technical Reference
Specifications, audits, and implementation records for AITBC internals.
## Reading Order
| # | File | Topic |
|---|------|-------|
| 1 | [1_cli-reference.md](./1_cli-reference.md) | Full CLI command reference (90+ commands) |
| 2 | [2_payment-architecture.md](./2_payment-architecture.md) | Payment system design |
| 3 | [3_wallet-coordinator-integration.md](./3_wallet-coordinator-integration.md) | Wallet ↔ coordinator flow |
| 4 | [4_confidential-transactions.md](./4_confidential-transactions.md) | Confidential tx architecture + implementation |
| 5 | [5_zk-proofs.md](./5_zk-proofs.md) | ZK receipt attestation design + comparison |
| 6 | [6_enterprise-sla.md](./6_enterprise-sla.md) | Enterprise SLA definitions |
| 7 | [7_threat-modeling.md](./7_threat-modeling.md) | Privacy feature threat model |
| 8 | [8_blockchain-deployment-summary.md](./8_blockchain-deployment-summary.md) | Node deployment record |
| 9 | [9_payment-integration-complete.md](./9_payment-integration-complete.md) | Payment integration status |
| 10 | [10_implementation-complete-summary.md](./10_implementation-complete-summary.md) | Feature completion record |
| 11–14 | `11_`–`14_` | Integration test fixes, updates, status reports |
| 15 | [15_skipped-tests-roadmap.md](./15_skipped-tests-roadmap.md) | Skipped tests plan |
| 16 | [16_security-audit-2026-02-13.md](./16_security-audit-2026-02-13.md) | Security audit results |
| 17 | [17_docs-gaps.md](./17_docs-gaps.md) | Documentation gap analysis |
## Related
- [Architecture](../6_architecture/) — System design docs
- [Security](../9_security/) — Security guides
- [Roadmap](../1_project/2_roadmap.md) — Development roadmap

0
docs/reports/IMPLEMENTATION_COMPLETE_SUMMARY.md → docs/5_reference/10_implementation-complete-summary.md
View File

0
docs/reports/INTEGRATION_TEST_FIXES.md → docs/5_reference/11_integration-test-fixes.md
View File

0
docs/reports/INTEGRATION_TEST_UPDATES.md → docs/5_reference/12_integration-test-updates.md
View File

0
docs/reports/TEST_FIXES_COMPLETE.md → docs/5_reference/13_test-fixes-complete.md
View File

0
docs/reports/TESTING_STATUS_REPORT.md → docs/5_reference/14_testing-status-report.md
View File

0
docs/reports/SKIPPED_TESTS_ROADMAP.md → docs/5_reference/15_skipped-tests-roadmap.md
View File

36
docs/reports/security-audit-2026-02-13.md → docs/5_reference/16_security-audit-2026-02-13.md
View File

@@ -126,6 +126,42 @@ encrypted = encrypt_value(private_key, password) # Fernet
- Replaced `requests` with `httpx` (already a dependency) - Replaced `requests` with `httpx` (already a dependency)
- Added graceful fallback for missing dependencies - Added graceful fallback for missing dependencies
### Code Quality & Observability ✅
#### Structured Logging
- ✅ Added JSON structured logging to Coordinator API
- `StructuredLogFormatter` class for consistent log output
- Added `AuditLogger` class for tracking sensitive operations
- Configurable JSON/text format via settings
- ✅ Added JSON structured logging to Blockchain Node
- Consistent log format with Coordinator API
- Added `service` field for log parsing
#### Structured Error Responses
- ✅ Implemented standardized error responses across all APIs
- Added `ErrorResponse` and `ErrorDetail` Pydantic models
- All exceptions now have `error_code`, `status_code`, and `to_response()` method
- Added new exception types: `AuthorizationError`, `NotFoundError`, `ConflictError`
#### OpenAPI Documentation
- ✅ Enabled OpenAPI documentation with ReDoc
- Added `docs_url="/docs"`, `redoc_url="/redoc"`, `openapi_url="/openapi.json"`
- Added OpenAPI tags for all router groups
#### Health Check Endpoints
- ✅ Added liveness and readiness probes
- `/health/live` - Simple alive check
- `/health/ready` - Database connectivity check
#### Connection Pooling
- ✅ Added database connection pooling
- `QueuePool` for PostgreSQL with configurable pool settings
- `pool_size=10`, `max_overflow=20`, `pool_pre_ping=True`
#### Systemd Service Standardization
- ✅ Standardized all service paths to `/opt/<service-name>` convention
- Updated 10 systemd service files for consistent deployment paths
## Deployment ## Deployment
### Site A (aitbc.bubuit.net) ### Site A (aitbc.bubuit.net)

0
docs/reference/docs-gaps.md → docs/5_reference/17_docs-gaps.md
View File

0
docs/cli-reference.md → docs/5_reference/1_cli-reference.md
View File

0
docs/reports/AITBC_PAYMENT_ARCHITECTURE.md → docs/5_reference/2_payment-architecture.md
View File

0
docs/reports/WALLET_COORDINATOR_INTEGRATION.md → docs/5_reference/3_wallet-coordinator-integration.md
View File

188
docs/reference/confidential-transactions.md → docs/5_reference/4_confidential-transactions.md
View File

@@ -1,4 +1,190 @@
# Confidential Transactions Architecture # Confidential Transactions Implementation Summary
## Overview
Successfully implemented a comprehensive confidential transaction system for AITBC with opt-in encryption, selective disclosure, and full audit compliance. The implementation provides privacy for sensitive transaction data while maintaining regulatory compliance.
## Completed Components
### 1. Encryption Service ✅
- **Hybrid Encryption**: AES-256-GCM for data encryption, X25519 for key exchange
- **Envelope Pattern**: Random DEK per transaction, encrypted for each participant
- **Audit Escrow**: Separate encryption key for regulatory access
- **Performance**: Efficient batch operations, key caching
### 2. Key Management ✅
- **Per-Participant Keys**: X25519 key pairs for each participant
- **Key Rotation**: Automated rotation with re-encryption of active data
- **Secure Storage**: File-based storage (development), HSM-ready interface
- **Access Control**: Role-based permissions for key operations
### 3. Access Control ✅
- **Role-Based Policies**: Client, Miner, Coordinator, Auditor, Regulator roles
- **Time Restrictions**: Business hours, retention periods
- **Purpose-Based Access**: Settlement, Audit, Compliance, Dispute, Support
- **Dynamic Policies**: Custom policy creation and management
### 4. Audit Logging ✅
- **Tamper-Evident**: Chain of hashes for integrity verification
- **Comprehensive**: All access, key operations, policy changes
- **Export Capabilities**: JSON, CSV formats for regulators
- **Retention**: Configurable retention periods by role
### 5. API Endpoints ✅
- **/confidential/transactions**: Create and manage confidential transactions
- **/confidential/access**: Request access to encrypted data
- **/confidential/audit**: Regulatory access with authorization
- **/confidential/keys**: Key registration and rotation
- **Rate Limiting**: Protection against abuse
### 6. Data Models ✅
- **ConfidentialTransaction**: Opt-in privacy flags
- **Access Control Models**: Requests, responses, logs
- **Key Management Models**: Registration, rotation, audit
## Security Features
### Encryption
- AES-256-GCM provides confidentiality + integrity
- X25519 ECDH for secure key exchange
- Per-transaction DEKs for forward secrecy
- Random IVs per encryption
### Access Control
- Multi-factor authentication ready
- Time-bound access permissions
- Business hour restrictions for auditors
- Retention period enforcement
### Audit Compliance
- GDPR right to encryption
- SEC Rule 17a-4 compliance
- Immutable audit trails
- Regulatory access with court orders
## Current Limitations
### 1. Database Persistence ❌
- Current implementation uses mock storage
- Needs SQLModel/SQLAlchemy integration
- Transaction storage and querying
- Encrypted data BLOB handling
### 2. Private Key Security ❌
- File storage writes keys unencrypted
- Needs HSM or KMS integration
- Key escrow for recovery
- Hardware security module support
### 3. Async Issues ❌
- AuditLogger uses threading in async context
- Needs asyncio task conversion
- Background writer refactoring
- Proper async/await patterns
### 4. Rate Limiting ⚠️
- slowapi not properly integrated
- Needs FastAPI app state setup
- Distributed rate limiting for production
- Redis backend for scalability
## Production Readiness Checklist
### Critical (Must Fix)
- [ ] Database persistence layer
- [ ] HSM/KMS integration for private keys
- [ ] Fix async issues in audit logging
- [ ] Proper rate limiting setup
### Important (Should Fix)
- [ ] Performance optimization for high volume
- [ ] Distributed key management
- [ ] Backup and recovery procedures
- [ ] Monitoring and alerting
### Nice to Have (Future)
- [ ] Multi-party computation
- [ ] Zero-knowledge proofs integration
- [ ] Advanced privacy features
- [ ] Cross-chain confidential settlements
## Testing Coverage
### Unit Tests ✅
- Encryption/decryption correctness
- Key management operations
- Access control logic
- Audit logging functionality
### Integration Tests ✅
- End-to-end transaction flow
- Cross-service integration
- API endpoint testing
- Error handling scenarios
### Performance Tests ⚠️
- Basic benchmarks included
- Needs load testing
- Scalability assessment
- Resource usage profiling
## Migration Strategy
### Phase 1: Infrastructure (Week 1-2)
1. Implement database persistence
2. Integrate HSM for key storage
3. Fix async issues
4. Set up proper rate limiting
### Phase 2: Security Hardening (Week 3-4)
1. Security audit and penetration testing
2. Implement additional monitoring
3. Create backup procedures
4. Document security controls
### Phase 3: Production Rollout (Month 2)
1. Gradual rollout with feature flags
2. Performance monitoring
3. User training and documentation
4. Compliance validation
## Compliance Status
### GDPR ✅
- Right to encryption implemented
- Data minimization by design
- Privacy by default
### Financial Regulations ✅
- SEC Rule 17a-4 audit logs
- MiFID II transaction reporting
- AML/KYC integration points
### Industry Standards ✅
- ISO 27001 alignment
- NIST Cybersecurity Framework
- PCI DSS considerations
## Next Steps
1. **Immediate**: Fix database persistence and HSM integration
2. **Short-term**: Complete security hardening and testing
3. **Long-term**: Production deployment and monitoring
## Documentation
- [Architecture Design](confidential-transactions.md)
- [API Documentation](../6_architecture/3_coordinator-api.md)
- [Security Guide](security-guidelines.md)
- [Compliance Matrix](compliance-matrix.md)
## Conclusion
The confidential transaction system provides a solid foundation for privacy-preserving transactions in AITBC. While the core functionality is complete and tested, several production readiness items need to be addressed before deployment.
The modular design allows for incremental improvements and ensures the system can evolve with changing requirements and regulations.
---
## Overview ## Overview

609
docs/5_reference/5_zk-proofs.md Normal file
View File

@@ -0,0 +1,609 @@
# ZK Receipt Attestation Implementation Summary
## Overview
Successfully implemented a zero-knowledge proof system for privacy-preserving receipt attestation in AITBC, enabling confidential settlements while maintaining verifiability.
## Components Implemented
### 1. ZK Circuits (`apps/zk-circuits/`)
- **Basic Circuit**: Receipt hash preimage proof in circom
- **Advanced Circuit**: Full receipt validation with pricing (WIP)
- **Build System**: npm scripts for compilation, setup, and proving
- **Testing**: Proof generation and verification tests
- **Benchmarking**: Performance measurement tools
### 2. Proof Service (`apps/coordinator-api/src/app/services/zk_proofs.py`)
- **ZKProofService**: Handles proof generation and verification
- **Privacy Levels**: Basic (hide computation) and Enhanced (hide amounts)
- **Integration**: Works with existing receipt signing system
- **Error Handling**: Graceful fallback when ZK unavailable
### 3. Receipt Integration (`apps/coordinator-api/src/app/services/receipts.py`)
- **Async Support**: Updated create_receipt to support async ZK generation
- **Optional Privacy**: ZK proofs generated only when requested
- **Backward Compatibility**: Existing receipts work unchanged
### 4. Verification Contract (`contracts/ZKReceiptVerifier.sol`)
- **On-Chain Verification**: Groth16 proof verification
- **Security Features**: Double-spend prevention, timestamp validation
- **Authorization**: Controlled access to verification functions
- **Batch Support**: Efficient batch verification
### 5. Settlement Integration (`apps/coordinator-api/aitbc/settlement/hooks.py`)
- **Privacy Options**: Settlement requests can specify privacy level
- **Proof Inclusion**: ZK proofs included in settlement messages
- **Bridge Support**: Works with existing cross-chain bridges
## Key Features
### Privacy Levels
1. **Basic**: Hide computation details, reveal settlement amount
2. **Enhanced**: Hide all amounts, prove correctness mathematically
### Performance Metrics
- **Proof Size**: ~200 bytes (Groth16)
- **Generation Time**: 5-15 seconds
- **Verification Time**: <5ms on-chain
- **Gas Cost**: ~200k gas
### Security Measures
- Trusted setup requirements documented
- Circuit audit procedures defined
- Gradual rollout strategy
- Emergency pause capabilities
## Testing Coverage
### Unit Tests
- Proof generation with various inputs
- Verification success/failure scenarios
- Privacy level validation
- Error handling
### Integration Tests
- Receipt creation with ZK proofs
- Settlement flow with privacy
- Cross-chain bridge integration
### Benchmarks
- Proof generation time measurement
- Verification performance
- Memory usage tracking
- Gas cost estimation
## Usage Examples
### Creating Private Receipt
```python
receipt = await receipt_service.create_receipt(
job=job,
miner_id=miner_id,
job_result=result,
result_metrics=metrics,
privacy_level="basic" # Enable ZK proof
)
```
### Cross-Chain Settlement with Privacy
```python
settlement = await settlement_hook.initiate_manual_settlement(
job_id="job-123",
target_chain_id=2,
use_zk_proof=True,
privacy_level="enhanced"
)
```
### On-Chain Verification
```solidity
bool verified = verifier.verifyAndRecord(
proof.a,
proof.b,
proof.c,
proof.publicSignals
);
```
## Current Status
### Completed ✅
1. Research and technology selection (Groth16)
2. Development environment setup
3. Basic circuit implementation
4. Proof generation service
5. Verification contract
6. Settlement integration
7. Comprehensive testing
8. Performance benchmarking
### Pending ⏳
1. Trusted setup ceremony (production requirement)
2. Circuit security audit
3. Full receipt validation circuit
4. Production deployment
## Next Steps for Production
### Immediate (Week 1-2)
1. Run end-to-end tests with real data
2. Performance optimization based on benchmarks
3. Security review of implementation
### Short Term (Month 1)
1. Plan and execute trusted setup ceremony
2. Complete advanced circuit with signature verification
3. Third-party security audit
### Long Term (Month 2-3)
1. Production deployment with gradual rollout
2. Monitor performance and gas costs
3. Consider PLONK for universal setup
## Risks and Mitigations
### Technical Risks
- **Trusted Setup**: Mitigate with multi-party ceremony
- **Performance**: Optimize circuits and use batch verification
- **Complexity**: Maintain clear documentation and examples
### Operational Risks
- **User Adoption**: Provide clear UI indicators for privacy
- **Gas Costs**: Optimize proof size and verification
- **Regulatory**: Ensure compliance with privacy regulations
## Documentation
- [ZK Technology Comparison](zk-technology-comparison.md)
- [Circuit Design](zk-receipt-attestation.md)
- [Development Guide](./5_zk-proofs.md)
- [API Documentation](../6_architecture/3_coordinator-api.md)
## Conclusion
The ZK receipt attestation system provides a solid foundation for privacy-preserving settlements in AITBC. The implementation balances privacy, performance, and usability while maintaining backward compatibility with existing systems.
The modular design allows for gradual adoption and future enhancements, making it suitable for both testing and production deployment.
---
## Overview
This document outlines the design for adding zero-knowledge proof capabilities to the AITBC receipt attestation system, enabling privacy-preserving settlement flows while maintaining verifiability.
## Goals
1. **Privacy**: Hide sensitive transaction details (amounts, parties, specific computations)
2. **Verifiability**: Prove receipts are valid and correctly signed without revealing contents
3. **Compatibility**: Work with existing receipt signing and settlement systems
4. **Efficiency**: Minimize proof generation and verification overhead
## Architecture
### Current Receipt System
The existing system has:
- Receipt signing with coordinator private key
- Optional coordinator attestations
- History retrieval endpoints
- Cross-chain settlement hooks
Receipt structure includes:
- Job ID and metadata
- Computation results
- Pricing information
- Miner and coordinator signatures
### Privacy-Preserving Flow
```
1. Job Execution
↓
2. Receipt Generation (clear text)
↓
3. ZK Circuit Input Preparation
↓
4. ZK Proof Generation
↓
5. On-Chain Settlement (with proof)
↓
6. Verification (without revealing data)
```
## ZK Circuit Design
### What to Prove
1. **Receipt Validity**
- Receipt was signed by coordinator
- Computation was performed correctly
- Pricing follows agreed rules
2. **Settlement Conditions**
- Amount owed is correctly calculated
- Parties have sufficient funds/balance
- Cross-chain transfer conditions met
### What to Hide
1. **Sensitive Data**
- Actual computation amounts
- Specific job details
- Pricing rates
- Participant identities
### Circuit Components
```circom
// High-level circuit structure
template ReceiptAttestation() {
// Public inputs
signal input receiptHash;
signal input settlementAmount;
signal input timestamp;
// Private inputs
signal input receipt;
signal input computationResult;
signal input pricingRate;
signal input minerReward;
// Verify receipt signature
component signatureVerifier = ECDSAVerify();
// ... signature verification logic
// Verify computation correctness
component computationChecker = ComputationVerify();
// ... computation verification logic
// Verify pricing calculation
component pricingVerifier = PricingVerify();
// ... pricing verification logic
// Output settlement proof
settlementAmount <== minerReward + coordinatorFee;
}
```
## Implementation Plan
### Phase 1: Research & Prototyping
1. **Library Selection**
- snarkjs for development (JavaScript/TypeScript)
- circomlib2 for standard circuits
- Web3.js for blockchain integration
2. **Basic Circuit**
- Simple receipt hash preimage proof
- ECDSA signature verification
- Basic arithmetic operations
### Phase 2: Integration
1. **Coordinator API Updates**
- Add ZK proof generation endpoint
- Integrate with existing receipt signing
- Add proof verification utilities
2. **Settlement Flow**
- Modify cross-chain hooks to accept proofs
- Update verification logic
- Maintain backward compatibility
### Phase 3: Optimization
1. **Performance**
- Trusted setup for Groth16
- Batch proof generation
- Recursive proofs for complex receipts
2. **Security**
- Audit circuits
- Formal verification
- Side-channel resistance
## Data Flow
### Proof Generation (Coordinator)
```python
async def generate_receipt_proof(receipt: Receipt) -> ZKProof:
# 1. Prepare circuit inputs
public_inputs = {
"receiptHash": hash_receipt(receipt),
"settlementAmount": calculate_settlement(receipt),
"timestamp": receipt.timestamp
}
private_inputs = {
"receipt": receipt,
"computationResult": receipt.result,
"pricingRate": receipt.pricing.rate,
"minerReward": receipt.pricing.miner_reward
}
# 2. Generate witness
witness = generate_witness(public_inputs, private_inputs)
# 3. Generate proof
proof = groth16.prove(witness, proving_key)
return {
"proof": proof,
"publicSignals": public_inputs
}
```
### Proof Verification (On-Chain/Settlement Layer)
```solidity
contract SettlementVerifier {
// Groth16 verifier
function verifySettlement(
uint256[2] memory a,
uint256[2][2] memory b,
uint256[2] memory c,
uint256[] memory input
) public pure returns (bool) {
return verifyProof(a, b, c, input);
}
function settleWithProof(
address recipient,
uint256 amount,
ZKProof memory proof
) public {
require(verifySettlement(proof.a, proof.b, proof.c, proof.inputs));
// Execute settlement
_transfer(recipient, amount);
}
}
```
## Privacy Levels
### Level 1: Basic Privacy
- Hide computation amounts
- Prove pricing correctness
- Reveal participant identities
### Level 2: Enhanced Privacy
- Hide all amounts
- Zero-knowledge participant proofs
- Anonymous settlement
### Level 3: Full Privacy
- Complete transaction privacy
- Ring signatures or similar
- Confidential transfers
## Security Considerations
1. **Trusted Setup**
- Multi-party ceremony for Groth16
- Documentation of setup process
- Toxic waste destruction proof
2. **Circuit Security**
- Constant-time operations
- No side-channel leaks
- Formal verification where possible
3. **Integration Security**
- Maintain existing security guarantees
- Fail-safe verification
- Gradual rollout with monitoring
## Migration Strategy
1. **Parallel Operation**
- Run both clear and ZK receipts
- Gradual opt-in adoption
- Performance monitoring
2. **Backward Compatibility**
- Existing receipts remain valid
- Optional ZK proofs
- Graceful degradation
3. **Network Upgrade**
- Coordinate with all participants
- Clear communication
- Rollback capability
## Next Steps
1. **Research Task**
- Evaluate zk-SNARKs vs zk-STARKs trade-offs
- Benchmark proof generation times
- Assess gas costs for on-chain verification
2. **Prototype Development**
- Implement basic circuit in circom
- Create proof generation service
- Build verification contract
3. **Integration Planning**
- Design API changes
- Plan data migration
- Prepare rollout strategy
---
## Overview
Analysis of zero-knowledge proof systems for AITBC receipt attestation, focusing on practical considerations for integration with existing infrastructure.
## Technology Options
### 1. zk-SNARKs (Zero-Knowledge Succinct Non-Interactive Argument of Knowledge)
**Examples**: Groth16, PLONK, Halo2
**Pros**:
- **Small proof size**: ~200 bytes for Groth16
- **Fast verification**: Constant time, ~3ms on-chain
- **Mature ecosystem**: circom, snarkjs, bellman, arkworks
- **Low gas costs**: ~200k gas for verification on Ethereum
- **Industry adoption**: Used by Aztec, Tornado Cash, Zcash
**Cons**:
- **Trusted setup**: Required for Groth16 (toxic waste problem)
- **Longer proof generation**: 10-30 seconds depending on circuit size
- **Complex setup**: Ceremony needs multiple participants
- **Quantum vulnerability**: Not post-quantum secure
### 2. zk-STARKs (Zero-Knowledge Scalable Transparent Argument of Knowledge)
**Examples**: STARKEx, Winterfell, gnark
**Pros**:
- **No trusted setup**: Transparent setup process
- **Post-quantum secure**: Resistant to quantum attacks
- **Faster proving**: Often faster than SNARKs for large circuits
- **Transparent**: No toxic waste, fully verifiable setup
**Cons**:
- **Larger proofs**: ~45KB for typical circuits
- **Higher verification cost**: ~500k-1M gas on-chain
- **Newer ecosystem**: Fewer tools and libraries
- **Less adoption**: Limited production deployments
## Use Case Analysis
### Receipt Attestation Requirements
1. **Proof Size**: Important for on-chain storage costs
2. **Verification Speed**: Critical for settlement latency
3. **Setup Complexity**: Affects deployment timeline
4. **Ecosystem Maturity**: Impacts development speed
5. **Privacy Needs**: Moderate (hiding amounts, not full anonymity)
### Quantitative Comparison
| Metric | Groth16 (SNARK) | PLONK (SNARK) | STARK |
|--------|----------------|---------------|-------|
| Proof Size | 200 bytes | 400-500 bytes | 45KB |
| Prover Time | 10-30s | 5-15s | 2-10s |
| Verifier Time | 3ms | 5ms | 50ms |
| Gas Cost | 200k | 300k | 800k |
| Trusted Setup | Yes | Universal | No |
| Library Support | Excellent | Good | Limited |
## Recommendation
### Phase 1: Groth16 for MVP
**Rationale**:
1. **Proven technology**: Battle-tested in production
2. **Small proofs**: Essential for cost-effective on-chain verification
3. **Fast verification**: Critical for settlement performance
4. **Tool maturity**: circom + snarkjs ecosystem
5. **Community knowledge**: Extensive documentation and examples
**Mitigations for trusted setup**:
- Multi-party ceremony with >100 participants
- Public documentation of process
- Consider PLONK for Phase 2 if setup becomes bottleneck
### Phase 2: Evaluate PLONK
**Rationale**:
- Universal trusted setup (one-time for all circuits)
- Slightly larger proofs but acceptable
- More flexible for circuit updates
- Growing ecosystem support
### Phase 3: Consider STARKs
**Rationale**:
- If quantum resistance becomes priority
- If proof size optimizations improve
- If gas costs become less critical
## Implementation Strategy
### Circuit Complexity Analysis
**Basic Receipt Circuit**:
- Hash verification: ~50 constraints
- Signature verification: ~10,000 constraints
- Arithmetic operations: ~100 constraints
- Total: ~10,150 constraints
**With Privacy Features**:
- Range proofs: ~1,000 constraints
- Merkle proofs: ~1,000 constraints
- Additional checks: ~500 constraints
- Total: ~12,650 constraints
### Performance Estimates
**Groth16**:
- Setup time: 2-5 hours
- Proving time: 5-15 seconds
- Verification: 3ms
- Proof size: 200 bytes
**Infrastructure Impact**:
- Coordinator: Additional 5-15s per receipt
- Settlement layer: Minimal impact (fast verification)
- Storage: Negligible increase
## Security Considerations
### Trusted Setup Risks
1. **Toxic Waste**: If compromised, can forge proofs
2. **Setup Integrity**: Requires honest participants
3. **Documentation**: Must be publicly verifiable
### Mitigation Strategies
1. **Multi-party Ceremony**:
- Minimum 100 participants
- Geographically distributed
- Public livestream
2. **Circuit Audits**:
- Formal verification where possible
- Third-party security review
- Public disclosure of circuits
3. **Gradual Rollout**:
- Start with low-value transactions
- Monitor for anomalies
- Emergency pause capability
## Development Plan
### Week 1-2: Environment Setup
- Install circom and snarkjs
- Create basic test circuit
- Benchmark proof generation
### Week 3-4: Basic Circuit
- Implement receipt hash verification
- Add signature verification
- Test with sample receipts
### Week 5-6: Integration
- Add to coordinator API
- Create verification contract
- Test settlement flow
### Week 7-8: Trusted Setup
- Plan ceremony logistics
- Prepare ceremony software
- Execute multi-party setup
### Week 9-10: Testing & Audit
- End-to-end testing
- Security review
- Performance optimization
## Next Steps
1. **Immediate**: Set up development environment
2. **Research**: Deep dive into circom best practices
3. **Prototype**: Build minimal viable circuit
4. **Evaluate**: Performance with real receipt data
5. **Decide**: Final technology choice based on testing

0
docs/reference/enterprise-sla.md → docs/5_reference/6_enterprise-sla.md
View File

0
docs/reference/threat-modeling.md → docs/5_reference/7_threat-modeling.md
View File

0
docs/reports/BLOCKCHAIN_DEPLOYMENT_SUMMARY.md → docs/5_reference/8_blockchain-deployment-summary.md
View File

0
docs/reports/PAYMENT_INTEGRATION_COMPLETE.md → docs/5_reference/9_payment-integration-complete.md
View File

0
docs/flowchart.md → docs/6_architecture/1_system-flow.md
View File

0
docs/components.md → docs/6_architecture/2_components-overview.md
View File

0
docs/coordinator-api.md → docs/6_architecture/3_coordinator-api.md
View File

0
docs/blockchain-node.md → docs/6_architecture/4_blockchain-node.md
View File

0
docs/marketplace-web.md → docs/6_architecture/5_marketplace-web.md
View File

0
docs/trade-exchange.md → docs/6_architecture/6_trade-exchange.md
View File

0
docs/wallet-documentation.md → docs/6_architecture/7_wallet.md
View File

0
docs/structure.md → docs/6_architecture/8_codebase-structure.md
View File

0
docs/full-documentation.md → docs/6_architecture/9_full-technical-reference.md
View File

20
docs/7_deployment/0_index.md Normal file
View File

@@ -0,0 +1,20 @@
# Deployment & Operations
Deploy, operate, and maintain AITBC infrastructure.
## Reading Order
| # | File | What you learn |
|---|------|----------------|
| 1 | [1_remote-deployment-guide.md](./1_remote-deployment-guide.md) | Deploy to remote servers |
| 2 | [2_service-naming-convention.md](./2_service-naming-convention.md) | Systemd service names and standards |
| 3 | [3_backup-restore.md](./3_backup-restore.md) | Backup PostgreSQL, Redis, ledger data |
| 4 | [4_incident-runbooks.md](./4_incident-runbooks.md) | Handle outages and incidents |
| 5 | [5_marketplace-deployment.md](./5_marketplace-deployment.md) | Deploy GPU marketplace endpoints |
| 6 | [6_beta-release-plan.md](./6_beta-release-plan.md) | Beta release checklist and timeline |
## Related
- [Installation](../0_getting_started/2_installation.md) — Initial setup
- [Security](../9_security/) — Security architecture and hardening
- [Architecture](../6_architecture/) — System design docs

0
docs/REMOTE_DEPLOYMENT_GUIDE.md → docs/7_deployment/1_remote-deployment-guide.md
View File

85
docs/7_deployment/2_service-naming-convention.md Normal file
View File

@@ -0,0 +1,85 @@
# AITBC Service Naming Convention
## Updated Service Names (2026-02-13)
All AITBC systemd services now follow the `aitbc-` prefix convention for consistency and easier management.
### Site A (aitbc.bubuit.net) - Production Services
| Old Name | New Name | Port | Description |
|----------|----------|------|-------------|
| blockchain-node.service | aitbc-blockchain-node-1.service | 8081 | Blockchain Node 1 |
| blockchain-node-2.service | aitbc-blockchain-node-2.service | 8082 | Blockchain Node 2 |
| blockchain-rpc.service | aitbc-blockchain-rpc-1.service | - | RPC API for Node 1 |
| blockchain-rpc-2.service | aitbc-blockchain-rpc-2.service | - | RPC API for Node 2 |
| coordinator-api.service | aitbc-coordinator-api.service | 8000 | Coordinator API |
| exchange-mock-api.service | aitbc-exchange-mock-api.service | - | Exchange Mock API |
### Site B (ns3 container) - Remote Node
| Old Name | New Name | Port | Description |
|----------|----------|------|-------------|
| blockchain-node.service | aitbc-blockchain-node-3.service | 8082 | Blockchain Node 3 |
| blockchain-rpc.service | aitbc-blockchain-rpc-3.service | - | RPC API for Node 3 |
### Already Compliant Services
These services already had the `aitbc-` prefix:
- aitbc-exchange-api.service (port 3003)
- aitbc-exchange.service (port 3002)
- aitbc-miner-dashboard.service
### Removed Services
- aitbc-blockchain.service (legacy, was on port 9080)
## Management Commands
### Check Service Status
```bash
# Site A (via SSH)
ssh aitbc-cascade "systemctl status aitbc-blockchain-node-1.service"
# Site B (via SSH)
ssh ns3-root "incus exec aitbc -- systemctl status aitbc-blockchain-node-3.service"
```
### Restart Services
```bash
# Site A
ssh aitbc-cascade "sudo systemctl restart aitbc-blockchain-node-1.service"
# Site B
ssh ns3-root "incus exec aitbc -- sudo systemctl restart aitbc-blockchain-node-3.service"
```
### View Logs
```bash
# Site A
ssh aitbc-cascade "journalctl -u aitbc-blockchain-node-1.service -f"
# Site B
ssh ns3-root "incus exec aitbc -- journalctl -u aitbc-blockchain-node-3.service -f"
```
## Service Dependencies
### Blockchain Nodes
- Node 1: `/opt/blockchain-node` → port 8081
- Node 2: `/opt/blockchain-node-2` → port 8082
- Node 3: `/opt/blockchain-node` → port 8082 (Site B)
### RPC Services
- RPC services are companion services to the main nodes
- They provide HTTP API endpoints for blockchain operations
### Coordinator API
- Main API for job submission, miner management, and receipts
- Runs on localhost:8000 inside container
- Proxied via nginx at https://aitbc.bubuit.net/api/
## Benefits of Standardized Naming
1. **Clarity**: Easy to identify AITBC services among system services
2. **Management**: Simpler to filter and manage with wildcards (`systemctl status aitbc-*`)
3. **Documentation**: Consistent naming across all documentation
4. **Automation**: Easier scripting and automation with predictable names
5. **Debugging**: Faster identification of service-related issues

0
docs/operator/backup_restore.md → docs/7_deployment/3_backup-restore.md
View File

0
docs/operator/incident-runbooks.md → docs/7_deployment/4_incident-runbooks.md
View File

0
docs/marketplace-deployment-summary.md → docs/7_deployment/5_marketplace-deployment.md
View File

0
docs/operator/beta-release-plan.md → docs/7_deployment/6_beta-release-plan.md
View File

31
docs/8_development/0_index.md Normal file
View File

@@ -0,0 +1,31 @@
# Developer Documentation
Build on the AITBC platform: APIs, SDKs, and contribution guides.
## Reading Order
| # | File | What you learn |
|---|------|----------------|
| 1 | [1_overview.md](./1_overview.md) | Platform architecture for developers |
| 2 | [2_setup.md](./2_setup.md) | Dev environment setup |
| 3 | [3_contributing.md](./3_contributing.md) | How to contribute |
| 4 | [4_examples.md](./4_examples.md) | Code examples |
| 5 | [5_developer-guide.md](./5_developer-guide.md) | SDKs, APIs, bounties |
| 6 | [6_api-authentication.md](./6_api-authentication.md) | Auth flow and tokens |
| 7 | [7_payments-receipts.md](./7_payments-receipts.md) | Payment system internals |
| 8 | [8_blockchain-node-deployment.md](./8_blockchain-node-deployment.md) | Deploy a node |
| 9 | [9_block-production-runbook.md](./9_block-production-runbook.md) | Block production ops |
| 10 | [10_bitcoin-wallet-setup.md](./10_bitcoin-wallet-setup.md) | BTC wallet integration |
| 11 | [11_marketplace-backend-analysis.md](./11_marketplace-backend-analysis.md) | Marketplace internals |
| 12 | [12_marketplace-extensions.md](./12_marketplace-extensions.md) | Build marketplace plugins |
| 13 | [13_user-interface-guide.md](./13_user-interface-guide.md) | Trade exchange UI |
| 14 | [14_user-management-setup.md](./14_user-management-setup.md) | User management system |
| 15 | [15_ecosystem-initiatives.md](./15_ecosystem-initiatives.md) | Ecosystem roadmap |
| 16 | [16_local-assets.md](./16_local-assets.md) | Local asset management |
| 17 | [17_windsurf-testing.md](./17_windsurf-testing.md) | Testing with Windsurf |
## Related
- [Architecture](../6_architecture/) — System design docs
- [Deployment](../7_deployment/) — Production deployment guides
- [CLI Reference](../5_reference/1_cli-reference.md) — Full CLI docs

0
docs/user/guides/BITCOIN-WALLET-SETUP.md → docs/8_development/10_bitcoin-wallet-setup.md
View File

0
docs/marketplace-backend-analysis.md → docs/8_development/11_marketplace-backend-analysis.md
View File

0
docs/tutorials/marketplace-extensions.md → docs/8_development/12_marketplace-extensions.md
View File

0
docs/user/guides/USER-INTERFACE-GUIDE.md → docs/8_development/13_user-interface-guide.md
View File

0
docs/user/guides/USER-MANAGEMENT-SETUP.md → docs/8_development/14_user-management-setup.md
View File

0
docs/ecosystem/ecosystem-initiatives-summary.md → docs/8_development/15_ecosystem-initiatives.md
View File

0
docs/user/guides/LOCAL_ASSETS_SUMMARY.md → docs/8_development/16_local-assets.md
View File

41
docs/guides/WINDSURF_TESTING_GUIDE.md → docs/8_development/17_windsurf-testing.md
View File

@@ -172,3 +172,44 @@ Your Windsurf testing integration is now fully configured! You can:
- Use all pytest features - Use all pytest features
Happy testing! 🚀 Happy testing! 🚀
---
## Issue
Unittest discovery errors when using Windsurf's test runner with the `tests/` folder.
## Solution
1. **Updated pyproject.toml** - Added `tests` to the testpaths configuration
2. **Created minimal conftest.py** - Removed complex imports that were causing discovery failures
3. **Test discovery now works** for files matching `test_*.py` pattern
## Current Status
- ✅ Test discovery works for simple tests (e.g., `tests/test_discovery.py`)
- ✅ All `test_*.py` files are discovered by pytest
- ⚠️ Tests with complex imports may fail during execution due to module path issues
## Running Tests
### For test discovery only (Windsurf integration):
```bash
cd /home/oib/windsurf/aitbc
python -m pytest --collect-only tests/
```
### For running all tests (with full setup):
```bash
cd /home/oib/windsurf/aitbc
python run_tests.py tests/
```
## Test Files Found
- `tests/e2e/test_wallet_daemon.py`
- `tests/integration/test_blockchain_node.py`
- `tests/security/test_confidential_transactions.py`
- `tests/unit/test_coordinator_api.py`
- `tests/test_discovery.py` (simple test file)
## Notes
- The original `conftest_full.py` contains complex fixtures requiring full module setup
- To run tests with full functionality, restore `conftest_full.py` and use the wrapper script
- For Windsurf's test discovery, the minimal `conftest.py` provides better experience

6
docs/developer/overview.md → docs/8_development/1_overview.md
View File

@@ -134,9 +134,9 @@ aitbc dev start
Choose a tutorial based on your interest: Choose a tutorial based on your interest:
- [AI Inference Service](../../tutorials/building-dapp.md) - [AI Inference Service](./12_marketplace-extensions.md)
- [Marketplace Bot](../../tutorials/integration-examples.md) - [Marketplace Bot](./4_examples.md)
- [Mining Operation](../../tutorials/mining-setup.md) - [Mining Operation](../3_miners/1_quick-start.md)
## Developer Resources ## Developer Resources

0
docs/developer/setup.md → docs/8_development/2_setup.md
View File

0
docs/developer/contributing.md → docs/8_development/3_contributing.md
View File

0
docs/developer/examples.md → docs/8_development/4_examples.md
View File

0
docs/developer-documentation.md → docs/8_development/5_developer-guide.md
View File

0
docs/developer/api-authentication.md → docs/8_development/6_api-authentication.md
View File

4
docs/user/guides/payments-receipts.md → docs/8_development/7_payments-receipts.md
View File

@@ -113,7 +113,7 @@ See [Bitcoin Wallet Setup](BITCOIN-WALLET-SETUP.md) for detailed instructions.
### Via Mining ### Via Mining
Earn AITBC by providing GPU compute: Earn AITBC by providing GPU compute:
- See [Miner Documentation](../../reference/components/miner_node.md) - See [Miner Documentation](../6_architecture/4_blockchain-node.md)
## Verifying Receipts ## Verifying Receipts
@@ -133,7 +133,7 @@ print(f"Receipt valid: {is_valid}")
Receipts can be anchored on-chain for permanent proof: Receipts can be anchored on-chain for permanent proof:
- ZK proofs enable privacy-preserving verification - ZK proofs enable privacy-preserving verification
- See [ZK Applications](../../reference/components/zk-applications.md) - See [ZK Applications](../5_reference/5_zk-proofs.md)
## Payment Disputes ## Payment Disputes

0
docs/guides/blockchain-node-deployment.md → docs/8_development/8_blockchain-node-deployment.md
View File

0
docs/guides/block-production-runbook.md → docs/8_development/9_block-production-runbook.md
View File

10
docs/SECURITY_CLEANUP_GUIDE.md → docs/9_security/1_security-cleanup-guide.md
View File

@@ -29,6 +29,16 @@
- ✅ Removed legacy session dependencies - ✅ Removed legacy session dependencies
- ✅ Consistent session management across services - ✅ Consistent session management across services
6. **Structured Error Responses**
- ✅ Implemented standardized error responses across all APIs
- ✅ Added `ErrorResponse` and `ErrorDetail` Pydantic models
- ✅ All exceptions now have `error_code`, `status_code`, and `to_response()` method
7. **Health Check Endpoints**
- ✅ Added liveness and readiness probes
- ✅ `/health/live` - Simple alive check
- ✅ `/health/ready` - Database connectivity check
## 🔐 SECURITY FINDINGS ## 🔐 SECURITY FINDINGS
### Files Currently Tracked That Should Be Removed ### Files Currently Tracked That Should Be Removed

0
docs/operator/security.md → docs/9_security/2_security-architecture.md
View File

142
docs/README.md Normal file
View File

@@ -0,0 +1,142 @@
# AITBC Documentation
**AI Training Blockchain - Decentralized GPU Computing Platform**
Welcome to the AITBC documentation! This guide will help you navigate the documentation based on your role.
## Quick Navigation
### 👤 New Users - Start Here!
Start with the **Getting Started** section to learn the basics:
| Order | Topic | Description |
|-------|-------|-------------|
| 1 | [0_getting_started/1_intro.md](./0_getting_started/1_intro.md) | What is AITBC? |
| 2 | [0_getting_started/2_installation.md](./0_getting_started/2_installation.md) | Install AITBC |
| 3 | [0_getting_started/3_cli.md](./0_getting_started/3_cli.md) | Use the CLI |
### 💻 Clients
If you're a **client** looking to rent GPU computing power:
| Order | Topic | Description |
|-------|-------|-------------|
| 1 | [2_clients/1_quick-start.md](./2_clients/1_quick-start.md) | Quick start guide |
| 2 | [2_clients/2_job-submission.md](./2_clients/2_job-submission.md) | Submit compute jobs |
| 3 | [2_clients/3_job-lifecycle.md](./2_clients/3_job-lifecycle.md) | Status, results, history, cancellation |
| 4 | [2_clients/4_wallet.md](./2_clients/4_wallet.md) | Manage tokens |
| 5 | [2_clients/5_pricing-billing.md](./2_clients/5_pricing-billing.md) | Costs & invoices |
| 6 | [2_clients/6_api-reference.md](./2_clients/6_api-reference.md) | Client API reference |
### ⛏️ Miners
If you're a **miner** providing GPU resources:
| Order | Topic | Description |
|-------|-------|-------------|
| 1 | [3_miners/1_quick-start.md](./3_miners/1_quick-start.md) | Quick start guide |
| 2 | [3_miners/2_registration.md](./3_miners/2_registration.md) | Register your miner |
| 3 | [3_miners/3_job-management.md](./3_miners/3_job-management.md) | Handle jobs |
| 4 | [3_miners/4_earnings.md](./3_miners/4_earnings.md) | Track earnings |
| 5 | [3_miners/5_gpu-setup.md](./3_miners/5_gpu-setup.md) | Configure GPUs |
### 🔗 Node Operators
If you're running a **blockchain node**:
| Order | Topic | Description |
|-------|-------|-------------|
| 1 | [4_blockchain/1_quick-start.md](./4_blockchain/1_quick-start.md) | Quick start guide |
| 2 | [4_blockchain/2_configuration.md](./4_blockchain/2_configuration.md) | Configure your node |
| 3 | [4_blockchain/3_operations.md](./4_blockchain/3_operations.md) | Day-to-day operations |
| 4 | [4_blockchain/4_consensus.md](./4_blockchain/4_consensus.md) | Consensus mechanism |
| 5 | [4_blockchain/7_monitoring.md](./4_blockchain/7_monitoring.md) | Monitor your node |
## Documentation Structure
```
docs/
├── 0_getting_started/ # New users start here
│ ├── 1_intro.md # What is AITBC?
│ ├── 2_installation.md # Installation guide
│ └── 3_cli.md # CLI usage
├── 1_project/ # Project management
│ ├── 1_files.md # File reference
│ ├── 2_roadmap.md # Future plans
│ ├── 3_currenttask.md # Current task (gitignored)
│ ├── 4_currentissue.md # Current issue (gitignored)
│ ├── 5_done.md # Completed work
│ └── 6_cross-site-sync-resolved.md
├── 2_clients/ # Client docs (beginner → advanced)
│ ├── 0_readme.md # Overview
│ ├── 1_quick-start.md # Get started
│ ├── 2_job-submission.md # Submit jobs
│ ├── 3_job-lifecycle.md # Status, results, history, cancel
│ ├── 4_wallet.md # Token management
│ ├── 5_pricing-billing.md # Costs & invoices
│ └── 6_api-reference.md # API reference
├── 3_miners/ # Miner docs (beginner → advanced)
│ ├── 0_readme.md # Overview
│ ├── 1_quick-start.md → 7_api-miner.md
├── 4_blockchain/ # Node operator docs (beginner → advanced)
│ ├── 0_readme.md # Overview
│ ├── 1_quick-start.md → 10_api-blockchain.md
├── 5_reference/ # Technical reference (17 files)
│ ├── 0_index.md
│ ├── 1_cli-reference.md → 17_docs-gaps.md
├── 6_architecture/ # Architecture + component deep-dives
│ ├── 1_system-flow.md # End-to-end flow
│ ├── 2_components-overview.md
│ ├── 3_coordinator-api.md # Component docs
│ ├── 4_blockchain-node.md
│ ├── 5_marketplace-web.md
│ ├── 6_trade-exchange.md
│ ├── 7_wallet.md
│ ├── 8_codebase-structure.md
│ └── 9_full-technical-reference.md
├── 7_deployment/ # Deployment & ops
│ ├── 0_index.md
│ ├── 1_remote-deployment-guide.md → 6_beta-release-plan.md
├── 8_development/ # Developer guides (17 files)
│ ├── 0_index.md
│ ├── 1_overview.md → 17_windsurf-testing.md
├── 9_security/ # Security docs
│ ├── 1_security-cleanup-guide.md
│ └── 2_security-architecture.md
└── README.md # This navigation guide
```
## Common Tasks
| Task | Documentation |
|------|---------------|
| Install AITBC | [0_getting_started/2_installation.md](./0_getting_started/2_installation.md) |
| Submit a job | [2_clients/2_job-submission.md](./2_clients/2_job-submission.md) |
| Register as miner | [3_miners/2_registration.md](./3_miners/2_registration.md) |
| Set up a node | [4_blockchain/1_quick-start.md](./4_blockchain/1_quick-start.md) |
| Check balance | [2_clients/4_wallet.md](./2_clients/4_wallet.md) |
| Monitor node | [4_blockchain/7_monitoring.md](./4_blockchain/7_monitoring.md) |
| Troubleshooting | [4_blockchain/8_troubleshooting.md](./4_blockchain/8_troubleshooting.md) |
## Additional Resources
| Resource | Description |
|----------|-------------|
| [README.md](../README.md) | Project overview |
| [1_project/2_roadmap.md](./1_project/2_roadmap.md) | Development roadmap |
| [infrastructure.md](./infrastructure.md) | Network topology |
| [1_project/5_done.md](./1_project/5_done.md) | Completed features |
| [GitHub](https://github.com/oib/AITBC) | Source code |
## Support
- **Issues**: [GitHub Issues](https://github.com/oib/AITBC/issues)
- **Discord**: [Join our community](https://discord.gg/aitbc)
- **Email**: support@aitbc.io
---
**Version**: 1.0.0
**Last Updated**: 2026-02-13
**Maintainers**: AITBC Development Team

80
docs/cli-progress-summary.md
View File

@@ -1,80 +0,0 @@
# AITBC CLI Enhancement Progress Summary
## Status: ALL PHASES COMPLETE ✅
**141/141 tests passing** | **0 failures** | **12 command groups** | **90+ subcommands**
## Completed Phases
### Phase 0: Foundation ✅
- Standardized URLs, package structure, credential storage
- Created unified CLI entry point with Click framework
### Phase 1: Core Enhancements ✅
- **client.py**: Retry with exponential backoff, job history/filtering, batch submit (CSV/JSON), job templates
- **miner.py**: Earnings tracking, capability management, deregistration, job filtering, concurrent processing
- **wallet.py**: Multi-wallet, backup/restore, staking, `--wallet-path`, multi-signature wallets
- **auth.py**: Login/logout, token management, multi-environment, API key rotation
### Phase 2: New CLI Tools ✅
- blockchain.py, marketplace.py, admin.py, config.py, simulate.py
### Phase 3: Testing & Documentation ✅
- 141/141 CLI unit tests across 9 test files + 24 integration tests (0 failures)
- CI/CD: `.github/workflows/cli-tests.yml` (Python 3.10/3.11/3.12)
- CLI reference docs (`docs/cli-reference.md` — 560+ lines)
- Shell completion script, man page (`cli/man/aitbc.1`)
### Phase 4: Backend Integration ✅
- MarketplaceOffer model extended with GPU-specific fields
- GPU booking system, review system, sync-offers endpoint
### Phase 5: Advanced Features ✅
- **Scripting**: Batch CSV/JSON ops, job templates, webhook notifications, plugin system
- **Monitoring**: Real-time dashboard, metrics collection/export, alert configuration, historical analysis
- **Security**: Multi-signature wallets, encrypted config, audit logging
- **UX**: Rich progress bars, colored output, interactive prompts, auto-completion, man pages
## Test Coverage (141 tests)
| File | Tests |
|------|-------|
| test_config.py | 37 |
| test_wallet.py | 24 |
| test_auth.py | 15 |
| test_admin.py | 13 |
| test_governance.py | 13 |
| test_simulate.py | 12 |
| test_marketplace.py | 11 |
| test_blockchain.py | 10 |
| test_client.py | 12 |
## CLI Structure
```
aitbc
├── client - Submit/manage jobs, batch submit, templates, payments
├── miner - Register, mine, earnings, capabilities, concurrent
├── wallet - Balance, staking, multisig, backup/restore, liquidity
├── auth - Login/logout, tokens, API keys
├── blockchain - Blocks, transactions, validators, supply
├── marketplace - GPU list/book/release, orders, reviews
├── admin - Status, jobs, miners, maintenance, audit-log
├── config - Set/get, profiles, secrets, import/export
├── monitor - Dashboard, metrics, alerts, webhooks, campaigns
├── simulate - Init, users, workflow, load-test, scenarios
├── governance - Propose, vote, list, result
├── plugin - Install/uninstall/list/toggle custom commands
└── version - Show version information
```
## Quick Start
```bash
cd /home/oib/windsurf/aitbc && pip install -e .
export CLIENT_API_KEY=your_key_here
aitbc config set coordinator_url http://localhost:8000
aitbc client submit --prompt "What is AI?"
aitbc wallet balance
aitbc monitor dashboard
```

56
docs/cli-summary.md
View File

@@ -1,56 +0,0 @@
# AITBC CLI Enhancement Summary
## Overview
All CLI enhancement phases (0–5) are complete. The AITBC CLI provides a production-ready interface with 141/141 tests passing, 12 command groups, and 90+ subcommands.
## Architecture
- **Package**: `cli/aitbc_cli/` with modular commands
- **Framework**: Click + Rich for output formatting
- **Testing**: pytest with Click CliRunner, 141/141 passing
- **CI/CD**: `.github/workflows/cli-tests.yml` (Python 3.10/3.11/3.12)
## Command Groups
| Group | Subcommands |
|-------|-------------|
| **client** | submit, status, blocks, receipts, cancel, history, batch-submit, template, create-payment, get-payment, release-payment, refund-payment |
| **miner** | register, poll, mine, heartbeat, status, earnings, update-capabilities, deregister, jobs, concurrent-mine |
| **wallet** | balance, earn, spend, send, history, address, stats, stake, unstake, staking-info, create, list, switch, delete, backup, restore, info, request-payment, multisig-create, multisig-propose, multisig-sign, liquidity-stake, liquidity-unstake, rewards |
| **auth** | login, logout, token, status, refresh, keys (create/list/revoke), import-env |
| **blockchain** | blocks, block, transaction, status, sync-status, peers, info, supply, validators |
| **marketplace** | gpu (register/list/details/book/release), orders, pricing, reviews |
| **admin** | status, jobs, miners, analytics, logs, maintenance, audit-log |
| **config** | show, set, path, edit, reset, export, import, validate, environments, profiles, set-secret, get-secret |
| **monitor** | dashboard, metrics, alerts, history, webhooks, campaigns, campaign-stats |
| **simulate** | init, user (create/list/balance/fund), workflow, load-test, scenario, results, reset |
| **governance** | propose, vote, list, result |
| **plugin** | install, uninstall, list, toggle |
## Global Options
- `--output table|json|yaml` — Output format
- `--url URL` — Override coordinator URL
- `--api-key KEY` — Override API key
- `-v|-vv|-vvv` — Verbosity levels
- `--debug` — Debug mode
- `--config-file PATH` — Custom config file
## Installation
```bash
cd /home/oib/windsurf/aitbc
pip install -e .
```
## Key Features
- Rich output formatting (table/JSON/YAML)
- Retry with exponential backoff
- Progress bars for long-running operations
- Interactive prompts for destructive operations
- Multi-wallet support with staking and multi-sig
- Encrypted configuration secrets
- Audit logging
- Plugin system for custom commands
- Real-time monitoring dashboard
- Webhook notifications
- Batch job submission from CSV/JSON
- Job templates for repeated tasks
- Shell completion and man pages

305
docs/client-documentation.md
View File

@@ -1,305 +0,0 @@
# Client Documentation - AITBC
Use AITBC for AI/ML Workloads: Access secure, private, and verifiable AI/ML computation on the decentralized network
> ✅ **Now Available: CLI Wrapper Tool**
>
> Submit jobs, check status, and verify receipts with our new bash CLI wrapper. Supporting 13+ Ollama models with real-time blockchain verification!
## Key Features
- **Privacy First** - Your data and models remain confidential with zero-knowledge proofs and secure enclaves
- **Verifiable Results** - Every computation is cryptographically verified on the blockchain for trust and transparency
- **Fast & Efficient** - Access thousands of GPUs worldwide with sub-second response times
## Getting Started
Start using AITBC in minutes with our simple client SDK or web interface.
### Quick Start Options
- **CLI Wrapper Tool**: ✅ NEW - Unified bash script for job management
- **Web Interface**: No installation required
- **Python SDK**: For AI/ML developers
- **JavaScript SDK**: For web applications
- **REST API**: For any platform
### CLI Wrapper Tool (Recommended)
#### Submit an Inference Job
Use the bash CLI wrapper for easy job submission:
```bash
# Submit job with CLI wrapper
./scripts/aitbc-cli.sh submit inference \
--prompt "What is machine learning?" \
--model llama3.2:latest
# Check job status
./scripts/aitbc-cli.sh status <job_id>
# View receipt with payment details
./scripts/aitbc-cli.sh receipts --job-id <job_id>
```
> **Available Models:** llama3.2, mistral, deepseek-r1:14b, gemma3, qwen2.5-coder, and 8+ more via Ollama integration. Processing time: 11-25 seconds. Rate: 0.02 AITBC per GPU second.
### Web Interface (Fastest)
1. **Visit the Marketplace**
- Go to [aitbc.bubuit.net/marketplace](https://aitbc.bubuit.net/marketplace)
2. **Connect Your Wallet**
- Connect MetaMask or create a new AITBC wallet
3. **Submit Your Job**
- Upload your data or model, select parameters, and submit
4. **Get Results**
- Receive verified results with cryptographic proof
## Popular Use Cases
### AI Inference ✅ LIVE
Run inference on pre-trained models including LLama, Mistral, DeepSeek, and custom models via Ollama
- Text generation (13+ models)
- Code generation (DeepSeek, Qwen)
- Translation (Qwen2.5-translator)
- Real-time processing (11-25s)
### Model Training
Train and fine-tune models on your data with privacy guarantees
- Fine-tuning LLMs
- Custom model training
- Federated learning
- Transfer learning
### Data Analysis
Process large datasets with confidential computing
- Statistical analysis
- Pattern recognition
- Predictive modeling
- Data visualization
### Secure Computation
Run sensitive computations with end-to-end encryption
- Financial modeling
- Healthcare analytics
- Legal document processing
- Proprietary algorithms
## SDK Examples
### Python SDK
```python
# Install the SDK
pip install aitbc
# Initialize client
from aitbc import AITBCClient
client = AITBCClient(api_key="your-api-key")
# Run inference
result = client.inference(
model="gpt-4",
prompt="Explain quantum computing",
max_tokens=500,
temperature=0.7
)
print(result.text)
# Verify the receipt
is_valid = client.verify_receipt(result.receipt_id)
print(f"Verified: {is_valid}")
```
### JavaScript SDK
```javascript
// Install the SDK
npm install @aitbc/client
// Initialize client
import { AITBCClient } from '@aitbc/client';
const client = new AITBCClient({
apiKey: 'your-api-key',
network: 'mainnet'
});
// Run inference
const result = await client.inference({
model: 'stable-diffusion',
prompt: 'A futuristic city',
steps: 50,
cfg_scale: 7.5
});
// Download the image
await client.downloadImage(result.imageId, './output.png');
// Verify computation
const verified = await client.verify(result.receiptId);
console.log('Computation verified:', verified);
```
### REST API
```bash
# Submit a job
curl -X POST https://aitbc.bubuit.net/api/v1/jobs \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"type": "inference",
"model": "gpt-4",
"input": {
"prompt": "Hello, AITBC!",
"max_tokens": 100
},
"privacy": {
"confidential": true,
"zk_proof": true
}
}'
# Check job status
curl -X GET https://aitbc.bubuit.net/api/v1/jobs/JOB_ID \
-H "Authorization: Bearer YOUR_TOKEN"
```
## Pricing
Flexible pricing options for every use case
### Pay-per-use
- **$0.01/1K tokens**
- No minimum commitment
- Pay only for what you use
- All models available
- Basic support
### Professional
- **$99/month**
- $500 included credits
- Priority processing
- Advanced models
- Email support
- API access
### Enterprise
- **Custom**
- Unlimited usage
- Dedicated resources
- Custom models
- 24/7 support
- SLA guarantee
## Privacy & Security
> **Your data is never stored or exposed** - All computations are performed in secure enclaves with zero-knowledge proof verification.
### Privacy Features
- **End-to-end encryption** - Your data is encrypted before leaving your device
- **Zero-knowledge proofs** - Prove computation without revealing inputs
- **Secure enclaves** - Computations run in isolated, verified environments
- **No data retention** - Providers cannot access or store your data
- **Audit trails** - Full transparency on blockchain
### Compliance
- GDPR compliant
- SOC 2 Type II certified
- HIPAA eligible
- ISO 27001 certified
## Best Practices
### Optimizing Performance
- Use appropriate model sizes for your task
- Batch requests when possible
- Enable caching for repeated queries
- Choose the right privacy level for your needs
- Monitor your usage and costs
### Security Tips
- Keep your API keys secure
- Use environment variables for credentials
- Enable two-factor authentication
- Regularly rotate your keys
- Use VPN for additional privacy
### Cost Optimization
- Start with smaller models for testing
- Use streaming for long responses
- Set appropriate limits and timeouts
- Monitor token usage
- Consider subscription plans for regular use
## Support & Resources
### Getting Help
- **Documentation**: [Full API reference](full-documentation.html)
- **Community**: [Join our Discord](https://discord.gg/aitbc)
- **Email**: [aitbc@bubuit.net](mailto:aitbc@bubuit.net)
- **Status**: [System status](https://status.aitbc.bubuit.net)
### Tutorials
- [Getting Started with AI Inference](#)
- [Building a Chat Application](#)
- [Image Generation Guide](#)
- [Privacy-Preserving ML](#)
- [API Integration Best Practices](#)
### Examples
- [GitHub Repository](#)
- [Code Examples](#)
- [Sample Applications](#)
- [SDK Documentation](#)
## Frequently Asked Questions
> **Question not answered?** Contact us at [aitbc@bubuit.net](mailto:aitbc@bubuit.net)
### General
- **How do I get started?** - Sign up for an account, connect your wallet, and submit your first job through the web interface or API.
- **What models are available?** - We support GPT-3.5/4, Claude, Llama, Stable Diffusion, and many custom models.
- **Can I use my own model?** - Yes, you can upload and run private models with full confidentiality.
### Privacy
- **Is my data private?** - Absolutely. Your data is encrypted and never exposed to providers.
- **How do ZK proofs work?** - They prove computation was done correctly without revealing inputs.
- **Can you see my prompts?** - No, prompts are encrypted and processed in secure enclaves.
### Technical
- **What's the response time?** - Most jobs complete in 1-5 seconds depending on complexity.
- **Do you support streaming?** - Yes, streaming is available for real-time applications.
- **Can I run batch jobs?** - Yes, batch processing is supported for large workloads.
### Billing
- **How am I billed?** - Pay-per-use or monthly subscription options available.
- **Can I set spending limits?** - Yes, you can set daily/monthly limits in your dashboard.
- **Do you offer refunds?** - Yes, we offer refunds for service issues within 30 days.
---
© 2025 AITBC. All rights reserved.

Some files were not shown because too many files have changed in this diff Show More