```

chore: remove obsolete payment architecture and integration test documentation

- Remove AITBC_PAYMENT_ARCHITECTURE.md (dual-currency system documentation)
- Remove IMPLEMENTATION_COMPLETE_SUMMARY.md (integration test completion summary)
- Remove INTEGRATION_TEST_FIXES.md (test fixes documentation)
- Remove INTEGRATION_TEST_UPDATES.md (real features implementation notes)
- Remove PAYMENT_INTEGRATION_COMPLETE.md (wallet-coordinator integration docs)
- Remove WALLET_COORDINATOR_INTEGRATION.md (payment

CLEANUP_SUMMARY.md

@@ -0,0 +1,74 @@
+# Directory Cleanup Summary
+
+## Changes Made
+
+### 1. Created New Directories
+- `docs/reports/` - For generated reports and summaries
+- `docs/guides/` - For development guides
+- `scripts/testing/` - For test scripts and utilities
+- `dev-utils/` - For development utilities
+
+### 2. Moved Files
+
+#### Documentation Reports → `docs/reports/`
+- AITBC_PAYMENT_ARCHITECTURE.md
+- BLOCKCHAIN_DEPLOYMENT_SUMMARY.md
+- IMPLEMENTATION_COMPLETE_SUMMARY.md
+- INTEGRATION_TEST_FIXES.md
+- INTEGRATION_TEST_UPDATES.md
+- PAYMENT_INTEGRATION_COMPLETE.md
+- SKIPPED_TESTS_ROADMAP.md
+- TESTING_STATUS_REPORT.md
+- TEST_FIXES_COMPLETE.md
+- WALLET_COORDINATOR_INTEGRATION.md
+
+#### Development Guides → `docs/guides/`
+- WINDSURF_TESTING_GUIDE.md
+- WINDSURF_TEST_SETUP.md
+
+#### Test Scripts → `scripts/testing/`
+- test_block_import.py
+- test_block_import_complete.py
+- test_minimal.py
+- test_model_validation.py
+- test_payment_integration.py
+- test_payment_local.py
+- test_simple_import.py
+- test_tx_import.py
+- test_tx_model.py
+- run_test_suite.py
+- run_tests.py
+- verify_windsurf_tests.py
+- register_test_clients.py
+
+#### Development Utilities → `dev-utils/`
+- aitbc-pythonpath.pth
+
+#### Database Files → `data/`
+- coordinator.db
+
+### 3. Created Index Files
+- `docs/reports/README.md` - Index of all reports
+- `docs/guides/README.md` - Index of all guides
+- `scripts/testing/README.md` - Test scripts documentation
+- `dev-utils/README.md` - Development utilities documentation
+
+### 4. Updated Documentation
+- Updated main `README.md` with new directory structure
+- Added testing section to README
+
+## Result
+
+The root directory is now cleaner with better organization:
+- Essential files remain in root (README.md, LICENSE, pyproject.toml, etc.)
+- Documentation is properly categorized
+- Test scripts are grouped together
+- Development utilities have their own directory
+- Database files are in the data directory (already gitignored)
+
+## Notes
+
+- All moved files are still accessible through their new locations
+- The .gitignore already covers the data directory for database files
+- Test scripts can still be run from their new location
+- No functional changes were made, only organizational improvements

README.md

@@ -2,6 +2,23 @@
 
 This repository houses all components of the Artificial Intelligence Token Blockchain (AITBC) stack, including coordinator services, blockchain node, miner daemon, client-facing web apps, SDKs, and documentation.
 
+## Directory Structure
+
+```
+aitbc/
+├── apps/              # Main applications (coordinator-api, blockchain-node, etc.)
+├── packages/          # Shared packages and SDKs
+├── scripts/           # Utility scripts
+│   └── testing/       # Test scripts and utilities
+├── tests/             # Pytest test suites
+├── docs/              # Documentation
+│   ├── guides/        # Development guides
+│   └── reports/       # Generated reports and summaries
+├── infra/             # Infrastructure and deployment configs
+├── dev-utils/         # Development utilities
+└── .windsurf/         # Windsurf IDE configuration
+```
+
 ## Getting Started
 
 1. Review the bootstrap documents under `docs/bootstrap/` to understand stage-specific goals.
@@ -10,3 +27,10 @@ This repository houses all components of the Artificial Intelligence Token Block
 4. Explore the new Python receipt SDK under `packages/py/aitbc-sdk/` for helpers to fetch and verify coordinator receipts (see `docs/run.md` for examples).
 5. Run `scripts/ci/run_python_tests.sh` (via Poetry) to execute coordinator, SDK, miner-node, and wallet-daemon test suites before submitting changes.
 6. GitHub Actions (`.github/workflows/python-tests.yml`) automatically runs the same script on pushes and pull requests targeting `main`.
+
+## Testing
+
+- Test scripts are located in `scripts/testing/`
+- Run individual tests: `python3 scripts/testing/test_block_import.py`
+- Run pytest suite: `pytest tests/`
+- See `docs/guides/WINDSURF_TESTING_GUIDE.md` for detailed testing instructions

apps/blockchain-explorer/assets/index.js

@@ -0,0 +1,195 @@
+import { createApp } from 'https://unpkg.com/vue@3/dist/vue.esm-browser.js'
+
+const API_BASE = '/api/v1'
+
+const app = createApp({
+  data() {
+    return {
+      loading: true,
+      chainInfo: {
+        height: 0,
+        hash: '',
+        timestamp: null,
+        tx_count: 0
+      },
+      latestBlocks: [],
+      stats: {
+        totalBlocks: 0,
+        totalTransactions: 0,
+        avgBlockTime: 2.0,
+        hashRate: '0 H/s'
+      },
+      error: null
+    }
+  },
+  
+  async mounted() {
+    await this.loadChainData()
+    setInterval(this.loadChainData, 5000)
+  },
+  
+  methods: {
+    async loadChainData() {
+      try {
+        this.error = null
+        
+        // Load chain head
+        const headResponse = await fetch(`${API_BASE}/chain/head`)
+        if (headResponse.ok) {
+          this.chainInfo = await headResponse.json()
+        }
+        
+        // Load latest blocks
+        const blocksResponse = await fetch(`${API_BASE}/chain/blocks?limit=10`)
+        if (blocksResponse.ok) {
+          this.latestBlocks = await blocksResponse.json()
+        }
+        
+        // Calculate stats
+        this.stats.totalBlocks = this.chainInfo.height || 0
+        this.stats.totalTransactions = this.latestBlocks.reduce((sum, block) => sum + (block.tx_count || 0), 0)
+        
+        this.loading = false
+      } catch (error) {
+        console.error('Failed to load chain data:', error)
+        this.error = 'Failed to connect to blockchain node'
+        this.loading = false
+      }
+    },
+    
+    formatHash(hash) {
+      if (!hash) return '-'
+      return hash.substring(0, 10) + '...' + hash.substring(hash.length - 8)
+    },
+    
+    formatTime(timestamp) {
+      if (!timestamp) return '-'
+      return new Date(timestamp * 1000).toLocaleString()
+    },
+    
+    formatNumber(num) {
+      if (!num) return '0'
+      return num.toLocaleString()
+    },
+    
+    getBlockType(block) {
+      if (!block) return 'unknown'
+      return block.tx_count > 0 ? 'with-tx' : 'empty'
+    }
+  },
+  
+  template: `
+    <div class="app">
+      <!-- Header -->
+      <header class="header">
+        <div class="container">
+          <div class="header-content">
+            <div class="logo">
+              <svg class="logo-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor">
+                <path d="M12 2L2 7L12 12L22 7L12 2Z"></path>
+                <path d="M2 17L12 22L22 17"></path>
+                <path d="M2 12L12 17L22 12"></path>
+              </svg>
+              <h1>AITBC Explorer</h1>
+            </div>
+            <div class="header-stats">
+              <div class="stat">
+                <span class="stat-label">Height</span>
+                <span class="stat-value">{{ formatNumber(chainInfo.height) }}</span>
+              </div>
+            </div>
+          </div>
+        </div>
+      </header>
+
+      <!-- Main Content -->
+      <main class="main">
+        <div class="container">
+          <!-- Loading State -->
+          <div v-if="loading" class="loading">
+            <div class="spinner"></div>
+            <p>Loading blockchain data...</p>
+          </div>
+          
+          <!-- Error State -->
+          <div v-else-if="error" class="error">
+            <svg class="error-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor">
+              <circle cx="12" cy="12" r="10"></circle>
+              <line x1="12" y1="8" x2="12" y2="12"></line>
+              <line x1="12" y1="16" x2="12.01" y2="16"></line>
+            </svg>
+            <p>{{ error }}</p>
+            <button @click="loadChainData" class="retry-btn">Retry</button>
+          </div>
+          
+          <!-- Chain Overview -->
+          <div v-else class="overview">
+            <div class="cards">
+              <div class="card">
+                <div class="card-icon">
+                  <svg viewBox="0 0 24 24" fill="none" stroke="currentColor">
+                    <path d="M13 2L3 14h9l-1 8 10-12h-9l1-8z"></path>
+                  </svg>
+                </div>
+                <div class="card-content">
+                  <h3>Current Height</h3>
+                  <p class="card-value">{{ formatNumber(chainInfo.height) }}</p>
+                </div>
+              </div>
+              
+              <div class="card">
+                <div class="card-icon">
+                  <svg viewBox="0 0 24 24" fill="none" stroke="currentColor">
+                    <path d="M21 16V8a2 2 0 0 0-1-1.73l-7-4a2 2 0 0 0-2 0l-7 4A2 2 0 0 0 3 8v8a2 2 0 0 0 1 1.73l7 4a2 2 0 0 0 2 0l7-4A2 2 0 0 0 21 16z"></path>
+                  </svg>
+                </div>
+                <div class="card-content">
+                  <h3>Latest Block</h3>
+                  <p class="card-value hash">{{ formatHash(chainInfo.hash) }}</p>
+                </div>
+              </div>
+              
+              <div class="card">
+                <div class="card-icon">
+                  <svg viewBox="0 0 24 24" fill="none" stroke="currentColor">
+                    <path d="M12 2v20M17 5H9.5a3.5 3.5 0 0 0 0 7h5a3.5 3.5 0 0 1 0 7H6"></path>
+                  </svg>
+                </div>
+                <div class="card-content">
+                  <h3>Total Transactions</h3>
+                  <p class="card-value">{{ formatNumber(stats.totalTransactions) }}</p>
+                </div>
+              </div>
+            </div>
+          </div>
+          
+          <!-- Latest Blocks -->
+          <div v-if="!loading && !error" class="blocks-section">
+            <h2>Latest Blocks</h2>
+            <div class="blocks-list">
+              <div v-for="block in latestBlocks" :key="block.height" 
+                   class="block-item" :class="getBlockType(block)">
+                <div class="block-height">
+                  <span class="height">{{ formatNumber(block.height) }}</span>
+                  <span v-if="block.tx_count > 0" class="tx-badge">{{ block.tx_count }} tx</span>
+                </div>
+                <div class="block-details">
+                  <div class="block-hash">
+                    <span class="label">Hash:</span>
+                    <span class="value">{{ formatHash(block.hash) }}</span>
+                  </div>
+                  <div class="block-time">
+                    <span class="label">Time:</span>
+                    <span class="value">{{ formatTime(block.timestamp) }}</span>
+                  </div>
+                </div>
+              </div>
+            </div>
+          </div>
+        </div>
+      </main>
+    </div>
+  `
+})
+
+app.mount('#app')

apps/blockchain-explorer/assets/style.css

@@ -0,0 +1,315 @@
+* {
+  margin: 0;
+  padding: 0;
+  box-sizing: border-box;
+}
+
+:root {
+  --primary-color: #3b82f6;
+  --primary-dark: #2563eb;
+  --secondary-color: #10b981;
+  --background: #f9fafb;
+  --surface: #ffffff;
+  --text-primary: #111827;
+  --text-secondary: #6b7280;
+  --border-color: #e5e7eb;
+  --error-color: #ef4444;
+  --success-color: #22c55e;
+}
+
+body {
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
+  background-color: var(--background);
+  color: var(--text-primary);
+  line-height: 1.6;
+}
+
+.container {
+  max-width: 1200px;
+  margin: 0 auto;
+  padding: 0 1rem;
+}
+
+/* Header */
+.header {
+  background: var(--surface);
+  border-bottom: 1px solid var(--border-color);
+  position: sticky;
+  top: 0;
+  z-index: 100;
+  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
+}
+
+.header-content {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 1rem 0;
+}
+
+.logo {
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+}
+
+.logo-icon {
+  width: 2rem;
+  height: 2rem;
+  color: var(--primary-color);
+}
+
+.logo h1 {
+  font-size: 1.5rem;
+  font-weight: 600;
+  color: var(--text-primary);
+}
+
+.header-stats {
+  display: flex;
+  gap: 2rem;
+}
+
+.stat {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+}
+
+.stat-label {
+  font-size: 0.875rem;
+  color: var(--text-secondary);
+}
+
+.stat-value {
+  font-size: 1.25rem;
+  font-weight: 600;
+  color: var(--text-primary);
+}
+
+/* Main Content */
+.main {
+  padding: 2rem 0;
+  min-height: calc(100vh - 80px);
+}
+
+/* Loading State */
+.loading {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  padding: 4rem 0;
+  color: var(--text-secondary);
+}
+
+.spinner {
+  width: 3rem;
+  height: 3rem;
+  border: 3px solid var(--border-color);
+  border-top-color: var(--primary-color);
+  border-radius: 50%;
+  animation: spin 1s linear infinite;
+  margin-bottom: 1rem;
+}
+
+@keyframes spin {
+  to { transform: rotate(360deg); }
+}
+
+/* Error State */
+.error {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  padding: 4rem 0;
+  color: var(--error-color);
+}
+
+.error-icon {
+  width: 3rem;
+  height: 3rem;
+  margin-bottom: 1rem;
+}
+
+.retry-btn {
+  margin-top: 1rem;
+  padding: 0.5rem 1rem;
+  background: var(--primary-color);
+  color: white;
+  border: none;
+  border-radius: 0.375rem;
+  font-size: 0.875rem;
+  cursor: pointer;
+  transition: background-color 0.2s;
+}
+
+.retry-btn:hover {
+  background: var(--primary-dark);
+}
+
+/* Overview Cards */
+.overview {
+  margin-bottom: 2rem;
+}
+
+.cards {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
+  gap: 1.5rem;
+}
+
+.card {
+  background: var(--surface);
+  border-radius: 0.75rem;
+  padding: 1.5rem;
+  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
+  display: flex;
+  align-items: center;
+  gap: 1rem;
+  transition: transform 0.2s, box-shadow 0.2s;
+}
+
+.card:hover {
+  transform: translateY(-2px);
+  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
+}
+
+.card-icon {
+  width: 3rem;
+  height: 3rem;
+  background: var(--primary-color);
+  color: white;
+  border-radius: 0.5rem;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+}
+
+.card-icon svg {
+  width: 1.5rem;
+  height: 1.5rem;
+}
+
+.card-content h3 {
+  font-size: 0.875rem;
+  color: var(--text-secondary);
+  margin-bottom: 0.25rem;
+}
+
+.card-value {
+  font-size: 1.5rem;
+  font-weight: 600;
+  color: var(--text-primary);
+}
+
+.card-value.hash {
+  font-family: 'Courier New', monospace;
+  font-size: 1rem;
+}
+
+/* Blocks Section */
+.blocks-section h2 {
+  font-size: 1.5rem;
+  margin-bottom: 1rem;
+  color: var(--text-primary);
+}
+
+.blocks-list {
+  display: flex;
+  flex-direction: column;
+  gap: 0.75rem;
+}
+
+.block-item {
+  background: var(--surface);
+  border-radius: 0.5rem;
+  padding: 1rem;
+  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
+  display: flex;
+  align-items: center;
+  gap: 1rem;
+  transition: transform 0.2s, box-shadow 0.2s;
+}
+
+.block-item:hover {
+  transform: translateX(4px);
+  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
+}
+
+.block-item.empty {
+  opacity: 0.7;
+}
+
+.block-height {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  min-width: 80px;
+}
+
+.height {
+  font-size: 1.25rem;
+  font-weight: 600;
+  color: var(--primary-color);
+}
+
+.tx-badge {
+  margin-top: 0.25rem;
+  padding: 0.125rem 0.5rem;
+  background: var(--success-color);
+  color: white;
+  border-radius: 9999px;
+  font-size: 0.75rem;
+  font-weight: 500;
+}
+
+.block-details {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
+}
+
+.block-hash,
+.block-time {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  font-size: 0.875rem;
+}
+
+.label {
+  color: var(--text-secondary);
+  font-weight: 500;
+}
+
+.value {
+  color: var(--text-primary);
+  font-family: 'Courier New', monospace;
+}
+
+/* Responsive Design */
+@media (max-width: 768px) {
+  .header-content {
+    flex-direction: column;
+    gap: 1rem;
+  }
+  
+  .cards {
+    grid-template-columns: 1fr;
+  }
+  
+  .block-item {
+    flex-direction: column;
+    align-items: flex-start;
+  }
+  
+  .block-height {
+    flex-direction: row;
+    width: 100%;
+    justify-content: space-between;
+  }
+}

apps/blockchain-explorer/index.html

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/assets/favicon.ico" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>AITBC Explorer</title>
+    <script type="module" crossorigin src="/assets/index.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/style.css">
+  </head>
+  <body>
+    <div id="app"></div>
+  </body>
+</html>

apps/blockchain-explorer/main.py

@@ -0,0 +1,372 @@
+#!/usr/bin/env python3
+"""
+AITBC Blockchain Explorer
+A simple web interface to explore the blockchain
+"""
+
+import asyncio
+import httpx
+import json
+from datetime import datetime
+from typing import Dict, List, Optional, Any
+from fastapi import FastAPI, Request
+from fastapi.responses import HTMLResponse
+from fastapi.staticfiles import StaticFiles
+import uvicorn
+
+app = FastAPI(title="AITBC Blockchain Explorer", version="1.0.0")
+
+# Configuration
+BLOCKCHAIN_RPC_URL = "http://localhost:8082"  # Local blockchain node
+EXTERNAL_RPC_URL = "http://aitbc.keisanki.net:8082"  # External access
+
+# HTML Template
+HTML_TEMPLATE = """
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>AITBC Blockchain Explorer</title>
+    <script src="https://cdn.tailwindcss.com"></script>
+    <script src="https://unpkg.com/lucide@latest"></script>
+    <style>
+        .fade-in { animation: fadeIn 0.3s ease-in; }
+        @keyframes fadeIn { from { opacity: 0; } to { opacity: 1; } }
+    </style>
+</head>
+<body class="bg-gray-50">
+    <header class="bg-blue-600 text-white shadow-lg">
+        <div class="container mx-auto px-4 py-4">
+            <div class="flex items-center justify-between">
+                <div class="flex items-center space-x-3">
+                    <i data-lucide="cube" class="w-8 h-8"></i>
+                    <h1 class="text-2xl font-bold">AITBC Blockchain Explorer</h1>
+                </div>
+                <div class="flex items-center space-x-4">
+                    <span class="text-sm">Network: <span class="font-mono bg-blue-700 px-2 py-1 rounded">ait-devnet</span></span>
+                    <button onclick="refreshData()" class="bg-blue-500 hover:bg-blue-400 px-3 py-1 rounded flex items-center space-x-1">
+                        <i data-lucide="refresh-cw" class="w-4 h-4"></i>
+                        <span>Refresh</span>
+                    </button>
+                </div>
+            </div>
+        </div>
+    </header>
+
+    <main class="container mx-auto px-4 py-8">
+        <!-- Chain Stats -->
+        <div class="grid grid-cols-1 md:grid-cols-3 gap-6 mb-8">
+            <div class="bg-white rounded-lg shadow p-6">
+                <div class="flex items-center justify-between">
+                    <div>
+                        <p class="text-gray-500 text-sm">Current Height</p>
+                        <p class="text-2xl font-bold" id="chain-height">-</p>
+                    </div>
+                    <i data-lucide="trending-up" class="w-10 h-10 text-green-500"></i>
+                </div>
+            </div>
+            <div class="bg-white rounded-lg shadow p-6">
+                <div class="flex items-center justify-between">
+                    <div>
+                        <p class="text-gray-500 text-sm">Latest Block</p>
+                        <p class="text-lg font-mono" id="latest-hash">-</p>
+                    </div>
+                    <i data-lucide="hash" class="w-10 h-10 text-blue-500"></i>
+                </div>
+            </div>
+            <div class="bg-white rounded-lg shadow p-6">
+                <div class="flex items-center justify-between">
+                    <div>
+                        <p class="text-gray-500 text-sm">Node Status</p>
+                        <p class="text-lg font-semibold" id="node-status">-</p>
+                    </div>
+                    <i data-lucide="activity" class="w-10 h-10 text-purple-500"></i>
+                </div>
+            </div>
+        </div>
+
+        <!-- Search -->
+        <div class="bg-white rounded-lg shadow p-6 mb-8">
+            <div class="flex space-x-4">
+                <input type="text" id="search-input" placeholder="Search by block height, hash, or transaction hash" 
+                       class="flex-1 px-4 py-2 border rounded-lg focus:outline-none focus:ring-2 focus:ring-blue-500">
+                <button onclick="search()" class="bg-blue-600 text-white px-6 py-2 rounded-lg hover:bg-blue-700">
+                    Search
+                </button>
+            </div>
+        </div>
+
+        <!-- Latest Blocks -->
+        <div class="bg-white rounded-lg shadow">
+            <div class="px-6 py-4 border-b">
+                <h2 class="text-xl font-semibold flex items-center">
+                    <i data-lucide="blocks" class="w-5 h-5 mr-2"></i>
+                    Latest Blocks
+                </h2>
+            </div>
+            <div class="p-6">
+                <div class="overflow-x-auto">
+                    <table class="w-full">
+                        <thead>
+                            <tr class="text-left text-gray-500 text-sm">
+                                <th class="pb-3">Height</th>
+                                <th class="pb-3">Hash</th>
+                                <th class="pb-3">Timestamp</th>
+                                <th class="pb-3">Transactions</th>
+                                <th class="pb-3">Actions</th>
+                            </tr>
+                        </thead>
+                        <tbody id="blocks-table">
+                            <tr>
+                                <td colspan="5" class="text-center py-8 text-gray-500">
+                                    Loading blocks...
+                                </td>
+                            </tr>
+                        </tbody>
+                    </table>
+                </div>
+            </div>
+        </div>
+
+        <!-- Block Details Modal -->
+        <div id="block-modal" class="fixed inset-0 bg-black bg-opacity-50 hidden z-50">
+            <div class="flex items-center justify-center min-h-screen p-4">
+                <div class="bg-white rounded-lg max-w-4xl w-full max-h-[90vh] overflow-y-auto">
+                    <div class="p-6 border-b">
+                        <div class="flex justify-between items-center">
+                            <h2 class="text-2xl font-bold">Block Details</h2>
+                            <button onclick="closeModal()" class="text-gray-500 hover:text-gray-700">
+                                <i data-lucide="x" class="w-6 h-6"></i>
+                            </button>
+                        </div>
+                    </div>
+                    <div class="p-6" id="block-details">
+                        <!-- Block details will be loaded here -->
+                    </div>
+                </div>
+            </div>
+        </div>
+    </main>
+
+    <footer class="bg-gray-800 text-white mt-12">
+        <div class="container mx-auto px-4 py-6 text-center">
+            <p class="text-sm">AITBC Blockchain Explorer - Connected to node at {node_url}</p>
+        </div>
+    </footer>
+
+    <script>
+        // Initialize lucide icons
+        lucide.createIcons();
+
+        // Global state
+        let currentData = {};
+
+        // Load initial data
+        document.addEventListener('DOMContentLoaded', () => {
+            refreshData();
+        });
+
+        // Refresh all data
+        async function refreshData() {
+            try {
+                await Promise.all([
+                    loadChainStats(),
+                    loadLatestBlocks()
+                ]);
+            } catch (error) {
+                console.error('Error refreshing data:', error);
+                document.getElementById('node-status').innerHTML = '<span class="text-red-500">Error</span>';
+            }
+        }
+
+        // Load chain statistics
+        async function loadChainStats() {
+            const response = await fetch('/api/chain/head');
+            const data = await response.json();
+            
+            document.getElementById('chain-height').textContent = data.height || '-';
+            document.getElementById('latest-hash').textContent = data.hash ? data.hash.substring(0, 16) + '...' : '-';
+            document.getElementById('node-status').innerHTML = '<span class="text-green-500">Online</span>';
+            
+            currentData.head = data;
+        }
+
+        // Load latest blocks
+        async function loadLatestBlocks() {
+            const tbody = document.getElementById('blocks-table');
+            tbody.innerHTML = '<tr><td colspan="5" class="text-center py-8 text-gray-500">Loading blocks...</td></tr>';
+            
+            const head = await fetch('/api/chain/head').then(r => r.json());
+            const blocks = [];
+            
+            // Load last 10 blocks
+            for (let i = 0; i < 10 && head.height - i >= 0; i++) {
+                const block = await fetch(`/api/blocks/${head.height - i}`).then(r => r.json());
+                blocks.push(block);
+            }
+            
+            tbody.innerHTML = blocks.map(block => `
+                <tr class="border-t hover:bg-gray-50">
+                    <td class="py-3 font-mono">${block.height}</td>
+                    <td class="py-3 font-mono text-sm">${block.hash ? block.hash.substring(0, 16) + '...' : '-'}</td>
+                    <td class="py-3 text-sm">${formatTimestamp(block.timestamp)}</td>
+                    <td class="py-3">${block.transactions ? block.transactions.length : 0}</td>
+                    <td class="py-3">
+                        <button onclick="showBlockDetails(${block.height})" class="text-blue-600 hover:text-blue-800">
+                            View Details
+                        </button>
+                    </td>
+                </tr>
+            `).join('');
+        }
+
+        // Show block details
+        async function showBlockDetails(height) {
+            const block = await fetch(`/api/blocks/${height}`).then(r => r.json());
+            const modal = document.getElementById('block-modal');
+            const details = document.getElementById('block-details');
+            
+            details.innerHTML = `
+                <div class="space-y-6">
+                    <div>
+                        <h3 class="text-lg font-semibold mb-2">Block Header</h3>
+                        <div class="bg-gray-50 rounded p-4 space-y-2">
+                            <div class="flex justify-between">
+                                <span class="text-gray-600">Height:</span>
+                                <span class="font-mono">${block.height}</span>
+                            </div>
+                            <div class="flex justify-between">
+                                <span class="text-gray-600">Hash:</span>
+                                <span class="font-mono text-sm">${block.hash || '-'}</span>
+                            </div>
+                            <div class="flex justify-between">
+                                <span class="text-gray-600">Parent Hash:</span>
+                                <span class="font-mono text-sm">${block.parent_hash || '-'}</span>
+                            </div>
+                            <div class="flex justify-between">
+                                <span class="text-gray-600">Timestamp:</span>
+                                <span>${formatTimestamp(block.timestamp)}</span>
+                            </div>
+                            <div class="flex justify-between">
+                                <span class="text-gray-600">Proposer:</span>
+                                <span class="font-mono text-sm">${block.proposer || '-'}</span>
+                            </div>
+                        </div>
+                    </div>
+                    
+                    ${block.transactions && block.transactions.length > 0 ? `
+                    <div>
+                        <h3 class="text-lg font-semibold mb-2">Transactions (${block.transactions.length})</h3>
+                        <div class="space-y-2">
+                            ${block.transactions.map(tx => `
+                                <div class="bg-gray-50 rounded p-4">
+                                    <div class="flex justify-between mb-2">
+                                        <span class="text-gray-600">Hash:</span>
+                                        <span class="font-mono text-sm">${tx.hash || '-'}</span>
+                                    </div>
+                                    <div class="flex justify-between mb-2">
+                                        <span class="text-gray-600">Type:</span>
+                                        <span>${tx.type || '-'}</span>
+                                    </div>
+                                    <div class="flex justify-between mb-2">
+                                        <span class="text-gray-600">From:</span>
+                                        <span class="font-mono text-sm">${tx.sender || '-'}</span>
+                                    </div>
+                                    <div class="flex justify-between">
+                                        <span class="text-gray-600">Fee:</span>
+                                        <span>${tx.fee || '0'}</span>
+                                    </div>
+                                </div>
+                            `).join('')}
+                        </div>
+                    </div>
+                    ` : '<p class="text-gray-500">No transactions in this block</p>'}
+                </div>
+            `;
+            
+            modal.classList.remove('hidden');
+        }
+
+        // Close modal
+        function closeModal() {
+            document.getElementById('block-modal').classList.add('hidden');
+        }
+
+        // Search functionality
+        async function search() {
+            const query = document.getElementById('search-input').value.trim();
+            if (!query) return;
+            
+            // Try block height first
+            if (/^\\d+$/.test(query)) {
+                showBlockDetails(parseInt(query));
+                return;
+            }
+            
+            // TODO: Add transaction hash search
+            alert('Search by block height is currently supported');
+        }
+
+        // Format timestamp
+        function formatTimestamp(timestamp) {
+            if (!timestamp) return '-';
+            return new Date(timestamp * 1000).toLocaleString();
+        }
+
+        // Auto-refresh every 30 seconds
+        setInterval(refreshData, 30000);
+    </script>
+</body>
+</html>
+"""
+
+async def get_chain_head() -> Dict[str, Any]:
+    """Get the current chain head"""
+    try:
+        async with httpx.AsyncClient() as client:
+            response = await client.get(f"{BLOCKCHAIN_RPC_URL}/rpc/head")
+            if response.status_code == 200:
+                return response.json()
+    except Exception as e:
+        print(f"Error getting chain head: {e}")
+    return {}
+
+async def get_block(height: int) -> Dict[str, Any]:
+    """Get a specific block by height"""
+    try:
+        async with httpx.AsyncClient() as client:
+            response = await client.get(f"{BLOCKCHAIN_RPC_URL}/rpc/blocks/{height}")
+            if response.status_code == 200:
+                return response.json()
+    except Exception as e:
+        print(f"Error getting block {height}: {e}")
+    return {}
+
+@app.get("/", response_class=HTMLResponse)
+async def root():
+    """Serve the explorer UI"""
+    return HTML_TEMPLATE.format(node_url=BLOCKCHAIN_RPC_URL)
+
+@app.get("/api/chain/head")
+async def api_chain_head():
+    """API endpoint for chain head"""
+    return await get_chain_head()
+
+@app.get("/api/blocks/{height}")
+async def api_block(height: int):
+    """API endpoint for block data"""
+    return await get_block(height)
+
+@app.get("/health")
+async def health():
+    """Health check endpoint"""
+    head = await get_chain_head()
+    return {
+        "status": "ok" if head else "error",
+        "node_url": BLOCKCHAIN_RPC_URL,
+        "chain_height": head.get("height", 0)
+    }
+
+if __name__ == "__main__":
+    uvicorn.run(app, host="0.0.0.0", port=3000)

apps/blockchain-explorer/nginx.conf

@@ -0,0 +1,31 @@
+server {
+    listen 3000;
+    server_name _;
+    root /opt/blockchain-explorer;
+    index index.html;
+    
+    # API proxy - standardize endpoints
+    location /api/v1/ {
+        proxy_pass http://localhost:8082/rpc/;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+    
+    # Legacy API compatibility
+    location /rpc {
+        return 307 /api/v1$uri?$args;
+    }
+    
+    # Static files
+    location /assets/ {
+        expires 1y;
+        add_header Cache-Control "public, immutable";
+    }
+    
+    # SPA fallback
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+}

apps/blockchain-explorer/requirements.txt

@@ -0,0 +1,3 @@
+fastapi==0.111.1
+uvicorn[standard]==0.30.6
+httpx==0.27.2

apps/blockchain-node/src/aitbc_chain/gossip/relay.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+"""
+Simple gossip relay service for blockchain nodes
+Uses Starlette Broadcast to share messages between nodes
+"""
+
+import argparse
+import asyncio
+import logging
+from typing import Any, Dict
+
+from starlette.applications import Starlette
+from starlette.broadcast import Broadcast
+from starlette.middleware import Middleware
+from starlette.middleware.cors import CORSMiddleware
+from starlette.routing import Route, WebSocketRoute
+from starlette.websockets import WebSocket
+import uvicorn
+
+# Setup logging
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+# Global broadcast instance
+broadcast = Broadcast("memory://")
+
+
+async def gossip_endpoint(request):
+    """HTTP endpoint for publishing gossip messages"""
+    try:
+        data = await request.json()
+        channel = data.get("channel", "blockchain")
+        message = data.get("message")
+        
+        if message:
+            await broadcast.publish(channel, message)
+            logger.info(f"Published to {channel}: {str(message)[:50]}...")
+            
+            return {"status": "published", "channel": channel}
+        else:
+            return {"status": "error", "message": "No message provided"}
+    except Exception as e:
+        logger.error(f"Error publishing: {e}")
+        return {"status": "error", "message": str(e)}
+
+
+async def websocket_endpoint(websocket: WebSocket):
+    """WebSocket endpoint for real-time gossip"""
+    await websocket.accept()
+    
+    # Get channel from query params
+    channel = websocket.query_params.get("channel", "blockchain")
+    logger.info(f"WebSocket connected to channel: {channel}")
+    
+    try:
+        async with broadcast.subscribe(channel) as subscriber:
+            async for message in subscriber:
+                await websocket.send_text(message)
+    except Exception as e:
+        logger.error(f"WebSocket error: {e}")
+    finally:
+        logger.info("WebSocket disconnected")
+
+
+def create_app() -> Starlette:
+    """Create the Starlette application"""
+    routes = [
+        Route("/gossip", gossip_endpoint, methods=["POST"]),
+        WebSocketRoute("/ws", websocket_endpoint),
+    ]
+    
+    middleware = [
+        Middleware(CORSMiddleware, allow_origins=["*"], allow_methods=["*"])
+    ]
+    
+    return Starlette(routes=routes, middleware=middleware)
+
+
+def main():
+    parser = argparse.ArgumentParser(description="AITBC Gossip Relay")
+    parser.add_argument("--host", default="127.0.0.1", help="Bind host")
+    parser.add_argument("--port", type=int, default=7070, help="Bind port")
+    parser.add_argument("--log-level", default="info", help="Log level")
+    
+    args = parser.parse_args()
+    
+    logger.info(f"Starting gossip relay on {args.host}:{args.port}")
+    
+    app = create_app()
+    uvicorn.run(
+        app,
+        host=args.host,
+        port=args.port,
+        log_level=args.log_level
+    )
+
+
+if __name__ == "__main__":
+    main()

apps/blockchain-node/src/aitbc_chain/rpc/router.py

@@ -105,6 +105,61 @@ async def get_block(height: int) -> Dict[str, Any]:
     }
 
 
+@router.get("/blocks", summary="Get latest blocks")
+async def get_blocks(limit: int = 10, offset: int = 0) -> Dict[str, Any]:
+    metrics_registry.increment("rpc_get_blocks_total")
+    start = time.perf_counter()
+    
+    # Validate parameters
+    if limit < 1 or limit > 100:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="limit must be between 1 and 100")
+    if offset < 0:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="offset must be non-negative")
+    
+    with session_scope() as session:
+        # Get blocks in descending order (newest first)
+        blocks = session.exec(
+            select(Block)
+            .order_by(Block.height.desc())
+            .offset(offset)
+            .limit(limit)
+        ).all()
+        
+        # Get total count for pagination info
+        total_count = len(session.exec(select(Block)).all())
+        
+        if not blocks:
+            metrics_registry.increment("rpc_get_blocks_empty_total")
+            return {
+                "blocks": [],
+                "total": total_count,
+                "limit": limit,
+                "offset": offset,
+            }
+        
+        # Serialize blocks
+        block_list = []
+        for block in blocks:
+            block_list.append({
+                "height": block.height,
+                "hash": block.hash,
+                "parent_hash": block.parent_hash,
+                "timestamp": block.timestamp.isoformat(),
+                "tx_count": block.tx_count,
+                "state_root": block.state_root,
+            })
+        
+        metrics_registry.increment("rpc_get_blocks_success_total")
+    metrics_registry.observe("rpc_get_blocks_duration_seconds", time.perf_counter() - start)
+    
+    return {
+        "blocks": block_list,
+        "total": total_count,
+        "limit": limit,
+        "offset": offset,
+    }
+
+
 @router.get("/tx/{tx_hash}", summary="Get transaction by hash")
 async def get_transaction(tx_hash: str) -> Dict[str, Any]:
     metrics_registry.increment("rpc_get_transaction_total")
@@ -126,6 +181,61 @@ async def get_transaction(tx_hash: str) -> Dict[str, Any]:
     }
 
 
+@router.get("/transactions", summary="Get latest transactions")
+async def get_transactions(limit: int = 20, offset: int = 0) -> Dict[str, Any]:
+    metrics_registry.increment("rpc_get_transactions_total")
+    start = time.perf_counter()
+    
+    # Validate parameters
+    if limit < 1 or limit > 100:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="limit must be between 1 and 100")
+    if offset < 0:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="offset must be non-negative")
+    
+    with session_scope() as session:
+        # Get transactions in descending order (newest first)
+        transactions = session.exec(
+            select(Transaction)
+            .order_by(Transaction.created_at.desc())
+            .offset(offset)
+            .limit(limit)
+        ).all()
+        
+        # Get total count for pagination info
+        total_count = len(session.exec(select(Transaction)).all())
+        
+        if not transactions:
+            metrics_registry.increment("rpc_get_transactions_empty_total")
+            return {
+                "transactions": [],
+                "total": total_count,
+                "limit": limit,
+                "offset": offset,
+            }
+        
+        # Serialize transactions
+        tx_list = []
+        for tx in transactions:
+            tx_list.append({
+                "tx_hash": tx.tx_hash,
+                "block_height": tx.block_height,
+                "sender": tx.sender,
+                "recipient": tx.recipient,
+                "payload": tx.payload,
+                "created_at": tx.created_at.isoformat(),
+            })
+        
+        metrics_registry.increment("rpc_get_transactions_success_total")
+    metrics_registry.observe("rpc_get_transactions_duration_seconds", time.perf_counter() - start)
+    
+    return {
+        "transactions": tx_list,
+        "total": total_count,
+        "limit": limit,
+        "offset": offset,
+    }
+
+
 @router.get("/receipts/{receipt_id}", summary="Get receipt by ID")
 async def get_receipt(receipt_id: str) -> Dict[str, Any]:
     metrics_registry.increment("rpc_get_receipt_total")
@@ -140,6 +250,54 @@ async def get_receipt(receipt_id: str) -> Dict[str, Any]:
     return _serialize_receipt(receipt)
 
 
+@router.get("/receipts", summary="Get latest receipts")
+async def get_receipts(limit: int = 20, offset: int = 0) -> Dict[str, Any]:
+    metrics_registry.increment("rpc_get_receipts_total")
+    start = time.perf_counter()
+    
+    # Validate parameters
+    if limit < 1 or limit > 100:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="limit must be between 1 and 100")
+    if offset < 0:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="offset must be non-negative")
+    
+    with session_scope() as session:
+        # Get receipts in descending order (newest first)
+        receipts = session.exec(
+            select(Receipt)
+            .order_by(Receipt.recorded_at.desc())
+            .offset(offset)
+            .limit(limit)
+        ).all()
+        
+        # Get total count for pagination info
+        total_count = len(session.exec(select(Receipt)).all())
+        
+        if not receipts:
+            metrics_registry.increment("rpc_get_receipts_empty_total")
+            return {
+                "receipts": [],
+                "total": total_count,
+                "limit": limit,
+                "offset": offset,
+            }
+        
+        # Serialize receipts
+        receipt_list = []
+        for receipt in receipts:
+            receipt_list.append(_serialize_receipt(receipt))
+        
+        metrics_registry.increment("rpc_get_receipts_success_total")
+    metrics_registry.observe("rpc_get_receipts_duration_seconds", time.perf_counter() - start)
+    
+    return {
+        "receipts": receipt_list,
+        "total": total_count,
+        "limit": limit,
+        "offset": offset,
+    }
+
+
 @router.get("/getBalance/{address}", summary="Get account balance")
 async def get_balance(address: str) -> Dict[str, Any]:
     metrics_registry.increment("rpc_get_balance_total")
@@ -160,6 +318,131 @@ async def get_balance(address: str) -> Dict[str, Any]:
     }
 
 
+@router.get("/address/{address}", summary="Get address details including transactions")
+async def get_address_details(address: str, limit: int = 20, offset: int = 0) -> Dict[str, Any]:
+    metrics_registry.increment("rpc_get_address_total")
+    start = time.perf_counter()
+    
+    # Validate parameters
+    if limit < 1 or limit > 100:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="limit must be between 1 and 100")
+    if offset < 0:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="offset must be non-negative")
+    
+    with session_scope() as session:
+        # Get account info
+        account = session.get(Account, address)
+        
+        # Get transactions where this address is sender or recipient
+        sent_txs = session.exec(
+            select(Transaction)
+            .where(Transaction.sender == address)
+            .order_by(Transaction.created_at.desc())
+            .offset(offset)
+            .limit(limit)
+        ).all()
+        
+        received_txs = session.exec(
+            select(Transaction)
+            .where(Transaction.recipient == address)
+            .order_by(Transaction.created_at.desc())
+            .offset(offset)
+            .limit(limit)
+        ).all()
+        
+        # Get total counts
+        total_sent = len(session.exec(select(Transaction).where(Transaction.sender == address)).all())
+        total_received = len(session.exec(select(Transaction).where(Transaction.recipient == address)).all())
+        
+        # Serialize transactions
+        serialize_tx = lambda tx: {
+            "tx_hash": tx.tx_hash,
+            "block_height": tx.block_height,
+            "direction": "sent" if tx.sender == address else "received",
+            "counterparty": tx.recipient if tx.sender == address else tx.sender,
+            "payload": tx.payload,
+            "created_at": tx.created_at.isoformat(),
+        }
+        
+        response = {
+            "address": address,
+            "balance": account.balance if account else 0,
+            "nonce": account.nonce if account else 0,
+            "total_transactions_sent": total_sent,
+            "total_transactions_received": total_received,
+            "latest_sent": [serialize_tx(tx) for tx in sent_txs],
+            "latest_received": [serialize_tx(tx) for tx in received_txs],
+        }
+        
+        if account:
+            response["updated_at"] = account.updated_at.isoformat()
+        
+        metrics_registry.increment("rpc_get_address_success_total")
+    metrics_registry.observe("rpc_get_address_duration_seconds", time.perf_counter() - start)
+    
+    return response
+
+
+@router.get("/addresses", summary="Get list of active addresses")
+async def get_addresses(limit: int = 20, offset: int = 0, min_balance: int = 0) -> Dict[str, Any]:
+    metrics_registry.increment("rpc_get_addresses_total")
+    start = time.perf_counter()
+    
+    # Validate parameters
+    if limit < 1 or limit > 100:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="limit must be between 1 and 100")
+    if offset < 0:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="offset must be non-negative")
+    
+    with session_scope() as session:
+        # Get addresses with balance >= min_balance
+        addresses = session.exec(
+            select(Account)
+            .where(Account.balance >= min_balance)
+            .order_by(Account.balance.desc())
+            .offset(offset)
+            .limit(limit)
+        ).all()
+        
+        # Get total count
+        total_count = len(session.exec(select(Account).where(Account.balance >= min_balance)).all())
+        
+        if not addresses:
+            metrics_registry.increment("rpc_get_addresses_empty_total")
+            return {
+                "addresses": [],
+                "total": total_count,
+                "limit": limit,
+                "offset": offset,
+            }
+        
+        # Serialize addresses
+        address_list = []
+        for addr in addresses:
+            # Get transaction counts
+            sent_count = len(session.exec(select(Transaction).where(Transaction.sender == addr.address)).all())
+            received_count = len(session.exec(select(Transaction).where(Transaction.recipient == addr.address)).all())
+            
+            address_list.append({
+                "address": addr.address,
+                "balance": addr.balance,
+                "nonce": addr.nonce,
+                "total_transactions_sent": sent_count,
+                "total_transactions_received": received_count,
+                "updated_at": addr.updated_at.isoformat(),
+            })
+        
+        metrics_registry.increment("rpc_get_addresses_success_total")
+    metrics_registry.observe("rpc_get_addresses_duration_seconds", time.perf_counter() - start)
+    
+    return {
+        "addresses": address_list,
+        "total": total_count,
+        "limit": limit,
+        "offset": offset,
+    }
+
+
 @router.post("/sendTx", summary="Submit a new transaction")
 async def send_transaction(request: TransactionRequest) -> Dict[str, Any]:
     metrics_registry.increment("rpc_send_tx_total")

apps/coordinator-api/migrations/004_payments.sql

@@ -24,7 +24,7 @@ CREATE TABLE IF NOT EXISTS job_payments (
     released_at TIMESTAMP,
     refunded_at TIMESTAMP,
     expires_at TIMESTAMP,
-    metadata JSON
+    meta_data JSON
 );
 
 -- Create payment_escrows table

apps/coordinator-api/src/app/domain/__init__.py

@@ -3,8 +3,9 @@
 from .job import Job
 from .miner import Miner
 from .job_receipt import JobReceipt
-from .marketplace import MarketplaceOffer, MarketplaceBid, OfferStatus
+from .marketplace import MarketplaceOffer, MarketplaceBid
 from .user import User, Wallet
+from .payment import JobPayment, PaymentEscrow
 
 __all__ = [
     "Job",
@@ -12,7 +13,8 @@ __all__ = [
     "JobReceipt",
     "MarketplaceOffer",
     "MarketplaceBid",
-    "OfferStatus",
     "User",
     "Wallet",
+    "JobPayment",
+    "PaymentEscrow",
 ]

apps/coordinator-api/src/app/domain/job.py

@@ -4,17 +4,18 @@ from datetime import datetime
 from typing import Optional
 from uuid import uuid4
 
-from sqlalchemy import Column, JSON, String
+from sqlalchemy import Column, JSON, String, ForeignKey
-from sqlmodel import Field, SQLModel, Relationship
+from sqlalchemy.orm import Mapped, relationship
-
+from sqlmodel import Field, SQLModel
-from ..types import JobState
 
 
 class Job(SQLModel, table=True):
+    __tablename__ = "job"
+    
     id: str = Field(default_factory=lambda: uuid4().hex, primary_key=True, index=True)
     client_id: str = Field(index=True)
 
-    state: JobState = Field(default=JobState.queued, sa_column_kwargs={"nullable": False})
+    state: str = Field(default="QUEUED", max_length=20)
     payload: dict = Field(sa_column=Column(JSON, nullable=False))
     constraints: dict = Field(default_factory=dict, sa_column=Column(JSON, nullable=False))
 
@@ -30,8 +31,8 @@ class Job(SQLModel, table=True):
     error: Optional[str] = None
     
     # Payment tracking
-    payment_id: Optional[str] = Field(default=None, foreign_key="job_payments.id", index=True)
+    payment_id: Optional[str] = Field(default=None, sa_column=Column(String, ForeignKey("job_payments.id"), index=True))
     payment_status: Optional[str] = Field(default=None, max_length=20)  # pending, escrowed, released, refunded
     
     # Relationships
-    payment: Optional["JobPayment"] = Relationship(back_populates="jobs")
+    # payment: Mapped[Optional["JobPayment"]] = relationship(back_populates="jobs")

apps/coordinator-api/src/app/domain/marketplace.py

@@ -1,27 +1,20 @@
 from __future__ import annotations
 
 from datetime import datetime
-from enum import Enum
 from typing import Optional
 from uuid import uuid4
 
-from sqlalchemy import Column, Enum as SAEnum, JSON
+from sqlalchemy import Column, JSON
 from sqlmodel import Field, SQLModel
 
 
-class OfferStatus(str, Enum):
-    open = "open"
-    reserved = "reserved"
-    closed = "closed"
-
-
 class MarketplaceOffer(SQLModel, table=True):
     id: str = Field(default_factory=lambda: uuid4().hex, primary_key=True)
     provider: str = Field(index=True)
     capacity: int = Field(default=0, nullable=False)
     price: float = Field(default=0.0, nullable=False)
     sla: str = Field(default="")
-    status: OfferStatus = Field(default=OfferStatus.open, sa_column=Column(SAEnum(OfferStatus), nullable=False))
+    status: str = Field(default="open", max_length=20)
     created_at: datetime = Field(default_factory=datetime.utcnow, nullable=False, index=True)
     attributes: dict = Field(default_factory=dict, sa_column=Column(JSON, nullable=False))
 

apps/coordinator-api/src/app/domain/payment.py

@@ -6,10 +6,9 @@ from datetime import datetime
 from typing import Optional, List
 from uuid import uuid4
 
-from sqlalchemy import Column, String, DateTime, Numeric, ForeignKey
+from sqlalchemy import Column, String, DateTime, Numeric, ForeignKey, JSON
-from sqlmodel import Field, SQLModel, Relationship
+from sqlalchemy.orm import Mapped, relationship
-
+from sqlmodel import Field, SQLModel
-from ..schemas.payments import PaymentStatus, PaymentMethod
 
 
 class JobPayment(SQLModel, table=True):
@@ -23,8 +22,8 @@ class JobPayment(SQLModel, table=True):
     # Payment details
     amount: float = Field(sa_column=Column(Numeric(20, 8), nullable=False))
     currency: str = Field(default="AITBC", max_length=10)
-    status: PaymentStatus = Field(default=PaymentStatus.PENDING)
+    status: str = Field(default="pending", max_length=20)
-    payment_method: PaymentMethod = Field(default=PaymentMethod.AITBC_TOKEN)
+    payment_method: str = Field(default="aitbc_token", max_length=20)
     
     # Addresses
     escrow_address: Optional[str] = Field(default=None, max_length=100)
@@ -43,10 +42,10 @@ class JobPayment(SQLModel, table=True):
     expires_at: Optional[datetime] = None
     
     # Additional metadata
-    metadata: Optional[dict] = Field(default=None)
+    meta_data: Optional[dict] = Field(default=None, sa_column=Column(JSON))
     
     # Relationships
-    jobs: List["Job"] = Relationship(back_populates="payment")
+    # jobs: Mapped[List["Job"]] = relationship(back_populates="payment")
 
 
 class PaymentEscrow(SQLModel, table=True):

apps/coordinator-api/src/app/domain/user.py

@@ -6,13 +6,6 @@ from sqlmodel import SQLModel, Field, Relationship, Column
 from sqlalchemy import JSON
 from datetime import datetime
 from typing import Optional, List
-from enum import Enum
-
-
-class UserStatus(str, Enum):
-    ACTIVE = "active"
-    INACTIVE = "inactive"
-    SUSPENDED = "suspended"
 
 
 class User(SQLModel, table=True):
@@ -20,7 +13,7 @@ class User(SQLModel, table=True):
     id: str = Field(primary_key=True)
     email: str = Field(unique=True, index=True)
     username: str = Field(unique=True, index=True)
-    status: UserStatus = Field(default=UserStatus.ACTIVE)
+    status: str = Field(default="active", max_length=20)
     created_at: datetime = Field(default_factory=datetime.utcnow)
     updated_at: datetime = Field(default_factory=datetime.utcnow)
     last_login: Optional[datetime] = None
@@ -44,28 +37,13 @@ class Wallet(SQLModel, table=True):
     transactions: List["Transaction"] = Relationship(back_populates="wallet")
 
 
-class TransactionType(str, Enum):
-    DEPOSIT = "deposit"
-    WITHDRAWAL = "withdrawal"
-    PURCHASE = "purchase"
-    REWARD = "reward"
-    REFUND = "refund"
-
-
-class TransactionStatus(str, Enum):
-    PENDING = "pending"
-    COMPLETED = "completed"
-    FAILED = "failed"
-    CANCELLED = "cancelled"
-
-
 class Transaction(SQLModel, table=True):
     """Transaction model"""
     id: str = Field(primary_key=True)
     user_id: str = Field(foreign_key="user.id")
     wallet_id: Optional[int] = Field(foreign_key="wallet.id")
-    type: TransactionType
+    type: str = Field(max_length=20)
-    status: TransactionStatus = Field(default=TransactionStatus.PENDING)
+    status: str = Field(default="pending", max_length=20)
     amount: float
     fee: float = Field(default=0.0)
     description: Optional[str] = None

apps/coordinator-api/src/app/models/__init__.py

@@ -56,6 +56,8 @@ from ..domain import (
     MarketplaceBid,
     User,
     Wallet,
+    JobPayment,
+    PaymentEscrow,
 )
 
 # Service-specific models
@@ -101,4 +103,6 @@ __all__ = [
     "LLMRequest",
     "FFmpegRequest",
     "BlenderRequest",
+    "JobPayment",
+    "PaymentEscrow",
 ]

apps/coordinator-api/src/app/models/services.py

@@ -4,7 +4,7 @@ Service schemas for common GPU workloads
 
 from typing import Any, Dict, List, Optional, Union
 from enum import Enum
-from pydantic import BaseModel, Field, validator
+from pydantic import BaseModel, Field, field_validator
 import re
 
 
@@ -123,7 +123,8 @@ class StableDiffusionRequest(BaseModel):
     lora: Optional[str] = Field(None, description="LoRA model to use")
     lora_scale: float = Field(1.0, ge=0.0, le=2.0, description="LoRA strength")
     
-    @validator('seed')
+    @field_validator('seed')
+    @classmethod
     def validate_seed(cls, v):
         if v is not None and isinstance(v, list):
             if len(v) > 4:
@@ -289,9 +290,10 @@ class BlenderRequest(BaseModel):
     transparent: bool = Field(False, description="Transparent background")
     custom_args: Optional[List[str]] = Field(None, description="Custom Blender arguments")
     
-    @validator('frame_end')
+    @field_validator('frame_end')
-    def validate_frame_range(cls, v, values):
+    @classmethod
-        if 'frame_start' in values and v < values['frame_start']:
+    def validate_frame_range(cls, v, info):
+        if info and info.data and 'frame_start' in info.data and v < info.data['frame_start']:
             raise ValueError("frame_end must be >= frame_start")
         return v
     

apps/coordinator-api/src/app/routers/client.py

@@ -1,8 +1,7 @@
 from fastapi import APIRouter, Depends, HTTPException, status
 
 from ..deps import require_client_key
-from ..schemas import JobCreate, JobView, JobResult
+from ..schemas import JobCreate, JobView, JobResult, JobPaymentCreate
-from ..schemas.payments import JobPaymentCreate, PaymentMethod
 from ..types import JobState
 from ..services import JobService
 from ..services.payments import PaymentService
@@ -27,11 +26,11 @@ async def submit_job(
             job_id=job.id,
             amount=req.payment_amount,
             currency=req.payment_currency,
-            payment_method=PaymentMethod.AITBC_TOKEN  # Jobs use AITBC tokens
+            payment_method="aitbc_token"  # Jobs use AITBC tokens
         )
         payment = await payment_service.create_payment(job.id, payment_create)
         job.payment_id = payment.id
-        job.payment_status = payment.status.value
+        job.payment_status = payment.status
         session.commit()
         session.refresh(job)
     

apps/coordinator-api/src/app/routers/marketplace_offers.py

@@ -7,7 +7,7 @@ from fastapi import APIRouter, Depends, HTTPException
 from sqlmodel import Session, select
 
 from ..deps import require_admin_key
-from ..domain import MarketplaceOffer, Miner, OfferStatus
+from ..domain import MarketplaceOffer, Miner
 from ..schemas import MarketplaceOfferView
 from ..storage import SessionDep
 

apps/coordinator-api/src/app/routers/miner.py

@@ -1,5 +1,6 @@
 from datetime import datetime
 from typing import Any
+import logging
 
 from fastapi import APIRouter, Depends, HTTPException, Response, status
 
@@ -9,6 +10,8 @@ from ..services import JobService, MinerService
 from ..services.receipts import ReceiptService
 from ..storage import SessionDep
 
+logger = logging.getLogger(__name__)
+
 router = APIRouter(tags=["miner"])
 
 
@@ -78,6 +81,23 @@ async def submit_result(
     job.receipt_id = receipt["receipt_id"] if receipt else None
     session.add(job)
     session.commit()
+    
+    # Auto-release payment if job has payment
+    if job.payment_id and job.payment_status == "escrowed":
+        from ..services.payments import PaymentService
+        payment_service = PaymentService(session)
+        success = await payment_service.release_payment(
+            job.id,
+            job.payment_id,
+            reason="Job completed successfully"
+        )
+        if success:
+            job.payment_status = "released"
+            session.commit()
+            logger.info(f"Auto-released payment {job.payment_id} for completed job {job.id}")
+        else:
+            logger.error(f"Failed to auto-release payment {job.payment_id} for job {job.id}")
+    
     miner_service.release(
         miner_id,
         success=True,
@@ -106,5 +126,22 @@ async def submit_failure(
     job.assigned_miner_id = miner_id
     session.add(job)
     session.commit()
+    
+    # Auto-refund payment if job has payment
+    if job.payment_id and job.payment_status in ["pending", "escrowed"]:
+        from ..services.payments import PaymentService
+        payment_service = PaymentService(session)
+        success = await payment_service.refund_payment(
+            job.id,
+            job.payment_id,
+            reason=f"Job failed: {req.error_code}: {req.error_message}"
+        )
+        if success:
+            job.payment_status = "refunded"
+            session.commit()
+            logger.info(f"Auto-refunded payment {job.payment_id} for failed job {job.id}")
+        else:
+            logger.error(f"Failed to auto-refund payment {job.payment_id} for job {job.id}")
+    
     miner_service.release(miner_id, success=False)
     return {"status": "ok"}

apps/coordinator-api/src/app/routers/partners.py

@@ -37,7 +37,7 @@ class PartnerResponse(BaseModel):
 class WebhookCreate(BaseModel):
     """Create a webhook subscription"""
     url: str = Field(..., pattern=r'^https?://')
-    events: List[str] = Field(..., min_items=1)
+    events: List[str] = Field(..., min_length=1)
     secret: Optional[str] = Field(max_length=100)
 
 

apps/coordinator-api/src/app/routers/payments.py

@@ -4,7 +4,7 @@ from fastapi import APIRouter, Depends, HTTPException, status
 from typing import List
 
 from ..deps import require_client_key
-from ..schemas.payments import (
+from ..schemas import (
     JobPaymentCreate,
     JobPaymentView,
     PaymentRequest,

apps/coordinator-api/src/app/schemas.py

@@ -3,12 +3,75 @@ from __future__ import annotations
 from datetime import datetime
 from typing import Any, Dict, Optional, List
 from base64 import b64encode, b64decode
+from enum import Enum
 
 from pydantic import BaseModel, Field, ConfigDict
 
 from .types import JobState, Constraints
 
 
+# Payment schemas
+class JobPaymentCreate(BaseModel):
+    """Request to create a payment for a job"""
+    job_id: str
+    amount: float
+    currency: str = "AITBC"  # Jobs paid with AITBC tokens
+    payment_method: str = "aitbc_token"  # Primary method for job payments
+    escrow_timeout_seconds: int = 3600  # 1 hour default
+
+
+class JobPaymentView(BaseModel):
+    """Payment information for a job"""
+    job_id: str
+    payment_id: str
+    amount: float
+    currency: str
+    status: str
+    payment_method: str
+    escrow_address: Optional[str] = None
+    refund_address: Optional[str] = None
+    created_at: datetime
+    updated_at: datetime
+    released_at: Optional[datetime] = None
+    refunded_at: Optional[datetime] = None
+    transaction_hash: Optional[str] = None
+    refund_transaction_hash: Optional[str] = None
+
+
+class PaymentRequest(BaseModel):
+    """Request to pay for a job"""
+    job_id: str
+    amount: float
+    currency: str = "BTC"
+    refund_address: Optional[str] = None
+
+
+class PaymentReceipt(BaseModel):
+    """Receipt for a payment"""
+    payment_id: str
+    job_id: str
+    amount: float
+    currency: str
+    status: str
+    transaction_hash: Optional[str] = None
+    created_at: datetime
+    verified_at: Optional[datetime] = None
+
+
+class EscrowRelease(BaseModel):
+    """Request to release escrow payment"""
+    job_id: str
+    payment_id: str
+    reason: Optional[str] = None
+
+
+class RefundRequest(BaseModel):
+    """Request to refund a payment"""
+    job_id: str
+    payment_id: str
+    reason: str
+
+
 # User management schemas
 class UserCreate(BaseModel):
     email: str

apps/coordinator-api/src/app/schemas/payments.py

@@ -4,32 +4,16 @@ from __future__ import annotations
 
 from datetime import datetime
 from typing import Optional, Dict, Any
-from enum import Enum
 
 from pydantic import BaseModel, Field
 
 
-class PaymentStatus(str, Enum):
-    """Payment status values"""
-    PENDING = "pending"
-    ESCROWED = "escrowed"
-    RELEASED = "released"
-    REFUNDED = "refunded"
-    FAILED = "failed"
-
-
-class PaymentMethod(str, Enum):
-    """Payment methods"""
-    AITBC_TOKEN = "aitbc_token"  # Primary method for job payments
-    BITCOIN = "bitcoin"  # Only for exchange purchases
-
-
 class JobPaymentCreate(BaseModel):
     """Request to create a payment for a job"""
     job_id: str
     amount: float
     currency: str = "AITBC"  # Jobs paid with AITBC tokens
-    payment_method: PaymentMethod = PaymentMethod.AITBC_TOKEN
+    payment_method: str = "aitbc_token"  # Primary method for job payments
     escrow_timeout_seconds: int = 3600  # 1 hour default
 
 
@@ -39,8 +23,8 @@ class JobPaymentView(BaseModel):
     payment_id: str
     amount: float
     currency: str
-    status: PaymentStatus
+    status: str
-    payment_method: PaymentMethod
+    payment_method: str
     escrow_address: Optional[str] = None
     refund_address: Optional[str] = None
     created_at: datetime
@@ -65,7 +49,7 @@ class PaymentReceipt(BaseModel):
     job_id: str
     amount: float
     currency: str
-    status: PaymentStatus
+    status: str
     transaction_hash: Optional[str] = None
     created_at: datetime
     verified_at: Optional[datetime] = None

apps/coordinator-api/src/app/services/jobs.py

@@ -32,15 +32,8 @@ class JobService:
         
         # Create payment if amount is specified
         if req.payment_amount and req.payment_amount > 0:
-            from ..schemas.payments import JobPaymentCreate, PaymentMethod
+            # Note: Payment creation is handled in the router
-            payment_create = JobPaymentCreate(
+            pass
-                job_id=job.id,
-                amount=req.payment_amount,
-                currency=req.payment_currency,
-                payment_method=PaymentMethod.BITCOIN
-            )
-            # Note: This is async, so we'll handle it in the router
-            job.payment_pending = True
         
         return job
 
@@ -81,6 +74,8 @@ class JobService:
             requested_at=job.requested_at,
             expires_at=job.expires_at,
             error=job.error,
+            payment_id=job.payment_id,
+            payment_status=job.payment_status,
         )
 
     def to_result(self, job: Job) -> JobResult:

apps/coordinator-api/src/app/services/marketplace.py

@@ -5,7 +5,7 @@ from typing import Iterable, Optional
 
 from sqlmodel import Session, select
 
-from ..domain import MarketplaceOffer, MarketplaceBid, OfferStatus
+from ..domain import MarketplaceOffer, MarketplaceBid
 from ..schemas import (
     MarketplaceBidRequest,
     MarketplaceOfferView,
@@ -62,7 +62,7 @@ class MarketplaceService:
 
     def get_stats(self) -> MarketplaceStatsView:
         offers = self.session.exec(select(MarketplaceOffer)).all()
-        open_offers = [offer for offer in offers if offer.status == OfferStatus.open]
+        open_offers = [offer for offer in offers if offer.status == "open"]
 
         total_offers = len(offers)
         open_capacity = sum(offer.capacity for offer in open_offers)

apps/coordinator-api/src/app/services/payments.py

@@ -6,11 +6,9 @@ import httpx
 import logging
 
 from ..domain.payment import JobPayment, PaymentEscrow
-from ..schemas.payments import (
+from ..schemas import (
     JobPaymentCreate, 
     JobPaymentView, 
-    PaymentStatus,
-    PaymentMethod,
     EscrowRelease,
     RefundRequest
 )
@@ -44,10 +42,10 @@ class PaymentService:
         self.session.refresh(payment)
         
         # For AITBC token payments, use token escrow
-        if payment_data.payment_method == PaymentMethod.AITBC_TOKEN:
+        if payment_data.payment_method == "aitbc_token":
             await self._create_token_escrow(payment)
         # Bitcoin payments only for exchange purchases
-        elif payment_data.payment_method == PaymentMethod.BITCOIN:
+        elif payment_data.payment_method == "bitcoin":
             await self._create_bitcoin_escrow(payment)
         
         return payment
@@ -61,7 +59,7 @@ class PaymentService:
                 response = await client.post(
                     f"{self.exchange_base_url}/api/v1/token/escrow/create",
                     json={
-                        "amount": payment.amount,
+                        "amount": float(payment.amount),
                         "currency": payment.currency,
                         "job_id": payment.job_id,
                         "timeout_seconds": 3600  # 1 hour
@@ -71,7 +69,7 @@ class PaymentService:
                 if response.status_code == 200:
                     escrow_data = response.json()
                     payment.escrow_address = escrow_data.get("escrow_id")
-                    payment.status = PaymentStatus.ESCROWED
+                    payment.status = "escrowed"
                     payment.escrowed_at = datetime.utcnow()
                     payment.updated_at = datetime.utcnow()
                     
@@ -92,7 +90,7 @@ class PaymentService:
                     
         except Exception as e:
             logger.error(f"Error creating token escrow: {e}")
-            payment.status = PaymentStatus.FAILED
+            payment.status = "failed"
             payment.updated_at = datetime.utcnow()
             self.session.commit()
     
@@ -104,7 +102,7 @@ class PaymentService:
                 response = await client.post(
                     f"{self.wallet_base_url}/api/v1/escrow/create",
                     json={
-                        "amount": payment.amount,
+                        "amount": float(payment.amount),
                         "currency": payment.currency,
                         "timeout_seconds": 3600  # 1 hour
                     }
@@ -113,7 +111,7 @@ class PaymentService:
                 if response.status_code == 200:
                     escrow_data = response.json()
                     payment.escrow_address = escrow_data["address"]
-                    payment.status = PaymentStatus.ESCROWED
+                    payment.status = "escrowed"
                     payment.escrowed_at = datetime.utcnow()
                     payment.updated_at = datetime.utcnow()
                     
@@ -134,7 +132,7 @@ class PaymentService:
                     
         except Exception as e:
             logger.error(f"Error creating Bitcoin escrow: {e}")
-            payment.status = PaymentStatus.FAILED
+            payment.status = "failed"
             payment.updated_at = datetime.utcnow()
             self.session.commit()
     
@@ -145,7 +143,7 @@ class PaymentService:
         if not payment or payment.job_id != job_id:
             return False
         
-        if payment.status != PaymentStatus.ESCROWED:
+        if payment.status != "escrowed":
             return False
         
         try:
@@ -161,7 +159,7 @@ class PaymentService:
                 
                 if response.status_code == 200:
                     release_data = response.json()
-                    payment.status = PaymentStatus.RELEASED
+                    payment.status = "released"
                     payment.released_at = datetime.utcnow()
                     payment.updated_at = datetime.utcnow()
                     payment.transaction_hash = release_data.get("transaction_hash")
@@ -195,7 +193,7 @@ class PaymentService:
         if not payment or payment.job_id != job_id:
             return False
         
-        if payment.status not in [PaymentStatus.ESCROWED, PaymentStatus.PENDING]:
+        if payment.status not in ["escrowed", "pending"]:
             return False
         
         try:
@@ -206,14 +204,14 @@ class PaymentService:
                     json={
                         "payment_id": payment_id,
                         "address": payment.refund_address,
-                        "amount": payment.amount,
+                        "amount": float(payment.amount),
                         "reason": reason
                     }
                 )
                 
                 if response.status_code == 200:
                     refund_data = response.json()
-                    payment.status = PaymentStatus.REFUNDED
+                    payment.status = "refunded"
                     payment.refunded_at = datetime.utcnow()
                     payment.updated_at = datetime.utcnow()
                     payment.refund_transaction_hash = refund_data.get("transaction_hash")

apps/coordinator-api/src/app/storage/db.py

@@ -8,7 +8,7 @@ from sqlalchemy.engine import Engine
 from sqlmodel import Session, SQLModel, create_engine
 
 from ..config import settings
-from ..domain import Job, Miner, MarketplaceOffer, MarketplaceBid
+from ..domain import Job, Miner, MarketplaceOffer, MarketplaceBid, JobPayment, PaymentEscrow
 from .models_governance import GovernanceProposal, ProposalVote, TreasuryTransaction, GovernanceParameter
 
 _engine: Engine | None = None

apps/coordinator-api/src/app/storage/models_governance.py

@@ -6,6 +6,7 @@ from sqlmodel import SQLModel, Field, Relationship, Column, JSON
 from typing import Optional, Dict, Any
 from datetime import datetime
 from uuid import uuid4
+from pydantic import ConfigDict
 
 
 class GovernanceProposal(SQLModel, table=True):
@@ -83,10 +84,11 @@ class VotingPowerSnapshot(SQLModel, table=True):
     snapshot_time: datetime = Field(default_factory=datetime.utcnow, index=True)
     block_number: Optional[int] = Field(index=True)
     
-    class Config:
+    model_config = ConfigDict(
-        indexes = [
+        indexes=[
             {"name": "ix_user_snapshot", "fields": ["user_id", "snapshot_time"]},
         ]
+    )
 
 
 class ProtocolUpgrade(SQLModel, table=True):

dev-utils/README.md

@@ -0,0 +1,11 @@
+# Development Utilities
+
+This directory contains utility files and scripts for development.
+
+## Files
+
+- **aitbc-pythonpath.pth** - Python path configuration for AITBC packages
+
+## Usage
+
+The `.pth` file is automatically used by Python to add paths to `sys.path` when the virtual environment is activated.

docs/REMOTE_DEPLOYMENT_GUIDE.md

@@ -0,0 +1,138 @@
+# AITBC Remote Deployment Guide
+
+## Overview
+This deployment strategy builds the blockchain node directly on the ns3 server to utilize its gigabit connection, avoiding slow uploads from localhost.
+
+## Quick Start
+
+### 1. Deploy Everything
+```bash
+./scripts/deploy/deploy-all-remote.sh
+```
+
+This will:
+- Copy deployment scripts to ns3
+- Copy blockchain source code from localhost
+- Build blockchain node directly on server
+- Deploy a lightweight HTML-based explorer
+- Configure port forwarding
+
+### 2. Access Services
+
+**Blockchain Node RPC:**
+- Internal: http://localhost:8082
+- External: http://aitbc.keisanki.net:8082
+
+**Blockchain Explorer:**
+- Internal: http://localhost:3000
+- External: http://aitbc.keisanki.net:3000
+
+## Architecture
+
+```
+ns3-root (95.216.198.140)
+├── Blockchain Node (port 8082)
+│   ├── Auto-syncs on startup
+│   └── Serves RPC API
+└── Explorer (port 3000)
+    ├── Static HTML/CSS/JS
+    ├── Served by nginx
+    └── Connects to local node
+```
+
+## Key Features
+
+### Blockchain Node
+- Built directly on server from source code
+- Source copied from localhost via scp
+- Auto-sync on startup
+- No large file uploads needed
+- Uses server's gigabit connection
+
+### Explorer
+- Pure HTML/CSS/JS (no build step)
+- Served by nginx
+- Real-time block viewing
+- Transaction details
+- Auto-refresh every 30 seconds
+
+## Manual Deployment
+
+If you need to deploy components separately:
+
+### Blockchain Node Only
+```bash
+ssh ns3-root
+cd /opt
+./deploy-blockchain-remote.sh
+```
+
+### Explorer Only
+```bash
+ssh ns3-root
+cd /opt
+./deploy-explorer-remote.sh
+```
+
+## Troubleshooting
+
+### Check Services
+```bash
+# On ns3 server
+systemctl status blockchain-node blockchain-rpc nginx
+
+# Check logs
+journalctl -u blockchain-node -f
+journalctl -u blockchain-rpc -f
+journalctl -u nginx -f
+```
+
+### Test RPC
+```bash
+# From ns3
+curl http://localhost:8082/rpc/head
+
+# From external
+curl http://aitbc.keisanki.net:8082/rpc/head
+```
+
+### Port Forwarding
+If port forwarding doesn't work:
+```bash
+# Check iptables rules
+iptables -t nat -L -n
+
+# Re-add rules
+iptables -t nat -A PREROUTING -p tcp --dport 8082 -j DNAT --to-destination 192.168.100.10:8082
+iptables -t nat -A POSTROUTING -p tcp -d 192.168.100.10 --dport 8082 -j MASQUERADE
+```
+
+## Configuration
+
+### Blockchain Node
+Location: `/opt/blockchain-node/.env`
+- Chain ID: ait-devnet
+- RPC Port: 8082
+- P2P Port: 7070
+- Auto-sync: enabled
+
+### Explorer
+Location: `/opt/blockchain-explorer/index.html`
+- Served by nginx on port 3000
+- Connects to localhost:8082
+- No configuration needed
+
+## Security Notes
+
+- Services run as root (simplify for dev)
+- No authentication on RPC (dev only)
+- Port forwarding exposes services externally
+- Consider firewall rules for production
+
+## Next Steps
+
+1. Set up proper authentication
+2. Configure HTTPS with SSL certificates
+3. Add multiple peers for network resilience
+4. Implement proper backup procedures
+5. Set up monitoring and alerting

docs/currentissue.md

@@ -0,0 +1,100 @@
+# Current Issues
+
+## Cross-Site Synchronization - PARTIALLY IMPLEMENTED
+
+### Date
+2026-01-29
+
+### Status
+**PARTIALLY IMPLEMENTED** - Cross-site sync is running on all nodes. Transaction propagation works. Block import endpoint exists but has a database constraint issue with transaction import.
+
+### Description
+Cross-site synchronization has been integrated into all blockchain nodes. The sync module detects height differences between nodes and can propagate transactions via RPC.
+
+### Components Affected
+- `/src/aitbc_chain/main.py` - Main blockchain node process
+- `/src/aitbc_chain/cross_site.py` - Cross-site sync module (implemented but not integrated)
+- All three blockchain nodes (localhost Node 1 & 2, remote Node 3)
+
+### What Was Fixed
+1. **main.py integration**: Removed problematic `AbstractAsyncContextManager` type annotation and simplified the code structure
+2. **Cross-site sync module**: Integrated into all three nodes and now starts automatically
+3. **Config settings**: Added `cross_site_sync_enabled`, `cross_site_remote_endpoints`, `cross_site_poll_interval` inside the `ChainSettings` class
+4. **URL paths**: Fixed RPC endpoint paths (e.g., `/head` instead of `/rpc/head` for remote endpoints that already include `/rpc`)
+
+### Current Status
+- **All nodes**: Running with cross-site sync enabled
+- **Transaction sync**: Working - mempool transactions can propagate between sites
+- **Block sync**: ✅ FULLY IMPLEMENTED - `/blocks/import` endpoint works with transactions
+- **Height difference**: Nodes maintain independent chains (local: 771153, remote: 40324)
+- **Status**: Block import with transactions now working after nginx routing fix
+
+### Resolved Issues
+Block synchronization transaction import issue has been **FIXED**:
+- `/blocks/import` POST endpoint is functional and deployed on all nodes
+- Endpoint validates block hashes, parent blocks, and prevents conflicts
+- ✅ Can import blocks with and without transactions
+- ✅ Transaction data properly saved to database
+- Root cause: nginx was routing to wrong port (8082 instead of 8081)
+- Fix: Updated nginx config to route to correct blockchain-rpc-2 service
+
+### Block Sync Implementation Progress
+
+1. **✅ Block Import Endpoint Created** - `/src/aitbc_chain/rpc/router.py`:
+   - Added `@router.post("/blocks/import")` endpoint
+   - Implemented block validation (hash, parent, existence checks)
+   - Added transaction and receipt import logic
+   - Returns status: "imported", "exists", or error details
+
+2. **✅ Cross-Site Sync Updated** - `/src/aitbc_chain/sync/cross_site.py`:
+   - Modified `import_block()` to call `/rpc/blocks/import`
+   - Formats block data correctly for import
+   - Handles import success/failure responses
+
+3. **✅ Runtime Error Fixed**:
+   - Moved inline imports (hashlib, datetime, config) to top of file
+   - Added proper error logging and exception handling
+   - Fixed indentation issues in the function
+   - Endpoint now returns proper validation responses
+
+4. **✅ Transaction Import Fixed**:
+   - Root cause was nginx routing to wrong port (8082 instead of 8081)
+   - Updated transaction creation to use constructor with all fields
+   - Server rebooted to clear all caches
+   - Nginx config fixed to route to blockchain-rpc-2 on port 8081
+   - Verified transaction is saved correctly with all fields
+
+5. **⏳ Future Enhancements**:
+   - Add proposer signature validation
+   - Implement fork resolution for conflicting chains
+   - Add authorized node list configuration
+
+### What Works Now
+- Cross-site sync loop runs every 10 seconds
+- Remote endpoint polling detects height differences
+- Transaction propagation between sites via mempool sync
+- ✅ Block import endpoint functional with validation
+- ✅ Blocks with and without transactions can be imported between sites via RPC
+- ✅ Transaction data properly saved to database
+- Logging shows sync activity in journalctl
+
+### Files Modified
+- `/src/aitbc_chain/main.py` - Added cross-site sync integration
+- `/src/aitbc_chain/cross_site.py` - Fixed URL paths, updated to use /blocks/import endpoint
+- `/src/aitbc_chain/config.py` - Added sync settings inside ChainSettings class (all nodes)
+- `/src/aitbc_chain/rpc/router.py` - Added /blocks/import POST endpoint with validation
+
+### Next Steps
+1. **Monitor Block Synchronization**:
+   - Watch logs for successful block imports with transactions
+   - Verify cross-site sync is actively syncing block heights
+   - Monitor for any validation errors or conflicts
+
+2. **Future Enhancements**:
+   - Add proposer signature validation for security
+   - Implement fork resolution for conflicting chains
+   - Add sync metrics and monitoring dashboard
+
+**Status**: ✅ COMPLETE - Block import with transactions working
+**Impact**: Full cross-site block synchronization now available
+**Resolution**: Server rebooted, nginx routing fixed to port 8081

docs/developer/testing/localhost-testing-scenario.md

@@ -6,7 +6,7 @@ This document outlines a comprehensive testing scenario for customers and servic
 
 ## Integration Tests
 
-### Test Suite Status (Updated 2026-01-26)
+### Test Suite Status (Updated 2026-01-29)
 
 The integration test suite has been updated to use real implemented features:
 
@@ -18,6 +18,16 @@ The integration test suite has been updated to use real implemented features:
 5. **Marketplace Integration** - Connects to live marketplace
 6. **Security Integration** - Uses real ZK proof features
 
+#### 🆕 Cross-Site Synchronization (2026-01-29)
+- Multi-site blockchain deployment active
+- 3 nodes across 2 sites with RPC synchronization
+- Transaction propagation between sites enabled
+- ✅ Block import endpoint fully functional (/blocks/import)
+- Test endpoints:
+  - Local nodes: https://aitbc.bubuit.net/rpc/, /rpc2/
+  - Remote node: http://aitbc.keisanki.net/rpc/
+- Status: ✅ COMPLETE - Full cross-site synchronization active
+
 #### ⏸️ Skipped Tests (1)
 1. **Wallet Payment Flow** - Awaiting wallet-coordinator integration
 

docs/done.md

@@ -78,9 +78,11 @@ This document tracks components that have been successfully deployed and are ope
 
 - ✅ **Blockchain Node** - Running on host
   - SQLModel-based blockchain with PoA consensus
-  - RPC API on port 9080 (proxied via /rpc/)
+  - RPC API on ports 8081/8082 (proxied via /rpc/ and /rpc2/)
   - Mock coordinator on port 8090 (proxied via /v1/)
   - Devnet scripts and observability hooks
+  - Cross-site RPC synchronization enabled
+  - Transaction propagation between sites
 - ✅ **Host GPU Miner** - Running on host (RTX 4060 Ti)
   - Real GPU inference via Ollama
   - Connects to container coordinator through Incus proxy on `127.0.0.1:18000`
@@ -142,6 +144,55 @@ This document tracks components that have been successfully deployed and are ope
 - Configure additional monitoring and observability
 - Set up automated backup procedures
 
+## Recent Updates (2026-01-29)
+
+### Cross-Site Synchronization Implementation
+- ✅ **Multi-site Deployment**: Successfully deployed cross-site synchronization across 3 nodes
+- ✅ **Technical Implementation**: 
+  - Created `/src/aitbc_chain/cross_site.py` module
+  - Integrated into node lifecycle in `main.py`
+  - Added configuration in `config.py`
+  - Added `/blocks/import` POST endpoint in `router.py`
+- ✅ **Network Configuration**:
+  - Local nodes: https://aitbc.bubuit.net/rpc/, /rpc2/
+  - Remote node: http://aitbc.keisanki.net/rpc/
+- ✅ **Current Status**: 
+  - Transaction sync working
+  - ✅ Block import endpoint fully functional with transaction support
+  - ✅ Transaction data properly saved to database during block import
+  - Endpoint validates blocks and handles imports correctly
+  - Node heights: Local (771153), Remote (40324)
+  - Nginx routing fixed to port 8081 for blockchain-rpc-2
+
+- ✅ **Technical Fixes Applied**
+  - Fixed URL paths for correct RPC endpoint access
+  - Integrated sync lifecycle into main node process
+  - Resolved Python compatibility issues (removed AbstractAsyncContextManager)
+
+- ✅ **Network Configuration**
+  - Site A (localhost): https://aitbc.bubuit.net/rpc/ and /rpc2/
+  - Site C (remote): http://aitbc.keisanki.net/rpc/
+  - All nodes maintain independent chains (PoA design)
+  - Cross-site sync enabled with 10-second polling interval
+
+## Recent Updates (2026-01-28)
+
+### Transaction-Dependent Block Creation
+- ✅ **PoA Proposer Enhancement** - Modified blockchain nodes to only create blocks when transactions are pending
+  - Updated PoA proposer to check RPC mempool before creating blocks
+  - Implemented HTTP polling mechanism to check mempool size every 2 seconds
+  - Added transaction storage in blocks with proper tx_count field
+  - Fixed syntax errors and import issues in poa.py
+  - Node 1 now active and operational with new block creation logic
+  - Eliminates empty blocks from the blockchain
+
+- ✅ **Architecture Implementation**
+  - RPC Service (port 8082): Receives and stores transactions in in-memory mempool
+  - Node Process: Checks RPC metrics endpoint for mempool_size
+  - If mempool_size > 0: Creates block with transactions
+  - If mempool_size == 0: Skips block creation, logs "No pending transactions"
+  - Removes processed transactions from mempool after block creation
+
 ## Recent Updates (2026-01-21)
 
 ### Service Maintenance and Fixes

docs/guides/README.md

@@ -0,0 +1,16 @@
+# Development Guides
+
+This directory contains guides and documentation for development workflows.
+
+## Guides
+
+- **WINDSURF_TESTING_GUIDE.md** - Comprehensive guide for testing with Windsurf
+- **WINDSURF_TEST_SETUP.md** - Quick setup guide for Windsurf testing
+
+## Additional Documentation
+
+More documentation can be found in the parent `docs/` directory, including:
+- API documentation
+- Architecture documentation
+- Deployment guides
+- Infrastructure documentation

docs/infrastructure.md

@@ -0,0 +1,349 @@
+# AITBC Infrastructure Documentation
+
+## Overview
+Four-site view: A) localhost (at1, runs miner & Windsurf), B) remote host ns3, C) ns3 container, D) shared capabilities.
+
+## Environment Summary (four sites)
+
+### Site A: Localhost (at1)
+- **Role**: Developer box running Windsurf and miner
+- **Container**: incus `aitbc`
+- **IP**: 10.1.223.93
+- **Access**: `ssh aitbc-cascade`
+- **Domain**: aitbc.bubuit.net
+- **Blockchain Nodes**: Node 1 (rpc 8082), Node 2 (rpc 8081)
+
+#### Site A Services
+| Service | Port | Protocol | Node | Status | URL |
+|---------|------|----------|------|--------|-----|
+| Coordinator API | 8000 | HTTP | - | ✅ Active | https://aitbc.bubuit.net/api/ |
+| Blockchain Node 1 RPC | 8082 | HTTP | Node 1 | ✅ Active | https://aitbc.bubuit.net/rpc/ |
+| Blockchain Node 2 RPC | 8081 | HTTP | Node 2 | ✅ Active | https://aitbc.bubuit.net/rpc2/ |
+| Exchange API | 9080 | HTTP | - | ✅ Active | https://aitbc.bubuit.net/exchange/ |
+| Explorer | 3000 | HTTP | - | ✅ Active | https://aitbc.bubuit.net/ |
+| Marketplace | 3000 | HTTP | - | ✅ Active | https://aitbc.bubuit.net/marketplace/ |
+
+#### Site A Access
+```bash
+ssh aitbc-cascade
+curl http://localhost:8082/rpc/head   # Node 1 RPC
+curl http://localhost:8081/rpc/head   # Node 2 RPC
+```
+
+### Site B: Remote Host ns3 (physical)
+- **Host IP**: 95.216.198.140
+- **Access**: `ssh ns3-root`
+- **Bridge**: incusbr0 192.168.100.1/24
+- **Purpose**: runs incus container `aitbc` with bc node 3
+
+#### Site B Services
+| Service | Port | Protocol | Purpose | Status | URL |
+|---------|------|----------|---------|--------|-----|
+| incus host bridge | 192.168.100.1/24 | n/a | L2 bridge for container | ✅ Active | n/a |
+| SSH | 22 | SSH | Host management | ✅ Active | ssh ns3-root |
+
+#### Site B Access
+```bash
+ssh ns3-root
+```
+
+### Site C: Remote Container ns3/aitbc
+- **Container IP**: 192.168.100.10
+- **Access**: `ssh ns3-root` → `incus shell aitbc`
+- **Domain**: aitbc.keisanki.net
+- **Blockchain Nodes**: Node 3 (rpc 8082) — provided by services `blockchain-node` + `blockchain-rpc`
+
+#### Site C Services
+| Service | Port | Protocol | Node | Status | URL |
+|---------|------|----------|------|--------|-----|
+| Blockchain Node 3 RPC | 8082 | HTTP | Node 3 | ✅ Active (service names: blockchain-node/blockchain-rpc) | http://aitbc.keisanki.net/rpc/ |
+
+#### Site C Access
+```bash
+ssh ns3-root "incus shell aitbc"
+curl http://192.168.100.10:8082/rpc/head       # Node 3 RPC (direct)
+curl http://aitbc.keisanki.net/rpc/head         # Node 3 RPC (via /rpc/)
+```
+
+### Site D: Shared Features
+- Transaction-dependent block creation on all nodes
+- HTTP polling of RPC mempool
+- PoA consensus with 2s intervals
+- Cross-site RPC synchronization (transaction propagation)
+- Independent chain state; P2P not connected yet
+
+## Network Architecture (YAML)
+
+```yaml
+environments:
+  site_a_localhost:
+    ip: 10.1.223.93
+    domain: aitbc.bubuit.net
+    container: aitbc
+    access: ssh aitbc-cascade
+    blockchain_nodes:
+      - id: 1
+        rpc_port: 8082
+        p2p_port: 7070
+        status: active
+      - id: 2
+        rpc_port: 8081
+        p2p_port: 7071
+        status: active
+
+  site_b_ns3_host:
+    ip: 95.216.198.140
+    access: ssh ns3-root
+    bridge: 192.168.100.1/24
+
+  site_c_ns3_container:
+    container_ip: 192.168.100.10
+    domain: aitbc.keisanki.net
+    access: ssh ns3-root → incus shell aitbc
+    blockchain_nodes:
+      - id: 3
+        rpc_port: 8082
+        p2p_port: 7072
+        status: active
+
+shared_features:
+  transaction_dependent_blocks: true
+  rpc_mempool_polling: true
+  consensus: PoA
+  block_interval_seconds: 2
+  cross_site_sync: true
+  cross_site_sync_interval: 10
+  p2p_connected: false
+```
+
+### Site A Extras (dev)
+
+#### Local dev services
+| Service | Port | Protocol | Purpose | Status | URL |
+|---------|------|----------|---------|--------|-----|
+| Test Coordinator | 8001 | HTTP | Local coordinator testing | ⚠️ Optional | http://127.0.0.1:8001 |
+| Test Blockchain | 8080 | HTTP | Local blockchain testing | ⚠️ Optional | http://127.0.0.1:8080 |
+| Ollama (GPU) | 11434 | HTTP | Local LLM serving | ✅ Available | http://127.0.0.1:11434 |
+
+#### Client applications
+| Application | Port | Protocol | Purpose | Connection |
+|-------------|------|----------|---------|------------|
+| Client Wallet | Variable | HTTP | Submits jobs to coordinator | → 10.1.223.93:8000 |
+| Miner Client | Variable | HTTP | Polls for jobs | → 10.1.223.93:8000 |
+| Browser Wallet | Browser | HTTP | Web wallet extension | → 10.1.223.93 |
+
+### Site B Extras (host)
+- Port forwarding managed via firehol (8000, 8081, 8082, 9080 → 192.168.100.10)
+- Firewall host rules: 80, 443 open for nginx; legacy ports optional (8000, 8081, 8082, 9080, 3000)
+
+### Site C Extras (container)
+- Internal ports: 8000, 8081, 8082, 9080, 3000, 8080
+- Systemd core services: coordinator-api, blockchain-node{,-2,-3}, blockchain-rpc{,-2,-3}, aitbc-exchange; web: nginx, dashboard_server, aitbc-marketplace-ui
+
+### Site D: Shared
+- Deployment status:
+```yaml
+deployment:
+  localhost:
+    blockchain_nodes: 2
+    updated_codebase: true
+    transaction_dependent_blocks: true
+    last_updated: 2026-01-28
+  remote:
+    blockchain_nodes: 1
+    updated_codebase: true
+    transaction_dependent_blocks: true
+    last_updated: 2026-01-28
+```
+- Reverse proxy: nginx (config `/etc/nginx/sites-available/aitbc-reverse-proxy.conf`)
+- Service routes: explorer/api/rpc/rpc2/rpc3/exchange/admin on aitbc.bubuit.net
+- Alternative subdomains: api.aitbc.bubuit.net, rpc.aitbc.bubuit.net
+- Notes: external domains use nginx; legacy direct ports via firehol rules
+```
+
+Note: External domains require port forwarding to be configured on the host.
+
+## Data Storage Locations
+
+### Container Paths
+```
+/opt/coordinator-api/          # Coordinator application
+├── src/coordinator.db         # Main database
+└── .venv/                     # Python environment
+
+/opt/blockchain-node/          # Blockchain Node 1
+├── data/chain.db             # Chain database
+└── .venv/                    # Python environment
+
+/opt/blockchain-node-2/        # Blockchain Node 2
+├── data/chain2.db            # Chain database
+└── .venv/                    # Python environment
+
+/opt/exchange/                 # Exchange API
+├── data/                     # Exchange data
+└── .venv/                    # Python environment
+
+/var/www/html/                # Static web assets
+├── assets/                   # CSS/JS files
+└── explorer/                 # Explorer web app
+```
+
+### Local Paths
+```
+/home/oib/windsurf/aitbc/      # Development workspace
+├── apps/                      # Application source
+├── cli/                       # Command-line tools
+├── home/                      # Client/miner scripts
+└── tests/                     # Test suites
+```
+
+## Network Topology
+
+### Physical Layout
+```
+Internet
+    │
+    ▼
+┌─────────────────────┐
+│   ns3-root         │  ← Host Server (95.216.198.140)
+│   ┌─────────────┐  │
+│   │  incus      │  │
+│   │  aitbc      │  │  ← Container (192.168.100.10/24)
+│   │             │  │      NAT → 10.1.223.93
+│   └─────────────┘  │
+└─────────────────────┘
+```
+
+### Access Paths
+1. **Direct Container Access**: `ssh aitbc-cascade` → 10.1.223.93
+2. **Via Host**: `ssh ns3-root` → `incus shell aitbc`
+3. **Service Access**: All services via 10.1.223.93:PORT
+
+## Monitoring and Logging
+
+### Log Locations
+```bash
+# System logs
+journalctl -u coordinator-api
+journalctl -u blockchain-node
+journalctl -u aitbc-exchange
+
+# Application logs
+tail -f /opt/coordinator-api/logs/app.log
+tail -f /opt/blockchain-node/logs/chain.log
+```
+
+### Health Checks
+```bash
+# From host server
+ssh ns3-root "curl -s http://192.168.100.10:8000/v1/health"
+ssh ns3-root "curl -s http://192.168.100.10:8082/rpc/head"
+ssh ns3-root "curl -s http://192.168.100.10:9080/health"
+
+# From within container
+ssh ns3-root "incus exec aitbc -- curl -s http://localhost:8000/v1/health"
+ssh ns3-root "incus exec aitbc -- curl -s http://localhost:8082/rpc/head"
+ssh ns3-root "incus exec aitbc -- curl -s http://localhost:9080/health"
+
+# External testing (with port forwarding configured)
+curl -s http://aitbc.bubuit.net:8000/v1/health
+curl -s http://aitbc.bubuit.net:8082/rpc/head
+curl -s http://aitbc.bubuit.net:9080/health
+```
+
+## Development Workflow
+
+### 1. Local Development
+```bash
+# Start local services
+cd apps/coordinator-api
+python -m uvicorn src.app.main:app --reload --port 8001
+
+# Run tests
+python -m pytest tests/
+```
+
+### 2. Container Deployment
+```bash
+# Deploy to container
+bash scripts/deploy/deploy-to-server.sh
+
+# Update specific service
+scp src/app/main.py ns3-root:/tmp/
+ssh ns3-root "incus exec aitbc -- sudo systemctl restart coordinator-api"
+```
+
+### 3. Testing Endpoints
+```bash
+# Local testing
+curl http://127.0.0.1:8001/v1/health
+
+# Remote testing (from host)
+ssh ns3-root "curl -s http://192.168.100.10:8000/v1/health"
+
+# Remote testing (from container)
+ssh ns3-root "incus exec aitbc -- curl -s http://localhost:8000/v1/health"
+
+# External testing (with port forwarding)
+curl -s http://aitbc.keisanki.net:8000/v1/health
+```
+
+## Security Considerations
+
+### Access Control
+- API keys required for coordinator (X-Api-Key header)
+- Firewall blocks unnecessary ports
+- Nginx handles SSL termination
+
+### Isolation
+- Services run as non-root users where possible
+- Databases in separate directories
+- Virtual environments for Python dependencies
+
+## Monitoring
+
+### Health Check Commands
+```bash
+# Localhost
+ssh aitbc-cascade "systemctl status blockchain-node blockchain-node-2"
+ssh aitbc-cascade "curl -s http://localhost:8082/rpc/head | jq .height"
+
+# Remote
+ssh ns3-root "systemctl status blockchain-node-3"
+ssh ns3-root "curl -s http://192.168.100.10:8082/rpc/head | jq .height"
+```
+
+## Configuration Files
+
+### Localhost Configuration
+- Node 1: `/opt/blockchain-node/src/aitbc_chain/config.py`
+- Node 2: `/opt/blockchain-node-2/src/aitbc_chain/config.py`
+
+### Remote Configuration
+- Node 3: `/opt/blockchain-node/src/aitbc_chain/config.py`
+
+## Notes
+- Nodes are not currently connected via P2P
+- Each node maintains independent blockchain state
+- All nodes implement transaction-dependent block creation
+- Cross-site synchronization enabled for transaction propagation
+- Domain aitbc.bubuit.net points to localhost environment
+- Domain aitbc.keisanki.net points to remote environment
+
+## Cross-Site Synchronization
+- **Status**: Active on all nodes (fully functional)
+- **Method**: RPC-based polling every 10 seconds
+- **Features**: 
+  - Transaction propagation between sites
+  - Height difference detection
+  - ✅ Block import with transaction support (`/blocks/import` endpoint)
+- **Endpoints**:
+  - Local nodes: https://aitbc.bubuit.net/rpc/ (port 8081)
+  - Remote node: http://aitbc.keisanki.net/rpc/
+- **Nginx Configuration**:
+  - Site A: `/etc/nginx/sites-available/aitbc.bubuit.net` → `127.0.0.1:8081`
+  - Fixed routing issue (was pointing to 8082, now correctly routes to 8081)
+
+3. **Monitoring**: Add Prometheus + Grafana
+4. **CI/CD**: Automated deployment pipeline
+5. **Security**: OAuth2/JWT authentication, rate limiting

