aitbc/docs/architecture/4_blockchain-node.md

Blockchain Node - AITBC Documentation

PoA/PoS consensus blockchain with REST/WebSocket RPC, real-time gossip layer, and comprehensive observability

● Live

Overview

The AITBC Blockchain Node is the core infrastructure component that maintains the distributed ledger. It implements a hybrid Proof-of-Authority/Proof-of-Stake consensus mechanism with fast finality and supports high throughput for AI workload transactions.

Key Features

• Hybrid PoA/PoS consensus with sub-second finality
• REST and WebSocket RPC APIs
• Real-time gossip protocol for block propagation
• Comprehensive observability with Prometheus metrics
• SQLModel-based data persistence
• Built-in devnet tooling and scripts

Architecture

The blockchain node is built with a modular architecture separating concerns for consensus, storage, networking, and API layers.

Consensus Engine

Hybrid PoA/PoS with proposer rotation and validator sets

Storage Layer

SQLModel with SQLite/PostgreSQL support

Networking

WebSocket gossip + REST API

Observability

Prometheus metrics + structured logging

API Reference

The blockchain node exposes both REST and WebSocket APIs for interaction.

REST Endpoints

GET /rpc/get_head Get the latest block header

POST /rpc/send_tx Submit a new transaction

GET /rpc/get_balance/{address} Get account balance

GET /rpc/get_block/{height} Get block by height

WebSocket Subscriptions

• new_blocks - Real-time block notifications
• new_transactions - Transaction pool updates
• consensus_events - Consensus round updates

Configuration

The node can be configured via environment variables or configuration file.

Key Settings

# Database
DATABASE_URL=sqlite:///blockchain.db

# Network
RPC_HOST=0.0.0.0
RPC_PORT=9080
WS_PORT=9081

# Consensus
CONSENSUS_MODE=poa
VALIDATOR_ADDRESS=0x...
BLOCK_TIME=1s

# Observability
METRICS_PORT=9090
LOG_LEVEL=info

Running a Node

Development Mode

# Initialize devnet
python -m blockchain.scripts.init_devnet

# Start node
python -m blockchain.main --config devnet.yaml

Production Mode

# Using Docker
docker run -d \
  -v /data/blockchain:/data \
  -p 9080:9080 \
  -p 9081:9081 \
  -p 9090:9090 \
  aitbc/blockchain-node:latest

Monitoring

Prometheus Metrics

Available at http://localhost:9090/metrics

Key metrics:

• blockchain_blocks_total - Total blocks produced
• blockchain_transactions_total - Total transactions processed
• blockchain_consensus_rounds - Consensus rounds completed
• blockchain_network_peers - Active peer connections

Health Checks

# Node status
curl http://localhost:9080/health

# Sync status
curl http://localhost:9080/sync_status

Troubleshooting

Common Issues

1. Node not syncing

   • Check peer connections: curl /rpc/peers
   • Verify network connectivity
   • Check logs for consensus errors

2. High memory usage

   • Reduce block_cache_size in config
   • Enable block pruning

3. RPC timeouts

   • Increase rpc_timeout setting
   • Check system resources

Development

Building from Source

git clone https://github.com/aitbc/blockchain
cd blockchain
pip install -e .

Running Tests

# Unit tests
pytest tests/

# Integration tests
pytest tests/integration/

Security Considerations

• Validator keys should be kept secure
• Use HTTPS in production
• Implement rate limiting on RPC endpoints
• Regular security updates for dependencies