aitbc/apps/blockchain-node

Blockchain Node (Brother Chain)

Minimal asset-backed blockchain node that validates compute receipts and mints AIT tokens.

Status

✅ Operational — Core blockchain functionality implemented and running.

Capabilities

• PoA consensus with single proposer (devnet)
• Transaction processing (TRANSFER, RECEIPT_CLAIM)
• Receipt validation and minting
• Gossip-based peer-to-peer networking (in-memory backend)
• RESTful RPC API (/rpc/*)
• Prometheus metrics (/metrics)
• Health check endpoint (/health)
• SQLite persistence with Alembic migrations

Quickstart (Devnet)

The blockchain node is already set up with a virtualenv. To launch:

cd /opt/aitbc/apps/blockchain-node
source .venv/bin/activate
bash scripts/devnet_up.sh

This will:

1. Generate genesis block at data/devnet/genesis.json
2. Start the blockchain node proposer loop (PID logged)
3. Start RPC API on http://127.0.0.1:8026
4. Start mock coordinator on http://127.0.0.1:8090

Press Ctrl+C to stop all processes.

Manual Startup

If you prefer to start components separately:

# Terminal 1: Blockchain node
cd /opt/aitbc/apps/blockchain-node
source .venv/bin/activate
PYTHONPATH=src python -m aitbc_chain.main

# Terminal 2: RPC API
cd /opt/aitbc/apps/blockchain-node
source .venv/bin/activate
PYTHONPATH=src uvicorn aitbc_chain.app:app --host 127.0.0.1 --port 8026

# Terminal 3: Mock coordinator (optional, for testing)
cd /opt/aitbc/apps/blockchain-node
source .venv/bin/activate
PYTHONPATH=src uvicorn mock_coordinator:app --host 127.0.0.1 --port 8090

API Endpoints

Once running, the RPC API is available at http://127.0.0.1:8026/rpc.

Health & Metrics

• GET /health — Health check with node info
• GET /metrics — Prometheus-format metrics

Blockchain Queries

• GET /rpc/head — Current chain head block
• GET /rpc/blocks/{height} — Get block by height
• GET /rpc/blocks-range?start=0&end=10 — Get block range
• GET /rpc/info — Chain information
• GET /rpc/supply — Token supply info
• GET /rpc/validators — List validators
• GET /rpc/state — Full state dump

Transactions

• POST /rpc/sendTx — Submit transaction (JSON body: TransactionRequest)
• GET /rpc/transactions — Latest transactions
• GET /rpc/tx/{tx_hash} — Get transaction by hash
• POST /rpc/estimateFee — Estimate fee for transaction type

Receipts (Compute Proofs)

• POST /rpc/submitReceipt — Submit receipt claim
• GET /rpc/receipts — Latest receipts
• GET /rpc/receipts/{receipt_id} — Get receipt by ID

Accounts

• GET /rpc/getBalance/{address} — Account balance
• GET /rpc/address/{address} — Address details + txs
• GET /rpc/addresses — List active addresses

Admin

• POST /rpc/admin/mintFaucet — Mint devnet funds (requires admin key)

Sync

• GET /rpc/syncStatus — Chain sync status

CLI Integration

Use the AITBC CLI to interact with the node:

source /opt/aitbc/cli/venv/bin/activate
aitbc blockchain status
aitbc blockchain head
aitbc blockchain balance --address <your-address>
aitbc blockchain faucet --address <your-address> --amount 1000

Configuration

Edit .env in this directory to change:

CHAIN_ID=ait-devnet
DB_PATH=./data/chain.db
RPC_BIND_HOST=0.0.0.0
RPC_BIND_PORT=8026
P2P_BIND_HOST=0.0.0.0
P2P_BIND_PORT=7070
PROPOSER_KEY=proposer_key_<timestamp>
MINT_PER_UNIT=1000
COORDINATOR_RATIO=0.05
GOSSIP_BACKEND=memory

Restart the node after changes.

Project Layout

blockchain-node/
├── src/aitbc_chain/
│   ├── app.py           # FastAPI app + routes
│   ├── main.py          # Proposer loop + startup
│   ├── config.py        # Settings from .env
│   ├── database.py      # DB init + session mgmt
│   ├── mempool.py       # Transaction mempool
│   ├── gossip/          # P2P message bus
│   ├── consensus/       # PoA proposer logic
│   ├── rpc/             # RPC endpoints
│   ├── contracts/       # Smart contract logic
│   └── models.py        # SQLModel definitions
├── data/
│   └── devnet/
│       └── genesis.json # Generated by make_genesis.py
├── scripts/
│   ├── make_genesis.py  # Genesis generator
│   ├── devnet_up.sh     # Devnet launcher
│   └── keygen.py        # Keypair generator
└── .env                  # Node configuration

Notes

• The node uses proof-of-authority (PoA) consensus with a single proposer for the devnet.
• Transactions require a valid signature (ed25519) unless running in test mode.
• Receipts represent compute work attestations and mint new AIT tokens to the miner.
• Gossip backend defaults to in-memory; for multi-node networks, configure a Redis backend.
• RPC API does not require authentication on devnet (add in production).

Troubleshooting

Port already in use: Change RPC_BIND_PORT in .env and restart.

Database locked: Ensure only one node instance is running; delete data/chain.db if corrupted.

No blocks proposed: Check proposer logs; ensure PROPOSER_KEY is set and no other proposers are conflicting.

Mock coordinator not responding: It's only needed for certain tests; the blockchain node can run standalone.