aitbc/docs/blockchain/IMPLEMENTATION_GUIDE.md

Blockchain Node Implementation Guide

Overview

AITBC has two blockchain node implementations with different capabilities and deployment scenarios.

Implementations

1. Integrated Blockchain Node (/opt/aitbc/apps/blockchain-node)

Location: /opt/aitbc/apps/blockchain-node/src/aitbc_chain/

Used By: aitbc (localhost), aitbc1

Features:

• ✅ Full RPC API including mempool endpoint
• ✅ Integrated with AITBC monorepo
• ✅ Multi-chain support
• ✅ PostgreSQL mempool backend
• ✅ Gossip relay
• ✅ WebSocket support
• ✅ Comprehensive monitoring

RPC Endpoints:

• GET /rpc/head - Get latest block
• GET /rpc/mempool - Get mempool status ✅ AVAILABLE
• GET /rpc/block/{height} - Get specific block
• POST /rpc/broadcast_tx_commit - Submit transaction

Configuration:

• Environment file: /etc/aitbc/blockchain.env
• Port: 8006
• Database: PostgreSQL (chain-specific)

Deployment:

• Managed via systemd: aitbc-blockchain-node.service
• Part of main AITBC repository
• Updated via git pull

2. Standalone Blockchain Node (/opt/blockchain-node)

Location: /opt/blockchain-node/src/aitbc_chain/

Used By: ns3 container (hub.aitbc.bubuit.net)

Features:

• ✅ Basic RPC API
• ❌ Missing mempool endpoint
• ✅ Lightweight deployment
• ✅ Container-friendly
• ⚠️ Limited feature set compared to integrated version

RPC Endpoints:

• GET /rpc/head - Get latest block ✅
• GET /rpc/mempool - Get mempool status ❌ NOT IMPLEMENTED
• GET /rpc/block/{height} - Get specific block ✅

Configuration:

• Environment file: /etc/aitbc/blockchain.env
• Port: 8082
• Database: SQLite (default)

Deployment:

• Managed via systemd: aitbc-blockchain-node-3.service
• Standalone package (not in main repo)
• Requires manual updates

Key Differences

Feature	Integrated	Standalone
Mempool Endpoint	✅ Available	❌ Missing
Repository	Main monorepo	Standalone package
Port	8006	8082
Database	PostgreSQL	SQLite
Updates	Git pull	Manual
Multi-chain	✅ Yes	⚠️ Limited
WebSocket	✅ Yes	❌ No
Gossip Relay	✅ Yes	⚠️ Basic

Deployment Recommendations

For Production Nodes (aitbc, aitbc1, etc.)

Use: Integrated Blockchain Node

Reason:

• Full feature set including mempool endpoint
• Integrated with main codebase
• Easier maintenance and updates
• Better monitoring and observability

Setup:

# Clone main repository
git clone https://gitea.bubuit.net:3000/oib/aitbc.git /opt/aitbc
cd /opt/aitbc

# Run setup script
sudo ./scripts/setup.sh

# Start service
sudo systemctl start aitbc-blockchain-node

For Container Deployments (ns3, hub nodes)

Use: Standalone Blockchain Node (with limitations)

Reason:

• Lightweight and container-friendly
• Simplified deployment
• Suitable for hub nodes that don't need full mempool functionality

Limitations:

• No mempool RPC endpoint
• Manual updates required
• Limited feature set

Setup:

# Deploy standalone package
# (deployment script specific to container environment)

Mempool Endpoint Status

Working Endpoints

• aitbc (localhost): http://localhost:8006/rpc/mempool ✅
• aitbc1: http://localhost:8006/rpc/mempool ✅

Non-Working Endpoints

• ns3 container: http://localhost:8082/rpc/mempool ❌ (404 Not Found)

Response Format (Integrated Node Only)

{
  "success": true,
  "transactions": [],
  "count": 0
}

Troubleshooting

Mempool Endpoint Returns 404

If using standalone blockchain node:

1. This is expected behavior - the endpoint is not implemented
2. Consider migrating to integrated blockchain node if mempool access is needed
3. Update cross-site sync code to handle missing endpoint gracefully

If using integrated blockchain node:

1. Check service status: systemctl status aitbc-blockchain-node
2. Verify port: Should be 8006, not 8082
3. Check logs: journalctl -u aitbc-blockchain-node -f

Port Conflicts

• Integrated node: Uses port 8006
• Standalone node: Uses port 8082
• Ensure no port conflicts when running both implementations

Migration Guide

From Standalone to Integrated

1. Stop standalone node:

sudo systemctl stop aitbc-blockchain-node-3
sudo systemctl disable aitbc-blockchain-node-3

2. Clone main repository:

sudo git clone https://gitea.bubuit.net:3000/oib/aitbc.git /opt/aitbc
cd /opt/aitbc

3. Run setup:

sudo ./scripts/setup.sh

4. Configure environment:

sudo cp /etc/aitbc/blockchain.env.backup /etc/aitbc/blockchain.env
# Update configuration as needed

5. Start integrated node:

sudo systemctl start aitbc-blockchain-node
sudo systemctl enable aitbc-blockchain-node

6. Verify mempool endpoint:

curl http://localhost:8006/rpc/mempool

Future Work

• Implement mempool endpoint in standalone blockchain node
• Unify implementations to reduce maintenance burden
• Update setup documentation to clarify which implementation to use
• Add feature matrix to API documentation
• Implement graceful fallback for missing mempool endpoint in cross-site sync