diff --git a/.windsurf/workflows/multi-node-blockchain-setup.md b/.windsurf/workflows/multi-node-blockchain-setup.md new file mode 100644 index 00000000..6df671e1 --- /dev/null +++ b/.windsurf/workflows/multi-node-blockchain-setup.md @@ -0,0 +1,269 @@ +--- +description: Multi-node blockchain deployment and setup workflow +--- + +# Multi-Node Blockchain Deployment Workflow + +This workflow sets up a two-node AITBC blockchain network (aitbc1 as genesis authority, aitbc as follower node), creates wallets, and demonstrates cross-node transactions. + +## Prerequisites + +- SSH access to both nodes (aitbc1 and aitbc) +- Both nodes have the AITBC repository cloned +- Redis available for cross-node gossip +- Python venv at `/opt/aitbc/venv` + +## Directory Structure + +- `/opt/aitbc/venv` - Central Python virtual environment +- `/opt/aitbc/requirements.txt` - Python dependencies +- `/var/lib/aitbc/data` - Blockchain database files +- `/var/lib/aitbc/keystore` - Wallet credentials +- `/etc/aitbc/` - Configuration files +- `/var/log/aitbc/` - Service logs + +## Steps + +### 1. Prepare aitbc1 (Genesis Authority Node) + +```bash +# SSH to aitbc1 +ssh aitbc1 + +# Pull latest code +cd /opt/aitbc +git pull origin main + +# Install/update dependencies +/opt/aitbc/venv/bin/pip install -r requirements.txt + +# Create required directories +mkdir -p /var/lib/aitbc/data /var/lib/aitbc/keystore /etc/aitbc /var/log/aitbc + +# Set up environment configuration +cat > /etc/aitbc/blockchain.env << 'EOF' +# Blockchain Node Configuration (aitbc1 - genesis authority) +chain_id=ait-mainnet +supported_chains=ait-mainnet +rpc_bind_host=0.0.0.0 +rpc_bind_port=8006 +p2p_bind_host=0.0.0.0 +p2p_bind_port=7070 +proposer_id=aitbc1genesis +enable_block_production=true +block_time_seconds=10 +keystore_path=/var/lib/aitbc/keystore +keystore_password_file=/var/lib/aitbc/keystore/.password +gossip_backend=broadcast +gossip_broadcast_url=redis://localhost:6379 +db_path=/var/lib/aitbc/data/ait-mainnet/chain.db +mint_per_unit=0 +coordinator_ratio=0.05 +EOF + +# Create genesis block with wallets +cd /opt/aitbc/apps/blockchain-node +/opt/aitbc/venv/bin/python scripts/setup_production.py \ + --base-dir /opt/aitbc/apps/blockchain-node \ + --chain-id ait-mainnet \ + --total-supply 1000000000 + +# Copy genesis and allocations to standard location +mkdir -p /var/lib/aitbc/data/ait-mainnet +cp data/ait-mainnet/genesis.json /var/lib/aitbc/data/ait-mainnet/ +cp data/ait-mainnet/allocations.json /var/lib/aitbc/data/ait-mainnet/ +cp keystore/* /var/lib/aitbc/keystore/ + +# Update systemd services to use new paths +sed -i 's|EnvironmentFile=/opt/aitbc/.env|EnvironmentFile=/etc/aitbc/blockchain.env|g' /opt/aitbc/systemd/aitbc-blockchain-*.service +sed -i 's|WorkingDirectory=/opt/aitbc/apps/blockchain-node|WorkingDirectory=/opt/aitbc/apps/blockchain-node|g' /opt/aitbc/systemd/aitbc-blockchain-*.service +sed -i 's|ExecStart=/opt/aitbc/venv/bin/python|ExecStart=/opt/aitbc/venv/bin/python|g' /opt/aitbc/systemd/aitbc-blockchain-*.service + +# Enable and start blockchain services +systemctl daemon-reload +systemctl enable aitbc-blockchain-node aitbc-blockchain-rpc +systemctl start aitbc-blockchain-node aitbc-blockchain-rpc + +# Monitor startup +journalctl -f -u aitbc-blockchain-node -u aitbc-blockchain-rpc +``` + +### 2. Verify aitbc1 Genesis State + +```bash +# Check blockchain state +curl -s http://localhost:8006/rpc/head | jq . +curl -s http://localhost:8006/rpc/info | jq . +curl -s http://localhost:8006/rpc/supply | jq . + +# Check genesis wallet balance +GENESIS_ADDR=$(cat /var/lib/aitbc/keystore/aitbc1genesis.json | jq -r '.address') +curl -s "http://localhost:8006/rpc/getBalance/$GENESIS_ADDR" | jq . +``` + +### 3. Prepare aitbc (Follower Node) + +```bash +# SSH to aitbc +ssh aitbc + +# Pull latest code +cd /opt/aitbc +git pull origin main + +# Install/update dependencies +/opt/aitbc/venv/bin/pip install -r requirements.txt + +# Create required directories +mkdir -p /var/lib/aitbc/data /var/lib/aitbc/keystore /etc/aitbc /var/log/aitbc + +# Set up follower configuration +cat > /etc/aitbc/blockchain.env << 'EOF' +# Blockchain Node Configuration (aitbc - follower node) +chain_id=ait-mainnet +supported_chains=ait-mainnet +rpc_bind_host=0.0.0.0 +rpc_bind_port=8006 +p2p_bind_host=0.0.0.0 +p2p_bind_port=7070 +proposer_id=follower-node-aitbc +enable_block_production=false +block_time_seconds=10 +keystore_path=/var/lib/aitbc/keystore +keystore_password_file=/var/lib/aitbc/keystore/.password +gossip_backend=broadcast +gossip_broadcast_url=redis://10.1.223.40:6379 +db_path=/var/lib/aitbc/data/ait-mainnet/chain.db +mint_per_unit=0 +coordinator_ratio=0.05 +EOF + +# Copy genesis from aitbc1 +scp aitbc1:/var/lib/aitbc/data/ait-mainnet/genesis.json /var/lib/aitbc/data/ait-mainnet/ +scp aitbc1:/var/lib/aitbc/data/ait-mainnet/allocations.json /var/lib/aitbc/data/ait-mainnet/ + +# Update systemd services +sed -i 's|EnvironmentFile=/opt/aitbc/.env|EnvironmentFile=/etc/aitbc/blockchain.env|g' /opt/aitbc/systemd/aitbc-blockchain-*.service + +# Stop any existing services and clear old data +systemctl stop aitbc-blockchain-* 2>/dev/null || true +rm -f /var/lib/aitbc/data/ait-mainnet/chain.db* + +# Start follower services +systemctl daemon-reload +systemctl enable aitbc-blockchain-node aitbc-blockchain-rpc +systemctl start aitbc-blockchain-node aitbc-blockchain-rpc + +# Monitor sync +journalctl -f -u aitbc-blockchain-node -u aitbc-blockchain-rpc +``` + +### 4. Watch Blockchain Sync + +```bash +# On aitbc, monitor sync progress +watch -n 2 'curl -s http://localhost:8006/rpc/head | jq .height' + +# Compare with aitbc1 +ssh aitbc1 'curl -s http://localhost:8006/rpc/head | jq .height' +``` + +### 5. Create Wallet on aitbc + +```bash +# On aitbc, create a new wallet +cd /opt/aitbc/apps/blockchain-node +/opt/aitbc/venv/bin/python scripts/keystore.py \ + --name aitbc-user \ + --create \ + --password $(cat /var/lib/aitbc/keystore/.password) + +# Note the new wallet address +WALLET_ADDR=$(cat /var/lib/aitbc/keystore/aitbc-user.json | jq -r '.address') +echo "New wallet: $WALLET_ADDR" +``` + +### 6. Send 1000 AIT from Genesis to aitbc Wallet + +```bash +# On aitbc1, create and sign transaction +cd /opt/aitbc/apps/blockchain-node + +# Get genesis wallet private key +PASSWORD=$(cat /var/lib/aitbc/keystore/.password) +GENESIS_KEY=$(/opt/aitbc/venv/bin/python -c " +import json, sys +from cryptography.hazmat.primitives.asymmetric import ed25519 +from cryptography.hazmat.primitives.ciphers.aead import AESGCM +from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC +from cryptography.hazmat.primitives import hashes +import base64 + +with open('/var/lib/aitbc/keystore/aitbc1genesis.json') as f: + ks = json.load(f) + +# Decrypt private key +crypto = ks['crypto'] +salt = bytes.fromhex(crypto['kdfparams']['salt']) +kdf = PBKDF2HMAC(hashes.SHA256(), 32, salt, crypto['kdfparams']['c']) +key = kdf.derive('$PASSWORD'.encode()) +aesgcm = AESGCM(key) +nonce = bytes.fromhex(crypto['cipherparams']['nonce']) +priv = aesgcm.decrypt(nonce, bytes.fromhex(crypto['ciphertext']), None) +print(priv.hex()) +") + +# Create transaction to send 1000 AIT +TX_JSON=$(cat << EOF +{ + "sender": "$(cat /var/lib/aitbc/keystore/aitbc1genesis.json | jq -r '.address')", + "recipient": "$WALLET_ADDR", + "value": 1000, + "fee": 10, + "nonce": 0, + "type": "transfer", + "payload": {} +} +EOF +) + +# Submit transaction via RPC +curl -X POST http://localhost:8006/sendTx \ + -H "Content-Type: application/json" \ + -d "$TX_JSON" + +# Wait for transaction to be mined +sleep 15 + +# Verify balance on aitbc +curl -s "http://localhost:8006/rpc/getBalance/$WALLET_ADDR" | jq . +``` + +### 7. Final Verification + +```bash +# Check both nodes are in sync +echo "=== aitbc1 height ===" +ssh aitbc1 'curl -s http://localhost:8006/rpc/head | jq .height' + +echo "=== aitbc height ===" +curl -s http://localhost:8006/rpc/head | jq .height + +echo "=== aitbc wallet balance ===" +curl -s "http://localhost:8006/rpc/getBalance/$WALLET_ADDR" | jq . +``` + +## Troubleshooting + +- **Services won't start**: Check `/var/log/aitbc/` for service logs +- **Sync issues**: Verify Redis connectivity between nodes +- **Transaction failures**: Check wallet nonce and balance +- **Permission errors**: Ensure `/var/lib/aitbc/` is owned by root with proper permissions + +## Notes + +- Only one `.env` file is used at `/etc/aitbc/blockchain.env` +- All services use the central venv at `/opt/aitbc/venv` +- Database files are stored in `/var/lib/aitbc/data` +- Wallet credentials are in `/var/lib/aitbc/keystore` +- Service logs go to `/var/log/aitbc/` via journald