Back to Components

# Blockchain Node

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