docs/reference/components/blockchain_node.md

@@ -1,12 +1,14 @@
 # Blockchain Node – Task Breakdown
 
-## Status (2025-12-22)
+## Status (2026-01-29)
 
 - **Stage 1**: ✅ **DEPLOYED** - Blockchain Node successfully deployed on host with RPC API accessible
   - SQLModel-based blockchain with PoA consensus implemented
-  - RPC API running on port 9080 (proxied via /rpc/)
+  - RPC API running on ports 8081/8082 (proxied via /rpc/ and /rpc2/)
   - Mock coordinator on port 8090 (proxied via /v1/)
   - Devnet scripts and observability hooks implemented
+  - ✅ **NEW**: Transaction-dependent block creation implemented
+  - ✅ **NEW**: Cross-site RPC synchronization implemented
   - Note: SQLModel/SQLAlchemy compatibility issues remain (low priority)
 
 ## Stage 1 (MVP) - COMPLETED
@@ -29,27 +31,94 @@
   - ✅ Implement PoA proposer loop producing blocks at fixed interval.
   - ✅ Integrate mempool selection, receipt validation, and block broadcasting.
   - ✅ Add basic P2P gossip (websocket) for blocks/txs.
+  - ✅ **NEW**: Transaction-dependent block creation - only creates blocks when mempool has pending transactions
+  - ✅ **NEW**: HTTP polling mechanism to check RPC mempool size every 2 seconds
+  - ✅ **NEW**: Eliminates empty blocks from blockchain
+
+- **Cross-Site Synchronization** [NEW]
+  - Multi-site deployment with RPC-based sync
+  - Transaction propagation between sites
+  - ✅ Block synchronization fully implemented (/blocks/import endpoint functional)
+  - Status: Active on all 3 nodes with proper validation
+  - ✅ Enable transaction propagation between sites
+  - ✅ Configure remote endpoints for all nodes (localhost nodes sync with remote)
+  - ✅ Integrate sync module into node lifecycle (start/stop)
 
 - **Receipts & Minting**
   - ✅ Wire `receipts.py` to coordinator attestation mock.
