aitbc/docs/reference/components/blockchain_node.md

Blockchain Node – Task Breakdown

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 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

• Project Scaffolding

  • ✅ Create apps/blockchain-node/src/ module layout (types.py, state.py, blocks.py, mempool.py, consensus.py, rpc.py, p2p.py, receipts.py, settings.py).
  • ✅ Add requirements.txt with FastAPI, SQLModel, websockets, orjson, python-dotenv.
  • ✅ Provide .env.example with CHAIN_ID, DB_PATH, bind addresses, proposer key.

• State & Persistence

  • ✅ Implement SQLModel tables for blocks, transactions, accounts, receipts, peers, params.
  • ✅ Set up database initialization and genesis loading.
  • ✅ Provide migration or reset script under scripts/.

• RPC Layer

  • ✅ Build FastAPI app exposing /rpc/* endpoints (sendTx, getTx, getBlock, getHead, getBalance, submitReceipt, metrics).
  • ✅ Implement admin endpoints for devnet (mintFaucet, paramSet, peers/add).

• Consensus & Block Production

  • ✅ 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.

• Devnet Tooling

  • ✅ Provide scripts/devnet_up.sh launching bootstrap node and mocks.
  • Document curl commands for faucet, transfer, receipt submission.

Production Deployment Details

Multi-Site Deployment

• Site A (localhost): 2 nodes (ports 8081, 8082) - https://aitbc.bubuit.net/rpc/ and /rpc2/
• Site B (remote host): ns3 server (95.216.198.140)
• Site C (remote container): 1 node (port 8082) - http://aitbc.keisanki.net/rpc/
• Service: systemd services for blockchain-node, blockchain-node-2, blockchain-rpc
• Proxy: nginx routes /rpc/, /rpc2/, /v1/ to appropriate services
• 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

# 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