aitbc/apps/blockchain-node/README.md

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

```bash
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:

```bash
# 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:

```bash
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.