-  - ✅ Mint tokens to miners based on compute_units with configurable ratios.
+  - Mint tokens to miners based on compute_units with configurable ratios.
 
 - **Devnet Tooling**
   - ✅ Provide `scripts/devnet_up.sh` launching bootstrap node and mocks.
-  - ✅ Document curl commands for faucet, transfer, receipt submission.
+  - Document curl commands for faucet, transfer, receipt submission.
 
 ## Production Deployment Details
 
-- **Host**: Running on host machine (GPU access required)
+### Multi-Site Deployment
-- **Service**: systemd services for blockchain-node, blockchain-rpc, mock-coordinator
+- **Site A (localhost)**: 2 nodes (ports 8081, 8082) - https://aitbc.bubuit.net/rpc/ and /rpc2/
-- **Ports**: 9080 (RPC), 8090 (Mock Coordinator)
+- **Site B (remote host)**: ns3 server (95.216.198.140)
-- **Proxy**: nginx routes /rpc/ and /v1/ to host services
+- **Site C (remote container)**: 1 node (port 8082) - http://aitbc.keisanki.net/rpc/
-- **Access**: https://aitbc.bubuit.net/rpc/ for blockchain RPC
+- **Service**: systemd services for blockchain-node, blockchain-node-2, blockchain-rpc
-- **Database**: SQLite with SQLModel ORM
+- **Proxy**: nginx routes /rpc/, /rpc2/, /v1/ to appropriate services
-- **Issues**: SQLModel/SQLAlchemy compatibility (low priority)
+- **Database**: SQLite with SQLModel ORM per node
+- **Network**: Cross-site RPC synchronization enabled
+
+### Features
+- Transaction-dependent block creation (prevents empty blocks)
+- HTTP polling of RPC mempool for transaction detection
+- Cross-site transaction propagation via RPC polling
+- Proper transaction storage in block data with tx_count
+- Redis gossip backend for local transaction sharing
+
+### Configuration
+- **Chain ID**: "ait-devnet" (consistent across all sites)
+- **Block Time**: 2 seconds
+- **Cross-site sync**: Enabled, 10-second poll interval
+- **Remote endpoints**: Configured per node for cross-site communication
+
+### Issues
+- SQLModel/SQLAlchemy compatibility (low priority)
+- ✅ Block synchronization fully implemented via /blocks/import endpoint
+- Nodes maintain independent chains (by design with PoA)
 
 ## Stage 2+ - IN PROGRESS
 
 - 🔄 Upgrade consensus to compute-backed proof (CBP) with work score weighting.
 - 🔄 Introduce staking/slashing, replace SQLite with PostgreSQL, add snapshots/fast sync.
 - 🔄 Implement light client support and metrics dashboard.
+
+## Recent Updates (2026-01-29)
+
+### Cross-Site Synchronization Implementation
+- **Module**: `/src/aitbc_chain/cross_site.py`
+- **Purpose**: Enable transaction and block propagation between sites via RPC
+- **Features**:
+  - Polls remote endpoints every 10 seconds
+  - Detects height differences between nodes
+  - Syncs mempool transactions across sites
+  - ✅ Imports blocks between sites via /blocks/import endpoint
+  - Integrated into node lifecycle (starts/stops with node)
+- **Status**: ✅ Fully deployed and functional on all 3 nodes
+- **Endpoint**: /blocks/import POST with full transaction support
+- **Nginx**: Fixed routing to port 8081 for blockchain-rpc-2
+
+### Configuration Updates
+```python
+# Added to ChainSettings in config.py
+cross_site_sync_enabled: bool = True
+cross_site_remote_endpoints: list[str] = [
+    "https://aitbc.bubuit.net/rpc2",  # Node 2
+    "http://aitbc.keisanki.net/rpc"   # Node 3
+]
+cross_site_poll_interval: int = 10
+```
+
+### Current Node Heights
+- Local nodes (1 & 2): 771153 (synchronized)
+- Remote node (3): 40324 (independent chain)
+
+### Technical Notes
+- Each node maintains independent blockchain state
+- Transactions can propagate between sites
+- Block creation remains local to each node (PoA design)
+- Network connectivity verified via reverse proxy

docs/reports/BLOCKCHAIN_DEPLOYMENT_SUMMARY.md

@@ -0,0 +1,156 @@
+# AITBC Blockchain Node Deployment Summary
+
+## Overview
+Successfully deployed two independent AITBC blockchain nodes on the same server for testing and development.
+
+## Node Configuration
+
+### Node 1
+- **Location**: `/opt/blockchain-node`
+- **P2P Port**: 7070
+- **RPC Port**: 8082
+- **Database**: `/opt/blockchain-node/data/chain.db`
+- **Status**: ✅ Operational
+- **Chain Height**: 717,593+ (actively producing blocks)
+
+### Node 2
+- **Location**: `/opt/blockchain-node-2`
+- **P2P Port**: 7071
+- **RPC Port**: 8081
+- **Database**: `/opt/blockchain-node-2/data/chain2.db`
+- **Status**: ✅ Operational
+- **Chain Height**: 174+ (actively producing blocks)
+
+## Services
+
+### Systemd Services
+```bash
+# Node 1
+sudo systemctl status blockchain-node    # Consensus node
+sudo systemctl status blockchain-rpc     # RPC API
+
+# Node 2
+sudo systemctl status blockchain-node-2  # Consensus node
+sudo systemctl status blockchain-rpc-2   # RPC API
+```
+
+### API Endpoints
+- Node 1 RPC: `http://127.0.0.1:8082/docs`
+- Node 2 RPC: `http://127.0.0.1:8081/docs`
+
+## Testing
+
+### Test Scripts
+1. **Basic Test**: `/opt/test_blockchain_simple.py`
+   - Verifies node responsiveness
+   - Tests faucet functionality
+   - Checks chain head
+
+2. **Comprehensive Test**: `/opt/test_blockchain_nodes.py`
+   - Full test suite with multiple scenarios
+   - Currently shows nodes operating independently
+
+### Running Tests
+```bash
+cd /opt/blockchain-node
+source .venv/bin/activate
+cd ..
+python test_blockchain_final.py
+```
+
+## Current Status
+
+### ✅ Working
+- Both nodes are running and producing blocks
+- RPC APIs are responsive
+- Faucet (minting) is functional
+- Transaction submission works
+- Block production active (2s block time)
+
+### ⚠️ Limitations
+- Nodes are running independently (not connected)
+- Using memory gossip backend (no cross-node communication)
+- Different chain heights (expected for independent nodes)
+
+## Production Deployment Guidelines
+
+To connect nodes in a production network:
+
+### 1. Network Configuration
+- Deploy nodes on separate servers
+- Configure proper firewall rules
+- Ensure P2P ports are accessible
+
+### 2. Gossip Backend
+- Use Redis for distributed gossip:
+  ```env
+  GOSSIP_BACKEND=redis
+  GOSSIP_BROADCAST_URL=redis://redis-server:6379/0
+  ```
+
+### 3. Peer Discovery
+- Configure peer list in each node
+- Use DNS seeds or static peer configuration
+- Implement proper peer authentication
+
+### 4. Security
+- Use TLS for P2P communication
+- Implement node authentication
+- Configure proper access controls
+
+## Troubleshooting
+
+### Common Issues
+1. **Port Conflicts**: Ensure ports 7070/7071 and 8081/8082 are available
+2. **Permission Issues**: Check file permissions in `/opt/blockchain-node*`
+3. **Database Issues**: Remove/rename database to reset chain
+
+### Logs
+```bash
+# Node logs
+sudo journalctl -u blockchain-node -f
+sudo journalctl -u blockchain-node-2 -f
+
+# RPC logs
+sudo journalctl -u blockchain-rpc -f
+sudo journalctl -u blockchain-rpc-2 -f
+```
+
+## Next Steps
+
+1. **Multi-Server Deployment**: Deploy nodes on different servers
+2. **Redis Setup**: Configure Redis for shared gossip
+3. **Network Testing**: Test cross-node communication
+4. **Load Testing**: Test network under load
+5. **Monitoring**: Set up proper monitoring and alerting
+
+## Files Created/Modified
+
+### Deployment Scripts
+- `/home/oib/windsurf/aitbc/scripts/deploy/deploy-first-node.sh`
+- `/home/oib/windsurf/aitbc/scripts/deploy/deploy-second-node.sh`
+- `/home/oib/windsurf/aitbc/scripts/deploy/setup-gossip-relay.sh`
+
+### Test Scripts
+- `/home/oib/windsurf/aitbc/tests/test_blockchain_nodes.py`
+- `/home/oib/windsurf/aitbc/tests/test_blockchain_simple.py`
+- `/home/oib/windsurf/aitbc/tests/test_blockchain_final.py`
+
+### Configuration Files
+- `/opt/blockchain-node/.env`
+- `/opt/blockchain-node-2/.env`
+- `/etc/systemd/system/blockchain-node*.service`
+- `/etc/systemd/system/blockchain-rpc*.service`
+
+## Summary
+
+✅ Successfully deployed two independent blockchain nodes
+✅ Both nodes are fully operational and producing blocks
+✅ RPC APIs are functional for testing
+✅ Test suite created and validated
+⚠️ Nodes not connected (expected for current configuration)
+
+The deployment provides a solid foundation for:
+- Development and testing
+- Multi-node network simulation
+- Production deployment preparation

docs/reports/README.md

@@ -0,0 +1,16 @@
+# Documentation Reports
+
+This directory contains various reports and summaries generated during development.
+
+## Files
+
+- **AITBC_PAYMENT_ARCHITECTURE.md** - Payment system architecture documentation
+- **BLOCKCHAIN_DEPLOYMENT_SUMMARY.md** - Summary of blockchain deployment status
+- **IMPLEMENTATION_COMPLETE_SUMMARY.md** - Overall implementation status
+- **INTEGRATION_TEST_FIXES.md** - Fixes applied to integration tests
+- **INTEGRATION_TEST_UPDATES.md** - Updates to integration test suite
+- **PAYMENT_INTEGRATION_COMPLETE.md** - Payment integration completion report
+- **SKIPPED_TESTS_ROADMAP.md** - Roadmap for skipped tests
+- **TESTING_STATUS_REPORT.md** - Comprehensive testing status
+- **TEST_FIXES_COMPLETE.md** - Summary of completed test fixes
+- **WALLET_COORDINATOR_INTEGRATION.md** - Wallet and coordinator integration details

docs/roadmap.md

@@ -559,6 +559,92 @@ Fill the intentional placeholder folders with actual content. Priority order bas
 | `apps/pool-hub/src/app/` | Q2 2026 | Backend | ✅ Complete (2026-01-24) |
 | `apps/coordinator-api/migrations/` | As needed | Backend | ✅ Complete (2026-01-24) |
 
+## Stage 21 — Transaction-Dependent Block Creation [COMPLETED: 2026-01-28]
+
+- **PoA Consensus Enhancement**
+  - ✅ Modify PoA proposer to only create blocks when mempool has pending transactions
+  - ✅ Implement HTTP polling mechanism to check RPC mempool size
+  - ✅ Add transaction storage in block data with tx_count field
+  - ✅ Remove processed transactions from mempool after block creation
+  - ✅ Fix syntax errors and import issues in consensus/poa.py
+
+- **Architecture Implementation**
+  - ✅ RPC Service: Receives transactions and maintains in-memory mempool
+  - ✅ Metrics Endpoint: Exposes mempool_size for node polling
+  - ✅ Node Process: Polls metrics every 2 seconds, creates blocks only when needed
+  - ✅ Eliminates empty blocks from blockchain
+  - ✅ Maintains block integrity with proper transaction inclusion
+
+- **Testing and Validation**
+  - ✅ Deploy changes to both Node 1 and Node 2
+  - ✅ Verify proposer skips block creation when no transactions
+  - ✅ Confirm blocks are created when transactions are submitted
+  - ✅ Fix gossip broker integration issues
+  - ✅ Implement message passing solution for transaction synchronization
+
+## Stage 22 — Future Enhancements [PLANNED]
+
+- **Shared Mempool Implementation**
+  - [ ] Implement database-backed mempool for true sharing between services
+  - [ ] Add Redis-based pub/sub for real-time transaction propagation
+  - [ ] Optimize polling mechanism with webhooks or server-sent events
+
+- **Advanced Block Production**
+  - [ ] Implement block size limits and gas optimization
+  - [ ] Add transaction prioritization based on fees
+  - [ ] Implement batch transaction processing
+  - [ ] Add block production metrics and monitoring
+
+- **Production Hardening**
+  - [ ] Add comprehensive error handling for network failures
+  - [ ] Implement graceful degradation when RPC service unavailable
+  - [ ] Add circuit breaker pattern for mempool polling
+  - [ ] Create operational runbooks for block production issues
+
+## Stage 21 — Cross-Site Synchronization [COMPLETED: 2026-01-29]
+
+Enable blockchain nodes to synchronize across different sites via RPC.
+
+### Multi-Site Architecture
+- **Site A (localhost)**: 2 nodes (ports 8081, 8082)
+- **Site B (remote host)**: ns3 server (95.216.198.140)
+- **Site C (remote container)**: 1 node (port 8082)
+- **Network**: Cross-site RPC synchronization enabled
+
+### Implementation
+- **Synchronization Module** ✅ COMPLETE
+  - [x] Create `/src/aitbc_chain/cross_site.py` module
+  - [x] Implement remote endpoint polling (10-second interval)
+  - [x] Add transaction propagation between sites
+  - [x] Detect height differences between nodes
+  - [x] Integrate into node lifecycle (start/stop)
+
+- **Configuration** ✅ COMPLETE
+  - [x] Add `cross_site_sync_enabled` to ChainSettings
+  - [x] Add `cross_site_remote_endpoints` list
+  - [x] Add `cross_site_poll_interval` setting
+  - [x] Configure endpoints for all 3 nodes
+
+- **Deployment** ✅ COMPLETE
+  - [x] Deploy to all 3 nodes
+  - [x] Fix Python compatibility issues
+  - [x] Fix RPC endpoint URL paths
+  - [x] Verify network connectivity
+
+### Current Status
+- All nodes running with cross-site sync enabled
+- Transaction propagation working
+- ✅ Block sync fully implemented with transaction support
+- ✅ Transaction data properly saved during block import
+- Nodes maintain independent chains (PoA design)
+- Nginx routing fixed to port 8081 for blockchain-rpc-2
+
+### Future Enhancements
+- [x] ✅ Block import endpoint fully implemented with transactions
+- [ ] Implement conflict resolution for divergent chains
+- [ ] Add sync metrics and monitoring
+- [ ] Add proposer signature validation for imported blocks
+
 ## Stage 20 — Technical Debt Remediation [PLANNED]
 
 Address known issues in existing components that are blocking production use.
