aitbc/docs/guides/getting-started/WORKING_SETUP.md

Brother Chain Deployment — Working Configuration

Agent: aitbc
Branch: aitbc/debug-brother-chain
Date: 2026-03-13

✅ Services Running on aitbc (main chain host)

• Coordinator API: http://10.1.223.93:8000 (healthy)
• Wallet Daemon: http://10.1.223.93:8002 (active)
• Blockchain Node: 10.1.223.93:8005 (PoA, 3s blocks)

---

🛠️ Systemd Override Pattern for Blockchain Node

The base service /etc/systemd/system/aitbc-blockchain-node.service:

[Unit]
Description=AITBC Blockchain Node
After=network.target

[Service]
Type=simple
User=aitbc
Group=aitbc
WorkingDirectory=/opt/aitbc/apps/blockchain-node
Restart=always
RestartSec=5
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

The override /etc/systemd/system/aitbc-blockchain-node.service.d/override.conf:

[Service]
Environment=NODE_PORT=8005
Environment=PYTHONPATH=/opt/aitbc/apps/blockchain-node/src:/opt/aitbc/apps/blockchain-node/scripts
ExecStart=
ExecStart=/opt/aitbc/apps/blockchain-node/.venv/bin/python3 -m uvicorn aitbc_chain.app:app --host 0.0.0.0 --port 8005

This runs the FastAPI app on port 8005. The aitbc_chain.app module provides the RPC API.

---

🔑 Coordinator API Configuration

File: /opt/aitbc/apps/coordinator-api/.env

MINER_API_KEYS=["your_key_here"]
DATABASE_URL=sqlite:///./aitbc_coordinator.db
LOG_LEVEL=INFO
ENVIRONMENT=development
API_HOST=0.0.0.0
API_PORT=8000
WORKERS=2
# Note: No miner service needed (CPU-only)

Important: MINER_API_KEYS must be a JSON array string, not comma-separated list.

---

💰 Wallet Files

Brother chain wallet for aitbc1 (pre-allocated):

/opt/aitbc/.aitbc/wallets/aitbc1.json

Contents (example):

{
  "name": "aitbc1",
  "address": "aitbc1aitbc1_simple",
  "balance": 500.0,
  "type": "simple",
  "created_at": "2026-03-13T12:00:00Z",
  "transactions": [ ... ]
}

Main chain wallet (separate):

/opt/aitbc/.aitbc/wallets/aitbc1_main.json

---

📦 Genesis Configuration

File: /opt/aitbc/genesis_brother_chain_*.yaml

Key properties:

• chain_id: aitbc-brother-chain
• chain_type: topic
• purpose: brother-connection
• privacy.visibility: private
• consensus.algorithm: poa
• block_time: 3 seconds
• accounts: includes aitbc1aitbc1_simple with 500 AITBC

---

🧪 Validation Steps

1. Coordinator health:

   curl http://localhost:8011/health
   # Expected: {"status":"ok",...}
   

2. Wallet balance (once wallet daemon is up and wallet file present):

   # Coordinator forwards to wallet daemon
   curl http://localhost:8011/v1/agent-identity/identities/.../wallets/<chain_id>/balance
   

3. Blockchain node health:

   curl http://localhost:8005/health
   # Or if using uvicorn default: /health
   

4. Chain head:

   curl http://localhost:8005/rpc/head
   

---

🔗 Peer Connection

Once brother chain node (aitbc1) is running on port 8005 (or 18001 if they choose), add peer:

On aitbc main chain node, probably need to call a method to add static peer or rely on gossip.

If using memory gossip backend, they need to be directly addressable. Configure:

• aitbc1 node: --host 0.0.0.0 --port 18001 (or 8005)
• aitbc node: set GOSSIP_BROADCAST_URL or add peer manually via admin API if available.

Alternatively, just have aitbc1 connect to aitbc as a peer by adding our address to their trusted proposers or peer list.

---

📝 Notes

• Both hosts are root in incus containers, no sudo required for systemd commands.
• Network: aitbc (10.1.223.93), aitbc1 (10.1.223.40) — reachable via internal IPs.
• Ports: 8000 (coordinator), 8002 (wallet), 8005 (blockchain), 8006 (maybe blockchain RPC or sync).
• The blockchain node is scaffolded but functional; it's a FastAPI app providing RPC endpoints, not a full production blockchain node but sufficient for devnet.

---

⚙️ Dependencies Installation

For each app under /opt/aitbc/apps/*:

cd /opt/aitbc/apps/<app-name>
python3 -m venv .venv
source .venv/bin/activate
pip install -e .  # if setup.py/pyproject.toml exists
# or pip install -r requirements.txt

For coordinator-api and wallet, they may share dependencies. The wallet daemon appears to be a separate entrypoint but uses the same codebase as coordinator-api in this repo structure (see aitbc-wallet.service pointing to app.main:app with SERVICE_TYPE=wallet).

---

Status: Coordinator and wallet up on my side. Blockchain node running. Ready to peer.