fix: resolve CLI service imports and update blockchain documentation

- Add proper package imports for coordinator-api services - Fix 6 command modules to use app.services.* with clean path resolution - Remove brittle path hacks and user-specific fallbacks - Update blockchain-node README with operational status, API endpoints, and troubleshooting - Add blockchain section to main README with quick launch and CLI examples - Remove generated genesis.json from repository (should be ignored) These changes fix import errors in surveillance, ai-trading, ai-surveillance, advanced-analytics, regulatory, and enterprise-integration commands, and document the now-operational Brother Chain (blockchain node). Co-authored with sibling aitbc instance (coordination via Gitea).
2026-03-15 10:09:48 +00:00
parent 0a0a8a1e15
commit c390ba07c1
9 changed files with 259 additions and 177 deletions
--- a/apps/blockchain-node/README.md
+++ b/apps/blockchain-node/README.md
@@ -1,25 +1,169 @@
-# Blockchain Node
+# Blockchain Node (Brother Chain)

-## Purpose & Scope
-
-Minimal asset-backed blockchain node that validates compute receipts and mints AIT tokens as described in `docs/bootstrap/blockchain_node.md`.
+Minimal asset-backed blockchain node that validates compute receipts and mints AIT tokens.

 ## Status

-Scaffolded. Implementation pending per staged roadmap.
+✅ **Operational** — Core blockchain functionality implemented and running.

-## Devnet Tooling
+### 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

- `scripts/make_genesis.py` — Generate a deterministic devnet genesis file (`data/devnet/genesis.json`).
- `scripts/keygen.py` — Produce throwaway devnet keypairs (printed or written to disk).
- `scripts/devnet_up.sh` — Launch the blockchain node and RPC API with a freshly generated genesis file.
+## Quickstart (Devnet)

-### Quickstart
+The blockchain node is already set up with a virtualenv. To launch:

 ```bash
-cd apps/blockchain-node
-python scripts/make_genesis.py --force
+cd /opt/aitbc/apps/blockchain-node
+source .venv/bin/activate
 bash scripts/devnet_up.sh
 ```

-The script sets `PYTHONPATH=src` and starts the proposer loop plus the FastAPI app (via `uvicorn`). Press `Ctrl+C` to stop the devnet.
+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.
--- a/apps/blockchain-node/data/devnet/genesis.json
+++ b/apps/blockchain-node/data/devnet/genesis.json
@@ -1,23 +0,0 @@
-{
-  "accounts": [
-    {
-      "address": "ait1faucet000000000000000000000000000000000",
-      "balance": 1000000000,
-      "nonce": 0
-    }
-  ],
-  "authorities": [
-    {
-      "address": "ait1devproposer000000000000000000000000000000",
-      "weight": 1
-    }
-  ],
-  "chain_id": "ait-devnet",
-  "params": {
-    "base_fee": 10,
-    "coordinator_ratio": 0.05,
-    "fee_per_byte": 1,
-    "mint_per_unit": 1000
-  },
-  "timestamp": 1772895053
-}