docs: update multi-node workflow to use central .env configuration

- Replace separate blockchain.env files with adaptations of central /opt/aitbc/.env
- Add environment configuration section explaining the centralized approach
- Update both aitbc1 (genesis) and aitbc (follower) setup to use central .env
- Add backup strategy for .env files before modification
- Remove genesis copying from aitbc1 to aitbc (follower should sync via blockchain)
- Add comprehensive environment management section with troubleshooting
- Maintain standardized directory structure while using single .env file
- Include commands for viewing and restoring .env configurations

.windsurf/workflows/multi-node-blockchain-setup.md

@@ -17,13 +17,23 @@ This workflow sets up a two-node AITBC blockchain network (aitbc1 as genesis aut
 
 - `/opt/aitbc/venv` - Central Python virtual environment
 - `/opt/aitbc/requirements.txt` - Python dependencies
+- `/opt/aitbc/.env` - Central environment configuration
 - `/var/lib/aitbc/data` - Blockchain database files
 - `/var/lib/aitbc/keystore` - Wallet credentials
-- `/etc/aitbc/` - Configuration files
+- `/etc/aitbc/` - System configuration files
 - `/var/log/aitbc/` - Service logs
 
 ## Steps
 
+### Environment Configuration
+
+The workflow uses the central `/opt/aitbc/.env` file as the base configuration for both nodes:
+
+- **Base Configuration**: The central `.env` contains all default settings
+- **Node-Specific Adaptation**: Each node adapts the `.env` for its role (genesis vs follower)
+- **Path Updates**: Paths are updated to use the standardized directory structure
+- **Backup Strategy**: Original `.env` is backed up before modifications
+
 ### 1. Prepare aitbc1 (Genesis Authority Node)
 
 ```bash
@@ -40,26 +50,20 @@ git pull origin main
 # Create required directories
 mkdir -p /var/lib/aitbc/data /var/lib/aitbc/keystore /etc/aitbc /var/log/aitbc
 
-# Set up environment configuration
+# Copy and adapt central .env for aitbc1 (genesis authority)
-cat > /etc/aitbc/blockchain.env << 'EOF'
+cp /opt/aitbc/.env /opt/aitbc/.env.aitbc1.backup
-# Blockchain Node Configuration (aitbc1 - genesis authority)
+
-chain_id=ait-mainnet
+# Update .env for aitbc1 genesis authority configuration
-supported_chains=ait-mainnet
+sed -i 's|proposer_id=.*|proposer_id=aitbc1genesis|g' /opt/aitbc/.env
-rpc_bind_host=0.0.0.0
+sed -i 's|keystore_path=/opt/aitbc/apps/blockchain-node/keystore|keystore_path=/var/lib/aitbc/keystore|g' /opt/aitbc/.env
-rpc_bind_port=8006
+sed -i 's|keystore_password_file=/opt/aitbc/apps/blockchain-node/keystore/.password|keystore_password_file=/var/lib/aitbc/keystore/.password|g' /opt/aitbc/.env
-p2p_bind_host=0.0.0.0
+sed -i 's|db_path=./data/ait-mainnet/chain.db|db_path=/var/lib/aitbc/data/ait-mainnet/chain.db|g' /opt/aitbc/.env
-p2p_bind_port=7070
+sed -i 's|enable_block_production=true|enable_block_production=true|g' /opt/aitbc/.env
-proposer_id=aitbc1genesis
+sed -i 's|gossip_broadcast_url=redis://127.0.0.1:6379|gossip_broadcast_url=redis://localhost:6379|g' /opt/aitbc/.env
-enable_block_production=true
+sed -i 's|p2p_bind_port=8005|p2p_bind_port=7070|g' /opt/aitbc/.env
-block_time_seconds=10
+
-keystore_path=/var/lib/aitbc/keystore
+# Add trusted proposers for follower nodes
-keystore_password_file=/var/lib/aitbc/keystore/.password
+echo "trusted_proposers=aitbc1genesis" >> /opt/aitbc/.env
-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
@@ -74,10 +78,10 @@ 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
+# Update systemd services to use central .env and standard paths
-sed -i 's|EnvironmentFile=/opt/aitbc/.env|EnvironmentFile=/etc/aitbc/blockchain.env|g' /opt/aitbc/systemd/aitbc-blockchain-*.service
+# Note: systemd services already reference /opt/aitbc/.env by default
-sed -i 's|WorkingDirectory=/opt/aitbc/apps/blockchain-node|WorkingDirectory=/opt/aitbc/apps/blockchain-node|g' /opt/aitbc/systemd/aitbc-blockchain-*.service
+# No need to modify EnvironmentFile as they should use the central .env
-sed -i 's|ExecStart=/opt/aitbc/venv/bin/python|ExecStart=/opt/aitbc/venv/bin/python|g' /opt/aitbc/systemd/aitbc-blockchain-*.service
+# Just ensure the paths in .env are correct for the standard directory structure
 
 # Enable and start blockchain services
 systemctl daemon-reload
@@ -117,33 +121,25 @@ git pull origin main
 # Create required directories
 mkdir -p /var/lib/aitbc/data /var/lib/aitbc/keystore /etc/aitbc /var/log/aitbc
 
-# Set up follower configuration
+# Copy and adapt central .env for aitbc (follower node)
-cat > /etc/aitbc/blockchain.env << 'EOF'
+cp /opt/aitbc/.env /opt/aitbc/.env.aitbc.backup
-# 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
+# Update .env for aitbc follower node configuration
-scp aitbc1:/var/lib/aitbc/data/ait-mainnet/genesis.json /var/lib/aitbc/data/ait-mainnet/
+sed -i 's|proposer_id=.*|proposer_id=follower-node-aitbc|g' /opt/aitbc/.env
-scp aitbc1:/var/lib/aitbc/data/ait-mainnet/allocations.json /var/lib/aitbc/data/ait-mainnet/
+sed -i 's|keystore_path=/opt/aitbc/apps/blockchain-node/keystore|keystore_path=/var/lib/aitbc/keystore|g' /opt/aitbc/.env
+sed -i 's|keystore_password_file=/opt/aitbc/apps/blockchain-node/keystore/.password|keystore_password_file=/var/lib/aitbc/keystore/.password|g' /opt/aitbc/.env
+sed -i 's|db_path=./data/ait-mainnet/chain.db|db_path=/var/lib/aitbc/data/ait-mainnet/chain.db|g' /opt/aitbc/.env
+sed -i 's|enable_block_production=true|enable_block_production=false|g' /opt/aitbc/.env
+sed -i 's|gossip_broadcast_url=redis://127.0.0.1:6379|gossip_broadcast_url=redis://10.1.223.40:6379|g' /opt/aitbc/.env
+sed -i 's|p2p_bind_port=8005|p2p_bind_port=7070|g' /opt/aitbc/.env
+sed -i 's|trusted_proposers=.*|trusted_proposers=ait1apmaugx6csz50q07m99z8k44llry0zpl0yurl23hygarcey8z85qy4zr96|g' /opt/aitbc/.env
 
-# Update systemd services
+# Note: aitbc should sync genesis from aitbc1, not copy it
-sed -i 's|EnvironmentFile=/opt/aitbc/.env|EnvironmentFile=/etc/aitbc/blockchain.env|g' /opt/aitbc/systemd/aitbc-blockchain-*.service
+# The follower node will receive the genesis block via blockchain sync
+
+# Note: systemd services already reference /opt/aitbc/.env by default
+# No need to modify EnvironmentFile as they should use the central .env
+# The .env file has been updated above with follower node configuration
 
 # Stop any existing services and clear old data
 systemctl stop aitbc-blockchain-* 2>/dev/null || true
@@ -253,17 +249,37 @@ echo "=== aitbc wallet balance ==="
 curl -s "http://localhost:8006/rpc/getBalance/$WALLET_ADDR" | jq .
 ```
 
+## Environment Management
+
+### Central .env Configuration
+
+The workflow uses `/opt/aitbc/.env` as the central configuration file:
+
+```bash
+# View current configuration
+cat /opt/aitbc/.env
+
+# Restore from backup if needed
+cp /opt/aitbc/.env.aitbc1.backup /opt/aitbc/.env  # aitbc1
+cp /opt/aitbc/.env.aitbc.backup /opt/aitbc/.env   # aitbc
+
+# Key configuration differences:
+# aitbc1: proposer_id=aitbc1genesis, enable_block_production=true
+# aitbc: proposer_id=follower-node-aitbc, enable_block_production=false
+```
+
+### Service Configuration
+
+- **Environment File**: All services use `/opt/aitbc/.env` (no separate config files)
+- **Virtual Environment**: Central venv at `/opt/aitbc/venv`
+- **Database Files**: `/var/lib/aitbc/data`
+- **Wallet Credentials**: `/var/lib/aitbc/keystore`
+- **Service Logs**: `/var/log/aitbc/` via journald
+
 ## 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
-
+- **Configuration issues**: Verify `.env` file contents and systemd service EnvironmentFile paths
-## 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