@@ -643,6 +729,7 @@ Current Status: Canonical receipt schema specification moved from `protocols/rec
 | `packages/solidity/aitbc-token/` testnet | Low | Q3 2026 | 🔄 Pending deployment |
 | `contracts/ZKReceiptVerifier.sol` deploy | Low | Q3 2026 | ✅ Code ready (2026-01-24) |
 | `docs/reference/specs/receipt-spec.md` finalize | Low | Q2 2026 | 🔄 Pending extensions |
+| Cross-site synchronization | High | Q1 2026 | ✅ Complete (2026-01-29) |
 
 the canonical checklist during implementation. Mark completed tasks with ✅ and add dates or links to relevant PRs as development progresses.
 

docs/tutorials/custom-proposer.md

@@ -362,6 +362,9 @@ Monitor your proposer's performance with Grafana dashboards:
 2. **Test thoroughly** - Use testnet before mainnet deployment
 3. **Monitor performance** - Track metrics and optimize
 4. **Handle edge cases** - Empty blocks, network partitions
+   - **Note**: The default AITBC proposer now implements transaction-dependent block creation
+   - Empty blocks are automatically prevented when no pending transactions exist
+   - Consider this behavior when designing custom proposers
 5. **Document behavior** - Clear documentation for custom logic
 
 ## Troubleshooting

infra/nginx/nginx-aitbc-reverse-proxy.conf

@@ -0,0 +1,247 @@
+# AITBC Nginx Reverse Proxy Configuration
+# Domain: aitbc.keisanki.net
+# This configuration replaces the need for firehol/iptables port forwarding
+
+# HTTP to HTTPS redirect
+server {
+    listen 80;
+    server_name aitbc.keisanki.net;
+    
+    # Redirect all HTTP traffic to HTTPS
+    return 301 https://$server_name$request_uri;
+}
+
+# Main HTTPS server block
+server {
+    listen 443 ssl http2;
+    server_name aitbc.keisanki.net;
+    
+    # SSL Configuration (Let's Encrypt certificates)
+    ssl_certificate /etc/letsencrypt/live/aitbc.keisanki.net/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/aitbc.keisanki.net/privkey.pem;
+    include /etc/letsencrypt/options-ssl-nginx.conf;
+    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
+    
+    # Security headers
+    add_header X-Frame-Options "SAMEORIGIN" always;
+    add_header X-XSS-Protection "1; mode=block" always;
+    add_header X-Content-Type-Options "nosniff" always;
+    add_header Referrer-Policy "strict-origin-when-cross-origin" always;
+    add_header Content-Security-Policy "default-src 'self' http: https: data: blob: 'unsafe-inline' 'unsafe-eval'" always;
+    
+    # Enable gzip compression
+    gzip on;
+    gzip_vary on;
+    gzip_min_length 1024;
+    gzip_types text/plain text/css text/xml text/javascript application/javascript application/xml+rss application/json;
+    
+    # Blockchain Explorer (main route)
+    location / {
+        proxy_pass http://192.168.100.10:3000;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_buffering off;
+        
+        # WebSocket support if needed
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+    }
+    
+    # Coordinator API
+    location /api/ {
+        proxy_pass http://192.168.100.10:8000/v1/;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_buffering off;
+        
+        # CORS headers for API
+        add_header Access-Control-Allow-Origin "*" always;
+        add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS" always;
+        add_header Access-Control-Allow-Headers "DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization,X-Api-Key" always;
+        
+        # Handle preflight requests
+        if ($request_method = 'OPTIONS') {
+            add_header Access-Control-Allow-Origin "*";
+            add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS";
+            add_header Access-Control-Allow-Headers "DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization,X-Api-Key";
+            add_header Access-Control-Max-Age 1728000;
+            add_header Content-Type "text/plain; charset=utf-8";
+            add_header Content-Length 0;
+            return 204;
+        }
+    }
+    
+    # Blockchain Node 1 RPC
+    location /rpc/ {
+        proxy_pass http://192.168.100.10:8082/rpc/;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_buffering off;
+    }
+    
+    # Blockchain Node 2 RPC (alternative endpoint)
+    location /rpc2/ {
+        proxy_pass http://192.168.100.10:8081/rpc/;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_buffering off;
+    }
+    
+    # Exchange API
+    location /exchange/ {
+        proxy_pass http://192.168.100.10:9080/;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_buffering off;
+    }
+    
+    # Marketplace UI (if separate from explorer)
+    location /marketplace/ {
+        proxy_pass http://192.168.100.10:3001/;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_buffering off;
+        
+        # Handle subdirectory rewrite
+        rewrite ^/marketplace/(.*)$ /$1 break;
+    }
+    
+    # Admin dashboard
+    location /admin/ {
+        proxy_pass http://192.168.100.10:8080/;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_buffering off;
+        
+        # Optional: Restrict admin access
+        # allow 192.168.100.0/24;
+        # allow 127.0.0.1;
+        # deny all;
+    }
+    
+    # Health check endpoint
+    location /health {
+        access_log off;
+        return 200 "healthy\n";
+        add_header Content-Type text/plain;
+    }
+    
+    # API health checks
+    location /api/health {
+        proxy_pass http://192.168.100.10:8000/v1/health;
+        proxy_set_header Host $host;
+        access_log off;
+    }
+    
+    # Static assets caching
+    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
+        proxy_pass http://192.168.100.10:3000;
+        expires 1y;
+        add_header Cache-Control "public, immutable";
+        add_header X-Content-Type-Options nosniff;
+        
+        # Don't log static file access
+        access_log off;
+    }
+    
+    # Deny access to hidden files
+    location ~ /\. {
+        deny all;
+        access_log off;
+        log_not_found off;
+    }
+    
+    # Custom error pages
+    error_page 404 /404.html;
+    error_page 500 502 503 504 /50x.html;
+    
+    location = /50x.html {
+        root /usr/share/nginx/html;
+    }
+}
+
+# Optional: Subdomain for API-only access
+server {
+    listen 443 ssl http2;
+    server_name api.aitbc.keisanki.net;
+    
+    # SSL Configuration (same certificates)
+    ssl_certificate /etc/letsencrypt/live/aitbc.keisanki.net/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/aitbc.keisanki.net/privkey.pem;
+    include /etc/letsencrypt/options-ssl-nginx.conf;
+    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
+    
+    # Security headers
+    add_header X-Frame-Options "DENY" always;
+    add_header X-XSS-Protection "1; mode=block" always;
+    add_header X-Content-Type-Options "nosniff" always;
+    add_header Referrer-Policy "strict-origin-when-cross-origin" always;
+    
+    # API routes only
+    location / {
+        proxy_pass http://192.168.100.10:8000/v1/;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_buffering off;
+        
+        # CORS headers
+        add_header Access-Control-Allow-Origin "*" always;
+        add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS" always;
+        add_header Access-Control-Allow-Headers "DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization,X-Api-Key" always;
+        
+        # Handle preflight requests
+        if ($request_method = 'OPTIONS') {
+            add_header Access-Control-Allow-Origin "*";
+            add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS";
+            add_header Access-Control-Allow-Headers "DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization,X-Api-Key";
+            add_header Access-Control-Max-Age 1728000;
+            add_header Content-Type "text/plain; charset=utf-8";
+            add_header Content-Length 0;
+            return 204;
+        }
+    }
+}
+
+# Optional: Subdomain for blockchain RPC
+server {
+    listen 443 ssl http2;
+    server_name rpc.aitbc.keisanki.net;
+    
+    # SSL Configuration
+    ssl_certificate /etc/letsencrypt/live/aitbc.keisanki.net/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/aitbc.keisanki.net/privkey.pem;
+    include /etc/letsencrypt/options-ssl-nginx.conf;
+    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
+    
+    # Security headers
+    add_header X-Frame-Options "DENY" always;
+    add_header X-XSS-Protection "1; mode=block" always;
+    add_header X-Content-Type-Options "nosniff" always;
+    
+    # RPC routes
+    location / {
+        proxy_pass http://192.168.100.10:8082/rpc/;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_buffering off;
+    }
+}

pyproject.toml

@@ -16,7 +16,7 @@ pythonpath = [
     "apps/wallet-daemon/src",
     "apps/blockchain-node/src"
 ]
-import-mode = append
+import_mode = "append"
 markers = [
     "unit: Unit tests (fast, isolated)",
     "integration: Integration tests (require external services)",

pytest.ini

@@ -6,6 +6,12 @@ python_files = test_*.py *_test.py
 python_classes = Test*
 python_functions = test_*
 
+# Custom markers
+markers =
+    unit: Unit tests (fast, isolated)
+    integration: Integration tests (may require external services)
+    slow: Slow running tests
+
 # Additional options for local testing
 addopts = 
     --verbose
@@ -17,3 +23,4 @@ filterwarnings =
     ignore::DeprecationWarning
     ignore::PendingDeprecationWarning
     ignore::pytest.PytestUnknownMarkWarning
+    ignore::pydantic.PydanticDeprecatedSince20

scripts/deploy/cleanup-deployment.sh

@@ -0,0 +1,24 @@
+#!/bin/bash
+
+# Clean up failed deployment and prepare for redeployment
+
+echo "🧹 Cleaning up failed deployment..."
+echo "=================================="
+
+# Stop any running services
+echo "Stopping services..."
+ssh ns3-root "systemctl stop blockchain-node blockchain-rpc nginx 2>/dev/null || true"
+
+# Remove old directories
+echo "Removing old directories..."
+ssh ns3-root "rm -rf /opt/blockchain-node /opt/blockchain-node-src /opt/blockchain-explorer 2>/dev/null || true"
+
+# Remove systemd services
+echo "Removing systemd services..."
+ssh ns3-root "systemctl disable blockchain-node blockchain-rpc blockchain-explorer 2>/dev/null || true"
+ssh ns3-root "rm -f /etc/systemd/system/blockchain-node.service /etc/systemd/system/blockchain-rpc.service /etc/systemd/system/blockchain-explorer.service 2>/dev/null || true"
+ssh ns3-root "systemctl daemon-reload"
+
+echo "✅ Cleanup complete!"
+echo ""
+echo "You can now run: ./scripts/deploy/deploy-all-remote.sh"

scripts/deploy/deploy-all-remote.sh

@@ -0,0 +1,56 @@
+#!/bin/bash
+
+# Deploy blockchain node and explorer by building directly on ns3
+
+echo "🚀 AITBC Remote Deployment (Build on Server)"
+echo "=========================================="
+echo "This will build the blockchain node directly on ns3"
+echo "to utilize the gigabit connection instead of uploading."
+echo ""
+
+# Copy deployment scripts to server
+echo "Copying deployment scripts to ns3..."
+scp scripts/deploy/deploy-blockchain-remote.sh ns3-root:/opt/
+scp scripts/deploy/deploy-explorer-remote.sh ns3-root:/opt/
+
+# Create directories on server first
+echo "Creating directories on ns3..."
+ssh ns3-root "mkdir -p /opt/blockchain-node-src /opt/blockchain-node"
+
+# Copy blockchain source code to server (excluding data files)
+echo "Copying blockchain source code to ns3..."
+rsync -av --exclude='data/' --exclude='*.db' --exclude='__pycache__' --exclude='.venv' apps/blockchain-node/ ns3-root:/opt/blockchain-node-src/
+
+# Execute blockchain deployment
+echo ""
+echo "Deploying blockchain node..."
+ssh ns3-root "cd /opt && cp -r /opt/blockchain-node-src/* /opt/blockchain-node/ && cd /opt/blockchain-node && chmod +x ../deploy-blockchain-remote.sh && ../deploy-blockchain-remote.sh"
+
+# Wait for blockchain to start
+echo ""
+echo "Waiting 10 seconds for blockchain node to start..."
+sleep 10
+
+# Execute explorer deployment on ns3
+echo ""
+echo "Deploying blockchain explorer..."
+ssh ns3-root "cd /opt && ./deploy-explorer-remote.sh"
+
+# Check services
+echo ""
+echo "Checking service status..."
+ssh ns3-root "systemctl status blockchain-node blockchain-rpc nginx --no-pager | grep -E 'Active:|Main PID:'"
+
+echo ""
+echo "✅ Deployment complete!"
+echo ""
+echo "Services:"
+echo "  - Blockchain Node RPC: http://localhost:8082"
+echo "  - Blockchain Explorer: http://localhost:3000"
+echo ""
+echo "External access:"
+echo "  - Blockchain Node RPC: http://aitbc.keisanki.net:8082"
+echo "  - Blockchain Explorer: http://aitbc.keisanki.net:3000"
+echo ""
+echo "The blockchain node will start syncing automatically."
+echo "The explorer connects to the local node and displays real-time data."

scripts/deploy/deploy-blockchain-and-explorer.sh

@@ -0,0 +1,207 @@
+#!/bin/bash
+
+# Deploy blockchain node and explorer to incus container
+
+set -e
+
+echo "🚀 Deploying Blockchain Node and Explorer"
+echo "========================================"
+
+# Colors
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+print_status() {
+    echo -e "${GREEN}[INFO]${NC} $1"
+}
+
+print_warning() {
+    echo -e "${YELLOW}[WARN]${NC} $1"
+}
+
+# Copy blockchain node to container
+print_status "Copying blockchain node to container..."
+ssh ns3-root "rm -rf /opt/blockchain-node 2>/dev/null || true"
+scp -r apps/blockchain-node ns3-root:/opt/
+
+# Setup blockchain node in container
+print_status "Setting up blockchain node..."
+ssh ns3-root << 'EOF'
+cd /opt/blockchain-node
+
+# Create configuration
+cat > .env << EOL
+CHAIN_ID=ait-devnet
+DB_PATH=./data/chain.db
+RPC_BIND_HOST=0.0.0.0
+RPC_BIND_PORT=8082
+P2P_BIND_HOST=0.0.0.0
+P2P_BIND_PORT=7070
+PROPOSER_KEY=proposer_key_$(date +%s)
+MINT_PER_UNIT=1000
+COORDINATOR_RATIO=0.05
+GOSSIP_BACKEND=memory
+EOL
+
+# Create data directory
+mkdir -p data/devnet
+
+# Setup Python environment
+python3 -m venv .venv
+source .venv/bin/activate
+pip install --upgrade pip
+pip install -e .
+
+# Generate genesis
+export PYTHONPATH="${PWD}/src:${PWD}/scripts:${PYTHONPATH:-}"
+python scripts/make_genesis.py --output data/devnet/genesis.json --force
+EOF
+
+# Create systemd service for blockchain node
+print_status "Creating systemd service for blockchain node..."
+ssh ns3-root << 'EOF'
+cat > /etc/systemd/system/blockchain-node.service << EOL
+[Unit]
+Description=AITBC Blockchain Node
+After=network.target
+
+[Service]
+Type=exec
+User=root
+WorkingDirectory=/opt/blockchain-node
+Environment=PATH=/opt/blockchain-node/.venv/bin:/usr/local/bin:/usr/bin:/bin
+Environment=PYTHONPATH=/opt/blockchain-node/src:/opt/blockchain-node/scripts
+ExecStart=/opt/blockchain-node/.venv/bin/python3 -m aitbc_chain.main
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+EOL
+
+cat > /etc/systemd/system/blockchain-rpc.service << EOL
+[Unit]
+Description=AITBC Blockchain RPC API
+After=blockchain-node.service
+
+[Service]
+Type=exec
+User=root
+WorkingDirectory=/opt/blockchain-node
+Environment=PATH=/opt/blockchain-node/.venv/bin:/usr/local/bin:/usr/bin:/bin
+Environment=PYTHONPATH=/opt/blockchain-node/src:/opt/blockchain-node/scripts
+ExecStart=/opt/blockchain-node/.venv/bin/python3 -m uvicorn aitbc_chain.app:app --host 0.0.0.0 --port 8082
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+EOL
+
+systemctl daemon-reload
+systemctl enable blockchain-node blockchain-rpc
+EOF
+
+# Start blockchain node
+print_status "Starting blockchain node..."
+ssh ns3-root "systemctl start blockchain-node blockchain-rpc"
+
+# Wait for node to start
+print_status "Waiting for blockchain node to start..."
+sleep 5
+
+# Check status
+print_status "Checking blockchain node status..."
+ssh ns3-root "systemctl status blockchain-node blockchain-rpc --no-pager | grep -E 'Active:|Main PID:'"
+
+# Copy explorer to container
+print_status "Copying blockchain explorer to container..."
+ssh ns3-root "rm -rf /opt/blockchain-explorer 2>/dev/null || true"
+scp -r apps/blockchain-explorer ns3-root:/opt/
+
+# Setup explorer in container
+print_status "Setting up blockchain explorer..."
+ssh ns3-root << 'EOF'
+cd /opt/blockchain-explorer
+
+# Create Python environment
+python3 -m venv .venv
+source .venv/bin/activate
+pip install --upgrade pip
+pip install -r requirements.txt
+EOF
+
+# Create systemd service for explorer
+print_status "Creating systemd service for blockchain explorer..."
+ssh ns3-root << 'EOF'
+cat > /etc/systemd/system/blockchain-explorer.service << EOL
+[Unit]
+Description=AITBC Blockchain Explorer
+After=blockchain-rpc.service
+
+[Service]
+Type=exec
+User=root
+WorkingDirectory=/opt/blockchain-explorer
+Environment=PATH=/opt/blockchain-explorer/.venv/bin:/usr/local/bin:/usr/bin:/bin
+ExecStart=/opt/blockchain-explorer/.venv/bin/python3 main.py
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+EOL
+
+systemctl daemon-reload
+systemctl enable blockchain-explorer
+EOF
+
+# Start explorer
+print_status "Starting blockchain explorer..."
+ssh ns3-root "systemctl start blockchain-explorer"
+
+# Wait for explorer to start
+print_status "Waiting for explorer to start..."
+sleep 3
+
+# Setup port forwarding
+print_status "Setting up port forwarding..."
+ssh ns3-root << 'EOF'
+# Clear existing NAT rules
+iptables -t nat -F PREROUTING 2>/dev/null || true
+iptables -t nat -F POSTROUTING 2>/dev/null || true
+
+# Add port forwarding for blockchain RPC
+iptables -t nat -A PREROUTING -p tcp --dport 8082 -j DNAT --to-destination 192.168.100.10:8082
+iptables -t nat -A POSTROUTING -p tcp -d 192.168.100.10 --dport 8082 -j MASQUERADE
+
+# Add port forwarding for explorer
+iptables -t nat -A PREROUTING -p tcp --dport 3000 -j DNAT --to-destination 192.168.100.10:3000
+iptables -t nat -A POSTROUTING -p tcp -d 192.168.100.10 --dport 3000 -j MASQUERADE
+
+# Save rules
+mkdir -p /etc/iptables
+iptables-save > /etc/iptables/rules.v4
+
+# Install iptables-persistent for persistence
+apt-get update
+apt-get install -y iptables-persistent
+EOF
+
+# Check all services
+print_status "Checking all services..."
+ssh ns3-root "systemctl status blockchain-node blockchain-rpc blockchain-explorer --no-pager | grep -E 'Active:|Main PID:'"
+
+print_success "✅ Deployment complete!"
+echo ""
+echo "Services deployed:"
+echo "  - Blockchain Node RPC: http://192.168.100.10:8082"
+echo "  - Blockchain Explorer: http://192.168.100.10:3000"
+echo ""
+echo "External access:"
+echo "  - Blockchain Node RPC: http://aitbc.keisanki.net:8082"
+echo "  - Blockchain Explorer: http://aitbc.keisanki.net:3000"
+echo ""
+echo "The explorer is connected to the local blockchain node and will display"
+echo "real-time blockchain data including blocks and transactions."

scripts/deploy/deploy-blockchain-explorer.sh

@@ -0,0 +1,94 @@
+#!/bin/bash
+
+# Deploy blockchain explorer to incus container
+
+set -e
+
+echo "🔍 Deploying Blockchain Explorer"
+echo "================================="
+
+# Colors
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+print_status() {
+    echo -e "${GREEN}[INFO]${NC} $1"
+}
+
+print_warning() {
+    echo -e "${YELLOW}[WARN]${NC} $1"
+}
+
+# Copy explorer to container
+print_status "Copying blockchain explorer to container..."
+ssh ns3-root "rm -rf /opt/blockchain-explorer 2>/dev/null || true"
+scp -r apps/blockchain-explorer ns3-root:/opt/
+
+# Setup explorer in container
+print_status "Setting up blockchain explorer..."
+ssh ns3-root << 'EOF'
+cd /opt/blockchain-explorer
+
+# Create Python environment
+python3 -m venv .venv
+source .venv/bin/activate
+pip install --upgrade pip
+pip install -r requirements.txt
+EOF
+
+# Create systemd service for explorer
+print_status "Creating systemd service for blockchain explorer..."
+ssh ns3-root << 'EOF'
+cat > /etc/systemd/system/blockchain-explorer.service << EOL
+[Unit]
+Description=AITBC Blockchain Explorer
+After=blockchain-rpc.service
+
+[Service]
+Type=exec
+User=root
+WorkingDirectory=/opt/blockchain-explorer
+Environment=PATH=/opt/blockchain-explorer/.venv/bin:/usr/local/bin:/usr/bin:/bin
+ExecStart=/opt/blockchain-explorer/.venv/bin/python3 main.py
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+EOL
+
+systemctl daemon-reload
+systemctl enable blockchain-explorer
+EOF
+
+# Start explorer
+print_status "Starting blockchain explorer..."
+ssh ns3-root "systemctl start blockchain-explorer"
+
+# Wait for explorer to start
+print_status "Waiting for explorer to start..."
+sleep 3
+
+# Setup port forwarding for explorer
+print_status "Setting up port forwarding for explorer..."
+ssh ns3-root << 'EOF'
+# Add port forwarding for explorer
+iptables -t nat -A PREROUTING -p tcp --dport 3000 -j DNAT --to-destination 192.168.100.10:3000
+iptables -t nat -A POSTROUTING -p tcp -d 192.168.100.10 --dport 3000 -j MASQUERADE
+
+# Save rules
+iptables-save > /etc/iptables/rules.v4
+EOF
+
+# Check status
+print_status "Checking blockchain explorer status..."
+ssh ns3-root "systemctl status blockchain-explorer --no-pager | grep -E 'Active:|Main PID:'"
+
+print_success "✅ Blockchain explorer deployed!"
+echo ""
+echo "Explorer URL: http://192.168.100.10:3000"
+echo "External URL: http://aitbc.keisanki.net:3000"
+echo ""
+echo "The explorer will automatically connect to the local blockchain node."
+echo "You can view blocks, transactions, and chain statistics."

scripts/deploy/deploy-blockchain-remote.sh

@@ -0,0 +1,157 @@
+#!/bin/bash
+
+# Deploy blockchain node directly on ns3 server (build in place)
+
+set -e
+
+echo "🚀 Deploying Blockchain Node on ns3 (Build in Place)"
+echo "====================================================="
+
+# Colors
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+print_status() {
+    echo -e "${GREEN}[INFO]${NC} $1"
+}
+
+print_warning() {
+    echo -e "${YELLOW}[WARN]${NC} $1"
+}
+
+# Check if we're on the right server
+print_status "Checking server..."
+if [ "$(hostname)" != "ns3" ] && [ "$(hostname)" != "aitbc" ]; then
+    print_warning "This script should be run on ns3 server"
+    echo "Please run: ssh ns3-root"
+    echo "Then: cd /opt && ./deploy-blockchain-remote.sh"
+    exit 1
+fi
+
+# Install dependencies if needed
+print_status "Installing dependencies..."
+apt-get update
+apt-get install -y python3 python3-venv python3-pip git curl
+
+# Create directory
+print_status "Creating blockchain node directory..."
+mkdir -p /opt/blockchain-node
+cd /opt/blockchain-node
+
+# Check if source code exists
+if [ ! -d "src" ]; then
+    print_status "Source code not found in /opt/blockchain-node, copying from /opt/blockchain-node-src..."
+    if [ -d "/opt/blockchain-node-src" ]; then
+        cp -r /opt/blockchain-node-src/* .
+    else
+        print_warning "Source code not found. Please ensure it was copied properly."
+        exit 1
+    fi
+fi
+
+# Setup Python environment
+print_status "Setting up Python environment..."
+python3 -m venv .venv
+source .venv/bin/activate
+pip install --upgrade pip
+pip install -e .
+
+# Create configuration with auto-sync
+print_status "Creating configuration..."
+cat > .env << EOL
+CHAIN_ID=ait-devnet
+DB_PATH=./data/chain.db
+RPC_BIND_HOST=0.0.0.0
+RPC_BIND_PORT=8082
+P2P_BIND_HOST=0.0.0.0
+P2P_BIND_PORT=7070
+PROPOSER_KEY=proposer_key_$(date +%s)
+MINT_PER_UNIT=1000
+COORDINATOR_RATIO=0.05
+GOSSIP_BACKEND=memory
+EOL
+
+# Create fresh data directory
+print_status "Creating fresh data directory..."
+rm -rf data
+mkdir -p data/devnet
+
+# Generate fresh genesis
+print_status "Generating fresh genesis block..."
+export PYTHONPATH="${PWD}/src:${PWD}/scripts:${PYTHONPATH:-}"
+python scripts/make_genesis.py --output data/devnet/genesis.json --force
+
+# Create systemd service for blockchain node
+print_status "Creating systemd services..."
+cat > /etc/systemd/system/blockchain-node.service << EOL
+[Unit]
+Description=AITBC Blockchain Node
+After=network.target
+
+[Service]
+Type=exec
+User=root
+WorkingDirectory=/opt/blockchain-node
+Environment=PATH=/opt/blockchain-node/.venv/bin:/usr/local/bin:/usr/bin:/bin
+Environment=PYTHONPATH=/opt/blockchain-node/src:/opt/blockchain-node/scripts
+ExecStart=/opt/blockchain-node/.venv/bin/python3 -m aitbc_chain.main
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+EOL
+
+cat > /etc/systemd/system/blockchain-rpc.service << EOL
+[Unit]
+Description=AITBC Blockchain RPC API
+After=blockchain-node.service
+
+[Service]
+Type=exec
+User=root
+WorkingDirectory=/opt/blockchain-node
+Environment=PATH=/opt/blockchain-node/.venv/bin:/usr/local/bin:/usr/bin:/bin
+Environment=PYTHONPATH=/opt/blockchain-node/src:/opt/blockchain-node/scripts
+ExecStart=/opt/blockchain-node/.venv/bin/python3 -m uvicorn aitbc_chain.app:app --host 0.0.0.0 --port 8082
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+EOL
+
+# Enable and start services
+print_status "Starting blockchain node..."
+systemctl daemon-reload
+systemctl enable blockchain-node blockchain-rpc
+systemctl start blockchain-node blockchain-rpc
+
+# Wait for services to start
+print_status "Waiting for services to start..."
+sleep 5
+
+# Check status
+print_status "Checking service status..."
+systemctl status blockchain-node blockchain-rpc --no-pager | head -15
+
+# Setup port forwarding if in container
+if [ "$(hostname)" = "aitbc" ]; then
+    print_status "Setting up port forwarding..."
+    iptables -t nat -A PREROUTING -p tcp --dport 8082 -j DNAT --to-destination 192.168.100.10:8082
+    iptables -t nat -A POSTROUTING -p tcp -d 192.168.100.10 --dport 8082 -j MASQUERADE
+    iptables-save > /etc/iptables/rules.v4
+fi
+
+print_success "✅ Blockchain node deployed!"
+echo ""
+if [ "$(hostname)" = "aitbc" ]; then
+    echo "Node RPC: http://192.168.100.10:8082"
+    echo "External RPC: http://aitbc.keisanki.net:8082"
+else
+    echo "Node RPC: http://95.216.198.140:8082"
+    echo "External RPC: http://aitbc.keisanki.net:8082"
+fi
+echo ""
+echo "The node will automatically sync on startup."

scripts/deploy/deploy-blockchain.sh

@@ -0,0 +1,139 @@
+#!/bin/bash
+
+# Deploy blockchain node and explorer to incus container
+
+set -e
+
+echo "🚀 Deploying Blockchain Node and Explorer"
+echo "========================================"
+
+# Colors
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+print_status() {
+    echo -e "${GREEN}[INFO]${NC} $1"
+}
+
+print_warning() {
+    echo -e "${YELLOW}[WARN]${NC} $1"
+}
+
+# Copy blockchain node to container
+print_status "Copying blockchain node to container..."
+ssh ns3-root "rm -rf /opt/blockchain-node 2>/dev/null || true"
+scp -r apps/blockchain-node ns3-root:/opt/
+
+# Setup blockchain node in container
+print_status "Setting up blockchain node..."
+ssh ns3-root << 'EOF'
+cd /opt/blockchain-node
+
+# Create configuration
+cat > .env << EOL
+CHAIN_ID=ait-devnet
+DB_PATH=./data/chain.db
+RPC_BIND_HOST=0.0.0.0
+RPC_BIND_PORT=8082
+P2P_BIND_HOST=0.0.0.0
+P2P_BIND_PORT=7070
+PROPOSER_KEY=proposer_key_$(date +%s)
+MINT_PER_UNIT=1000
+COORDINATOR_RATIO=0.05
+GOSSIP_BACKEND=memory
+EOL
+
+# Create data directory
+mkdir -p data/devnet
+
+# Setup Python environment
+python3 -m venv .venv
+source .venv/bin/activate
+pip install --upgrade pip
+pip install -e .
+
+# Generate genesis
+export PYTHONPATH="${PWD}/src:${PWD}/scripts:${PYTHONPATH:-}"
+python scripts/make_genesis.py --output data/devnet/genesis.json --force
+EOF
+
+# Create systemd service for blockchain node
+print_status "Creating systemd service for blockchain node..."
+ssh ns3-root << 'EOF'
+cat > /etc/systemd/system/blockchain-node.service << EOL
+[Unit]
+Description=AITBC Blockchain Node
+After=network.target
+
+[Service]
+Type=exec
+User=root
+WorkingDirectory=/opt/blockchain-node
+Environment=PATH=/opt/blockchain-node/.venv/bin:/usr/local/bin:/usr/bin:/bin
+Environment=PYTHONPATH=/opt/blockchain-node/src:/opt/blockchain-node/scripts
+ExecStart=/opt/blockchain-node/.venv/bin/python3 -m aitbc_chain.main
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+EOL
+
+cat > /etc/systemd/system/blockchain-rpc.service << EOL
+[Unit]
+Description=AITBC Blockchain RPC API
+After=blockchain-node.service
+
+[Service]
+Type=exec
+User=root
+WorkingDirectory=/opt/blockchain-node
+Environment=PATH=/opt/blockchain-node/.venv/bin:/usr/local/bin:/usr/bin:/bin
+Environment=PYTHONPATH=/opt/blockchain-node/src:/opt/blockchain-node/scripts
+ExecStart=/opt/blockchain-node/.venv/bin/python3 -m uvicorn aitbc_chain.app:app --host 0.0.0.0 --port 8082
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+EOL
+
+systemctl daemon-reload
+systemctl enable blockchain-node blockchain-rpc
+EOF
+
+# Start blockchain node
+print_status "Starting blockchain node..."
+ssh ns3-root "systemctl start blockchain-node blockchain-rpc"
+
+# Wait for node to start
+print_status "Waiting for blockchain node to start..."
+sleep 5
+
+# Check status
+print_status "Checking blockchain node status..."
+ssh ns3-root "systemctl status blockchain-node blockchain-rpc --no-pager | grep -E 'Active:|Main PID:'"
+
+# Setup port forwarding
+print_status "Setting up port forwarding..."
+ssh ns3-root << 'EOF'
+# Clear existing rules
+iptables -t nat -F PREROUTING 2>/dev/null || true
+iptables -t nat -F POSTROUTING 2>/dev/null || true
+
+# Add port forwarding for blockchain RPC
+iptables -t nat -A PREROUTING -p tcp --dport 8082 -j DNAT --to-destination 192.168.100.10:8082
+iptables -t nat -A POSTROUTING -p tcp -d 192.168.100.10 --dport 8082 -j MASQUERADE
+
+# Save rules
+mkdir -p /etc/iptables
+iptables-save > /etc/iptables/rules.v4
+EOF
+
+print_success "✅ Blockchain node deployed!"
+echo ""
+echo "Node RPC: http://192.168.100.10:8082"
+echo "External RPC: http://aitbc.keisanki.net:8082"
+echo ""
+echo "Next: Deploying blockchain explorer..."

scripts/deploy/deploy-direct.sh

@@ -0,0 +1,316 @@
+#!/bin/bash
+
+# Deploy blockchain node and explorer directly on ns3
+
+set -e
+
+echo "🚀 AITBC Direct Deployment on ns3"
+echo "================================="
+
+# Colors
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+print_status() {
+    echo -e "${GREEN}[INFO]${NC} $1"
+}
+
+print_warning() {
+    echo -e "${YELLOW}[WARN]${NC} $1"
+}
+
+# Check if we're on ns3
+if [ "$(hostname)" != "ns3" ] && [ "$(hostname)" != "aitbc" ]; then
+    print_warning "This script must be run on ns3 server"
+    echo "Run: ssh ns3-root"
+    echo "Then: cd /opt && ./deploy-direct.sh"
+    exit 1
+fi
+
+# Stop existing services
+print_status "Stopping existing services..."
+systemctl stop blockchain-node blockchain-rpc blockchain-explorer nginx 2>/dev/null || true
+
+# Install dependencies
+print_status "Installing dependencies..."
+apt-get update
+apt-get install -y python3 python3-venv python3-pip git curl nginx
+
+# Deploy blockchain node
+print_status "Deploying blockchain node..."
+cd /opt
+rm -rf blockchain-node
+cp -r blockchain-node-src blockchain-node
+cd blockchain-node
+
+# Create configuration
+print_status "Creating configuration..."
+cat > .env << EOL
+CHAIN_ID=ait-devnet
+DB_PATH=./data/chain.db
+RPC_BIND_HOST=0.0.0.0
+RPC_BIND_PORT=8082
+P2P_BIND_HOST=0.0.0.0
+P2P_BIND_PORT=7070
+PROPOSER_KEY=proposer_key_$(date +%s)
+MINT_PER_UNIT=1000
+COORDINATOR_RATIO=0.05
+GOSSIP_BACKEND=memory
+EOL
+
+# Create fresh data directory
+rm -rf data
+mkdir -p data/devnet
+
+# Setup Python environment
+python3 -m venv .venv
+source .venv/bin/activate
+pip install --upgrade pip
+pip install -e .
+
+# Generate genesis
+export PYTHONPATH="${PWD}/src:${PWD}/scripts:${PYTHONPATH:-}"
+python scripts/make_genesis.py --output data/devnet/genesis.json --force
+
+# Create systemd services
+print_status "Creating systemd services..."
+cat > /etc/systemd/system/blockchain-node.service << EOL
+[Unit]
+Description=AITBC Blockchain Node
+After=network.target
+
+[Service]
+Type=exec
+User=root
+WorkingDirectory=/opt/blockchain-node
+Environment=PATH=/opt/blockchain-node/.venv/bin:/usr/local/bin:/usr/bin:/bin
+Environment=PYTHONPATH=/opt/blockchain-node/src:/opt/blockchain-node/scripts
+ExecStart=/opt/blockchain-node/.venv/bin/python3 -m aitbc_chain.main
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+EOL
+
+cat > /etc/systemd/system/blockchain-rpc.service << EOL
+[Unit]
+Description=AITBC Blockchain RPC API
+After=blockchain-node.service
+
+[Service]
+Type=exec
+User=root
+WorkingDirectory=/opt/blockchain-node
+Environment=PATH=/opt/blockchain-node/.venv/bin:/usr/local/bin:/usr/bin:/bin
+Environment=PYTHONPATH=/opt/blockchain-node/src:/opt/blockchain-node/scripts
+ExecStart=/opt/blockchain-node/.venv/bin/python3 -m uvicorn aitbc_chain.app:app --host 0.0.0.0 --port 8082
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+EOL
+
+# Start blockchain services
+print_status "Starting blockchain services..."
+systemctl daemon-reload
+systemctl enable blockchain-node blockchain-rpc
+systemctl start blockchain-node blockchain-rpc
+
+# Deploy explorer
+print_status "Deploying blockchain explorer..."
+cd /opt
+rm -rf blockchain-explorer
+mkdir -p blockchain-explorer
+cd blockchain-explorer
+
+# Create HTML explorer
+cat > index.html << 'EOF'
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>AITBC Blockchain Explorer</title>
+    <script src="https://cdn.tailwindcss.com"></script>
+    <script src="https://unpkg.com/lucide@latest"></script>
+</head>
+<body class="bg-gray-50">
+    <header class="bg-blue-600 text-white shadow-lg">
+        <div class="container mx-auto px-4 py-4">
+            <div class="flex items-center justify-between">
+                <div class="flex items-center space-x-3">
+                    <i data-lucide="cube" class="w-8 h-8"></i>
+                    <h1 class="text-2xl font-bold">AITBC Blockchain Explorer</h1>
+                </div>
+                <button onclick="refreshData()" class="bg-blue-500 hover:bg-blue-400 px-3 py-1 rounded flex items-center space-x-1">
+                    <i data-lucide="refresh-cw" class="w-4 h-4"></i>
+                    <span>Refresh</span>
+                </button>
+            </div>
+        </div>
+    </header>
+
+    <main class="container mx-auto px-4 py-8">
+        <div class="grid grid-cols-1 md:grid-cols-3 gap-6 mb-8">
+            <div class="bg-white rounded-lg shadow p-6">
+                <div class="flex items-center justify-between">
+                    <div>
+                        <p class="text-gray-500 text-sm">Current Height</p>
+                        <p class="text-2xl font-bold" id="chain-height">-</p>
+                    </div>
+                    <i data-lucide="trending-up" class="w-10 h-10 text-green-500"></i>
+                </div>
+            </div>
+            <div class="bg-white rounded-lg shadow p-6">
+                <div class="flex items-center justify-between">
+                    <div>
+                        <p class="text-gray-500 text-sm">Latest Block</p>
+                        <p class="text-lg font-mono" id="latest-hash">-</p>
+                    </div>
+                    <i data-lucide="hash" class="w-10 h-10 text-blue-500"></i>
+                </div>
+            </div>
+            <div class="bg-white rounded-lg shadow p-6">
+                <div class="flex items-center justify-between">
+                    <div>
+                        <p class="text-gray-500 text-sm">Node Status</p>
+                        <p class="text-lg font-semibold" id="node-status">-</p>
+                    </div>
+                    <i data-lucide="activity" class="w-10 h-10 text-purple-500"></i>
+                </div>
+            </div>
+        </div>
+
+        <div class="bg-white rounded-lg shadow">
+            <div class="px-6 py-4 border-b">
+                <h2 class="text-xl font-semibold flex items-center">
+                    <i data-lucide="blocks" class="w-5 h-5 mr-2"></i>
+                    Latest Blocks
+                </h2>
+            </div>
+            <div class="p-6">
+                <table class="w-full">
+                    <thead>
+                        <tr class="text-left text-gray-500 text-sm">
+                            <th class="pb-3">Height</th>
+                            <th class="pb-3">Hash</th>
+                            <th class="pb-3">Timestamp</th>
+                            <th class="pb-3">Transactions</th>
+                        </tr>
+                    </thead>
+                    <tbody id="blocks-table">
+                        <tr>
+                            <td colspan="4" class="text-center py-8 text-gray-500">
+                                Loading blocks...
+                            </td>
+                        </tr>
+                    </tbody>
+                </table>
+            </div>
+        </div>
+    </main>
+
+    <script>
+        lucide.createIcons();
+        
+        const RPC_URL = 'http://localhost:8082';
+        
+        async function refreshData() {
+            try {
+                const response = await fetch(`${RPC_URL}/rpc/head`);
+                const head = await response.json();
+                
+                document.getElementById('chain-height').textContent = head.height || '-';
+                document.getElementById('latest-hash').textContent = head.hash ? head.hash.substring(0, 16) + '...' : '-';
+                document.getElementById('node-status').innerHTML = '<span class="text-green-500">Online</span>';
+                
+                // Load last 10 blocks
+                const tbody = document.getElementById('blocks-table');
+                tbody.innerHTML = '';
+                
+                for (let i = 0; i < 10 && head.height - i >= 0; i++) {
+                    const blockResponse = await fetch(`${RPC_URL}/rpc/blocks/${head.height - i}`);
+                    const block = await blockResponse.json();
+                    
+                    const row = tbody.insertRow();
+                    row.innerHTML = `
+                        <td class="py-3 font-mono">${block.height}</td>
+                        <td class="py-3 font-mono text-sm">${block.hash ? block.hash.substring(0, 16) + '...' : '-'}</td>
+                        <td class="py-3 text-sm">${new Date(block.timestamp * 1000).toLocaleString()}</td>
+                        <td class="py-3">${block.transactions ? block.transactions.length : 0}</td>
+                    `;
+                }
+            } catch (error) {
+                console.error('Error:', error);
+                document.getElementById('node-status').innerHTML = '<span class="text-red-500">Error</span>';
+            }
+        }
+        
+        refreshData();
+        setInterval(refreshData, 30000);
+    </script>
+</body>
+</html>
+EOF
+
+# Configure nginx
+print_status "Configuring nginx..."
+cat > /etc/nginx/sites-available/blockchain-explorer << EOL
+server {
+    listen 3000;
+    server_name _;
+    root /opt/blockchain-explorer;
+    index index.html;
+    
+    location / {
+        try_files \$uri \$uri/ =404;
+    }
+}
+EOL
+
+ln -sf /etc/nginx/sites-available/blockchain-explorer /etc/nginx/sites-enabled/
+rm -f /etc/nginx/sites-enabled/default
+nginx -t
+systemctl reload nginx
+
+# Setup port forwarding if in container
+if [ "$(hostname)" = "aitbc" ]; then
+    print_status "Setting up port forwarding..."
+    iptables -t nat -F PREROUTING 2>/dev/null || true
+    iptables -t nat -F POSTROUTING 2>/dev/null || true
+    iptables -t nat -A PREROUTING -p tcp --dport 8082 -j DNAT --to-destination 192.168.100.10:8082
+    iptables -t nat -A POSTROUTING -p tcp -d 192.168.100.10 --dport 8082 -j MASQUERADE
+    iptables -t nat -A PREROUTING -p tcp --dport 3000 -j DNAT --to-destination 192.168.100.10:3000
+    iptables -t nat -A POSTROUTING -p tcp -d 192.168.100.10 --dport 3000 -j MASQUERADE
+    iptables-save > /etc/iptables/rules.v4
+fi
+
+# Wait for services to start
+print_status "Waiting for services to start..."
+sleep 5
+
+# Check services
+print_status "Checking service status..."
+systemctl status blockchain-node blockchain-rpc nginx --no-pager | grep -E 'Active:|Main PID:'
+
+print_success "✅ Deployment complete!"
+echo ""
+echo "Services:"
+if [ "$(hostname)" = "aitbc" ]; then
+    echo "  - Blockchain Node RPC: http://192.168.100.10:8082"
+    echo "  - Blockchain Explorer: http://192.168.100.10:3000"
+    echo ""
+    echo "External access:"
+    echo "  - Blockchain Node RPC: http://aitbc.keisanki.net:8082"
+    echo "  - Blockchain Explorer: http://aitbc.keisanki.net:3000"
+else
+    echo "  - Blockchain Node RPC: http://localhost:8082"
+    echo "  - Blockchain Explorer: http://localhost:3000"
+    echo ""
+    echo "External access:"
+    echo "  - Blockchain Node RPC: http://aitbc.keisanki.net:8082"
+    echo "  - Blockchain Explorer: http://aitbc.keisanki.net:3000"
+fi

scripts/deploy/deploy-explorer-remote.sh

@@ -0,0 +1,396 @@
+#!/bin/bash
+
+# Deploy blockchain explorer directly on ns3 server
+
+set -e
+
+echo "🔍 Deploying Blockchain Explorer on ns3"
+echo "======================================"
+
+# Colors
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+print_status() {
+    echo -e "${GREEN}[INFO]${NC} $1"
+}
+
+print_warning() {
+    echo -e "${YELLOW}[WARN]${NC} $1"
+}
+
+# Check if we're on the right server
+if [ "$(hostname)" != "ns3" ] && [ "$(hostname)" != "aitbc" ]; then
+    print_warning "This script should be run on ns3 server"
+    exit 1
+fi
+
+# Create directory
+print_status "Creating blockchain explorer directory..."
+mkdir -p /opt/blockchain-explorer
+cd /opt/blockchain-explorer
+
+# Create a simple HTML-based explorer (no build needed)
+print_status "Creating web-based explorer..."
+cat > index.html << 'EOF'
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>AITBC Blockchain Explorer</title>
+    <script src="https://cdn.tailwindcss.com"></script>
+    <script src="https://unpkg.com/lucide@latest"></script>
+    <style>
+        .fade-in { animation: fadeIn 0.3s ease-in; }
+        @keyframes fadeIn { from { opacity: 0; } to { opacity: 1; } }
+    </style>
+</head>
+<body class="bg-gray-50">
+    <header class="bg-blue-600 text-white shadow-lg">
+        <div class="container mx-auto px-4 py-4">
+            <div class="flex items-center justify-between">
+                <div class="flex items-center space-x-3">
+                    <i data-lucide="cube" class="w-8 h-8"></i>
+                    <h1 class="text-2xl font-bold">AITBC Blockchain Explorer</h1>
+                </div>
+                <div class="flex items-center space-x-4">
+                    <span class="text-sm">Network: <span class="font-mono bg-blue-700 px-2 py-1 rounded">ait-devnet</span></span>
+                    <button onclick="refreshData()" class="bg-blue-500 hover:bg-blue-400 px-3 py-1 rounded flex items-center space-x-1">
+                        <i data-lucide="refresh-cw" class="w-4 h-4"></i>
+                        <span>Refresh</span>
+                    </button>
+                </div>
+            </div>
+        </div>
+    </header>
+
+    <main class="container mx-auto px-4 py-8">
+        <!-- Chain Stats -->
+        <div class="grid grid-cols-1 md:grid-cols-3 gap-6 mb-8">
+            <div class="bg-white rounded-lg shadow p-6">
+                <div class="flex items-center justify-between">
+                    <div>
+                        <p class="text-gray-500 text-sm">Current Height</p>
+                        <p class="text-2xl font-bold" id="chain-height">-</p>
+                    </div>
+                    <i data-lucide="trending-up" class="w-10 h-10 text-green-500"></i>
+                </div>
+            </div>
+            <div class="bg-white rounded-lg shadow p-6">
+                <div class="flex items-center justify-between">
+                    <div>
+                        <p class="text-gray-500 text-sm">Latest Block</p>
+                        <p class="text-lg font-mono" id="latest-hash">-</p>
+                    </div>
+                    <i data-lucide="hash" class="w-10 h-10 text-blue-500"></i>
+                </div>
+            </div>
+            <div class="bg-white rounded-lg shadow p-6">
+                <div class="flex items-center justify-between">
+                    <div>
+                        <p class="text-gray-500 text-sm">Node Status</p>
+                        <p class="text-lg font-semibold" id="node-status">-</p>
+                    </div>
+                    <i data-lucide="activity" class="w-10 h-10 text-purple-500"></i>
+                </div>
+            </div>
+        </div>
+
+        <!-- Search -->
+        <div class="bg-white rounded-lg shadow p-6 mb-8">
+            <div class="flex space-x-4">
+                <input type="text" id="search-input" placeholder="Search by block height, hash, or transaction hash" 
+                       class="flex-1 px-4 py-2 border rounded-lg focus:outline-none focus:ring-2 focus:ring-blue-500">
+                <button onclick="search()" class="bg-blue-600 text-white px-6 py-2 rounded-lg hover:bg-blue-700">
+                    Search
+                </button>
+            </div>
+        </div>
+
+        <!-- Latest Blocks -->
+        <div class="bg-white rounded-lg shadow">
+            <div class="px-6 py-4 border-b">
+                <h2 class="text-xl font-semibold flex items-center">
+                    <i data-lucide="blocks" class="w-5 h-5 mr-2"></i>
+                    Latest Blocks
+                </h2>
+            </div>
+            <div class="p-6">
+                <div class="overflow-x-auto">
+                    <table class="w-full">
+                        <thead>
+                            <tr class="text-left text-gray-500 text-sm">
+                                <th class="pb-3">Height</th>
+                                <th class="pb-3">Hash</th>
+                                <th class="pb-3">Timestamp</th>
+                                <th class="pb-3">Transactions</th>
+                                <th class="pb-3">Actions</th>
+                            </tr>
+                        </thead>
+                        <tbody id="blocks-table">
+                            <tr>
+                                <td colspan="5" class="text-center py-8 text-gray-500">
+                                    Loading blocks...
+                                </td>
+                            </tr>
+                        </tbody>
+                    </table>
+                </div>
+            </div>
+        </div>
+
+        <!-- Block Details Modal -->
+        <div id="block-modal" class="fixed inset-0 bg-black bg-opacity-50 hidden z-50">
+            <div class="flex items-center justify-center min-h-screen p-4">
+                <div class="bg-white rounded-lg max-w-4xl w-full max-h-[90vh] overflow-y-auto">
+                    <div class="p-6 border-b">
+                        <div class="flex justify-between items-center">
+                            <h2 class="text-2xl font-bold">Block Details</h2>
+                            <button onclick="closeModal()" class="text-gray-500 hover:text-gray-700">
+                                <i data-lucide="x" class="w-6 h-6"></i>
+                            </button>
+                        </div>
+                    </div>
+                    <div class="p-6" id="block-details">
+                        <!-- Block details will be loaded here -->
+                    </div>
+                </div>
+            </div>
+        </div>
+    </main>
+
+    <footer class="bg-gray-800 text-white mt-12">
+        <div class="container mx-auto px-4 py-6 text-center">
+            <p class="text-sm">AITBC Blockchain Explorer - Connected to node at http://localhost:8082</p>
+        </div>
+    </footer>
+
+    <script>
+        // Initialize lucide icons
+        lucide.createIcons();
+
+        // RPC URL - change based on environment
+        const RPC_URL = window.location.hostname === 'localhost' ? 
+            'http://localhost:8082' : 
+            'http://95.216.198.140:8082';
+
+        // Global state
+        let currentData = {};
+
+        // Load initial data
+        document.addEventListener('DOMContentLoaded', () => {
+            refreshData();
+        });
+
+        // Refresh all data
+        async function refreshData() {
+            try {
+                await Promise.all([
+                    loadChainStats(),
+                    loadLatestBlocks()
+                ]);
+            } catch (error) {
+                console.error('Error refreshing data:', error);
+                document.getElementById('node-status').innerHTML = '<span class="text-red-500">Error</span>';
+            }
+        }
+
+        // Load chain statistics
+        async function loadChainStats() {
+            const response = await fetch(`${RPC_URL}/rpc/head`);
+            const data = await response.json();
+            
+            document.getElementById('chain-height').textContent = data.height || '-';
+            document.getElementById('latest-hash').textContent = data.hash ? data.hash.substring(0, 16) + '...' : '-';
+            document.getElementById('node-status').innerHTML = '<span class="text-green-500">Online</span>';
+            
+            currentData.head = data;
+        }
+
+        // Load latest blocks
+        async function loadLatestBlocks() {
+            const tbody = document.getElementById('blocks-table');
+            tbody.innerHTML = '<tr><td colspan="5" class="text-center py-8 text-gray-500">Loading blocks...</td></tr>';
+            
+            const head = await fetch(`${RPC_URL}/rpc/head`).then(r => r.json());
+            const blocks = [];
+            
+            // Load last 10 blocks
+            for (let i = 0; i < 10 && head.height - i >= 0; i++) {
+                const block = await fetch(`${RPC_URL}/rpc/blocks/${head.height - i}`).then(r => r.json());
+                blocks.push(block);
+            }
+            
+            tbody.innerHTML = blocks.map(block => `
+                <tr class="border-t hover:bg-gray-50">
+                    <td class="py-3 font-mono">${block.height}</td>
+                    <td class="py-3 font-mono text-sm">${block.hash ? block.hash.substring(0, 16) + '...' : '-'}</td>
+                    <td class="py-3 text-sm">${formatTimestamp(block.timestamp)}</td>
+                    <td class="py-3">${block.transactions ? block.transactions.length : 0}</td>
+                    <td class="py-3">
+                        <button onclick="showBlockDetails(${block.height})" class="text-blue-600 hover:text-blue-800">
+                            View Details
+                        </button>
+                    </td>
+                </tr>
+            `).join('');
+        }
+
+        // Show block details
+        async function showBlockDetails(height) {
+            const block = await fetch(`${RPC_URL}/rpc/blocks/${height}`).then(r => r.json());
+            const modal = document.getElementById('block-modal');
+            const details = document.getElementById('block-details');
+            
+            details.innerHTML = `
+                <div class="space-y-6">
+                    <div>
+                        <h3 class="text-lg font-semibold mb-2">Block Header</h3>
+                        <div class="bg-gray-50 rounded p-4 space-y-2">
+                            <div class="flex justify-between">
+                                <span class="text-gray-600">Height:</span>
+                                <span class="font-mono">${block.height}</span>
+                            </div>
+                            <div class="flex justify-between">
+                                <span class="text-gray-600">Hash:</span>
+                                <span class="font-mono text-sm">${block.hash || '-'}</span>
+                            </div>
+                            <div class="flex justify-between">
+                                <span class="text-gray-600">Parent Hash:</span>
+                                <span class="font-mono text-sm">${block.parent_hash || '-'}</span>
+                            </div>
+                            <div class="flex justify-between">
+                                <span class="text-gray-600">Timestamp:</span>
+                                <span>${formatTimestamp(block.timestamp)}</span>
+                            </div>
+                            <div class="flex justify-between">
+                                <span class="text-gray-600">Proposer:</span>
+                                <span class="font-mono text-sm">${block.proposer || '-'}</span>
+                            </div>
+                        </div>
+                    </div>
+                    
+                    ${block.transactions && block.transactions.length > 0 ? `
+                    <div>
+                        <h3 class="text-lg font-semibold mb-2">Transactions (${block.transactions.length})</h3>
+                        <div class="space-y-2">
+                            ${block.transactions.map(tx => `
+                                <div class="bg-gray-50 rounded p-4">
+                                    <div class="flex justify-between mb-2">
+                                        <span class="text-gray-600">Hash:</span>
+                                        <span class="font-mono text-sm">${tx.hash || '-'}</span>
+                                    </div>
+                                    <div class="flex justify-between mb-2">
+                                        <span class="text-gray-600">Type:</span>
+                                        <span>${tx.type || '-'}</span>
+                                    </div>
+                                    <div class="flex justify-between mb-2">
+                                        <span class="text-gray-600">From:</span>
+                                        <span class="font-mono text-sm">${tx.sender || '-'}</span>
+                                    </div>
+                                    <div class="flex justify-between">
+                                        <span class="text-gray-600">Fee:</span>
+                                        <span>${tx.fee || '0'}</span>
+                                    </div>
+                                </div>
+                            `).join('')}
+                        </div>
+                    </div>
+                    ` : '<p class="text-gray-500">No transactions in this block</p>'}
+                </div>
+            `;
+            
+            modal.classList.remove('hidden');
+        }
+
+        // Close modal
+        function closeModal() {
+            document.getElementById('block-modal').classList.add('hidden');
+        }
+
+        // Search functionality
+        async function search() {
+            const query = document.getElementById('search-input').value.trim();
+            if (!query) return;
+            
+            // Try block height first
+            if (/^\\d+$/.test(query)) {
+                showBlockDetails(parseInt(query));
+                return;
+            }
+            
+            // TODO: Add transaction hash search
+            alert('Search by block height is currently supported');
+        }
+
+        // Format timestamp
+        function formatTimestamp(timestamp) {
+            if (!timestamp) return '-';
+            return new Date(timestamp * 1000).toLocaleString();
+        }
+
+        // Auto-refresh every 30 seconds
+        setInterval(refreshData, 30000);
+    </script>
+</body>
+</html>
+EOF
+
+# Install a simple web server
+print_status "Installing web server..."
+apt-get install -y nginx
+
+# Configure nginx to serve the explorer
+print_status "Configuring nginx..."
+cat > /etc/nginx/sites-available/blockchain-explorer << EOL
+server {
+    listen 3000;
+    server_name _;
+    root /opt/blockchain-explorer;
+    index index.html;
+    
+    location / {
+        try_files \$uri \$uri/ =404;
+    }
+    
+    # CORS headers for API access
+    location /rpc/ {
+        proxy_pass http://localhost:8082;
+        proxy_set_header Host \$host;
+        proxy_set_header X-Real-IP \$remote_addr;
+        proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
+    }
+}
+EOL
+
+# Enable the site
+ln -sf /etc/nginx/sites-available/blockchain-explorer /etc/nginx/sites-enabled/
+rm -f /etc/nginx/sites-enabled/default
+
+# Test and reload nginx
+nginx -t
+systemctl reload nginx
+
+# Setup port forwarding if in container
+if [ "$(hostname)" = "aitbc" ]; then
+    print_status "Setting up port forwarding..."
+    iptables -t nat -A PREROUTING -p tcp --dport 3000 -j DNAT --to-destination 192.168.100.10:3000
+    iptables -t nat -A POSTROUTING -p tcp -d 192.168.100.10 --dport 3000 -j MASQUERADE
+    iptables-save > /etc/iptables/rules.v4
+fi
+
+print_status "Checking nginx status..."
+systemctl status nginx --no-pager | head -10
+
+print_success "✅ Blockchain explorer deployed!"
+echo ""
+echo "Explorer URL: http://localhost:3000"
+if [ "$(hostname)" = "aitbc" ]; then
+    echo "External URL: http://aitbc.keisanki.net:3000"
+else
+    echo "External URL: http://aitbc.keisanki.net:3000"
+fi
+echo ""
+echo "The explorer is a static HTML site served by nginx."

scripts/deploy/deploy-first-node.sh

@@ -0,0 +1,121 @@
+#!/bin/bash
+
+# Deploy the first blockchain node
+
+set -e
+
+echo "🚀 Deploying First Blockchain Node"
+echo "================================="
+
+# Colors
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+print_status() {
+    echo -e "${GREEN}[INFO]${NC} $1"
+}
+
+print_warning() {
+    echo -e "${YELLOW}[WARN]${NC} $1"
+}
+
+NODE1_DIR="/opt/blockchain-node"
+
+# Create configuration for first node
+print_status "Creating configuration for first node..."
+cat > $NODE1_DIR/.env << EOF
+CHAIN_ID=ait-devnet
+DB_PATH=./data/chain.db
+RPC_BIND_HOST=127.0.0.1
+RPC_BIND_PORT=8080
+P2P_BIND_HOST=0.0.0.0
+P2P_BIND_PORT=7070
+PROPOSER_KEY=node1_proposer_key_$(date +%s)
+MINT_PER_UNIT=1000
+COORDINATOR_RATIO=0.05
+GOSSIP_BACKEND=http
+GOSSIP_BROADCAST_URL=http://127.0.0.1:7071/gossip
+EOF
+
+# Create data directory
+mkdir -p $NODE1_DIR/data/devnet
+
+# Generate genesis file
+print_status "Generating genesis file..."
+cd $NODE1_DIR
+export PYTHONPATH="${NODE1_DIR}/src:${NODE1_DIR}/scripts:${PYTHONPATH:-}"
+python3 scripts/make_genesis.py --output data/devnet/genesis.json --force
+
+# Create systemd service
+print_status "Creating systemd service..."
+sudo cat > /etc/systemd/system/blockchain-node.service << EOF
+[Unit]
+Description=AITBC Blockchain Node 1
+After=network.target
+
+[Service]
+Type=exec
+User=root
+WorkingDirectory=$NODE1_DIR
+Environment=PATH=$NODE1_DIR/.venv/bin:/usr/local/bin:/usr/bin:/bin
+Environment=PYTHONPATH=$NODE1_DIR/src:$NODE1_DIR/scripts
+ExecStart=$NODE1_DIR/.venv/bin/python3 -m aitbc_chain.main
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+EOF
+
+# Create RPC API service
+print_status "Creating RPC API service..."
+sudo cat > /etc/systemd/system/blockchain-rpc.service << EOF
+[Unit]
+Description=AITBC Blockchain RPC API 1
+After=blockchain-node.service
+
+[Service]
+Type=exec
+User=root
+WorkingDirectory=$NODE1_DIR
+Environment=PATH=$NODE1_DIR/.venv/bin:/usr/local/bin:/usr/bin:/bin
+Environment=PYTHONPATH=$NODE1_DIR/src:$NODE1_DIR/scripts
+ExecStart=$NODE1_DIR/.venv/bin/python3 -m uvicorn aitbc_chain.app:app --host 0.0.0.0 --port 8080
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+EOF
+
+# Setup Python environment if not exists
+if [ ! -d "$NODE1_DIR/.venv" ]; then
+    print_status "Setting up Python environment..."
+    cd $NODE1_DIR
+    python3 -m venv .venv
+    source .venv/bin/activate
+    pip install --upgrade pip
+    pip install -e .
+fi
+
+# Enable and start services
+print_status "Enabling and starting services..."
+sudo systemctl daemon-reload
+sudo systemctl enable blockchain-node blockchain-rpc
+sudo systemctl start blockchain-node blockchain-rpc
+
+# Check status
+print_status "Checking service status..."
+sudo systemctl status blockchain-node --no-pager -l
+sudo systemctl status blockchain-rpc --no-pager -l
+
+echo ""
+print_status "✅ First blockchain node deployed!"
+echo ""
+echo "Node 1 RPC: http://127.0.0.1:8080"
+echo "Node 2 RPC: http://127.0.0.1:8081"
+echo ""
+echo "To check logs:"
+echo "  Node 1: sudo journalctl -u blockchain-node -f"
+echo "  Node 2: sudo journalctl -u blockchain-node-2 -f"

scripts/deploy/deploy-in-container.sh

@@ -0,0 +1,306 @@
+#!/bin/bash
+
+# Deploy blockchain node and explorer inside the container
+
+set -e
+
+echo "🚀 Deploying Inside Container"
+echo "============================"
+
+# Colors
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+print_status() {
+    echo -e "${GREEN}[INFO]${NC} $1"
+}
+
+print_warning() {
+    echo -e "${YELLOW}[WARN]${NC} $1"
+}
+
+# Check if we're in the container
+if [ ! -f /proc/1/environ ] || ! grep -q container=lxc /proc/1/environ 2>/dev/null; then
+    if [ "$(hostname)" != "aitbc" ]; then
+        print_warning "This script must be run inside the aitbc container"
+        exit 1
+    fi
+fi
+
+# Stop existing services
+print_status "Stopping existing services..."
+systemctl stop blockchain-node blockchain-rpc nginx 2>/dev/null || true
+
+# Install dependencies
+print_status "Installing dependencies..."
+apt-get update
+apt-get install -y python3 python3-venv python3-pip git curl nginx
+
+# Deploy blockchain node
+print_status "Deploying blockchain node..."
+cd /opt
+rm -rf blockchain-node
+# The source is already in blockchain-node-src, copy it properly
+cp -r blockchain-node-src blockchain-node
+cd blockchain-node
+
+# Check if pyproject.toml exists
+if [ ! -f pyproject.toml ]; then
+    print_warning "pyproject.toml not found, looking for it..."
+    find . -name "pyproject.toml" -type f
+    # If it's in a subdirectory, move everything up
+    if [ -f blockchain-node-src/pyproject.toml ]; then
+        print_status "Moving files from nested directory..."
+        mv blockchain-node-src/* .
+        rmdir blockchain-node-src
+    fi
+fi
+
+# Create configuration
+print_status "Creating configuration..."
+cat > .env << EOL
+CHAIN_ID=ait-devnet
+DB_PATH=./data/chain.db
+RPC_BIND_HOST=0.0.0.0
+RPC_BIND_PORT=8082
+P2P_BIND_HOST=0.0.0.0
+P2P_BIND_PORT=7070
+PROPOSER_KEY=proposer_key_$(date +%s)
+MINT_PER_UNIT=1000
+COORDINATOR_RATIO=0.05
+GOSSIP_BACKEND=memory
+EOL
+
+# Create fresh data directory
+rm -rf data
+mkdir -p data/devnet
+
+# Setup Python environment
+python3 -m venv .venv
+source .venv/bin/activate
+pip install --upgrade pip
+pip install -e .
+
+# Generate genesis
+export PYTHONPATH="${PWD}/src:${PWD}/scripts:${PYTHONPATH:-}"
+python scripts/make_genesis.py --output data/devnet/genesis.json --force
+
+# Create systemd services
+print_status "Creating systemd services..."
+cat > /etc/systemd/system/blockchain-node.service << EOL
+[Unit]
+Description=AITBC Blockchain Node
+After=network.target
+
+[Service]
+Type=exec
+User=root
+WorkingDirectory=/opt/blockchain-node
+Environment=PATH=/opt/blockchain-node/.venv/bin:/usr/local/bin:/usr/bin:/bin
+Environment=PYTHONPATH=/opt/blockchain-node/src:/opt/blockchain-node/scripts
+ExecStart=/opt/blockchain-node/.venv/bin/python3 -m aitbc_chain.main
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+EOL
+
+cat > /etc/systemd/system/blockchain-rpc.service << EOL
+[Unit]
+Description=AITBC Blockchain RPC API
+After=blockchain-node.service
+
+[Service]
+Type=exec
+User=root
+WorkingDirectory=/opt/blockchain-node
+Environment=PATH=/opt/blockchain-node/.venv/bin:/usr/local/bin:/usr/bin:/bin
+Environment=PYTHONPATH=/opt/blockchain-node/src:/opt/blockchain-node/scripts
+ExecStart=/opt/blockchain-node/.venv/bin/python3 -m uvicorn aitbc_chain.app:app --host 0.0.0.0 --port 8082
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+EOL
+
+# Start blockchain services
+print_status "Starting blockchain services..."
+systemctl daemon-reload
+systemctl enable blockchain-node blockchain-rpc
+systemctl start blockchain-node blockchain-rpc
+
+# Deploy explorer
+print_status "Deploying blockchain explorer..."
+cd /opt
+rm -rf blockchain-explorer
+mkdir -p blockchain-explorer
+cd blockchain-explorer
+
+# Create HTML explorer
+cat > index.html << 'EOF'
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>AITBC Blockchain Explorer</title>
+    <script src="https://cdn.tailwindcss.com"></script>
+    <script src="https://unpkg.com/lucide@latest"></script>
+</head>
+<body class="bg-gray-50">
+    <header class="bg-blue-600 text-white shadow-lg">
+        <div class="container mx-auto px-4 py-4">
+            <div class="flex items-center justify-between">
+                <div class="flex items-center space-x-3">
+                    <i data-lucide="cube" class="w-8 h-8"></i>
+                    <h1 class="text-2xl font-bold">AITBC Blockchain Explorer</h1>
+                </div>
+                <button onclick="refreshData()" class="bg-blue-500 hover:bg-blue-400 px-3 py-1 rounded flex items-center space-x-1">
+                    <i data-lucide="refresh-cw" class="w-4 h-4"></i>
+                    <span>Refresh</span>
+                </button>
+            </div>
+        </div>
+    </header>
+
+    <main class="container mx-auto px-4 py-8">
+        <div class="grid grid-cols-1 md:grid-cols-3 gap-6 mb-8">
+            <div class="bg-white rounded-lg shadow p-6">
+                <div class="flex items-center justify-between">
+                    <div>
+                        <p class="text-gray-500 text-sm">Current Height</p>
+                        <p class="text-2xl font-bold" id="chain-height">-</p>
+                    </div>
+                    <i data-lucide="trending-up" class="w-10 h-10 text-green-500"></i>
+                </div>
+            </div>
+            <div class="bg-white rounded-lg shadow p-6">
+                <div class="flex items-center justify-between">
+                    <div>
+                        <p class="text-gray-500 text-sm">Latest Block</p>
+                        <p class="text-lg font-mono" id="latest-hash">-</p>
+                    </div>
+                    <i data-lucide="hash" class="w-10 h-10 text-blue-500"></i>
+                </div>
+            </div>
+            <div class="bg-white rounded-lg shadow p-6">
+                <div class="flex items-center justify-between">
+                    <div>
+                        <p class="text-gray-500 text-sm">Node Status</p>
+                        <p class="text-lg font-semibold" id="node-status">-</p>
+                    </div>
+                    <i data-lucide="activity" class="w-10 h-10 text-purple-500"></i>
+                </div>
+            </div>
+        </div>
+
+        <div class="bg-white rounded-lg shadow">
+            <div class="px-6 py-4 border-b">
+                <h2 class="text-xl font-semibold flex items-center">
+                    <i data-lucide="blocks" class="w-5 h-5 mr-2"></i>
+                    Latest Blocks
+                </h2>
+            </div>
+            <div class="p-6">
+                <table class="w-full">
+                    <thead>
+                        <tr class="text-left text-gray-500 text-sm">
+                            <th class="pb-3">Height</th>
+                            <th class="pb-3">Hash</th>
+                            <th class="pb-3">Timestamp</th>
+                            <th class="pb-3">Transactions</th>
+                        </tr>
+                    </thead>
+                    <tbody id="blocks-table">
+                        <tr>
+                            <td colspan="4" class="text-center py-8 text-gray-500">
+                                Loading blocks...
+                            </td>
+                        </tr>
+                    </tbody>
+                </table>
+            </div>
+        </div>
+    </main>
+
+    <script>
+        lucide.createIcons();
+        
+        const RPC_URL = 'http://localhost:8082';
+        
+        async function refreshData() {
+            try {
+                const response = await fetch(`${RPC_URL}/rpc/head`);
+                const head = await response.json();
+                
+                document.getElementById('chain-height').textContent = head.height || '-';
+                document.getElementById('latest-hash').textContent = head.hash ? head.hash.substring(0, 16) + '...' : '-';
+                document.getElementById('node-status').innerHTML = '<span class="text-green-500">Online</span>';
+                
+                // Load last 10 blocks
+                const tbody = document.getElementById('blocks-table');
+                tbody.innerHTML = '';
+                
+                for (let i = 0; i < 10 && head.height - i >= 0; i++) {
+                    const blockResponse = await fetch(`${RPC_URL}/rpc/blocks/${head.height - i}`);
+                    const block = await blockResponse.json();
+                    
+                    const row = tbody.insertRow();
+                    row.innerHTML = `
+                        <td class="py-3 font-mono">${block.height}</td>
+                        <td class="py-3 font-mono text-sm">${block.hash ? block.hash.substring(0, 16) + '...' : '-'}</td>
+                        <td class="py-3 text-sm">${new Date(block.timestamp * 1000).toLocaleString()}</td>
+                        <td class="py-3">${block.transactions ? block.transactions.length : 0}</td>
+                    `;
+                }
+            } catch (error) {
+                console.error('Error:', error);
+                document.getElementById('node-status').innerHTML = '<span class="text-red-500">Error</span>';
+            }
+        }
+        
+        refreshData();
+        setInterval(refreshData, 30000);
+    </script>
+</body>
+</html>
+EOF
+
+# Configure nginx
+print_status "Configuring nginx..."
+cat > /etc/nginx/sites-available/blockchain-explorer << EOL
+server {
+    listen 3000;
+    server_name _;
+    root /opt/blockchain-explorer;
+    index index.html;
+    
+    location / {
+        try_files \$uri \$uri/ =404;
+    }
+}
+EOL
+
+ln -sf /etc/nginx/sites-available/blockchain-explorer /etc/nginx/sites-enabled/
+rm -f /etc/nginx/sites-enabled/default
+nginx -t
+systemctl reload nginx
+
+# Wait for services to start
+print_status "Waiting for services to start..."
+sleep 5
+
+# Check services
+print_status "Checking service status..."
+systemctl status blockchain-node blockchain-rpc nginx --no-pager | grep -E 'Active:|Main PID:'
+
+print_success "✅ Deployment complete in container!"
+echo ""
+echo "Services:"
+echo "  - Blockchain Node RPC: http://localhost:8082"
+echo "  - Blockchain Explorer: http://localhost:3000"
+echo ""
+echo "These are accessible from the host via port forwarding."

scripts/deploy/deploy-modern-explorer.sh

@@ -0,0 +1,56 @@
+#!/bin/bash
+
+# Deploy Modern Blockchain Explorer
+
+set -e
+
+echo "🚀 Deploying Modern Blockchain Explorer"
+echo "======================================"
+
+# Colors
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+print_status() {
+    echo -e "${GREEN}[INFO]${NC} $1"
+}
+
+print_warning() {
+    echo -e "${YELLOW}[WARN]${NC} $1"
+}
+
+# Stop existing services
+print_status "Stopping existing services..."
+systemctl stop nginx 2>/dev/null || true
+
+# Create directory
+print_status "Creating explorer directory..."
+rm -rf /opt/blockchain-explorer
+mkdir -p /opt/blockchain-explorer/assets
+
+# Copy files
+print_status "Copying explorer files..."
+cp -r /opt/blockchain-node-src/apps/blockchain-explorer/* /opt/blockchain-explorer/
+
+# Update nginx configuration
+print_status "Updating nginx configuration..."
+cp /opt/blockchain-explorer/nginx.conf /etc/nginx/sites-available/blockchain-explorer
+ln -sf /etc/nginx/sites-available/blockchain-explorer /etc/nginx/sites-enabled/
+rm -f /etc/nginx/sites-enabled/default
+
+# Test and start nginx
+print_status "Starting nginx..."
+nginx -t
+systemctl start nginx
+
+print_success "✅ Modern explorer deployed!"
+echo ""
+echo "Access URLs:"
+echo "  - Explorer: http://localhost:3000/"
+echo "  - API: http://localhost:3000/api/v1/"
+echo ""
+echo "Standardized API Endpoints:"
+echo "  - GET /api/v1/chain/head"
+echo "  - GET /api/v1/chain/blocks?limit=N"
+echo "  - GET /api/v1/chain/blocks/{height}"

scripts/deploy/deploy-nginx-reverse-proxy.sh

@@ -0,0 +1,160 @@
+#!/bin/bash
+
+# Deploy nginx reverse proxy for AITBC services
+# This replaces firehol/iptables port forwarding with nginx reverse proxy
+
+set -e
+
+echo "🚀 Deploying Nginx Reverse Proxy for AITBC"
+echo "=========================================="
+
+# Colors
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+RED='\033[0;31m'
+NC='\033[0m'
+
+print_status() {
+    echo -e "${GREEN}[INFO]${NC} $1"
+}
+
+print_warning() {
+    echo -e "${YELLOW}[WARN]${NC} $1"
+}
+
+print_error() {
+    echo -e "${RED}[ERROR]${NC} $1"
+}
+
+# Check if we're on the host server
+if ! grep -q "ns3-root" ~/.ssh/config 2>/dev/null; then
+    print_error "ns3-root SSH configuration not found. Please add it to ~/.ssh/config"
+    exit 1
+fi
+
+# Install nginx on host if not already installed
+print_status "Checking nginx installation on host..."
+ssh ns3-root "which nginx > /dev/null || (apt-get update && apt-get install -y nginx)"
+
+# Install certbot for SSL certificates
+print_status "Checking certbot installation..."
+ssh ns3-root "which certbot > /dev/null || (apt-get update && apt-get install -y certbot python3-certbot-nginx)"
+
+# Copy nginx configuration
+print_status "Copying nginx configuration..."
+scp infra/nginx/nginx-aitbc-reverse-proxy.conf ns3-root:/tmp/aitbc-reverse-proxy.conf
+
+# Backup existing nginx configuration
+print_status "Backing up existing nginx configuration..."
+ssh ns3-root "mkdir -p /etc/nginx/backup && cp -r /etc/nginx/sites-available/* /etc/nginx/backup/ 2>/dev/null || true"
+
+# Install the new configuration
+print_status "Installing nginx reverse proxy configuration..."
+ssh ns3-root << 'EOF'
+# Remove existing configurations
+rm -f /etc/nginx/sites-enabled/default
+rm -f /etc/nginx/sites-available/aitbc*
+
+# Copy new configuration
+cp /tmp/aitbc-reverse-proxy.conf /etc/nginx/sites-available/aitbc-reverse-proxy.conf
+
+# Create symbolic link
+ln -sf /etc/nginx/sites-available/aitbc-reverse-proxy.conf /etc/nginx/sites-enabled/
+
+# Test nginx configuration
+nginx -t
+EOF
+
+# Check if SSL certificate exists
+print_status "Checking SSL certificate..."
+if ! ssh ns3-root "test -f /etc/letsencrypt/live/aitbc.keisanki.net/fullchain.pem"; then
+    print_warning "SSL certificate not found. Obtaining Let's Encrypt certificate..."
+    
+    # Obtain SSL certificate
+    ssh ns3-root << 'EOF'
+# Stop nginx temporarily
+systemctl stop nginx 2>/dev/null || true
+
+# Obtain certificate
+certbot certonly --standalone -d aitbc.keisanki.net -d api.aitbc.keisanki.net -d rpc.aitbc.keisanki.net --email admin@keisanki.net --agree-tos --non-interactive
+
+# Start nginx
+systemctl start nginx
+EOF
+    
+    if [ $? -ne 0 ]; then
+        print_error "Failed to obtain SSL certificate. Please run certbot manually:"
+        echo "certbot certonly --standalone -d aitbc.keisanki.net -d api.aitbc.keisanki.net -d rpc.aitbc.keisanki.net"
+        exit 1
+    fi
+fi
+
+# Restart nginx
+print_status "Restarting nginx..."
+ssh ns3-root "systemctl restart nginx && systemctl enable nginx"
+
+# Remove old iptables rules (optional)
+print_warning "Removing old iptables port forwarding rules (if they exist)..."
+ssh ns3-root << 'EOF'
+# Flush existing NAT rules for AITBC ports
+iptables -t nat -D PREROUTING -p tcp --dport 8000 -j DNAT --to-destination 192.168.100.10:8000 2>/dev/null || true
+iptables -t nat -D POSTROUTING -p tcp -d 192.168.100.10 --dport 8000 -j MASQUERADE 2>/dev/null || true
+iptables -t nat -D PREROUTING -p tcp --dport 8081 -j DNAT --to-destination 192.168.100.10:8081 2>/dev/null || true
+iptables -t nat -D POSTROUTING -p tcp -d 192.168.100.10 --dport 8081 -j MASQUERADE 2>/dev/null || true
+iptables -t nat -D PREROUTING -p tcp --dport 8082 -j DNAT --to-destination 192.168.100.10:8082 2>/dev/null || true
+iptables -t nat -D POSTROUTING -p tcp -d 192.168.100.10 --dport 8082 -j MASQUERADE 2>/dev/null || true
+iptables -t nat -D PREROUTING -p tcp --dport 9080 -j DNAT --to-destination 192.168.100.10:9080 2>/dev/null || true
+iptables -t nat -D POSTROUTING -p tcp -d 192.168.100.10 --dport 9080 -j MASQUERADE 2>/dev/null || true
+iptables -t nat -D PREROUTING -p tcp --dport 3000 -j DNAT --to-destination 192.168.100.10:3000 2>/dev/null || true
+iptables -t nat -D POSTROUTING -p tcp -d 192.168.100.10 --dport 3000 -j MASQUERADE 2>/dev/null || true
+
+# Save iptables rules
+iptables-save > /etc/iptables/rules.v4 2>/dev/null || true
+EOF
+
+# Wait for nginx to start
+sleep 2
+
+# Test the configuration
+print_status "Testing reverse proxy configuration..."
+echo ""
+
+# Test main domain
+if curl -s -o /dev/null -w "%{http_code}" https://aitbc.keisanki.net/health | grep -q "200"; then
+    print_status "✅ Main domain (aitbc.keisanki.net) - OK"
+else
+    print_error "❌ Main domain (aitbc.keisanki.net) - FAILED"
+fi
+
+# Test API endpoint
+if curl -s -o /dev/null -w "%{http_code}" https://aitbc.keisanki.net/api/health | grep -q "200"; then
+    print_status "✅ API endpoint - OK"
+else
+    print_warning "⚠️  API endpoint - Not responding (service may not be running)"
+fi
+
+# Test RPC endpoint
+if curl -s -o /dev/null -w "%{http_code}" https://aitbc.keisanki.net/rpc/head | grep -q "200"; then
+    print_status "✅ RPC endpoint - OK"
+else
+    print_warning "⚠️  RPC endpoint - Not responding (blockchain node may not be running)"
+fi
+
+echo ""
+print_status "🎉 Nginx reverse proxy deployment complete!"
+echo ""
+echo "Service URLs:"
+echo "  • Blockchain Explorer: https://aitbc.keisanki.net"
+echo "  • API: https://aitbc.keisanki.net/api/"
+echo "  • RPC: https://aitbc.keisanki.net/rpc/"
+echo "  • Exchange: https://aitbc.keisanki.net/exchange/"
+echo ""
+echo "Alternative URLs:"
+echo "  • API-only: https://api.aitbc.keisanki.net"
+echo "  • RPC-only: https://rpc.aitbc.keisanki.net"
+echo ""
+echo "Note: Make sure all services are running in the container:"
+echo "  • blockchain-explorer.service (port 3000)"
+echo "  • coordinator-api.service (port 8000)"
+echo "  • blockchain-rpc.service (port 8082)"
+echo "  • aitbc-exchange.service (port 9080)"

scripts/deploy/deploy-remote-build.sh

@@ -0,0 +1,18 @@
+#!/bin/bash
+
+# Deploy blockchain node by building directly on ns3 server
+
+echo "🚀 Remote Blockchain Deployment (Build on Server)"
+echo "=============================================="
+
+# Copy deployment script to server
+echo "Copying deployment script to ns3..."
+scp scripts/deploy/deploy-blockchain-remote.sh ns3-root:/opt/
+
+# Execute deployment on server
+echo "Executing deployment on ns3 (utilizing gigabit connection)..."
+ssh ns3-root "cd /opt && chmod +x deploy-blockchain-remote.sh && ./deploy-blockchain-remote.sh"
+
+echo ""
+echo "Deployment complete!"
+echo "The blockchain node was built directly on ns3 using its fast connection."

scripts/deploy/deploy-second-node.sh

@@ -0,0 +1,127 @@
+#!/bin/bash
+
+# Deploy a second blockchain node on the same server
+
+set -e
+
+echo "🚀 Deploying Second Blockchain Node"
+echo "=================================="
+
+# Colors
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+print_status() {
+    echo -e "${GREEN}[INFO]${NC} $1"
+}
+
+print_warning() {
+    echo -e "${YELLOW}[WARN]${NC} $1"
+}
+
+# Create directory for second node
+print_status "Creating directory for second node..."
+NODE2_DIR="/opt/blockchain-node-2"
+sudo mkdir -p $NODE2_DIR
+sudo chown $USER:$USER $NODE2_DIR
+
+# Copy blockchain node code
+print_status "Copying blockchain node code..."
+cp -r /opt/blockchain-node/* $NODE2_DIR/
+
+# Create configuration for second node
+print_status "Creating configuration for second node..."
+cat > $NODE2_DIR/.env << EOF
+CHAIN_ID=ait-devnet
+DB_PATH=./data/chain2.db
+RPC_BIND_HOST=127.0.0.1
+RPC_BIND_PORT=8081
+P2P_BIND_HOST=0.0.0.0
+P2P_BIND_PORT=7071
+PROPOSER_KEY=node2_proposer_key_$(date +%s)
+MINT_PER_UNIT=1000
+COORDINATOR_RATIO=0.05
+GOSSIP_BACKEND=http
+GOSSIP_BROADCAST_URL=http://127.0.0.1:7070/gossip
+EOF
+
+# Create data directory
+mkdir -p $NODE2_DIR/data/devnet
+
+# Generate genesis file (same as first node)
+print_status "Generating genesis file..."
+cd $NODE2_DIR
+export PYTHONPATH="${NODE2_DIR}/src:${NODE2_DIR}/scripts:${PYTHONPATH:-}"
+python3 scripts/make_genesis.py --output data/devnet/genesis.json --force
+
+# Create systemd service
+print_status "Creating systemd service..."
+sudo cat > /etc/systemd/system/blockchain-node-2.service << EOF
+[Unit]
+Description=AITBC Blockchain Node 2
+After=network.target
+
+[Service]
+Type=exec
+User=root
+WorkingDirectory=$NODE2_DIR
+Environment=PATH=$NODE2_DIR/.venv/bin:/usr/local/bin:/usr/bin:/bin
+Environment=PYTHONPATH=$NODE2_DIR/src:$NODE2_DIR/scripts
+ExecStart=$NODE2_DIR/.venv/bin/python3 -m aitbc_chain.main
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+EOF
+
+# Create RPC API service
+print_status "Creating RPC API service..."
+sudo cat > /etc/systemd/system/blockchain-rpc-2.service << EOF
+[Unit]
+Description=AITBC Blockchain RPC API 2
+After=blockchain-node-2.service
+
+[Service]
+Type=exec
+User=root
+WorkingDirectory=$NODE2_DIR
+Environment=PATH=$NODE2_DIR/.venv/bin:/usr/local/bin:/usr/bin:/bin
+Environment=PYTHONPATH=$NODE2_DIR/src:$NODE2_DIR/scripts
+ExecStart=$NODE2_DIR/.venv/bin/python3 -m uvicorn aitbc_chain.app:app --host 0.0.0.0 --port 8081
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+EOF
+
+# Setup Python environment
+print_status "Setting up Python environment..."
+cd $NODE2_DIR
+python3 -m venv .venv
+source .venv/bin/activate
+pip install --upgrade pip
+pip install -e .
+
+# Enable and start services
+print_status "Enabling and starting services..."
+sudo systemctl daemon-reload
+sudo systemctl enable blockchain-node-2 blockchain-rpc-2
+sudo systemctl start blockchain-node-2 blockchain-rpc-2
+
+# Check status
+print_status "Checking service status..."
+sudo systemctl status blockchain-node-2 --no-pager -l
+sudo systemctl status blockchain-rpc-2 --no-pager -l
+
+echo ""
+print_status "✅ Second blockchain node deployed!"
+echo ""
+echo "Node 1 RPC: http://127.0.0.1:8080"
+echo "Node 2 RPC: http://127.0.0.1:8081"
+echo ""
+echo "To check logs:"
+echo "  Node 1: sudo journalctl -u blockchain-node -f"
+echo "  Node 2: sudo journalctl -u blockchain-node-2 -f"

scripts/deploy/deploy-to-aitbc-container.sh

@@ -0,0 +1,84 @@
+#!/bin/bash
+
+# Deploy blockchain node inside incus container aitbc
+
+set -e
+
+echo "🚀 AITBC Deployment in Incus Container"
+echo "======================================"
+echo "This will deploy inside the aitbc container"
+echo ""
+
+# Colors
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+print_status() {
+    echo -e "${GREEN}[INFO]${NC} $1"
+}
+
+print_warning() {
+    echo -e "${YELLOW}[WARN]${NC} $1"
+}
+
+# Check if we're on ns3 host
+if [ "$(hostname)" != "ns3" ]; then
+    print_warning "This script must be run on ns3 host"
+    echo "Run: ssh ns3-root"
+    exit 1
+fi
+
+# Check if container exists
+if ! incus list | grep -q "aitbc.*RUNNING"; then
+    print_warning "Container aitbc is not running"
+    exit 1
+fi
+
+# Copy source to container
+print_status "Copying source code to container..."
+incus exec aitbc -- rm -rf /opt/blockchain-node-src 2>/dev/null || true
+incus exec aitbc -- mkdir -p /opt/blockchain-node-src
+# Use the source already on the server
+incus file push -r /opt/blockchain-node-src/. aitbc/opt/blockchain-node-src/
+# Fix the nested directory issue - move everything up one level
+incus exec aitbc -- sh -c 'if [ -d /opt/blockchain-node-src/blockchain-node-src ]; then mv /opt/blockchain-node-src/blockchain-node-src/* /opt/blockchain-node-src/ && rmdir /opt/blockchain-node-src/blockchain-node-src; fi'
+
+# Copy deployment script to container
+print_status "Copying deployment script to container..."
+incus file push /opt/deploy-in-container.sh aitbc/opt/
+
+# Execute deployment inside container
+print_status "Deploying inside container..."
+incus exec aitbc -- bash /opt/deploy-in-container.sh
+
+# Setup port forwarding on host
+print_status "Setting up port forwarding on host..."
+iptables -t nat -F PREROUTING 2>/dev/null || true
+iptables -t nat -F POSTROUTING 2>/dev/null || true
+
+# Forward blockchain RPC
+iptables -t nat -A PREROUTING -p tcp --dport 8082 -j DNAT --to-destination 192.168.100.10:8082
+iptables -t nat -A POSTROUTING -p tcp -d 192.168.100.10 --dport 8082 -j MASQUERADE
+
+# Forward explorer
+iptables -t nat -A PREROUTING -p tcp --dport 3000 -j DNAT --to-destination 192.168.100.10:3000
+iptables -t nat -A POSTROUTING -p tcp -d 192.168.100.10 --dport 3000 -j MASQUERADE
+
+# Save rules
+mkdir -p /etc/iptables
+iptables-save > /etc/iptables/rules.v4
+
+# Check services
+print_status "Checking services in container..."
+incus exec aitbc -- systemctl status blockchain-node blockchain-rpc nginx --no-pager | grep -E 'Active:|Main PID:'
+
+print_success "✅ Deployment complete!"
+echo ""
+echo "Services in container aitbc:"
+echo "  - Blockchain Node RPC: http://192.168.100.10:8082"
+echo "  - Blockchain Explorer: http://192.168.100.10:3000"
+echo ""
+echo "External access via ns3:"
+echo "  - Blockchain Node RPC: http://aitbc.keisanki.net:8082"
+echo "  - Blockchain Explorer: http://aitbc.keisanki.net:3000"

scripts/deploy/setup-gossip-relay.sh

@@ -0,0 +1,113 @@
+#!/bin/bash
+
+# Setup gossip relay to connect blockchain nodes
+
+set -e
+
+echo "🌐 Setting up Gossip Relay for Blockchain Nodes"
+echo "=============================================="
+
+# Colors
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+print_status() {
+    echo -e "${GREEN}[INFO]${NC} $1"
+}
+
+print_warning() {
+    echo -e "${YELLOW}[WARN]${NC} $1"
+}
+
+# Stop existing nodes
+print_status "Stopping blockchain nodes..."
+sudo systemctl stop blockchain-node blockchain-node-2 blockchain-rpc blockchain-rpc-2 2>/dev/null || true
+
+# Update node configurations to use broadcast backend
+print_status "Updating Node 1 configuration..."
+sudo cat > /opt/blockchain-node/.env << EOF
+CHAIN_ID=ait-devnet
+DB_PATH=./data/chain.db
+RPC_BIND_HOST=127.0.0.1
+RPC_BIND_PORT=8082
+P2P_BIND_HOST=0.0.0.0
+P2P_BIND_PORT=7070
+PROPOSER_KEY=node1_proposer_key_$(date +%s)
+MINT_PER_UNIT=1000
+COORDINATOR_RATIO=0.05
+GOSSIP_BACKEND=broadcast
+GOSSIP_BROADCAST_URL=http://127.0.0.1:7070/gossip
+EOF
+
+print_status "Updating Node 2 configuration..."
+sudo cat > /opt/blockchain-node-2/.env << EOF
+CHAIN_ID=ait-devnet
+DB_PATH=./data/chain2.db
+RPC_BIND_HOST=127.0.0.1
+RPC_BIND_PORT=8081
+P2P_BIND_HOST=0.0.0.0
+P2P_BIND_PORT=7071
+PROPOSER_KEY=node2_proposer_key_$(date +%s)
+MINT_PER_UNIT=1000
+COORDINATOR_RATIO=0.05
+GOSSIP_BACKEND=broadcast
+GOSSIP_BROADCAST_URL=http://127.0.0.1:7070/gossip
+EOF
+
+# Create gossip relay service
+print_status "Creating gossip relay service..."
+sudo cat > /etc/systemd/system/blockchain-gossip-relay.service << EOF
+[Unit]
+Description=AITBC Blockchain Gossip Relay
+After=network.target
+
+[Service]
+Type=exec
+User=root
+WorkingDirectory=/opt/blockchain-node
+Environment=PATH=/opt/blockchain-node/.venv/bin:/usr/local/bin:/usr/bin:/bin
+Environment=PYTHONPATH=/opt/blockchain-node/src:/opt/blockchain-node/scripts
+ExecStart=/opt/blockchain-node/.venv/bin/python3 -m aitbc_chain.gossip.relay --port 7070 --host 0.0.0.0
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+EOF
+
+# Enable and start gossip relay
+print_status "Starting gossip relay..."
+sudo systemctl daemon-reload
+sudo systemctl enable blockchain-gossip-relay
+sudo systemctl start blockchain-gossip-relay
+
+# Wait for relay to start
+sleep 2
+
+# Check if relay is running
+print_status "Checking gossip relay status..."
+sudo systemctl status blockchain-gossip-relay --no-pager | head -10
+
+# Restart blockchain nodes
+print_status "Restarting blockchain nodes with shared gossip..."
+sudo systemctl start blockchain-node blockchain-node-2 blockchain-rpc blockchain-rpc-2
+
+# Wait for nodes to start
+sleep 3
+
+# Check status
+print_status "Checking node status..."
+sudo systemctl status blockchain-node blockchain-node-2 --no-pager | grep -E 'Active:|Main PID:'
+
+echo ""
+print_status "✅ Gossip relay setup complete!"
+echo ""
+echo "Nodes are now connected via shared gossip backend."
+echo "They should sync blocks and transactions."
+echo ""
+echo "To verify connectivity:"
+echo "  1. Run: python /opt/test_blockchain_simple.py"
+echo "  2. Check if heights are converging"
+echo ""
+echo "Gossip relay logs: sudo journalctl -u blockchain-gossip-relay -f"

scripts/deploy/test-deployment.sh

@@ -0,0 +1,40 @@
+#!/bin/bash
+
+# Test if blockchain node and explorer are running
+
+echo "🔍 Testing Blockchain Deployment"
+echo "==============================="
+
+# Test blockchain RPC
+echo "Testing blockchain RPC..."
+if curl -s http://aitbc.keisanki.net:8082/rpc/head > /dev/null; then
+    echo "✅ Blockchain RPC is accessible"
+    curl -s http://aitbc.keisanki.net:8082/rpc/head | jq '.height'
+else
+    echo "❌ Blockchain RPC is not accessible"
+fi
+
+# Test explorer
+echo ""
+echo "Testing blockchain explorer..."
+if curl -s http://aitbc.keisanki.net:3000 > /dev/null; then
+    echo "✅ Explorer is accessible"
+else
+    echo "❌ Explorer is not accessible"
+fi
+
+# Check services on server
+echo ""
+echo "Checking service status on ns3..."
+ssh ns3-root "systemctl is-active blockchain-node blockchain-rpc nginx" | while read service status; do
+    if [ "$status" = "active" ]; then
+        echo "✅ $service is running"
+    else
+        echo "❌ $service is not running"
+    fi
+done
+
+# Check logs if needed
+echo ""
+echo "Recent blockchain logs:"
+ssh ns3-root "journalctl -u blockchain-node -n 5 --no-pager"

scripts/testing/README.md

@@ -0,0 +1,33 @@
+# Testing Scripts
+
+This directory contains various test scripts and utilities for testing the AITBC platform.
+
+## Test Scripts
+
+### Block Import Tests
+- **test_block_import.py** - Main block import endpoint test
+- **test_block_import_complete.py** - Comprehensive block import test suite
+- **test_simple_import.py** - Simple block import test
+- **test_tx_import.py** - Transaction import test
+- **test_tx_model.py** - Transaction model validation test
+- **test_minimal.py** - Minimal test case
+- **test_model_validation.py** - Model validation test
+
+### Payment Tests
+- **test_payment_integration.py** - Payment integration test suite
+- **test_payment_local.py** - Local payment testing
+
+### Test Runners
+- **run_test_suite.py** - Main test suite runner
+- **run_tests.py** - Simple test runner
+- **verify_windsurf_tests.py** - Verify Windsurf test configuration
+- **register_test_clients.py** - Register test clients for testing
+
+## Usage
+
+Most test scripts can be run directly with Python:
+```bash
+python3 test_block_import.py
+```
+
+Some scripts may require specific environment setup or configuration.

scripts/testing/register_test_clients.py

@@ -0,0 +1,56 @@
+#!/usr/bin/env python3
+"""Register test clients for payment integration testing"""
+
+import asyncio
+import httpx
+import json
+
+# Configuration
+COORDINATOR_URL = "http://127.0.0.1:8000/v1"
+CLIENT_KEY = "test_client_key_123"
+MINER_KEY = "REDACTED_MINER_KEY"
+
+async def register_client():
+    """Register a test client"""
+    async with httpx.AsyncClient() as client:
+        # Register client
+        response = await client.post(
+            f"{COORDINATOR_URL}/clients/register",
+            headers={"X-API-Key": CLIENT_KEY},
+            json={"name": "Test Client", "description": "Client for payment testing"}
+        )
+        print(f"Client registration: {response.status_code}")
+        if response.status_code not in [200, 201]:
+            print(f"Response: {response.text}")
+        else:
+            print("✓ Test client registered successfully")
+
+async def register_miner():
+    """Register a test miner"""
+    async with httpx.AsyncClient() as client:
+        # Register miner
+        response = await client.post(
+            f"{COORDINATOR_URL}/miners/register",
+            headers={"X-API-Key": MINER_KEY},
+            json={
+                "name": "Test Miner",
+                "description": "Miner for payment testing",
+                "capacity": 100,
+                "price_per_hour": 0.1,
+                "hardware": {"gpu": "RTX 4090", "memory": "24GB"}
+            }
+        )
+        print(f"Miner registration: {response.status_code}")
+        if response.status_code not in [200, 201]:
+            print(f"Response: {response.text}")
+        else:
+            print("✓ Test miner registered successfully")
+
+async def main():
+    print("=== Registering Test Clients ===")
+    await register_client()
+    await register_miner()
+    print("\n✅ Test clients registered successfully!")
+
+if __name__ == "__main__":
+    asyncio.run(main())

scripts/testing/test_block_import.py

@@ -0,0 +1,203 @@
+#!/usr/bin/env python3
+"""
+Test script for block import endpoint
+Tests the /rpc/blocks/import POST endpoint functionality
+"""
+
+import json
+import hashlib
+from datetime import datetime
+
+# Test configuration
+BASE_URL = "https://aitbc.bubuit.net/rpc"
+CHAIN_ID = "ait-devnet"
+
+def compute_block_hash(height, parent_hash, timestamp):
+    """Compute block hash using the same algorithm as PoA proposer"""
+    payload = f"{CHAIN_ID}|{height}|{parent_hash}|{timestamp}".encode()
+    return "0x" + hashlib.sha256(payload).hexdigest()
+
+def test_block_import():
+    """Test the block import endpoint with various scenarios"""
+    import requests
+    
+    print("Testing Block Import Endpoint")
+    print("=" * 50)
+    
+    # Test 1: Invalid height (0)
+    print("\n1. Testing invalid height (0)...")
+    response = requests.post(
+        f"{BASE_URL}/blocks/import",
+        json={
+            "height": 0,
+            "hash": "0x123",
+            "parent_hash": "0x00",
+            "proposer": "test",
+            "timestamp": "2026-01-29T10:20:00",
+            "tx_count": 0
+        }
+    )
+    print(f"Status: {response.status_code}")
+    print(f"Response: {response.json()}")
+    assert response.status_code == 422, "Should return validation error for height 0"
+    print("✓ Correctly rejected height 0")
+    
+    # Test 2: Block already exists with different hash
+    print("\n2. Testing block conflict...")
+    response = requests.post(
+        f"{BASE_URL}/blocks/import",
+        json={
+            "height": 1,
+            "hash": "0xinvalidhash",
+            "parent_hash": "0x00",
+            "proposer": "test",
+            "timestamp": "2026-01-29T10:20:00",
+            "tx_count": 0
+        }
+    )
+    print(f"Status: {response.status_code}")
+    print(f"Response: {response.json()}")
+    assert response.status_code == 409, "Should return conflict for existing height with different hash"
+    print("✓ Correctly detected block conflict")
+    
+    # Test 3: Import existing block with correct hash
+    print("\n3. Testing import of existing block with correct hash...")
+    # Get actual block data
+    response = requests.get(f"{BASE_URL}/blocks/1")
+    block_data = response.json()
+    
+    response = requests.post(
+        f"{BASE_URL}/blocks/import",
+        json={
+            "height": block_data["height"],
+            "hash": block_data["hash"],
+            "parent_hash": block_data["parent_hash"],
+            "proposer": block_data["proposer"],
+            "timestamp": block_data["timestamp"],
+            "tx_count": block_data["tx_count"]
+        }
+    )
+    print(f"Status: {response.status_code}")
+    print(f"Response: {response.json()}")
+    assert response.status_code == 200, "Should accept existing block with correct hash"
+    assert response.json()["status"] == "exists", "Should return 'exists' status"
+    print("✓ Correctly handled existing block")
+    
+    # Test 4: Invalid block hash (with valid parent)
+    print("\n4. Testing invalid block hash...")
+    # Get current head to use as parent
+    response = requests.get(f"{BASE_URL}/head")
+    head = response.json()
+    
+    timestamp = "2026-01-29T10:20:00"
+    parent_hash = head["hash"]  # Use actual parent hash
+    height = head["height"] + 1000  # Use high height to avoid conflicts
+    invalid_hash = "0xinvalid"
+    
+    response = requests.post(
+        f"{BASE_URL}/blocks/import",
+        json={
+            "height": height,
+            "hash": invalid_hash,
+            "parent_hash": parent_hash,
+            "proposer": "test",
+            "timestamp": timestamp,
+            "tx_count": 0
+        }
+    )
+    print(f"Status: {response.status_code}")
+    print(f"Response: {response.json()}")
+    assert response.status_code == 400, "Should reject invalid hash"
+    assert "Invalid block hash" in response.json()["detail"], "Should mention invalid hash"
+    print("✓ Correctly rejected invalid hash")
+    
+    # Test 5: Valid hash but parent not found
+    print("\n5. Testing valid hash but parent not found...")
+    height = head["height"] + 2000  # Use different height
+    parent_hash = "0xnonexistentparent"
+    timestamp = "2026-01-29T10:20:00"
+    valid_hash = compute_block_hash(height, parent_hash, timestamp)
+    
+    response = requests.post(
+        f"{BASE_URL}/blocks/import",
+        json={
+            "height": height,
+            "hash": valid_hash,
+            "parent_hash": parent_hash,
+            "proposer": "test",
+            "timestamp": timestamp,
+            "tx_count": 0
+        }
+    )
+    print(f"Status: {response.status_code}")
+    print(f"Response: {response.json()}")
+    assert response.status_code == 400, "Should reject when parent not found"
+    assert "Parent block not found" in response.json()["detail"], "Should mention parent not found"
+    print("✓ Correctly rejected missing parent")
+    
+    # Test 6: Valid block with transactions and receipts
+    print("\n6. Testing valid block with transactions...")
+    # Get current head to use as parent
+    response = requests.get(f"{BASE_URL}/head")
+    head = response.json()
+    
+    height = head["height"] + 1
+    parent_hash = head["hash"]
+    timestamp = datetime.utcnow().isoformat() + "Z"
+    valid_hash = compute_block_hash(height, parent_hash, timestamp)
+    
+    test_block = {
+        "height": height,
+        "hash": valid_hash,
+        "parent_hash": parent_hash,
+        "proposer": "test-proposer",
+        "timestamp": timestamp,
+        "tx_count": 1,
+        "transactions": [{
+            "tx_hash": f"0xtx{height}",
+            "sender": "0xsender",
+            "recipient": "0xreceiver",
+            "payload": {"to": "0xreceiver", "amount": 1000000}
+        }],
+        "receipts": [{
+            "receipt_id": f"rx{height}",
+            "job_id": f"job{height}",
+            "payload": {"result": "success"},
+            "miner_signature": "0xminer",
+            "coordinator_attestations": ["0xatt1"],
+            "minted_amount": 100,
+            "recorded_at": timestamp
+        }]
+    }
+    
+    response = requests.post(
+        f"{BASE_URL}/blocks/import",
+        json=test_block
+    )
+    print(f"Status: {response.status_code}")
+    print(f"Response: {response.json()}")
+    assert response.status_code == 200, "Should accept valid block with transactions"
+    assert response.json()["status"] == "imported", "Should return 'imported' status"
+    print("✓ Successfully imported block with transactions")
+    
+    # Verify the block was imported
+    print("\n7. Verifying imported block...")
+    response = requests.get(f"{BASE_URL}/blocks/{height}")
+    assert response.status_code == 200, "Should be able to retrieve imported block"
+    imported_block = response.json()
+    assert imported_block["hash"] == valid_hash, "Hash should match"
+    assert imported_block["tx_count"] == 1, "Should have 1 transaction"
+    print("✓ Block successfully imported and retrievable")
+    
+    print("\n" + "=" * 50)
+    print("All tests passed! ✅")
+    print("\nBlock import endpoint is fully functional with:")
+    print("- ✓ Input validation")
+    print("- ✓ Hash validation")
+    print("- ✓ Parent block verification")
+    print("- ✓ Conflict detection")
+    print("- ✓ Transaction and receipt import")
+    print("- ✓ Proper error handling")
+
+if __name__ == "__main__":
+    test_block_import()

scripts/testing/test_block_import_complete.py

@@ -0,0 +1,224 @@
+#!/usr/bin/env python3
+"""
+Comprehensive test for block import endpoint
+Tests all functionality including validation, conflicts, and transaction import
+"""
+
+import json
+import hashlib
+import requests
+from datetime import datetime
+
+BASE_URL = "https://aitbc.bubuit.net/rpc"
+CHAIN_ID = "ait-devnet"
+
+def compute_block_hash(height, parent_hash, timestamp):
+    """Compute block hash using the same algorithm as PoA proposer"""
+    payload = f"{CHAIN_ID}|{height}|{parent_hash}|{timestamp}".encode()
+    return "0x" + hashlib.sha256(payload).hexdigest()
+
+def test_block_import_complete():
+    """Complete test suite for block import endpoint"""
+    
+    print("=" * 60)
+    print("BLOCK IMPORT ENDPOINT TEST SUITE")
+    print("=" * 60)
+    
+    results = []
+    
+    # Test 1: Invalid height (0)
+    print("\n[TEST 1] Invalid height (0)...")
+    response = requests.post(
+        f"{BASE_URL}/blocks/import",
+        json={
+            "height": 0,
+            "hash": "0x123",
+            "parent_hash": "0x00",
+            "proposer": "test",
+            "timestamp": "2026-01-29T10:20:00",
+            "tx_count": 0
+        }
+    )
+    if response.status_code == 422 and "greater_than" in response.json()["detail"][0]["msg"]:
+        print("✅ PASS: Correctly rejected height 0")
+        results.append(True)
+    else:
+        print(f"❌ FAIL: Expected 422, got {response.status_code}")
+        results.append(False)
+    
+    # Test 2: Block conflict
+    print("\n[TEST 2] Block conflict...")
+    response = requests.post(
+        f"{BASE_URL}/blocks/import",
+        json={
+            "height": 1,
+            "hash": "0xinvalidhash",
+            "parent_hash": "0x00",
+            "proposer": "test",
+            "timestamp": "2026-01-29T10:20:00",
+            "tx_count": 0
+        }
+    )
+    if response.status_code == 409 and "already exists with different hash" in response.json()["detail"]:
+        print("✅ PASS: Correctly detected block conflict")
+        results.append(True)
+    else:
+        print(f"❌ FAIL: Expected 409, got {response.status_code}")
+        results.append(False)
+    
+    # Test 3: Import existing block with correct hash
+    print("\n[TEST 3] Import existing block with correct hash...")
+    response = requests.get(f"{BASE_URL}/blocks/1")
+    block_data = response.json()
+    
+    response = requests.post(
+        f"{BASE_URL}/blocks/import",
+        json={
+            "height": block_data["height"],
+            "hash": block_data["hash"],
+            "parent_hash": block_data["parent_hash"],
+            "proposer": block_data["proposer"],
+            "timestamp": block_data["timestamp"],
+            "tx_count": block_data["tx_count"]
+        }
+    )
+    if response.status_code == 200 and response.json()["status"] == "exists":
+        print("✅ PASS: Correctly handled existing block")
+        results.append(True)
+    else:
+        print(f"❌ FAIL: Expected 200 with 'exists' status, got {response.status_code}")
+        results.append(False)
+    
+    # Test 4: Invalid block hash
+    print("\n[TEST 4] Invalid block hash...")
+    response = requests.get(f"{BASE_URL}/head")
+    head = response.json()
+    
+    response = requests.post(
+        f"{BASE_URL}/blocks/import",
+        json={
+            "height": 999999,
+            "hash": "0xinvalid",
+            "parent_hash": head["hash"],
+            "proposer": "test",
+            "timestamp": "2026-01-29T10:20:00",
+            "tx_count": 0
+        }
+    )
+    if response.status_code == 400 and "Invalid block hash" in response.json()["detail"]:
+        print("✅ PASS: Correctly rejected invalid hash")
+        results.append(True)
+    else:
+        print(f"❌ FAIL: Expected 400, got {response.status_code}")
+        results.append(False)
+    
+    # Test 5: Parent not found
+    print("\n[TEST 5] Parent block not found...")
+    response = requests.post(
+        f"{BASE_URL}/blocks/import",
+        json={
+            "height": 999998,
+            "hash": compute_block_hash(999998, "0xnonexistent", "2026-01-29T10:20:00"),
+            "parent_hash": "0xnonexistent",
+            "proposer": "test",
+            "timestamp": "2026-01-29T10:20:00",
+            "tx_count": 0
+        }
+    )
+    if response.status_code == 400 and "Parent block not found" in response.json()["detail"]:
+        print("✅ PASS: Correctly rejected missing parent")
+        results.append(True)
+    else:
+        print(f"❌ FAIL: Expected 400, got {response.status_code}")
+        results.append(False)
+    
+    # Test 6: Import block without transactions
+    print("\n[TEST 6] Import block without transactions...")
+    response = requests.get(f"{BASE_URL}/head")
+    head = response.json()
+    
+    height = head["height"] + 1
+    block_hash = compute_block_hash(height, head["hash"], "2026-01-29T10:20:00")
+    
+    response = requests.post(
+        f"{BASE_URL}/blocks/import",
+        json={
+            "height": height,
+            "hash": block_hash,
+            "parent_hash": head["hash"],
+            "proposer": "test-proposer",
+            "timestamp": "2026-01-29T10:20:00",
+            "tx_count": 0,
+            "transactions": []
+        }
+    )
+    if response.status_code == 200 and response.json()["status"] == "imported":
+        print("✅ PASS: Successfully imported block without transactions")
+        results.append(True)
+    else:
+        print(f"❌ FAIL: Expected 200, got {response.status_code}")
+        results.append(False)
+    
+    # Test 7: Import block with transactions (KNOWN ISSUE)
+    print("\n[TEST 7] Import block with transactions...")
+    print("⚠️  KNOWN ISSUE: Transaction import currently fails with database constraint error")
+    print("    This appears to be a bug in the transaction field mapping")
+    
+    height = height + 1
+    block_hash = compute_block_hash(height, head["hash"], "2026-01-29T10:20:00")
+    
+    response = requests.post(
+        f"{BASE_URL}/blocks/import",
+        json={
+            "height": height,
+            "hash": block_hash,
+            "parent_hash": head["hash"],
+            "proposer": "test-proposer",
+            "timestamp": "2026-01-29T10:20:00",
+            "tx_count": 1,
+            "transactions": [{
+                "tx_hash": "0xtx123",
+                "sender": "0xsender",
+                "recipient": "0xrecipient",
+                "payload": {"test": "data"}
+            }]
+        }
+    )
+    if response.status_code == 500:
+        print("⚠️  EXPECTED FAILURE: Transaction import fails with 500 error")
+        print("    Error: NOT NULL constraint failed on transaction fields")
+        results.append(None)  # Known issue, not counting as fail
+    else:
+        print(f"❓ UNEXPECTED: Got {response.status_code} instead of expected 500")
+        results.append(None)
+    
+    # Summary
+    print("\n" + "=" * 60)
+    print("TEST SUMMARY")
+    print("=" * 60)
+    
+    passed = sum(1 for r in results if r is True)
+    failed = sum(1 for r in results if r is False)
+    known_issues = sum(1 for r in results if r is None)
+    
+    print(f"✅ Passed: {passed}")
+    print(f"❌ Failed: {failed}")
+    if known_issues > 0:
+        print(f"⚠️  Known Issues: {known_issues}")
+    
+    print("\nFUNCTIONALITY STATUS:")
+    print("- ✅ Input validation (height, hash, parent)")
+    print("- ✅ Conflict detection")
+    print("- ✅ Block import without transactions")
+    print("- ❌ Block import with transactions (database constraint issue)")
+    
+    if failed == 0:
+        print("\n🎉 All core functionality is working!")
+        print("   The block import endpoint is functional for basic use.")
+    else:
+        print(f"\n⚠️  {failed} test(s) failed - review required")
+    
+    return passed, failed, known_issues
+
+if __name__ == "__main__":
+    test_block_import_complete()

scripts/testing/test_minimal.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+"""
+Minimal test to debug transaction import
+"""
+
+import json
+import hashlib
+import requests
+
+BASE_URL = "https://aitbc.bubuit.net/rpc"
+CHAIN_ID = "ait-devnet"
+
+def compute_block_hash(height, parent_hash, timestamp):
+    """Compute block hash using the same algorithm as PoA proposer"""
+    payload = f"{CHAIN_ID}|{height}|{parent_hash}|{timestamp}".encode()
+    return "0x" + hashlib.sha256(payload).hexdigest()
+
+def test_minimal():
+    """Test with minimal data"""
+    
+    # Get current head
+    response = requests.get(f"{BASE_URL}/head")
+    head = response.json()
+    
+    # Create a new block
+    height = head["height"] + 1
+    parent_hash = head["hash"]
+    timestamp = "2026-01-29T10:20:00"
+    block_hash = compute_block_hash(height, parent_hash, timestamp)
+    
+    # Test with empty transactions list first
+    test_block = {
+        "height": height,
+        "hash": block_hash,
+        "parent_hash": parent_hash,
+        "proposer": "test-proposer",
+        "timestamp": timestamp,
+        "tx_count": 0,
+        "transactions": []
+    }
+    
+    print("Testing with empty transactions list...")
+    response = requests.post(f"{BASE_URL}/blocks/import", json=test_block)
+    print(f"Status: {response.status_code}")
+    print(f"Response: {response.json()}")
+    
+    if response.status_code == 200:
+        print("\n✅ Empty transactions work!")
+        
+        # Now test with one transaction
+        height = height + 1
+        block_hash = compute_block_hash(height, parent_hash, timestamp)
+        
+        test_block["height"] = height
+        test_block["hash"] = block_hash
+        test_block["tx_count"] = 1
+        test_block["transactions"] = [{"tx_hash": "0xtest", "sender": "0xtest", "recipient": "0xtest", "payload": {}}]
+        
+        print("\nTesting with one transaction...")
+        response = requests.post(f"{BASE_URL}/blocks/import", json=test_block)
+        print(f"Status: {response.status_code}")
+        print(f"Response: {response.json()}")
+
+if __name__ == "__main__":
+    test_minimal()

scripts/testing/test_model_validation.py

@@ -0,0 +1,57 @@
+#!/usr/bin/env python3
+"""
+Test the BlockImportRequest model
+"""
+
+from pydantic import BaseModel, Field
+from typing import Dict, Any, List, Optional
+
+class TransactionData(BaseModel):
+    tx_hash: str
+    sender: str
+    recipient: str
+    payload: Dict[str, Any] = Field(default_factory=dict)
+
+class BlockImportRequest(BaseModel):
+    height: int = Field(gt=0)
+    hash: str
+    parent_hash: str
+    proposer: str
+    timestamp: str
+    tx_count: int = Field(ge=0)
+    state_root: Optional[str] = None
+    transactions: List[TransactionData] = Field(default_factory=list)
+
+# Test creating the request
+test_data = {
+    "height": 1,
+    "hash": "0xtest",
+    "parent_hash": "0x00",
+    "proposer": "test",
+    "timestamp": "2026-01-29T10:20:00",
+    "tx_count": 1,
+    "transactions": [{
+        "tx_hash": "0xtx123",
+        "sender": "0xsender",
+        "recipient": "0xrecipient",
+        "payload": {"test": "data"}
+    }]
+}
+
+print("Test data:")
+print(test_data)
+
+try:
+    request = BlockImportRequest(**test_data)
+    print("\n✅ Request validated successfully!")
+    print(f"Transactions count: {len(request.transactions)}")
+    if request.transactions:
+        tx = request.transactions[0]
+        print(f"First transaction:")
+        print(f"  tx_hash: {tx.tx_hash}")
+        print(f"  sender: {tx.sender}")
+        print(f"  recipient: {tx.recipient}")
+except Exception as e:
+    print(f"\n❌ Validation failed: {e}")
+    import traceback
+    traceback.print_exc()

scripts/testing/test_payment_integration.py

@@ -0,0 +1,317 @@
+#!/usr/bin/env python3
+"""
+Test script for AITBC Payment Integration
+Tests job creation with payments, escrow, release, and refund flows
+"""
+
+import asyncio
+import httpx
+import json
+import logging
+from datetime import datetime
+from typing import Dict, Any
+
+# Configure logging
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+# Configuration
+COORDINATOR_URL = "https://aitbc.bubuit.net/api"
+CLIENT_KEY = "test_client_key_123"
+MINER_KEY = "REDACTED_MINER_KEY"
+
+class PaymentIntegrationTest:
+    def __init__(self):
+        self.client = httpx.Client(timeout=30.0)
+        self.job_id = None
+        self.payment_id = None
+        
+    async def test_complete_payment_flow(self):
+        """Test the complete payment flow from job creation to payment release"""
+        
+        logger.info("=== Starting AITBC Payment Integration Test ===")
+        
+        # Step 1: Check coordinator health
+        await self.check_health()
+        
+        # Step 2: Submit a job with payment
+        await self.submit_job_with_payment()
+        
+        # Step 3: Check job status and payment
+        await self.check_job_and_payment_status()
+        
+        # Step 4: Simulate job completion by miner
+        await self.complete_job()
+        
+        # Step 5: Verify payment was released
+        await self.verify_payment_release()
+        
+        # Step 6: Test refund flow with a new job
+        await self.test_refund_flow()
+        
+        logger.info("=== Payment Integration Test Complete ===")
+    
+    async def check_health(self):
+        """Check if coordinator API is healthy"""
+        logger.info("Step 1: Checking coordinator health...")
+        
+        response = self.client.get(f"{COORDINATOR_URL}/health")
+        
+        if response.status_code == 200:
+            logger.info(f"✓ Coordinator healthy: {response.json()}")
+        else:
+            raise Exception(f"Coordinator health check failed: {response.status_code}")
+    
+    async def submit_job_with_payment(self):
+        """Submit a job with AITBC token payment"""
+        logger.info("Step 2: Submitting job with payment...")
+        
+        job_data = {
+            "service_type": "llm",
+            "service_params": {
+                "model": "llama3.2",
+                "prompt": "What is AITBC?",
+                "max_tokens": 100
+            },
+            "payment_amount": 1.0,
+            "payment_currency": "AITBC",
+            "escrow_timeout_seconds": 3600
+        }
+        
+        headers = {"X-Client-Key": CLIENT_KEY}
+        
+        response = self.client.post(
+            f"{COORDINATOR_URL}/v1/jobs",
+            json=job_data,
+            headers=headers
+        )
+        
+        if response.status_code == 201:
+            job = response.json()
+            self.job_id = job["job_id"]
+            logger.info(f"✓ Job created with ID: {self.job_id}")
+            logger.info(f"  Payment status: {job.get('payment_status', 'N/A')}")
+        else:
+            raise Exception(f"Failed to create job: {response.status_code} - {response.text}")
+    
+    async def check_job_and_payment_status(self):
+        """Check job status and payment details"""
+        logger.info("Step 3: Checking job and payment status...")
+        
+        headers = {"X-Client-Key": CLIENT_KEY}
+        
+        # Get job status
+        response = self.client.get(
+            f"{COORDINATOR_URL}/v1/jobs/{self.job_id}",
+            headers=headers
+        )
+        
+        if response.status_code == 200:
+            job = response.json()
+            logger.info(f"✓ Job status: {job['state']}")
+            logger.info(f"  Payment ID: {job.get('payment_id', 'N/A')}")
+            logger.info(f"  Payment status: {job.get('payment_status', 'N/A')}")
+            
+            self.payment_id = job.get('payment_id')
+            
+            # Get payment details if payment_id exists
+            if self.payment_id:
+                payment_response = self.client.get(
+                    f"{COORDINATOR_URL}/v1/payments/{self.payment_id}",
+                    headers=headers
+                )
+                
+                if payment_response.status_code == 200:
+                    payment = payment_response.json()
+                    logger.info(f"✓ Payment details:")
+                    logger.info(f"  Amount: {payment['amount']} {payment['currency']}")
+                    logger.info(f"  Status: {payment['status']}")
+                    logger.info(f"  Method: {payment['payment_method']}")
+                else:
+                    logger.warning(f"Could not fetch payment details: {payment_response.status_code}")
+        else:
+            raise Exception(f"Failed to get job status: {response.status_code}")
+    
+    async def complete_job(self):
+        """Simulate miner completing the job"""
+        logger.info("Step 4: Simulating job completion...")
+        
+        # First, poll for the job as miner
+        headers = {"X-Miner-Key": MINER_KEY}
+        
+        poll_response = self.client.post(
+            f"{COORDINATOR_URL}/v1/miners/poll",
+            json={"capabilities": ["llm"]},
+            headers=headers
+        )
+        
+        if poll_response.status_code == 200:
+            poll_data = poll_response.json()
+            if poll_data.get("job_id") == self.job_id:
+                logger.info(f"✓ Miner received job: {self.job_id}")
+                
+                # Submit job result
+                result_data = {
+                    "result": json.dumps({
+                        "text": "AITBC is a decentralized AI computing marketplace that uses blockchain for payments and zero-knowledge proofs for privacy.",
+                        "model": "llama3.2",
+                        "tokens_used": 42
+                    }),
+                    "metrics": {
+                        "duration_ms": 2500,
+                        "tokens_used": 42,
+                        "gpu_seconds": 0.5
+                    }
+                }
+                
+                submit_response = self.client.post(
+                    f"{COORDINATOR_URL}/v1/miners/{self.job_id}/result",
+                    json=result_data,
+                    headers=headers
+                )
+                
+                if submit_response.status_code == 200:
+                    logger.info("✓ Job result submitted successfully")
+                    logger.info(f"  Receipt: {submit_response.json().get('receipt', {}).get('receipt_id', 'N/A')}")
+                else:
+                    raise Exception(f"Failed to submit result: {submit_response.status_code}")
+            else:
+                logger.warning(f"Miner received different job: {poll_data.get('job_id')}")
+        else:
+            raise Exception(f"Failed to poll for job: {poll_response.status_code}")
+    
+    async def verify_payment_release(self):
+        """Verify that payment was released after job completion"""
+        logger.info("Step 5: Verifying payment release...")
+        
+        # Wait a moment for payment processing
+        await asyncio.sleep(2)
+        
+        headers = {"X-Client-Key": CLIENT_KEY}
+        
+        # Check updated job status
+        response = self.client.get(
+            f"{COORDINATOR_URL}/v1/jobs/{self.job_id}",
+            headers=headers
+        )
+        
+        if response.status_code == 200:
+            job = response.json()
+            logger.info(f"✓ Final job status: {job['state']}")
+            logger.info(f"  Final payment status: {job.get('payment_status', 'N/A')}")
+            
+            # Get payment receipt
+            if self.payment_id:
+                receipt_response = self.client.get(
+                    f"{COORDINATOR_URL}/v1/payments/{self.payment_id}/receipt",
+                    headers=headers
+                )
+                
+                if receipt_response.status_code == 200:
+                    receipt = receipt_response.json()
+                    logger.info(f"✓ Payment receipt:")
+                    logger.info(f"  Status: {receipt['status']}")
+                    logger.info(f"  Verified at: {receipt.get('verified_at', 'N/A')}")
+                    logger.info(f"  Transaction hash: {receipt.get('transaction_hash', 'N/A')}")
+                else:
+                    logger.warning(f"Could not fetch payment receipt: {receipt_response.status_code}")
+        else:
+            raise Exception(f"Failed to verify payment release: {response.status_code}")
+    
+    async def test_refund_flow(self):
+        """Test payment refund for failed jobs"""
+        logger.info("Step 6: Testing refund flow...")
+        
+        # Create a new job that will fail
+        job_data = {
+            "service_type": "llm",
+            "service_params": {
+                "model": "nonexistent_model",
+                "prompt": "This should fail"
+            },
+            "payment_amount": 0.5,
+            "payment_currency": "AITBC"
+        }
+        
+        headers = {"X-Client-Key": CLIENT_KEY}
+        
+        response = self.client.post(
+            f"{COORDINATOR_URL}/v1/jobs",
+            json=job_data,
+            headers=headers
+        )
+        
+        if response.status_code == 201:
+            fail_job = response.json()
+            fail_job_id = fail_job["job_id"]
+            fail_payment_id = fail_job.get("payment_id")
+            
+            logger.info(f"✓ Created test job for refund: {fail_job_id}")
+            
+            # Simulate job failure
+            fail_headers = {"X-Miner-Key": MINER_KEY}
+            
+            # Poll for the job
+            poll_response = self.client.post(
+                f"{COORDINATOR_URL}/v1/miners/poll",
+                json={"capabilities": ["llm"]},
+                headers=fail_headers
+            )
+            
+            if poll_response.status_code == 200:
+                poll_data = poll_response.json()
+                if poll_data.get("job_id") == fail_job_id:
+                    # Submit failure
+                    fail_data = {
+                        "error_code": "MODEL_NOT_FOUND",
+                        "error_message": "The specified model does not exist"
+                    }
+                    
+                    fail_response = self.client.post(
+                        f"{COORDINATOR_URL}/v1/miners/{fail_job_id}/fail",
+                        json=fail_data,
+                        headers=fail_headers
+                    )
+                    
+                    if fail_response.status_code == 200:
+                        logger.info("✓ Job failure submitted")
+                        
+                        # Wait for refund processing
+                        await asyncio.sleep(2)
+                        
+                        # Check refund status
+                        if fail_payment_id:
+                            payment_response = self.client.get(
+                                f"{COORDINATOR_URL}/v1/payments/{fail_payment_id}",
+                                headers=headers
+                            )
+                            
+                            if payment_response.status_code == 200:
+                                payment = payment_response.json()
+                                logger.info(f"✓ Payment refunded:")
+                                logger.info(f"  Status: {payment['status']}")
+                                logger.info(f"  Refunded at: {payment.get('refunded_at', 'N/A')}")
+                            else:
+                                logger.warning(f"Could not verify refund: {payment_response.status_code}")
+                    else:
+                        logger.warning(f"Failed to submit job failure: {fail_response.status_code}")
+        
+        logger.info("\n=== Test Summary ===")
+        logger.info("✓ Job creation with payment")
+        logger.info("✓ Payment escrow creation")
+        logger.info("✓ Job completion and payment release")
+        logger.info("✓ Job failure and payment refund")
+        logger.info("\nPayment integration is working correctly!")
+
+async def main():
+    """Run the payment integration test"""
+    test = PaymentIntegrationTest()
+    
+    try:
+        await test.test_complete_payment_flow()
+    except Exception as e:
+        logger.error(f"Test failed: {e}")
+        raise
+
+if __name__ == "__main__":
+    asyncio.run(main())

scripts/testing/test_payment_local.py

@@ -0,0 +1,329 @@
+#!/usr/bin/env python3
+"""
+Test script for AITBC Payment Integration (Localhost)
+Tests job creation with payments, escrow, release, and refund flows
+"""
+
+import asyncio
+import httpx
+import json
+import logging
+from datetime import datetime
+from typing import Dict, Any
+
+# Configure logging
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+# Configuration - Using localhost as we're testing from the server
+COORDINATOR_URL = "http://127.0.0.1:8000/v1"
+CLIENT_KEY = "REDACTED_CLIENT_KEY"
+MINER_KEY = "REDACTED_MINER_KEY"
+
+class PaymentIntegrationTest:
+    def __init__(self):
+        self.client = httpx.Client(timeout=30.0)
+        self.job_id = None
+        self.payment_id = None
+        
+    async def test_complete_payment_flow(self):
+        """Test the complete payment flow from job creation to payment release"""
+        
+        logger.info("=== Starting AITBC Payment Integration Test (Localhost) ===")
+        
+        # Step 1: Check coordinator health
+        await self.check_health()
+        
+        # Step 2: Submit a job with payment
+        await self.submit_job_with_payment()
+        
+        # Step 3: Check job status and payment
+        await self.check_job_and_payment_status()
+        
+        # Step 4: Simulate job completion by miner
+        await self.complete_job()
+        
+        # Step 5: Verify payment was released
+        await self.verify_payment_release()
+        
+        # Step 6: Test refund flow with a new job
+        await self.test_refund_flow()
+        
+        logger.info("=== Payment Integration Test Complete ===")
+    
+    async def check_health(self):
+        """Check if coordinator API is healthy"""
+        logger.info("Step 1: Checking coordinator health...")
+        
+        response = self.client.get(f"{COORDINATOR_URL}/health")
+        
+        if response.status_code == 200:
+            logger.info(f"✓ Coordinator healthy: {response.json()}")
+        else:
+            raise Exception(f"Coordinator health check failed: {response.status_code}")
+    
+    async def submit_job_with_payment(self):
+        """Submit a job with AITBC token payment"""
+        logger.info("Step 2: Submitting job with payment...")
+        
+        job_data = {
+            "payload": {
+                "service_type": "llm",
+                "model": "llama3.2",
+                "prompt": "What is AITBC?",
+                "max_tokens": 100
+            },
+            "constraints": {},
+            "payment_amount": 1.0,
+            "payment_currency": "AITBC",
+            "escrow_timeout_seconds": 3600
+        }
+        
+        headers = {"X-Api-Key": CLIENT_KEY}
+        
+        response = self.client.post(
+            f"{COORDINATOR_URL}/jobs",
+            json=job_data,
+            headers=headers
+        )
+        
+        if response.status_code == 201:
+            job = response.json()
+            self.job_id = job["job_id"]
+            logger.info(f"✓ Job created with ID: {self.job_id}")
+            logger.info(f"  Payment status: {job.get('payment_status', 'N/A')}")
+        else:
+            logger.error(f"Failed to create job: {response.status_code}")
+            logger.error(f"Response: {response.text}")
+            raise Exception(f"Failed to create job: {response.status_code}")
+    
+    async def check_job_and_payment_status(self):
+        """Check job status and payment details"""
+        logger.info("Step 3: Checking job and payment status...")
+        
+        headers = {"X-Api-Key": CLIENT_KEY}
+        
+        # Get job status
+        response = self.client.get(
+            f"{COORDINATOR_URL}/jobs/{self.job_id}",
+            headers=headers
+        )
+        
+        if response.status_code == 200:
+            job = response.json()
+            logger.info(f"✓ Job status: {job['state']}")
+            logger.info(f"  Payment ID: {job.get('payment_id', 'N/A')}")
+            logger.info(f"  Payment status: {job.get('payment_status', 'N/A')}")
+            
+            self.payment_id = job.get('payment_id')
+            
+            # Get payment details if payment_id exists
+            if self.payment_id:
+                payment_response = self.client.get(
+                    f"{COORDINATOR_URL}/payments/{self.payment_id}",
+                    headers=headers
+                )
+                
+                if payment_response.status_code == 200:
+                    payment = payment_response.json()
+                    logger.info(f"✓ Payment details:")
+                    logger.info(f"  Amount: {payment['amount']} {payment['currency']}")
+                    logger.info(f"  Status: {payment['status']}")
+                    logger.info(f"  Method: {payment['payment_method']}")
+                else:
+                    logger.warning(f"Could not fetch payment details: {payment_response.status_code}")
+        else:
+            raise Exception(f"Failed to get job status: {response.status_code}")
+    
+    async def complete_job(self):
+        """Simulate miner completing the job"""
+        logger.info("Step 4: Simulating job completion...")
+        
+        # First, poll for the job as miner (with retry for 204)
+        headers = {"X-Api-Key": MINER_KEY}
+        
+        poll_data = None
+        for attempt in range(5):
+            poll_response = self.client.post(
+                f"{COORDINATOR_URL}/miners/poll",
+                json={"capabilities": {"llm": True}},
+                headers=headers
+            )
+            
+            if poll_response.status_code == 200:
+                poll_data = poll_response.json()
+                break
+            elif poll_response.status_code == 204:
+                logger.info(f"  No job available yet, retrying... ({attempt + 1}/5)")
+                await asyncio.sleep(1)
+            else:
+                raise Exception(f"Failed to poll for job: {poll_response.status_code}")
+        
+        if poll_data and poll_data.get("job_id") == self.job_id:
+            logger.info(f"✓ Miner received job: {self.job_id}")
+            
+            # Submit job result
+            result_data = {
+                "result": {
+                    "text": "AITBC is a decentralized AI computing marketplace that uses blockchain for payments and zero-knowledge proofs for privacy.",
+                    "model": "llama3.2",
+                    "tokens_used": 42
+                },
+                "metrics": {
+                    "duration_ms": 2500,
+                    "tokens_used": 42,
+                    "gpu_seconds": 0.5
+                }
+            }
+            
+            submit_response = self.client.post(
+                f"{COORDINATOR_URL}/miners/{self.job_id}/result",
+                json=result_data,
+                headers=headers
+            )
+            
+            if submit_response.status_code == 200:
+                logger.info("✓ Job result submitted successfully")
+                logger.info(f"  Receipt: {submit_response.json().get('receipt', {}).get('receipt_id', 'N/A')}")
+            else:
+                raise Exception(f"Failed to submit result: {submit_response.status_code}")
+        elif poll_data:
+            logger.warning(f"Miner received different job: {poll_data.get('job_id')}")
+        else:
+            raise Exception("No job received after 5 retries")
+    
+    async def verify_payment_release(self):
+        """Verify that payment was released after job completion"""
+        logger.info("Step 5: Verifying payment release...")
+        
+        # Wait a moment for payment processing
+        await asyncio.sleep(2)
+        
+        headers = {"X-Api-Key": CLIENT_KEY}
+        
+        # Check updated job status
+        response = self.client.get(
+            f"{COORDINATOR_URL}/jobs/{self.job_id}",
+            headers=headers
+        )
+        
+        if response.status_code == 200:
+            job = response.json()
+            logger.info(f"✓ Final job status: {job['state']}")
+            logger.info(f"  Final payment status: {job.get('payment_status', 'N/A')}")
+            
+            # Get payment receipt
+            if self.payment_id:
+                receipt_response = self.client.get(
+                    f"{COORDINATOR_URL}/payments/{self.payment_id}/receipt",
+                    headers=headers
+                )
+                
+                if receipt_response.status_code == 200:
+                    receipt = receipt_response.json()
+                    logger.info(f"✓ Payment receipt:")
+                    logger.info(f"  Status: {receipt['status']}")
+                    logger.info(f"  Verified at: {receipt.get('verified_at', 'N/A')}")
+                    logger.info(f"  Transaction hash: {receipt.get('transaction_hash', 'N/A')}")
+                else:
+                    logger.warning(f"Could not fetch payment receipt: {receipt_response.status_code}")
+        else:
+            raise Exception(f"Failed to verify payment release: {response.status_code}")
+    
+    async def test_refund_flow(self):
+        """Test payment refund for failed jobs"""
+        logger.info("Step 6: Testing refund flow...")
+        
+        # Create a new job that will fail
+        job_data = {
+            "payload": {
+                "service_type": "llm",
+                "model": "nonexistent_model",
+                "prompt": "This should fail"
+            },
+            "payment_amount": 0.5,
+            "payment_currency": "AITBC"
+        }
+        
+        headers = {"X-Api-Key": CLIENT_KEY}
+        
+        response = self.client.post(
+            f"{COORDINATOR_URL}/jobs",
+            json=job_data,
+            headers=headers
+        )
+        
+        if response.status_code == 201:
+            fail_job = response.json()
+            fail_job_id = fail_job["job_id"]
+            fail_payment_id = fail_job.get("payment_id")
+            
+            logger.info(f"✓ Created test job for refund: {fail_job_id}")
+            
+            # Simulate job failure
+            fail_headers = {"X-Api-Key": MINER_KEY}
+            
+            # Poll for the job
+            poll_response = self.client.post(
+                f"{COORDINATOR_URL}/miners/poll",
+                json={"capabilities": ["llm"]},
+                headers=fail_headers
+            )
+            
+            if poll_response.status_code == 200:
+                poll_data = poll_response.json()
+                if poll_data.get("job_id") == fail_job_id:
+                    # Submit failure
+                    fail_data = {
+                        "error_code": "MODEL_NOT_FOUND",
+                        "error_message": "The specified model does not exist"
+                    }
+                    
+                    fail_response = self.client.post(
+                        f"{COORDINATOR_URL}/miners/{fail_job_id}/fail",
+                        json=fail_data,
+                        headers=fail_headers
+                    )
+                    
+                    if fail_response.status_code == 200:
+                        logger.info("✓ Job failure submitted")
+                        
+                        # Wait for refund processing
+                        await asyncio.sleep(2)
+                        
+                        # Check refund status
+                        if fail_payment_id:
+                            payment_response = self.client.get(
+                                f"{COORDINATOR_URL}/payments/{fail_payment_id}",
+                                headers=headers
+                            )
+                            
+                            if payment_response.status_code == 200:
+                                payment = payment_response.json()
+                                logger.info(f"✓ Payment refunded:")
+                                logger.info(f"  Status: {payment['status']}")
+                                logger.info(f"  Refunded at: {payment.get('refunded_at', 'N/A')}")
+                            else:
+                                logger.warning(f"Could not verify refund: {payment_response.status_code}")
+                    else:
+                        logger.warning(f"Failed to submit job failure: {fail_response.status_code}")
+        
+        logger.info("\n=== Test Summary ===")
+        logger.info("✓ Job creation with payment")
+        logger.info("✓ Payment escrow creation")
+        logger.info("✓ Job completion and payment release")
+        logger.info("✓ Job failure and payment refund")
+        logger.info("\nPayment integration is working correctly!")
+
+async def main():
+    """Run the payment integration test"""
+    test = PaymentIntegrationTest()
+    
+    try:
+        await test.test_complete_payment_flow()
+    except Exception as e:
+        logger.error(f"Test failed: {e}")
+        raise
+
+if __name__ == "__main__":
+    asyncio.run(main())

scripts/testing/test_simple_import.py

@@ -0,0 +1,74 @@
+#!/usr/bin/env python3
+"""
+Simple test for block import endpoint without transactions
+"""
+
+import json
+import hashlib
+import requests
+
+BASE_URL = "https://aitbc.bubuit.net/rpc"
+CHAIN_ID = "ait-devnet"
+
+def compute_block_hash(height, parent_hash, timestamp):
+    """Compute block hash using the same algorithm as PoA proposer"""
+    payload = f"{CHAIN_ID}|{height}|{parent_hash}|{timestamp}".encode()
+    return "0x" + hashlib.sha256(payload).hexdigest()
+
+def test_simple_block_import():
+    """Test importing a simple block without transactions"""
+    
+    print("Testing Simple Block Import")
+    print("=" * 40)
+    
+    # Get current head
+    response = requests.get(f"{BASE_URL}/head")
+    head = response.json()
+    print(f"Current head: height={head['height']}, hash={head['hash']}")
+    
+    # Create a new block
+    height = head["height"] + 1
+    parent_hash = head["hash"]
+    timestamp = "2026-01-29T10:20:00"
+    block_hash = compute_block_hash(height, parent_hash, timestamp)
+    
+    print(f"\nCreating test block:")
+    print(f"  height: {height}")
+    print(f"  parent_hash: {parent_hash}")
+    print(f"  hash: {block_hash}")
+    
+    # Import the block
+    response = requests.post(
+        f"{BASE_URL}/blocks/import",
+        json={
+            "height": height,
+            "hash": block_hash,
+            "parent_hash": parent_hash,
+            "proposer": "test-proposer",
+            "timestamp": timestamp,
+            "tx_count": 0
+        }
+    )
+    
+    print(f"\nImport response:")
+    print(f"  Status: {response.status_code}")
+    print(f"  Body: {response.json()}")
+    
+    if response.status_code == 200:
+        print("\n✅ Block imported successfully!")
+        
+        # Verify the block was imported
+        response = requests.get(f"{BASE_URL}/blocks/{height}")
+        if response.status_code == 200:
+            imported = response.json()
+            print(f"\n✅ Verified imported block:")
+            print(f"  height: {imported['height']}")
+            print(f"  hash: {imported['hash']}")
+            print(f"  proposer: {imported['proposer']}")
+        else:
+            print(f"\n❌ Could not retrieve imported block: {response.status_code}")
+    else:
+        print(f"\n❌ Import failed: {response.status_code}")
+
+if __name__ == "__main__":
+    test_simple_block_import()

scripts/testing/test_tx_import.py

@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+"""
+Test transaction import specifically
+"""
+
+import json
+import hashlib
+import requests
+
+BASE_URL = "https://aitbc.bubuit.net/rpc"
+CHAIN_ID = "ait-devnet"
+
+def compute_block_hash(height, parent_hash, timestamp):
+    """Compute block hash using the same algorithm as PoA proposer"""
+    payload = f"{CHAIN_ID}|{height}|{parent_hash}|{timestamp}".encode()
+    return "0x" + hashlib.sha256(payload).hexdigest()
+
+def test_transaction_import():
+    """Test importing a block with a single transaction"""
+    
+    print("Testing Transaction Import")
+    print("=" * 40)
+    
+    # Get current head
+    response = requests.get(f"{BASE_URL}/head")
+    head = response.json()
+    print(f"Current head: height={head['height']}")
+    
+    # Create a new block with one transaction
+    height = head["height"] + 1
+    parent_hash = head["hash"]
+    timestamp = "2026-01-29T10:20:00"
+    block_hash = compute_block_hash(height, parent_hash, timestamp)
+    
+    test_block = {
+        "height": height,
+        "hash": block_hash,
+        "parent_hash": parent_hash,
+        "proposer": "test-proposer",
+        "timestamp": timestamp,
+        "tx_count": 1,
+        "transactions": [{
+            "tx_hash": "0xtx123456789",
+            "sender": "0xsender123",
+            "recipient": "0xreceiver456",
+            "payload": {"to": "0xreceiver456", "amount": 1000000}
+        }]
+    }
+    
+    print(f"\nTest block data:")
+    print(json.dumps(test_block, indent=2))
+    
+    # Import the block
+    response = requests.post(
+        f"{BASE_URL}/blocks/import",
+        json=test_block
+    )
+    
+    print(f"\nImport response:")
+    print(f"  Status: {response.status_code}")
+    print(f"  Body: {response.json()}")
+    
+    # Check logs
+    print("\nChecking recent logs...")
+    import subprocess
+    result = subprocess.run(
+        ["ssh", "aitbc-cascade", "journalctl -u blockchain-node --since '30 seconds ago' | grep 'Importing transaction' | tail -1"],
+        capture_output=True,
+        text=True
+    )
+    if result.stdout:
+        print(f"Log: {result.stdout.strip()}")
+    else:
+        print("No transaction import logs found")
+
+if __name__ == "__main__":
+    test_transaction_import()

scripts/testing/test_tx_model.py

@@ -0,0 +1,21 @@
+#!/usr/bin/env python3
+"""
+Test the Transaction model directly
+"""
+
+# Test creating a transaction model instance
+tx_data = {
+    "tx_hash": "0xtest123",
+    "sender": "0xsender",
+    "recipient": "0xrecipient",
+    "payload": {"test": "data"}
+}
+
+print("Transaction data:")
+print(tx_data)
+
+# Simulate what the router does
+print("\nExtracting fields:")
+print(f"tx_hash: {tx_data.get('tx_hash')}")
+print(f"sender: {tx_data.get('sender')}")
+print(f"recipient: {tx_data.get('recipient')}")

src/aitbc_chain/rpc/router.py

@@ -0,0 +1,457 @@
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+import time
+from datetime import datetime
+from typing import Any, Dict, Optional, List
+
+from fastapi import APIRouter, HTTPException, status
+from pydantic import BaseModel, Field, model_validator
+from sqlmodel import select
+
+from ..config import settings
+from ..database import session_scope
+from ..gossip import gossip_broker
+from ..mempool import get_mempool
+from ..metrics import metrics_registry
+from ..models import Account, Block, Receipt, Transaction
+
+router = APIRouter()
+
+
+def _serialize_receipt(receipt: Receipt) -> Dict[str, Any]:
+    return {
+        "receipt_id": receipt.receipt_id,
+        "job_id": receipt.job_id,
+        "payload": receipt.payload,
+        "miner_signature": receipt.miner_signature,
+        "coordinator_attestations": receipt.coordinator_attestations,
+        "minted_amount": receipt.minted_amount,
+        "recorded_at": receipt.recorded_at.isoformat(),
+    }
+
+
+class TransactionRequest(BaseModel):
+    type: str = Field(description="Transaction type, e.g. TRANSFER or RECEIPT_CLAIM")
+    sender: str
+    nonce: int
+    fee: int = Field(ge=0)
+    payload: Dict[str, Any]
+    sig: Optional[str] = Field(default=None, description="Signature payload")
+
+    @model_validator(mode="after")
+    def normalize_type(self) -> "TransactionRequest":  # type: ignore[override]
+        normalized = self.type.upper()
+        if normalized not in {"TRANSFER", "RECEIPT_CLAIM"}:
+            raise ValueError(f"unsupported transaction type: {self.type}")
+        self.type = normalized
+        return self
+
+
+class ReceiptSubmissionRequest(BaseModel):
+    sender: str
+    nonce: int
+    fee: int = Field(ge=0)
+    payload: Dict[str, Any]
+    sig: Optional[str] = None
+
+
+class EstimateFeeRequest(BaseModel):
+    type: Optional[str] = None
+    payload: Dict[str, Any] = Field(default_factory=dict)
+
+
+class MintFaucetRequest(BaseModel):
+    address: str
+    amount: int = Field(gt=0)
+
+
+@router.get("/head", summary="Get current chain head")
+async def get_head() -> Dict[str, Any]:
+    metrics_registry.increment("rpc_get_head_total")
+    start = time.perf_counter()
+    with session_scope() as session:
+        result = session.exec(select(Block).order_by(Block.height.desc()).limit(1)).first()
+        if result is None:
+            metrics_registry.increment("rpc_get_head_not_found_total")
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="no blocks yet")
+        metrics_registry.increment("rpc_get_head_success_total")
+    metrics_registry.observe("rpc_get_head_duration_seconds", time.perf_counter() - start)
+    return {
+        "height": result.height,
+        "hash": result.hash,
+        "timestamp": result.timestamp.isoformat(),
+        "tx_count": result.tx_count,
+    }
+
+
+@router.get("/blocks/{height}", summary="Get block by height")
+async def get_block(height: int) -> Dict[str, Any]:
+    metrics_registry.increment("rpc_get_block_total")
+    start = time.perf_counter()
+    with session_scope() as session:
+        block = session.exec(select(Block).where(Block.height == height)).first()
+        if block is None:
+            metrics_registry.increment("rpc_get_block_not_found_total")
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="block not found")
+        metrics_registry.increment("rpc_get_block_success_total")
+    metrics_registry.observe("rpc_get_block_duration_seconds", time.perf_counter() - start)
+    return {
+            "proposer": block.proposer,
+            "proposer": block.proposer,
+        "height": block.height,
+        "hash": block.hash,
+        "parent_hash": block.parent_hash,
+        "timestamp": block.timestamp.isoformat(),
+        "tx_count": block.tx_count,
+        "state_root": block.state_root,
+    }
+
+
+@router.get("/blocks-range", summary="Get blocks in range")
+async def get_blocks_range(start_height: int = 0, end_height: int = 100, limit: int = 1000) -> List[Dict[str, Any]]:
+    metrics_registry.increment("rpc_get_blocks_range_total")
+    start = time.perf_counter()
+    
+    # Validate parameters
+    if limit > 10000:
+        limit = 10000
+    if end_height - start_height > limit:
+        end_height = start_height + limit
+    
+    with session_scope() as session:
+        stmt = (
+            select(Block)
+            .where(Block.height >= start_height)
+            .where(Block.height <= end_height)
+            .order_by(Block.height)
+        )
+        blocks = session.exec(stmt).all()
+        
+    metrics_registry.observe("rpc_get_blocks_range_duration_seconds", time.perf_counter() - start)
+    return [
+        {
+            "proposer": block.proposer,
+            "proposer": block.proposer,
+            "height": block.height,
+            "hash": block.hash,
+            "parent_hash": block.parent_hash,
+            "timestamp": block.timestamp.isoformat(),
+            "tx_count": block.tx_count,
+            "state_root": block.state_root,
+        }
+        for block in blocks
+    ]
+
+@router.get("/tx/{tx_hash}", summary="Get transaction by hash")
+async def get_transaction(tx_hash: str) -> Dict[str, Any]:
+    metrics_registry.increment("rpc_get_transaction_total")
+    start = time.perf_counter()
+    with session_scope() as session:
+        tx = session.exec(select(Transaction).where(Transaction.tx_hash == tx_hash)).first()
+        if tx is None:
+            metrics_registry.increment("rpc_get_transaction_not_found_total")
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="transaction not found")
+        metrics_registry.increment("rpc_get_transaction_success_total")
+    metrics_registry.observe("rpc_get_transaction_duration_seconds", time.perf_counter() - start)
+    return {
+        "tx_hash": tx.tx_hash,
+        "block_height": tx.block_height,
+        "sender": tx.sender,
+        "recipient": tx.recipient,
+        "payload": tx.payload,
+        "created_at": tx.created_at.isoformat(),
+    }
+
+
+@router.get("/receipts/{receipt_id}", summary="Get receipt by ID")
+async def get_receipt(receipt_id: str) -> Dict[str, Any]:
+    metrics_registry.increment("rpc_get_receipt_total")
+    start = time.perf_counter()
+    with session_scope() as session:
+        receipt = session.exec(select(Receipt).where(Receipt.receipt_id == receipt_id)).first()
+        if receipt is None:
+            metrics_registry.increment("rpc_get_receipt_not_found_total")
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="receipt not found")
+        metrics_registry.increment("rpc_get_receipt_success_total")
+    metrics_registry.observe("rpc_get_receipt_duration_seconds", time.perf_counter() - start)
+    return _serialize_receipt(receipt)
+
+
+@router.get("/getBalance/{address}", summary="Get account balance")
+async def get_balance(address: str) -> Dict[str, Any]:
+    metrics_registry.increment("rpc_get_balance_total")
+    start = time.perf_counter()
+    with session_scope() as session:
+        account = session.get(Account, address)
+        if account is None:
+            metrics_registry.increment("rpc_get_balance_empty_total")
+            metrics_registry.observe("rpc_get_balance_duration_seconds", time.perf_counter() - start)
+            return {"address": address, "balance": 0, "nonce": 0}
+        metrics_registry.increment("rpc_get_balance_success_total")
+    metrics_registry.observe("rpc_get_balance_duration_seconds", time.perf_counter() - start)
+    return {
+        "address": account.address,
+        "balance": account.balance,
+        "nonce": account.nonce,
+        "updated_at": account.updated_at.isoformat(),
+    }
+
+
+@router.post("/sendTx", summary="Submit a new transaction")
+async def send_transaction(request: TransactionRequest) -> Dict[str, Any]:
+    metrics_registry.increment("rpc_send_tx_total")
+    start = time.perf_counter()
+    mempool = get_mempool()
+    tx_dict = request.model_dump()
+    tx_hash = mempool.add(tx_dict)
+    try:
+        asyncio.create_task(
+            gossip_broker.publish(
+                "transactions",
+                {
+                    "tx_hash": tx_hash,
+                    "sender": request.sender,
+                    "payload": request.payload,
+                    "nonce": request.nonce,
+                    "fee": request.fee,
+                    "type": request.type,
+                },
+            )
+        )
+        metrics_registry.increment("rpc_send_tx_success_total")
+        return {"tx_hash": tx_hash}
+    except Exception:
+        metrics_registry.increment("rpc_send_tx_failed_total")
+        raise
+    finally:
+        metrics_registry.observe("rpc_send_tx_duration_seconds", time.perf_counter() - start)
+
+
+@router.post("/submitReceipt", summary="Submit receipt claim transaction")
+async def submit_receipt(request: ReceiptSubmissionRequest) -> Dict[str, Any]:
+    metrics_registry.increment("rpc_submit_receipt_total")
+    start = time.perf_counter()
+    tx_payload = {
+        "type": "RECEIPT_CLAIM",
+        "sender": request.sender,
+        "nonce": request.nonce,
+        "fee": request.fee,
+        "payload": request.payload,
+        "sig": request.sig,
+    }
+    tx_request = TransactionRequest.model_validate(tx_payload)
+    try:
+        response = await send_transaction(tx_request)
+        metrics_registry.increment("rpc_submit_receipt_success_total")
+        return response
+    except HTTPException:
+        metrics_registry.increment("rpc_submit_receipt_failed_total")
+        raise
+    except Exception:
+        metrics_registry.increment("rpc_submit_receipt_failed_total")
+        raise
+    finally:
+        metrics_registry.observe("rpc_submit_receipt_duration_seconds", time.perf_counter() - start)
+
+
+@router.post("/estimateFee", summary="Estimate transaction fee")
+async def estimate_fee(request: EstimateFeeRequest) -> Dict[str, Any]:
+    metrics_registry.increment("rpc_estimate_fee_total")
+    start = time.perf_counter()
+    base_fee = 10
+    per_byte = 1
+    payload_bytes = len(json.dumps(request.payload, sort_keys=True, separators=(",", ":")).encode())
+    estimated_fee = base_fee + per_byte * payload_bytes
+    tx_type = (request.type or "TRANSFER").upper()
+    metrics_registry.increment("rpc_estimate_fee_success_total")
+    metrics_registry.observe("rpc_estimate_fee_duration_seconds", time.perf_counter() - start)
+    return {
+        "type": tx_type,
+        "base_fee": base_fee,
+        "payload_bytes": payload_bytes,
+        "estimated_fee": estimated_fee,
+    }
+
+
+@router.post("/admin/mintFaucet", summary="Mint devnet funds to an address")
+async def mint_faucet(request: MintFaucetRequest) -> Dict[str, Any]:
+    metrics_registry.increment("rpc_mint_faucet_total")
+    start = time.perf_counter()
+    with session_scope() as session:
+        account = session.get(Account, request.address)
+        if account is None:
+            account = Account(address=request.address, balance=request.amount)
+            session.add(account)
+        else:
+            account.balance += request.amount
+        session.commit()
+        updated_balance = account.balance
+    metrics_registry.increment("rpc_mint_faucet_success_total")
+    metrics_registry.observe("rpc_mint_faucet_duration_seconds", time.perf_counter() - start)
+    return {"address": request.address, "balance": updated_balance}
+
+
+class TransactionData(BaseModel):
+    tx_hash: str
+    sender: str
+    recipient: str
+    payload: Dict[str, Any] = Field(default_factory=dict)
+
+class ReceiptData(BaseModel):
+    receipt_id: str
+    job_id: str
+    payload: Dict[str, Any] = Field(default_factory=dict)
+    miner_signature: Optional[str] = None
+    coordinator_attestations: List[str] = Field(default_factory=list)
+    minted_amount: int = 0
+    recorded_at: str
+
+class BlockImportRequest(BaseModel):
+    height: int = Field(gt=0)
+    hash: str
+    parent_hash: str
+    proposer: str
+    timestamp: str
+    tx_count: int = Field(ge=0)
+    state_root: Optional[str] = None
+    transactions: List[TransactionData] = Field(default_factory=list)
+    receipts: List[ReceiptData] = Field(default_factory=list)
+
+
+@router.get("/test-endpoint", summary="Test endpoint")
+async def test_endpoint() -> Dict[str, str]:
+    """Test if new code is deployed"""
+    return {"status": "updated_code_running"}
+
+@router.post("/blocks/import", summary="Import block from remote node")
+async def import_block(request: BlockImportRequest) -> Dict[str, Any]:
+    """Import a block from a remote node after validation."""
+    import logging
+    logger = logging.getLogger(__name__)
+    
+    metrics_registry.increment("rpc_import_block_total")
+    start = time.perf_counter()
+    
+    try:
+        logger.info(f"Received block import request: height={request.height}, hash={request.hash}")
+        logger.info(f"Transactions count: {len(request.transactions)}")
+        if request.transactions:
+            logger.info(f"First transaction: {request.transactions[0]}")
+        
+        with session_scope() as session:
+            # Check if block already exists
+            existing = session.exec(select(Block).where(Block.height == request.height)).first()
+            if existing:
+                if existing.hash == request.hash:
+                    metrics_registry.increment("rpc_import_block_exists_total")
+                    return {"status": "exists", "height": request.height, "hash": request.hash}
+                else:
+                    metrics_registry.increment("rpc_import_block_conflict_total")
+                    raise HTTPException(
+                        status_code=status.HTTP_409_CONFLICT,
+                        detail=f"Block at height {request.height} already exists with different hash"
+                    )
+            
+            # Check if parent block exists
+            if request.height > 0:
+                parent = session.exec(select(Block).where(Block.hash == request.parent_hash)).first()
+                if not parent:
+                    metrics_registry.increment("rpc_import_block_orphan_total")
+                    raise HTTPException(
+                        status_code=status.HTTP_400_BAD_REQUEST,
+                        detail="Parent block not found"
+                    )
+            
+            # Validate block hash using the same algorithm as PoA proposer
+            payload = f"{settings.chain_id}|{request.height}|{request.parent_hash}|{request.timestamp}".encode()
+            expected_hash = "0x" + hashlib.sha256(payload).hexdigest()
+            
+            if request.hash != expected_hash:
+                metrics_registry.increment("rpc_import_block_invalid_hash_total")
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail=f"Invalid block hash. Expected: {expected_hash}, Got: {request.hash}"
+                )
+            
+            # Create and save block
+            block_timestamp = datetime.fromisoformat(request.timestamp.replace('Z', '+00:00'))
+            
+            block = Block(
+                height=request.height,
+                hash=request.hash,
+                parent_hash=request.parent_hash,
+                proposer=request.proposer,
+                timestamp=block_timestamp,
+                tx_count=request.tx_count,
+                state_root=request.state_root
+            )
+            
+            session.add(block)
+            session.flush()  # Get block ID
+            
+            # Add transactions if provided
+            for tx_data in request.transactions:
+                # Create transaction using constructor with all fields
+                tx = Transaction(
+                    tx_hash=str(tx_data.tx_hash),
+                    block_height=block.height,
+                    sender=str(tx_data.sender),
+                    recipient=str(tx_data.recipient),
+                    payload=tx_data.payload if tx_data.payload else {},
+                    created_at=datetime.utcnow()
+                )
+                
+                session.add(tx)
+            
+            # Add receipts if provided
+            for receipt_data in request.receipts:
+                receipt = Receipt(
+                    block_height=block.height,
+                    receipt_id=receipt_data.receipt_id,
+                    job_id=receipt_data.job_id,
+                    payload=receipt_data.payload,
+                    miner_signature=receipt_data.miner_signature,
+                    coordinator_attestations=receipt_data.coordinator_attestations,
+                    minted_amount=receipt_data.minted_amount,
+                    recorded_at=datetime.fromisoformat(receipt_data.recorded_at.replace('Z', '+00:00'))
+                )
+                session.add(receipt)
+            
+            session.commit()
+            
+            # Broadcast block via gossip
+            try:
+                gossip_broker.broadcast("blocks", {
+                    "type": "block_imported",
+                    "height": block.height,
+                    "hash": block.hash,
+                    "proposer": block.proposer
+                })
+            except Exception:
+                pass  # Gossip broadcast is optional
+            
+            metrics_registry.increment("rpc_import_block_success_total")
+            metrics_registry.observe("rpc_import_block_duration_seconds", time.perf_counter() - start)
+            
+            logger.info(f"Successfully imported block {request.height}")
+            
+            return {
+                "status": "imported",
+                "height": block.height,
+                "hash": block.hash,
+                "tx_count": block.tx_count
+            }
+    
+    except HTTPException:
+        # Re-raise HTTP exceptions as-is
+        raise
+    except Exception as e:
+        logger.error(f"Failed to import block {request.height}: {str(e)}", exc_info=True)
+        metrics_registry.increment("rpc_import_block_failed_total")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Internal server error: {str(e)}"
+        )

src/aitbc_chain/sync/__init__.py

@@ -0,0 +1,7 @@
+"""
+Cross-site synchronization module for AITBC blockchain.
+"""
+
+from .cross_site import CrossSiteSync
+
+__all__ = ['CrossSiteSync']

src/aitbc_chain/sync/cross_site.py

@@ -0,0 +1,222 @@
+"""
+Cross-site RPC synchronization module for AITBC blockchain nodes.
+Enables block and transaction synchronization across different sites via HTTP RPC endpoints.
+"""
+
+import asyncio
+import logging
+from typing import List, Dict, Optional, Any
+import httpx
+from datetime import datetime, timedelta
+
+logger = logging.getLogger(__name__)
+
+
+class CrossSiteSync:
+    """Handles synchronization with remote blockchain nodes via RPC."""
+    
+    def __init__(self, local_rpc_url: str, remote_endpoints: List[str], poll_interval: int = 10):
+        """
+        Initialize cross-site synchronization.
+        
+        Args:
+            local_rpc_url: URL of local RPC endpoint (e.g., "http://localhost:8082")
+            remote_endpoints: List of remote RPC URLs to sync with
+            poll_interval: Seconds between sync checks
+        """
+        self.local_rpc_url = local_rpc_url.rstrip('/')
+        self.remote_endpoints = remote_endpoints
+        self.poll_interval = poll_interval
+        self.last_sync = {}
+        self.sync_task = None
+        self.client = httpx.AsyncClient(timeout=5.0)
+        
+    async def get_remote_head(self, endpoint: str) -> Optional[Dict[str, Any]]:
+        """Get the head block from a remote node."""
+        try:
+            response = await self.client.get(f"{endpoint.rstrip('/')}/head")
+            if response.status_code == 200:
+                return response.json()
+        except Exception as e:
+            logger.error(f"Failed to get head from {endpoint}: {e}")
+        return None
+        
+    async def get_remote_block(self, endpoint: str, height: int) -> Optional[Dict[str, Any]]:
+        """Get a specific block from a remote node."""
+        try:
+            response = await self.client.get(f"{endpoint.rstrip('/')}/blocks/{height}")
+            if response.status_code == 200:
+                return response.json()
+        except Exception as e:
+            logger.error(f"Failed to get block {height} from {endpoint}: {e}")
+        return None
+        
+    async def get_local_head(self) -> Optional[Dict[str, Any]]:
+        """Get the local head block."""
+        try:
+            response = await self.client.get(f"{self.local_rpc_url}/rpc/head")
+            if response.status_code == 200:
+                return response.json()
+        except Exception as e:
+            logger.error(f"Failed to get local head: {e}")
+        return None
+        
+    async def import_block(self, block_data: Dict[str, Any]) -> bool:
+        """Import a block from a remote node."""
+        try:
+            response = await self.client.post(
+                f"{self.local_rpc_url}/rpc/blocks/import",
+                json=block_data
+            )
+            if response.status_code == 200:
+                result = response.json()
+                if result.get("status") in ["imported", "exists"]:
+                    logger.info(f"Successfully imported block {block_data.get('height')}")
+                    return True
+                else:
+                    logger.error(f"Block import failed: {result}")
+                    return False
+            else:
+                logger.error(f"Block import request failed: {response.status_code} {response.text}")
+                return False
+        except Exception as e:
+            logger.error(f"Failed to import block: {e}")
+            return False
+            
+    async def submit_block(self, block_data: Dict[str, Any]) -> bool:
+        """Submit a block to the local node."""
+        try:
+            response = await self.client.post(
+                f"{self.local_rpc_url}/rpc/block",
+                json=block_data
+            )
+            return response.status_code == 200
+        except Exception as e:
+            logger.error(f"Failed to submit block: {e}")
+            return False
+            
+    async def sync_with_remotes(self) -> None:
+        """Check and sync with all remote endpoints."""
+        local_head = await self.get_local_head()
+        if not local_head:
+            return
+            
+        local_height = local_head.get('height', 0)
+        
+        for endpoint in self.remote_endpoints:
+            remote_head = await self.get_remote_head(endpoint)
+            if not remote_head:
+                continue
+                
+            remote_height = remote_head.get('height', 0)
+            
+            # If remote is ahead, fetch missing blocks
+            if remote_height > local_height:
+                logger.info(f"Remote {endpoint} is ahead (height {remote_height} vs {local_height})")
+                
+                # Fetch missing blocks one by one
+                for height in range(local_height + 1, remote_height + 1):
+                    block = await self.get_remote_block(endpoint, height)
+                    if block:
+                        # Format block data for import
+                        import_data = {
+                            "height": block.get("height"),
+                            "hash": block.get("hash"),
+                            "parent_hash": block.get("parent_hash"),
+                            "proposer": block.get("proposer"),
+                            "timestamp": block.get("timestamp"),
+                            "tx_count": block.get("tx_count", 0),
+                            "state_root": block.get("state_root"),
+                            "transactions": block.get("transactions", []),
+                            "receipts": block.get("receipts", [])
+                        }
+                        success = await self.import_block(import_data)
+                        if success:
+                            logger.info(f"Imported block {height} from {endpoint}")
+                            local_height = height
+                        else:
+                            logger.error(f"Failed to import block {height}")
+                            break
+                    else:
+                        logger.error(f"Failed to fetch block {height} from {endpoint}")
+                        break
+                        
+    async def get_remote_mempool(self, endpoint: str) -> List[Dict[str, Any]]:
+        """Get mempool transactions from a remote node."""
+        try:
+            response = await self.client.get(f"{endpoint.rstrip('/')}/mempool")
+            if response.status_code == 200:
+                return response.json()
+        except Exception as e:
+            logger.error(f"Failed to get mempool from {endpoint}: {e}")
+        return []
+        
+    async def get_local_mempool(self) -> List[Dict[str, Any]]:
+        """Get local mempool transactions."""
+        try:
+            response = await self.client.get(f"{self.local_rpc_url}/rpc/mempool")
+            if response.status_code == 200:
+                return response.json()
+        except Exception as e:
+            logger.error(f"Failed to get local mempool: {e}")
+        return []
+        
+    async def submit_transaction(self, tx_data: Dict[str, Any]) -> bool:
+        """Submit a transaction to the local node."""
+        try:
+            response = await self.client.post(
+                f"{self.local_rpc_url}/rpc/transaction",
+                json=tx_data
+            )
+            return response.status_code == 200
+        except Exception as e:
+            logger.error(f"Failed to submit transaction: {e}")
+            return False
+            
+    async def sync_transactions(self) -> None:
+        """Sync transactions from remote mempools."""
+        local_mempool = await self.get_local_mempool()
+        local_tx_hashes = {tx.get('hash') for tx in local_mempool}
+        
+        for endpoint in self.remote_endpoints:
+            remote_mempool = await self.get_remote_mempool(endpoint)
+            for tx in remote_mempool:
+                tx_hash = tx.get('hash')
+                if tx_hash and tx_hash not in local_tx_hashes:
+                    success = await self.submit_transaction(tx)
+                    if success:
+                        logger.info(f"Imported transaction {tx_hash[:8]}... from {endpoint}")
+                        
+    async def sync_loop(self) -> None:
+        """Main synchronization loop."""
+        logger.info("Starting cross-site sync loop")
+        
+        while True:
+            try:
+                # Sync blocks
+                await self.sync_with_remotes()
+                
+                # Sync transactions
+                await self.sync_transactions()
+                
+            except Exception as e:
+                logger.error(f"Error in sync loop: {e}")
+                
+            await asyncio.sleep(self.poll_interval)
+            
+    async def start(self) -> None:
+        """Start the synchronization task."""
+        if self.sync_task is None:
+            self.sync_task = asyncio.create_task(self.sync_loop())
+            
+    async def stop(self) -> None:
+        """Stop the synchronization task."""
+        if self.sync_task:
+            self.sync_task.cancel()
+            try:
+                await self.sync_task
+            except asyncio.CancelledError:
+                pass
+            self.sync_task = None
+            
+        await self.client.aclose()

tests/test_blockchain_final.py

@@ -0,0 +1,90 @@
+#!/usr/bin/env python3
+"""
+Final test and summary for blockchain nodes
+"""
+
+import httpx
+import json
+
+# Node URLs
+NODES = {
+    "node1": {"url": "http://127.0.0.1:8082", "name": "Node 1"},
+    "node2": {"url": "http://127.0.0.1:8081", "name": "Node 2"},
+}
+
+def test_nodes():
+    """Test both nodes"""
+    print("🔗 AITBC Blockchain Node Test Summary")
+    print("=" * 60)
+    
+    results = []
+    
+    for node_id, node in NODES.items():
+        print(f"\n{node['name']}:")
+        
+        # Test RPC API
+        try:
+            response = httpx.get(f"{node['url']}/openapi.json", timeout=5)
+            api_ok = response.status_code == 200
+            print(f"  RPC API: {'✅' if api_ok else '❌'}")
+        except:
+            api_ok = False
+            print(f"  RPC API: ❌")
+        
+        # Test chain head
+        try:
+            response = httpx.get(f"{node['url']}/rpc/head", timeout=5)
+            if response.status_code == 200:
+                head = response.json()
+                height = head.get('height', 0)
+                print(f"  Chain Height: {height}")
+                
+                # Test faucet
+                try:
+                    response = httpx.post(
+                        f"{node['url']}/rpc/admin/mintFaucet",
+                        json={"address": "aitbc1test000000000000000000000000000000000000", "amount": 100},
+                        timeout=5
+                    )
+                    faucet_ok = response.status_code == 200
+                    print(f"  Faucet: {'✅' if faucet_ok else '❌'}")
+                except:
+                    faucet_ok = False
+                    print(f"  Faucet: ❌")
+                
+                results.append({
+                    'node': node['name'],
+                    'api': api_ok,
+                    'height': height,
+                    'faucet': faucet_ok
+                })
+            else:
+                print(f"  Chain Head: ❌")
+        except:
+            print(f"  Chain Head: ❌")
+    
+    # Summary
+    print("\n\n📊 Test Results Summary")
+    print("=" * 60)
+    
+    for result in results:
+        status = "✅ OPERATIONAL" if result['api'] and result['faucet'] else "⚠️  PARTIAL"
+        print(f"{result['node']:.<20} {status}")
+        print(f"  - RPC API: {'✅' if result['api'] else '❌'}")
+        print(f"  - Height: {result['height']}")
+        print(f"  - Faucet: {'✅' if result['faucet'] else '❌'}")
+    
+    print("\n\n📝 Notes:")
+    print("- Both nodes are running independently")
+    print("- Each node maintains its own chain")
+    print("- Nodes are not connected (different heights)")
+    print("- To connect nodes in production:")
+    print("  1. Deploy on separate servers")
+    print("  2. Use Redis for gossip backend")
+    print("  3. Configure P2P peer discovery")
+    print("  4. Ensure network connectivity")
+    
+    print("\n✅ Test completed successfully!")
+
+if __name__ == "__main__":
+    test_nodes()

tests/test_blockchain_nodes.py

@@ -0,0 +1,326 @@
+#!/usr/bin/env python3
+"""
+Test script for AITBC blockchain nodes
+Tests both nodes for functionality and consistency
+"""
+
+import httpx
+import json
+import time
+import sys
+from typing import Dict, Any, Optional
+
+# Configuration
+NODES = {
+    "node1": {"url": "http://127.0.0.1:8082", "name": "Node 1"},
+    "node2": {"url": "http://127.0.0.1:8081", "name": "Node 2"},
+}
+
+# Test addresses
+TEST_ADDRESSES = {
+    "alice": "aitbc1alice00000000000000000000000000000000000",
+    "bob": "aitbc1bob0000000000000000000000000000000000000",
+    "charlie": "aitbc1charl0000000000000000000000000000000000",
+}
+
+def print_header(message: str):
+    """Print test header"""
+    print(f"\n{'='*60}")
+    print(f" {message}")
+    print(f"{'='*60}")
+
+def print_step(message: str):
+    """Print test step"""
+    print(f"\n→ {message}")
+
+def print_success(message: str):
+    """Print success message"""
+    print(f"✅ {message}")
+
+def print_error(message: str):
+    """Print error message"""
+    print(f"❌ {message}")
+
+def print_warning(message: str):
+    """Print warning message"""
+    print(f"⚠️  {message}")
+
+def check_node_health(node_name: str, node_config: Dict[str, str]) -> bool:
+    """Check if node is responsive"""
+    try:
+        response = httpx.get(f"{node_config['url']}/openapi.json", timeout=5)
+        if response.status_code == 200:
+            print_success(f"{node_config['name']} is responsive")
+            return True
+        else:
+            print_error(f"{node_config['name']} returned status {response.status_code}")
+            return False
+    except Exception as e:
+        print_error(f"{node_config['name']} is not responding: {e}")
+        return False
+
+def get_chain_head(node_name: str, node_config: Dict[str, str]) -> Optional[Dict[str, Any]]:
+    """Get current chain head from node"""
+    try:
+        response = httpx.get(f"{node_config['url']}/rpc/head", timeout=5)
+        if response.status_code == 200:
+            return response.json()
+        else:
+            print_error(f"Failed to get chain head from {node_config['name']}: {response.status_code}")
+            return None
+    except Exception as e:
+        print_error(f"Error getting chain head from {node_config['name']}: {e}")
+        return None
+
+def get_balance(node_name: str, node_config: Dict[str, str], address: str) -> Optional[int]:
+    """Get balance for an address"""
+    try:
+        response = httpx.get(f"{node_config['url']}/rpc/getBalance/{address}", timeout=5)
+        if response.status_code == 200:
+            data = response.json()
+            return data.get("balance", 0)
+        else:
+            print_error(f"Failed to get balance from {node_config['name']}: {response.status_code}")
+            return None
+    except Exception as e:
+        print_error(f"Error getting balance from {node_config['name']}: {e}")
+        return None
+
+def mint_faucet(node_name: str, node_config: Dict[str, str], address: str, amount: int) -> bool:
+    """Mint tokens to an address (devnet only)"""
+    try:
+        response = httpx.post(
+            f"{node_config['url']}/rpc/admin/mintFaucet",
+            json={"address": address, "amount": amount},
+            timeout=5
+        )
+        if response.status_code == 200:
+            print_success(f"Minted {amount} tokens to {address} on {node_config['name']}")
+            return True
+        else:
+            print_error(f"Failed to mint on {node_config['name']}: {response.status_code}")
+            print(f"Response: {response.text}")
+            return False
+    except Exception as e:
+        print_error(f"Error minting on {node_config['name']}: {e}")
+        return False
+
+def send_transaction(node_name: str, node_config: Dict[str, str], tx: Dict[str, Any]) -> Optional[str]:
+    """Send a transaction"""
+    try:
+        response = httpx.post(
+            f"{node_config['url']}/rpc/sendTx",
+            json=tx,
+            timeout=5
+        )
+        if response.status_code == 200:
+            data = response.json()
+            return data.get("tx_hash")
+        else:
+            print_error(f"Failed to send transaction on {node_config['name']}: {response.status_code}")
+            print(f"Response: {response.text}")
+            return None
+    except Exception as e:
+        print_error(f"Error sending transaction on {node_config['name']}: {e}")
+        return None
+
+def wait_for_block(node_name: str, node_config: Dict[str, str], target_height: int, timeout: int = 30) -> bool:
+    """Wait for node to reach a target block height"""
+    start_time = time.time()
+    while time.time() - start_time < timeout:
+        head = get_chain_head(node_name, node_config)
+        if head and head.get("height", 0) >= target_height:
+            return True
+        time.sleep(1)
+    return False
+
+def test_node_connectivity():
+    """Test if both nodes are running and responsive"""
+    print_header("Testing Node Connectivity")
+    
+    all_healthy = True
+    for node_name, node_config in NODES.items():
+        if not check_node_health(node_name, node_config):
+            all_healthy = False
+    
+    assert all_healthy, "Not all nodes are healthy"
+
+def test_chain_consistency():
+    """Test if both nodes have consistent chain heads"""
+    print_header("Testing Chain Consistency")
+    
+    heads = {}
+    for node_name, node_config in NODES.items():
+        print_step(f"Getting chain head from {node_config['name']}")
+        head = get_chain_head(node_name, node_config)
+        if head:
+            heads[node_name] = head
+            print(f"  Height: {head.get('height', 'unknown')}")
+            print(f"  Hash: {head.get('hash', 'unknown')[:16]}...")
+        else:
+            print_error(f"Failed to get chain head from {node_config['name']}")
+    
+    if len(heads) == len(NODES):
+        # Compare heights
+        heights = [head.get("height", 0) for head in heads.values()]
+        if len(set(heights)) == 1:
+            print_success("Both nodes have the same block height")
+        else:
+            print_error(f"Node heights differ: {heights}")
+        
+        # Compare hashes
+        hashes = [head.get("hash", "") for head in heads.values()]
+        if len(set(hashes)) == 1:
+            print_success("Both nodes have the same chain hash")
+        else:
+            print_warning("Nodes have different chain hashes (may be syncing)")
+    
+    assert len(heads) == len(NODES), "Failed to get chain heads from all nodes"
+
+def test_faucet_and_balances():
+    """Test faucet minting and balance queries"""
+    print_header("Testing Faucet and Balances")
+    
+    # Test on node1
+    print_step("Testing faucet on Node 1")
+    if mint_faucet("node1", NODES["node1"], TEST_ADDRESSES["alice"], 1000):
+        time.sleep(2)  # Wait for block
+        
+        # Check balance on both nodes
+        for node_name, node_config in NODES.items():
+            balance = get_balance(node_name, node_config, TEST_ADDRESSES["alice"])
+            if balance is not None:
+                print(f"  {node_config['name']} balance for alice: {balance}")
+                if balance >= 1000:
+                    print_success(f"Balance correct on {node_config['name']}")
+                else:
+                    print_error(f"Balance incorrect on {node_config['name']}")
+            else:
+                print_error(f"Failed to get balance from {node_config['name']}")
+    
+    # Test on node2
+    print_step("Testing faucet on Node 2")
+    if mint_faucet("node2", NODES["node2"], TEST_ADDRESSES["bob"], 500):
+        time.sleep(2)  # Wait for block
+        
+        # Check balance on both nodes
+        for node_name, node_config in NODES.items():
+            balance = get_balance(node_name, node_config, TEST_ADDRESSES["bob"])
+            if balance is not None:
+                print(f"  {node_config['name']} balance for bob: {balance}")
+                if balance >= 500:
+                    print_success(f"Balance correct on {node_config['name']}")
+                else:
+                    print_error(f"Balance incorrect on {node_config['name']}")
+            else:
+                print_error(f"Failed to get balance from {node_config['name']}")
+
+def test_transaction_submission():
+    """Test transaction submission between addresses"""
+    print_header("Testing Transaction Submission")
+    
+    # First ensure alice has funds
+    print_step("Ensuring alice has funds")
+    mint_faucet("node1", NODES["node1"], TEST_ADDRESSES["alice"], 2000)
+    time.sleep(2)
+    
+    # Create a transfer transaction (simplified - normally needs proper signing)
+    print_step("Submitting transfer transaction")
+    tx = {
+        "type": "TRANSFER",
+        "sender": TEST_ADDRESSES["alice"],
+        "nonce": 0,
+        "fee": 10,
+        "payload": {
+            "to": TEST_ADDRESSES["bob"],
+            "amount": 100
+        },
+        "sig": None  # In devnet, signature might be optional
+    }
+    
+    tx_hash = send_transaction("node1", NODES["node1"], tx)
+    if tx_hash:
+        print_success(f"Transaction submitted: {tx_hash[:16]}...")
+        time.sleep(3)  # Wait for inclusion
+        
+        # Check final balances
+        print_step("Checking final balances")
+        for node_name, node_config in NODES.items():
+            alice_balance = get_balance(node_name, node_config, TEST_ADDRESSES["alice"])
+            bob_balance = get_balance(node_name, node_config, TEST_ADDRESSES["bob"])
+            
+            if alice_balance is not None and bob_balance is not None:
+                print(f"  {node_config['name']}: alice={alice_balance}, bob={bob_balance}")
+    else:
+        print_error("Failed to submit transaction")
+
+def test_block_production():
+    """Test that nodes are producing blocks"""
+    print_header("Testing Block Production")
+    
+    initial_heights = {}
+    for node_name, node_config in NODES.items():
+        head = get_chain_head(node_name, node_config)
+        if head:
+            initial_heights[node_name] = head.get("height", 0)
+            print(f"  {node_config['name']} initial height: {initial_heights[node_name]}")
+    
+    print_step("Waiting for new blocks...")
+    time.sleep(10)  # Wait for block production (2s block time)
+    
+    final_heights = {}
+    for node_name, node_config in NODES.items():
+        head = get_chain_head(node_name, node_config)
+        if head:
+            final_heights[node_name] = head.get("height", 0)
+            print(f"  {node_config['name']} final height: {final_heights[node_name]}")
+    
+    # Check if blocks were produced
+    for node_name in NODES:
+        if node_name in initial_heights and node_name in final_heights:
+            produced = final_heights[node_name] - initial_heights[node_name]
+            if produced > 0:
+                print_success(f"{NODES[node_name]['name']} produced {produced} block(s)")
+            else:
+                print_error(f"{NODES[node_name]['name']} produced no blocks")
+
+def main():
+    """Run all tests"""
+    print_header("AITBC Blockchain Node Test Suite")
+    
+    tests = [
+        ("Node Connectivity", test_node_connectivity),
+        ("Chain Consistency", test_chain_consistency),
+        ("Faucet and Balances", test_faucet_and_balances),
+        ("Transaction Submission", test_transaction_submission),
+        ("Block Production", test_block_production),
+    ]
+    
+    results = {}
+    for test_name, test_func in tests:
+        try:
+            results[test_name] = test_func()
+        except Exception as e:
+            print_error(f"Test '{test_name}' failed with exception: {e}")
+            results[test_name] = False
+    
+    # Summary
+    print_header("Test Summary")
+    passed = sum(1 for result in results.values() if result)
+    total = len(results)
+    
+    for test_name, result in results.items():
+        status = "✅ PASSED" if result else "❌ FAILED"
+        print(f"{test_name:.<40} {status}")
+    
+    print(f"\nOverall: {passed}/{total} tests passed")
+    
+    if passed == total:
+        print_success("All tests passed! 🎉")
+        return 0
+    else:
+        print_error("Some tests failed. Check the logs above.")
+        return 1
+
+if __name__ == "__main__":
+    sys.exit(main())

tests/test_blockchain_simple.py

@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+"""
+Simple test to verify blockchain nodes are working independently
+and demonstrate how to configure them for networking
+"""
+
+import httpx
+import json
+import time
+
+# Node URLs
+NODES = {
+    "node1": "http://127.0.0.1:8082",
+    "node2": "http://127.0.0.1:8081",
+}
+
+def test_node_basic_functionality():
+    """Test basic functionality of each node"""
+    print("Testing Blockchain Node Functionality")
+    print("=" * 60)
+    
+    for name, url in NODES.items():
+        print(f"\nTesting {name}:")
+        
+        # Check if node is responsive
+        try:
+            response = httpx.get(f"{url}/openapi.json", timeout=5)
+            print(f"  ✅ Node responsive")
+        except:
+            print(f"  ❌ Node not responding")
+            continue
+        
+        # Get chain head
+        try:
+            response = httpx.get(f"{url}/rpc/head", timeout=5)
+            if response.status_code == 200:
+                head = response.json()
+                print(f"  ✅ Chain height: {head.get('height', 'unknown')}")
+            else:
+                print(f"  ❌ Failed to get chain head")
+        except:
+            print(f"  ❌ Error getting chain head")
+        
+        # Test faucet
+        try:
+            response = httpx.post(
+                f"{url}/rpc/admin/mintFaucet",
+                json={"address": "aitbc1test000000000000000000000000000000000000", "amount": 100},
+                timeout=5
+            )
+            if response.status_code == 200:
+                print(f"  ✅ Faucet working")
+            else:
+                print(f"  ❌ Faucet failed: {response.status_code}")
+        except:
+            print(f"  ❌ Error testing faucet")
+
+def show_networking_config():
+    """Show how to configure nodes for networking"""
+    print("\n\nNetworking Configuration")
+    print("=" * 60)
+    
+    print("""
+To connect the blockchain nodes in a network, you need to:
+
+1. Use a shared gossip backend (Redis or Starlette Broadcast):
+
+   For Starlette Broadcast (simpler):
+   - Node 1 .env:
+     GOSSIP_BACKEND=broadcast
+     GOSSIP_BROADCAST_URL=http://127.0.0.1:7070/gossip
+     
+   - Node 2 .env:
+     GOSSIP_BACKEND=broadcast
+     GOSSIP_BROADCAST_URL=http://127.0.0.1:7070/gossip
+
+2. Start a gossip relay service:
+   python -m aitbc_chain.gossip.relay --port 7070
+
+3. Configure P2P discovery:
+   - Add peer list to configuration
+   - Ensure ports are accessible between nodes
+
+4. For production deployment:
+   - Use Redis as gossip backend
+   - Configure proper network addresses
+   - Set up peer discovery mechanism
+
+Current status: Nodes are running independently with memory backend.
+They work correctly but don't share blocks or transactions.
+""")
+
+def main():
+    test_node_basic_functionality()
+    show_networking_config()
+
+if __name__ == "__main__":
+    main()