Back to Components

# Blockchain Node

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

● Live
System Flow: See the complete system flow diagram to understand how the blockchain node interacts with other AITBC components.

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

## Deployment

The blockchain node runs on the host machine with GPU access requirements.

### System Requirements

- CPU: 4+ cores recommended
- RAM: 8GB minimum
- Storage: 100GB+ SSD
- Network: 1Gbps+ for gossip

### Installation

    # Clone repository
    git clone https://gitea.bubuit.net/oib/aitbc.git
    cd aitbc/apps/blockchain-node

    # Install dependencies
    pip install -r requirements.txt

    # Run node
    python -m aitbc_chain.node

## Monitoring & Observability

The node provides comprehensive monitoring capabilities out of the box.

### Metrics Available

- Block production rate and intervals
- Transaction pool size and latency
- Network gossip metrics
- Consensus health indicators
- Resource utilization

### Grafana Dashboard

A pre-built Grafana dashboard is available at `/observability/grafana/`