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

- 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
2026-02-13 22:39:43 +01:00
parent 0cbd2b507c
commit 06e48ef34b
196 changed files with 4660 additions and 20090 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -184,3 +184,12 @@ scripts/gpu/*.local.py
 # Deployment secrets
 scripts/deploy/*.secret.*
 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
--- a/apps/blockchain-node/src/aitbc_chain/config.py
+++ b/apps/blockchain-node/src/aitbc_chain/config.py
@@ -32,7 +32,7 @@ class ChainSettings(BaseSettings):
    min_fee: int = 0  # Minimum fee to accept into mempool

    # 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_eviction_interval: int = 60  # seconds

--- a/apps/blockchain-node/src/aitbc_chain/logger.py
+++ b/apps/blockchain-node/src/aitbc_chain/logger.py
@@ -1,13 +1,16 @@
 from __future__ import annotations

 import logging
+import sys
 from datetime import datetime
 from typing import Any, Optional

 import json


-class JsonFormatter(logging.Formatter):
+class StructuredLogFormatter(logging.Formatter):
+    """Custom JSON formatter for structured logging - consistent with coordinator API."""
+    
    RESERVED = {
        "name",
        "msg",
@@ -34,8 +37,12 @@ class JsonFormatter(logging.Formatter):
    def format(self, record: logging.LogRecord) -> str:  # type: ignore[override]
        payload: dict[str, Any] = {
            "timestamp": datetime.utcnow().isoformat() + "Z",
+            "service": "aitbc-blockchain-node",
            "level": record.levelname,
            "logger": record.name,
+            "module": record.module,
+            "function": record.funcName,
+            "line": record.lineno,
            "message": record.getMessage(),
        }

@@ -45,27 +52,66 @@ class JsonFormatter(logging.Formatter):
            payload[key] = value

        if record.exc_info:
-            payload["exc_info"] = self.formatException(record.exc_info)
+            payload["exception"] = self.formatException(record.exc_info)
        if record.stack_info:
            payload["stack"] = record.stack_info

        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)
    root = logging.getLogger()
-    if root.handlers:
-        return
+    root.handlers.clear()
    
-    handler = logging.StreamHandler()
-    formatter = JsonFormatter()
+    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')
+        )
+    
    root.addHandler(handler)
    root.setLevel(log_level)
    
+    logging.getLogger('uvicorn').setLevel(log_level)
+    logging.getLogger('uvicorn.access').setLevel(log_level)
+

 def get_logger(name: str) -> logging.Logger:
+    """Get a logger instance."""
    if not logging.getLogger().handlers:
        configure_logging()
    return logging.getLogger(name)
+
+
+def get_audit_logger(name: str = "audit") -> AuditLogger:
+    """Get an audit logger instance."""
+    return AuditLogger(get_logger(name))
--- a/apps/coordinator-api/src/app/config.py
+++ b/apps/coordinator-api/src/app/config.py
@@ -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 typing import List, Optional
 from pathlib import Path
 import os


-class Settings(BaseSettings):
-    model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8", case_sensitive=False)
+class DatabaseConfig(BaseSettings):
+    """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_host: str = "127.0.0.1"
    app_port: int = 8011
    
-    # Use absolute path to avoid database duplicates in different working directories
-    @property
-    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}"
+    # Database
+    database: DatabaseConfig = DatabaseConfig()
    
+    # API Keys
    client_api_keys: List[str] = []
    miner_api_keys: List[str] = []
    admin_api_keys: List[str] = []
    
+    # Security
    hmac_secret: Optional[str] = None
+    jwt_secret: Optional[str] = None
+    jwt_algorithm: str = "HS256"
+    jwt_expiration_hours: int = 24
+    
+    # CORS
    allow_origins: List[str] = [
        "http://localhost:3000",
        "http://localhost:8080",
@@ -41,15 +85,41 @@ class Settings(BaseSettings):
        "http://localhost:8011"
    ]
    
+    # Job Configuration
    job_ttl_seconds: int = 900
    heartbeat_interval_seconds: int = 10
    heartbeat_timeout_seconds: int = 30
    
+    # Rate Limiting
    rate_limit_requests: int = 60
    rate_limit_window_seconds: int = 60
    
+    # Receipt Signing
    receipt_signing_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()
+
+# Validate secrets on import
+settings.validate_secrets()
--- a/apps/coordinator-api/src/app/deps.py
+++ b/apps/coordinator-api/src/app/deps.py
@@ -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 .config import settings
+from .storage import SessionDep


 class APIKeyValidator:
+    """Validator for API key authentication."""
+    
    def __init__(self, allowed_keys: list[str]):
        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]:
+    """Dependency for client API key authentication."""
    return APIKeyValidator(settings.client_api_keys)


 def require_miner_key() -> Callable[[str | None], str]:
+    """Dependency for miner API key authentication."""
    return APIKeyValidator(settings.miner_api_keys)


 def require_admin_key() -> Callable[[str | None], str]:
+    """Dependency for admin API key authentication."""
    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()
--- a/apps/coordinator-api/src/app/exceptions.py
+++ b/apps/coordinator-api/src/app/exceptions.py
@@ -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):
    """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):
    """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):
    """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)
        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):
    """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):
        super().__init__(message)
-        self.status_code = status_code
+        self.status_code = status_code or self.status_code
        self.response = response


 class ConfigurationError(AITBCError):
    """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):
    """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):
    """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):
    """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):
    """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):
    """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):
    """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):
    """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):
    """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):
    """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):
    """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)
--- a/apps/coordinator-api/src/app/logging.py
+++ b/apps/coordinator-api/src/app/logging.py
@@ -1,25 +1,101 @@
 """
 Logging configuration for the AITBC Coordinator API
+
+Provides structured JSON logging for better observability and log parsing.
 """

 import logging
 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:
-    """Setup structured logging for the application."""
-    logging.basicConfig(
-        level=getattr(logging, level.upper()),
-        format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
-        handlers=[logging.StreamHandler(sys.stdout)]
+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."""
+    root_logger = logging.getLogger()
+    root_logger.handlers.clear()
+    
+    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:
    """Get a logger instance."""
    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
 setup_logging()
--- a/apps/coordinator-api/src/app/main.py
+++ b/apps/coordinator-api/src/app/main.py
@@ -1,5 +1,7 @@
-from fastapi import FastAPI
+from fastapi import FastAPI, Request
 from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+from fastapi.exceptions import RequestValidationError
 from prometheus_client import make_asgi_app

 from .config import settings
@@ -21,6 +23,11 @@ from .routers import (
 from .routers.governance import router as governance
 from .routers.partners import router as partners
 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:
@@ -28,6 +35,19 @@ def create_app() -> FastAPI:
        title="AITBC Coordinator API",
        version="0.1.0",
        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
@@ -60,10 +80,66 @@ def create_app() -> FastAPI:
    metrics_app = make_asgi_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")
    async def health() -> dict[str, str]:
        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


--- a/apps/coordinator-api/src/app/storage/db.py
+++ b/apps/coordinator-api/src/app/storage/db.py
@@ -1,3 +1,9 @@
+"""
+Database storage module for AITBC Coordinator API
+
+Provides unified database session management with connection pooling.
+"""
+
 from __future__ import annotations

 from contextlib import contextmanager
@@ -5,6 +11,7 @@ from typing import Annotated, Generator

 from fastapi import Depends
 from sqlalchemy.engine import Engine
+from sqlalchemy.pool import QueuePool
 from sqlmodel import Session, SQLModel, create_engine

 from ..config import settings
@@ -15,27 +22,48 @@ _engine: Engine | None = None


 def get_engine() -> Engine:
+    """Get or create the database engine with connection pooling."""
    global _engine

    if _engine is None:
-        connect_args = {"check_same_thread": False} if settings.database_url.startswith("sqlite") else {}
-        _engine = create_engine(settings.database_url, echo=False, connect_args=connect_args)
+        db_config = settings.database
+        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


 def init_db() -> None:
+    """Initialize database tables."""
    engine = get_engine()
    SQLModel.metadata.create_all(engine)


@contextmanager
 def session_scope() -> Generator[Session, None, None]:
+    """Context manager for database sessions."""
    engine = get_engine()
-    with Session(engine) as session:
+    session = Session(engine)
+    try:
        yield session
+        session.commit()
+    except Exception:
+        session.rollback()
+        raise
+    finally:
+        session.close()


 def get_session() -> Generator[Session, None, None]:
+    """Get a database session (for FastAPI dependency)."""
    with session_scope() as session:
        yield session

--- a/docs/0_getting_started/1_intro.md
+++ b/docs/0_getting_started/1_intro.md
@@ -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
--- a/docs/0_getting_started/2_installation.md
+++ b/docs/0_getting_started/2_installation.md
@@ -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
--- a/docs/0_getting_started/3_cli.md
+++ b/docs/0_getting_started/3_cli.md
@@ -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.
--- a/docs/1_project/1_files.md
+++ b/docs/1_project/1_files.md
--- a/docs/1_project/2_roadmap.md
+++ b/docs/1_project/2_roadmap.md
@@ -797,7 +797,147 @@ Current Status: Canonical receipt schema specification moved from `protocols/rec
 - ✅ Site B (ns3): No action needed (blockchain node only)
 - ✅ 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
 - Renamed local `master` branch to `main` and set tracking to `github/main`
--- a/docs/1_project/5_done.md
+++ b/docs/1_project/5_done.md
@@ -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 B** (ns3): No action needed - only blockchain node running
 - ✅ **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
--- a/docs/issues/2026-01-29_cross-site-sync-resolved.md
+++ b/docs/issues/2026-01-29_cross-site-sync-resolved.md
--- a/docs/2_clients/0_readme.md
+++ b/docs/2_clients/0_readme.md
@@ -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
--- a/docs/2_clients/1_quick-start.md
+++ b/docs/2_clients/1_quick-start.md
@@ -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
--- a/docs/2_clients/2_job-submission.md
+++ b/docs/2_clients/2_job-submission.md
@@ -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
--- a/docs/2_clients/3_job-lifecycle.md
+++ b/docs/2_clients/3_job-lifecycle.md
@@ -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
--- a/docs/2_clients/4_wallet.md
+++ b/docs/2_clients/4_wallet.md
@@ -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
--- a/docs/2_clients/5_pricing-billing.md
+++ b/docs/2_clients/5_pricing-billing.md
@@ -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
--- a/docs/2_clients/6_api-reference.md
+++ b/docs/2_clients/6_api-reference.md
@@ -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
--- a/docs/3_miners/0_readme.md
+++ b/docs/3_miners/0_readme.md
@@ -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
--- a/docs/3_miners/1_quick-start.md
+++ b/docs/3_miners/1_quick-start.md
@@ -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
--- a/docs/3_miners/2_registration.md
+++ b/docs/3_miners/2_registration.md
@@ -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
--- a/docs/3_miners/3_job-management.md
+++ b/docs/3_miners/3_job-management.md
@@ -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
--- a/docs/3_miners/4_earnings.md
+++ b/docs/3_miners/4_earnings.md
@@ -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
--- a/docs/3_miners/5_gpu-setup.md
+++ b/docs/3_miners/5_gpu-setup.md
@@ -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
--- a/docs/3_miners/6_monitoring.md
+++ b/docs/3_miners/6_monitoring.md
@@ -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
--- a/docs/3_miners/7_api-miner.md
+++ b/docs/3_miners/7_api-miner.md
@@ -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
--- a/docs/4_blockchain/0_readme.md
+++ b/docs/4_blockchain/0_readme.md
@@ -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
--- a/docs/4_blockchain/10_api-blockchain.md
+++ b/docs/4_blockchain/10_api-blockchain.md
@@ -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
--- a/docs/4_blockchain/1_quick-start.md
+++ b/docs/4_blockchain/1_quick-start.md
@@ -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
--- a/docs/4_blockchain/2_configuration.md
+++ b/docs/4_blockchain/2_configuration.md
@@ -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
--- a/docs/4_blockchain/3_operations.md
+++ b/docs/4_blockchain/3_operations.md
@@ -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
--- a/docs/4_blockchain/4_consensus.md
+++ b/docs/4_blockchain/4_consensus.md
@@ -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
--- a/docs/4_blockchain/5_validator.md
+++ b/docs/4_blockchain/5_validator.md
@@ -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
--- a/docs/4_blockchain/6_networking.md
+++ b/docs/4_blockchain/6_networking.md
@@ -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
--- a/docs/4_blockchain/7_monitoring.md
+++ b/docs/4_blockchain/7_monitoring.md
@@ -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
--- a/docs/4_blockchain/8_troubleshooting.md
+++ b/docs/4_blockchain/8_troubleshooting.md
@@ -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
--- a/docs/4_blockchain/9_upgrades.md
+++ b/docs/4_blockchain/9_upgrades.md
@@ -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
--- a/docs/5_reference/0_index.md
+++ b/docs/5_reference/0_index.md
@@ -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
--- a/docs/5_reference/10_implementation-complete-summary.md
+++ b/docs/5_reference/10_implementation-complete-summary.md
--- a/docs/5_reference/11_integration-test-fixes.md
+++ b/docs/5_reference/11_integration-test-fixes.md
--- a/docs/5_reference/12_integration-test-updates.md
+++ b/docs/5_reference/12_integration-test-updates.md
--- a/docs/5_reference/13_test-fixes-complete.md
+++ b/docs/5_reference/13_test-fixes-complete.md
--- a/docs/5_reference/14_testing-status-report.md
+++ b/docs/5_reference/14_testing-status-report.md
--- a/docs/5_reference/15_skipped-tests-roadmap.md
+++ b/docs/5_reference/15_skipped-tests-roadmap.md
--- a/docs/5_reference/16_security-audit-2026-02-13.md
+++ b/docs/5_reference/16_security-audit-2026-02-13.md
@@ -126,6 +126,42 @@ encrypted = encrypt_value(private_key, password)  # Fernet
 - Replaced `requests` with `httpx` (already a dependency)
 - 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

 ### Site A (aitbc.bubuit.net)
--- a/docs/5_reference/17_docs-gaps.md
+++ b/docs/5_reference/17_docs-gaps.md
--- a/docs/5_reference/1_cli-reference.md
+++ b/docs/5_reference/1_cli-reference.md
--- a/docs/5_reference/2_payment-architecture.md
+++ b/docs/5_reference/2_payment-architecture.md
--- a/docs/5_reference/3_wallet-coordinator-integration.md
+++ b/docs/5_reference/3_wallet-coordinator-integration.md
--- a/docs/5_reference/4_confidential-transactions.md
+++ b/docs/5_reference/4_confidential-transactions.md
@@ -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

--- a/docs/5_reference/5_zk-proofs.md
+++ b/docs/5_reference/5_zk-proofs.md
@@ -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
--- a/docs/5_reference/6_enterprise-sla.md
+++ b/docs/5_reference/6_enterprise-sla.md
--- a/docs/5_reference/7_threat-modeling.md
+++ b/docs/5_reference/7_threat-modeling.md
--- a/docs/5_reference/8_blockchain-deployment-summary.md
+++ b/docs/5_reference/8_blockchain-deployment-summary.md
--- a/docs/5_reference/9_payment-integration-complete.md
+++ b/docs/5_reference/9_payment-integration-complete.md
--- a/docs/6_architecture/1_system-flow.md
+++ b/docs/6_architecture/1_system-flow.md
--- a/docs/6_architecture/2_components-overview.md
+++ b/docs/6_architecture/2_components-overview.md
--- a/docs/6_architecture/3_coordinator-api.md
+++ b/docs/6_architecture/3_coordinator-api.md
--- a/docs/6_architecture/4_blockchain-node.md
+++ b/docs/6_architecture/4_blockchain-node.md
--- a/docs/6_architecture/5_marketplace-web.md
+++ b/docs/6_architecture/5_marketplace-web.md
--- a/docs/6_architecture/6_trade-exchange.md
+++ b/docs/6_architecture/6_trade-exchange.md
--- a/docs/6_architecture/7_wallet.md
+++ b/docs/6_architecture/7_wallet.md
--- a/docs/6_architecture/8_codebase-structure.md
+++ b/docs/6_architecture/8_codebase-structure.md
--- a/docs/6_architecture/9_full-technical-reference.md
+++ b/docs/6_architecture/9_full-technical-reference.md
--- a/docs/7_deployment/0_index.md
+++ b/docs/7_deployment/0_index.md
@@ -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
--- a/docs/7_deployment/1_remote-deployment-guide.md
+++ b/docs/7_deployment/1_remote-deployment-guide.md
--- a/docs/7_deployment/2_service-naming-convention.md
+++ b/docs/7_deployment/2_service-naming-convention.md
@@ -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
--- a/docs/7_deployment/3_backup-restore.md
+++ b/docs/7_deployment/3_backup-restore.md
--- a/docs/7_deployment/4_incident-runbooks.md
+++ b/docs/7_deployment/4_incident-runbooks.md
--- a/docs/7_deployment/5_marketplace-deployment.md
+++ b/docs/7_deployment/5_marketplace-deployment.md
--- a/docs/7_deployment/6_beta-release-plan.md
+++ b/docs/7_deployment/6_beta-release-plan.md
--- a/docs/8_development/0_index.md
+++ b/docs/8_development/0_index.md
@@ -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
--- a/docs/8_development/10_bitcoin-wallet-setup.md
+++ b/docs/8_development/10_bitcoin-wallet-setup.md
--- a/docs/8_development/11_marketplace-backend-analysis.md
+++ b/docs/8_development/11_marketplace-backend-analysis.md
--- a/docs/8_development/12_marketplace-extensions.md
+++ b/docs/8_development/12_marketplace-extensions.md
--- a/docs/8_development/13_user-interface-guide.md
+++ b/docs/8_development/13_user-interface-guide.md
--- a/docs/8_development/14_user-management-setup.md
+++ b/docs/8_development/14_user-management-setup.md
--- a/docs/ecosystem/ecosystem-initiatives-summary.md
+++ b/docs/ecosystem/ecosystem-initiatives-summary.md
--- a/docs/user/guides/LOCAL_ASSETS_SUMMARY.md
+++ b/docs/user/guides/LOCAL_ASSETS_SUMMARY.md
--- a/docs/8_development/17_windsurf-testing.md
+++ b/docs/8_development/17_windsurf-testing.md
@@ -172,3 +172,44 @@ Your Windsurf testing integration is now fully configured! You can:
 - Use all pytest features

 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
--- a/docs/8_development/1_overview.md
+++ b/docs/8_development/1_overview.md
@@ -134,9 +134,9 @@ aitbc dev start

 Choose a tutorial based on your interest:

- [AI Inference Service](../../tutorials/building-dapp.md)
- [Marketplace Bot](../../tutorials/integration-examples.md)
- [Mining Operation](../../tutorials/mining-setup.md)
+- [AI Inference Service](./12_marketplace-extensions.md)
+- [Marketplace Bot](./4_examples.md)
+- [Mining Operation](../3_miners/1_quick-start.md)

 ## Developer Resources

--- a/docs/8_development/2_setup.md
+++ b/docs/8_development/2_setup.md
--- a/docs/8_development/3_contributing.md
+++ b/docs/8_development/3_contributing.md
--- a/docs/8_development/4_examples.md
+++ b/docs/8_development/4_examples.md
--- a/docs/8_development/5_developer-guide.md
+++ b/docs/8_development/5_developer-guide.md
--- a/docs/8_development/6_api-authentication.md
+++ b/docs/8_development/6_api-authentication.md
--- a/docs/8_development/7_payments-receipts.md
+++ b/docs/8_development/7_payments-receipts.md
@@ -113,7 +113,7 @@ See [Bitcoin Wallet Setup](BITCOIN-WALLET-SETUP.md) for detailed instructions.
 ### Via Mining

 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

@@ -133,7 +133,7 @@ print(f"Receipt valid: {is_valid}")

 Receipts can be anchored on-chain for permanent proof:
 - 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

--- a/docs/8_development/8_blockchain-node-deployment.md
+++ b/docs/8_development/8_blockchain-node-deployment.md
--- a/docs/8_development/9_block-production-runbook.md
+++ b/docs/8_development/9_block-production-runbook.md
--- a/docs/9_security/1_security-cleanup-guide.md
+++ b/docs/9_security/1_security-cleanup-guide.md
@@ -29,6 +29,16 @@
   - ✅ Removed legacy session dependencies
   - ✅ 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

 ### Files Currently Tracked That Should Be Removed
--- a/docs/9_security/2_security-architecture.md
+++ b/docs/9_security/2_security-architecture.md
--- a/docs/README.md
+++ b/docs/README.md
@@ -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
--- a/docs/cli-progress-summary.md
+++ b/docs/cli-progress-summary.md
@@ -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
-```
--- a/docs/cli-summary.md
+++ b/docs/cli-summary.md
@@ -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
--- a/docs/client-documentation.md
+++ b/docs/client-documentation.md
@@ -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.
--- a/Show More
+++ b/Show More