Move blockchain app READMEs to centralized documentation

- Relocate blockchain-event-bridge README content to docs/apps/blockchain/blockchain-event-bridge.md
- Relocate blockchain-explorer README content to docs/apps/blockchain/blockchain-explorer.md
- Replace app READMEs with redirect notices pointing to new documentation location
- Consolidate documentation in central docs/ directory for better organization

docs/apps/blockchain/README.md

@@ -0,0 +1,22 @@
+# Blockchain Applications
+
+Core blockchain infrastructure for AITBC.
+
+## Applications
+
+- [Blockchain Node](blockchain-node.md) - Production-ready blockchain node with PoA consensus
+- [Blockchain Event Bridge](blockchain-event-bridge.md) - Event bridge for blockchain events
+- [Blockchain Explorer](blockchain-explorer.md) - Blockchain explorer and analytics
+
+## Features
+
+- PoA consensus with single proposer
+- Transaction processing (TRANSFER, RECEIPT_CLAIM, MESSAGE, GPU_MARKETPLACE, EXCHANGE)
+- Gossip-based peer-to-peer networking
+- RESTful RPC API
+- Prometheus metrics
+- Multi-chain support
+
+## Quick Start
+
+See individual application documentation for setup instructions.

docs/apps/blockchain/blockchain-event-bridge.md

@@ -0,0 +1,135 @@
+# Blockchain Event Bridge
+
+Bridge between AITBC blockchain events and OpenClaw agent triggers using a hybrid event-driven and polling approach.
+
+## Overview
+
+This service connects AITBC blockchain events (blocks, transactions, smart contract events) to OpenClaw agent actions through:
+- **Event-driven**: Subscribe to gossip broker topics for real-time critical triggers
+- **Polling**: Periodic checks for batch operations and conditions
+- **Smart Contract Events**: Monitor contract events via blockchain RPC (Phase 2)
+
+## Features
+
+- Subscribes to blockchain block events via gossip broker
+- Subscribes to transaction events (when available)
+- Monitors smart contract events via blockchain RPC:
+  - AgentStaking (stake creation, rewards, tier updates)
+  - PerformanceVerifier (performance verification, penalties, rewards)
+  - AgentServiceMarketplace (service listings, purchases)
+  - BountyIntegration (bounty creation, completion)
+  - CrossChainBridge (bridge initiation, completion)
+- Triggers coordinator API actions based on blockchain events
+- Triggers agent daemon actions for agent wallet transactions
+- Triggers marketplace state updates
+- Configurable action handlers (enable/disable per type)
+- Prometheus metrics for monitoring
+- Health check endpoint
+
+## Installation
+
+```bash
+cd apps/blockchain-event-bridge
+poetry install
+```
+
+## Configuration
+
+Environment variables:
+
+- `BLOCKCHAIN_RPC_URL` - Blockchain RPC endpoint (default: `http://localhost:8006`)
+- `GOSSIP_BACKEND` - Gossip broker backend: `memory`, `broadcast`, or `redis` (default: `memory`)
+- `GOSSIP_BROADCAST_URL` - Broadcast URL for Redis backend (optional)
+- `COORDINATOR_API_URL` - Coordinator API endpoint (default: `http://localhost:8011`)
+- `COORDINATOR_API_KEY` - Coordinator API key (optional)
+- `SUBSCRIBE_BLOCKS` - Subscribe to block events (default: `true`)
+- `SUBSCRIBE_TRANSACTIONS` - Subscribe to transaction events (default: `true`)
+- `ENABLE_AGENT_DAEMON_TRIGGER` - Enable agent daemon triggers (default: `true`)
+- `ENABLE_COORDINATOR_API_TRIGGER` - Enable coordinator API triggers (default: `true`)
+- `ENABLE_MARKETPLACE_TRIGGER` - Enable marketplace triggers (default: `true`)
+- `ENABLE_POLLING` - Enable polling layer (default: `false`)
+- `POLLING_INTERVAL_SECONDS` - Polling interval in seconds (default: `60`)
+
+## Running
+
+### Development
+
+```bash
+poetry run uvicorn blockchain_event_bridge.main:app --reload --host 127.0.0.1 --port 8204
+```
+
+### Production (Systemd)
+
+```bash
+sudo systemctl start aitbc-blockchain-event-bridge
+sudo systemctl enable aitbc-blockchain-event-bridge
+```
+
+## API Endpoints
+
+- `GET /` - Service information
+- `GET /health` - Health check
+- `GET /metrics` - Prometheus metrics
+
+## Architecture
+
+```
+blockchain-event-bridge/
+├── src/blockchain_event_bridge/
+│   ├── main.py              # FastAPI app
+│   ├── config.py            # Settings
+│   ├── bridge.py            # Core bridge logic
+│   ├── metrics.py           # Prometheus metrics
+│   ├── event_subscribers/   # Event subscription modules
+│   ├── action_handlers/     # Action handler modules
+│   └── polling/             # Polling modules
+└── tests/
+```
+
+## Event Flow
+
+1. Blockchain publishes block event to gossip broker (topic: "blocks")
+2. Block event subscriber receives event
+3. Bridge parses block data and extracts transactions
+4. Bridge triggers appropriate action handlers:
+   - Coordinator API handler for AI jobs, agent messages
+   - Agent daemon handler for agent wallet transactions
+   - Marketplace handler for marketplace listings
+5. Action handlers make HTTP calls to respective services
+6. Metrics are recorded for monitoring
+
+## CLI Commands
+
+The blockchain event bridge service includes CLI commands for management and monitoring:
+
+```bash
+# Health check
+aitbc-cli bridge health
+
+# Get Prometheus metrics
+aitbc-cli bridge metrics
+
+# Get detailed service status
+aitbc-cli bridge status
+
+# Show current configuration
+aitbc-cli bridge config
+
+# Restart the service (via systemd)
+aitbc-cli bridge restart
+```
+
+All commands support `--test-mode` flag for testing without connecting to the service.
+
+## Testing
+
+```bash
+poetry run pytest
+```
+
+## Future Enhancements
+
+- Phase 2: Smart contract event subscription
+- Phase 3: Enhanced polling layer for batch operations
+- WebSocket support for real-time event streaming
+- Event replay for missed events

docs/apps/blockchain/blockchain-explorer.md

@@ -0,0 +1,396 @@
+# AITBC Blockchain Explorer - Enhanced Version
+
+## Overview
+
+The enhanced AITBC Blockchain Explorer provides comprehensive blockchain exploration capabilities with advanced search, analytics, and export features that match the power of CLI tools while providing an intuitive web interface.
+
+## 🚀 New Features
+
+### 🔍 Advanced Search
+- **Multi-criteria filtering**: Search by address, amount range, transaction type, and time range
+- **Complex queries**: Combine multiple filters for precise results
+- **Search history**: Save and reuse common searches
+- **Real-time results**: Instant search with pagination
+
+### 📊 Analytics Dashboard
+- **Transaction volume analytics**: Visualize transaction patterns over time
+- **Network activity monitoring**: Track blockchain health and performance
+- **Validator performance**: Monitor validator statistics and rewards
+- **Time period analysis**: 1h, 24h, 7d, 30d views with interactive charts
+
+### 📤 Data Export
+- **Multiple formats**: Export to CSV, JSON for analysis
+- **Custom date ranges**: Export specific time periods
+- **Bulk operations**: Export large datasets efficiently
+- **Search result exports**: Export filtered search results
+
+### ⚡ Real-time Updates
+- **Live transaction feed**: Monitor transactions as they happen
+- **Real-time block updates**: See new blocks immediately
+- **Network status monitoring**: Track blockchain health
+- **Alert system**: Get notified about important events
+
+## 🛠️ Installation
+
+### Prerequisites
+- Python 3.13+
+- Node.js (for frontend development)
+- Access to AITBC blockchain node
+
+### Setup
+```bash
+# Clone the repository
+git clone https://github.com/aitbc/blockchain-explorer.git
+cd blockchain-explorer
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Run the explorer
+python main.py
+```
+
+The explorer will be available at `http://localhost:3001`
+
+## 🔧 Configuration
+
+### Environment Variables
+```bash
+# Blockchain node URL
+export BLOCKCHAIN_RPC_URL="http://localhost:8082"
+
+# External node URL (for backup)
+export EXTERNAL_RPC_URL="http://aitbc.keisanki.net:8082"
+
+# Explorer settings
+export EXPLORER_HOST="0.0.0.0"
+export EXPLORER_PORT="3001"
+```
+
+### Configuration File
+Create `.env` file:
+```env
+BLOCKCHAIN_RPC_URL=http://localhost:8082
+EXTERNAL_RPC_URL=http://aitbc.keisanki.net:8082
+EXPLORER_HOST=0.0.0.0
+EXPLORER_PORT=3001
+```
+
+## 📚 API Documentation
+
+### Search Endpoints
+
+#### Advanced Transaction Search
+```http
+GET /api/search/transactions
+```
+
+Query Parameters:
+- `address` (string): Filter by address
+- `amount_min` (float): Minimum amount
+- `amount_max` (float): Maximum amount
+- `tx_type` (string): Transaction type (transfer, stake, smart_contract)
+- `since` (datetime): Start date
+- `until` (datetime): End date
+- `limit` (int): Results per page (max 1000)
+- `offset` (int): Pagination offset
+
+Example:
+```bash
+curl "http://localhost:3001/api/search/transactions?address=0x123...&amount_min=1.0&limit=50"
+```
+
+#### Advanced Block Search
+```http
+GET /api/search/blocks
+```
+
+Query Parameters:
+- `validator` (string): Filter by validator address
+- `since` (datetime): Start date
+- `until` (datetime): End date
+- `min_tx` (int): Minimum transaction count
+- `limit` (int): Results per page (max 1000)
+- `offset` (int): Pagination offset
+
+### Analytics Endpoints
+
+#### Analytics Overview
+```http
+GET /api/analytics/overview
+```
+
+Query Parameters:
+- `period` (string): Time period (1h, 24h, 7d, 30d)
+
+Response:
+```json
+{
+  "total_transactions": "1,234",
+  "transaction_volume": "5,678.90 AITBC",
+  "active_addresses": "89",
+  "avg_block_time": "2.1s",
+  "volume_data": {
+    "labels": ["00:00", "02:00", "04:00"],
+    "values": [100, 120, 110]
+  },
+  "activity_data": {
+    "labels": ["00:00", "02:00", "04:00"],
+    "values": [50, 60, 55]
+  }
+}
+```
+
+### Export Endpoints
+
+#### Export Search Results
+```http
+GET /api/export/search
+```
+
+Query Parameters:
+- `format` (string): Export format (csv, json)
+- `type` (string): Data type (transactions, blocks)
+- `data` (string): JSON-encoded search results
+
+#### Export Latest Blocks
+```http
+GET /api/export/blocks
+```
+
+Query Parameters:
+- `format` (string): Export format (csv, json)
+
+## 🎯 Usage Examples
+
+### Advanced Search
+1. **Search by address and amount range**:
+   - Enter address in search field
+   - Click "Advanced" to expand options
+   - Set amount range (min: 1.0, max: 100.0)
+   - Click "Search Transactions"
+
+2. **Search blocks by validator**:
+   - Expand advanced search
+   - Enter validator address
+   - Set time range if needed
+   - Click "Search Blocks"
+
+### Analytics
+1. **View 24-hour analytics**:
+   - Select "Last 24 Hours" from dropdown
+   - View transaction volume chart
+   - Check network activity metrics
+
+2. **Compare time periods**:
+   - Switch between 1h, 24h, 7d, 30d views
+   - Observe trends and patterns
+
+### Export Data
+1. **Export search results**:
+   - Perform search
+   - Click "Export CSV" or "Export JSON"
+   - Download file automatically
+
+2. **Export latest blocks**:
+   - Go to latest blocks section
+   - Click "Export" button
+   - Choose format
+
+## 🔍 CLI vs Web Explorer Feature Comparison
+
+| Feature | CLI | Web Explorer |
+|---------|-----|--------------|
+| **Basic Search** | ✅ `aitbc blockchain transaction` | ✅ Simple search |
+| **Advanced Search** | ✅ `aitbc blockchain search` | ✅ Advanced search form |
+| **Address Analytics** | ✅ `aitbc blockchain address` | ✅ Address details |
+| **Transaction Volume** | ✅ `aitbc blockchain analytics` | ✅ Volume charts |
+| **Data Export** | ✅ `--output csv/json` | ✅ Export buttons |
+| **Real-time Monitoring** | ✅ `aitbc blockchain monitor` | ✅ Live updates |
+| **Visual Analytics** | ❌ Text only | ✅ Interactive charts |
+| **User Interface** | ❌ Command line | ✅ Web interface |
+| **Mobile Access** | ❌ Limited | ✅ Responsive |
+
+## 🚀 Performance
+
+### Optimization Features
+- **Caching**: Frequently accessed data cached for performance
+- **Pagination**: Large result sets paginated to prevent memory issues
+- **Async operations**: Non-blocking API calls for better responsiveness
+- **Compression**: Gzip compression for API responses
+
+### Performance Metrics
+- **Page load time**: < 2 seconds for analytics dashboard
+- **Search response**: < 500ms for filtered searches
+- **Export generation**: < 30 seconds for 1000+ records
+- **Real-time updates**: < 5 second latency
+
+## 🔒 Security
+
+### Security Features
+- **Input validation**: All user inputs validated and sanitized
+- **Rate limiting**: API endpoints protected from abuse
+- **CORS protection**: Cross-origin requests controlled
+- **HTTPS support**: SSL/TLS encryption for production
+
+### Security Best Practices
+- **No sensitive data exposure**: Private keys never displayed
+- **Secure headers**: Security headers implemented
+- **Input sanitization**: XSS protection enabled
+- **Error handling**: No sensitive information in error messages
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+#### Explorer not loading
+```bash
+# Check if port is available
+netstat -tulpn | grep 3001
+
+# Check logs
+python main.py --log-level debug
+```
+
+#### Search not working
+```bash
+# Test blockchain node connectivity
+curl http://localhost:8082/rpc/head
+
+# Check API endpoints
+curl http://localhost:3001/health
+```
+
+#### Analytics not displaying
+```bash
+# Check browser console for JavaScript errors
+# Verify Chart.js library is loaded
+# Test API endpoint:
+curl http://localhost:3001/api/analytics/overview
+```
+
+### Debug Mode
+```bash
+# Run with debug logging
+python main.py --log-level debug
+
+# Check API responses
+curl -v http://localhost:3001/api/search/transactions
+```
+
+## 📱 Mobile Support
+
+The enhanced explorer is fully responsive and works on:
+- **Desktop browsers**: Chrome, Firefox, Safari, Edge
+- **Tablet devices**: iPad, Android tablets
+- **Mobile phones**: iOS Safari, Chrome Mobile
+
+Mobile-specific features:
+- **Touch-friendly interface**: Optimized for touch interactions
+- **Responsive charts**: Charts adapt to screen size
+- **Simplified navigation**: Mobile-optimized menu
+- **Quick actions**: One-tap export and search
+
+## 🔗 Integration
+
+### API Integration
+The explorer provides RESTful APIs for integration with:
+- **Custom dashboards**: Build custom analytics dashboards
+- **Mobile apps**: Integrate blockchain data into mobile applications
+- **Trading bots**: Provide blockchain data for automated trading
+- **Research tools**: Power blockchain research platforms
+
+### Webhook Support
+Configure webhooks for:
+- **New block notifications**: Get notified when new blocks are mined
+- **Transaction alerts**: Receive alerts for specific transactions
+- **Network events**: Monitor network health and performance
+
+## 🚀 Deployment
+
+### Docker Deployment
+```bash
+# Build Docker image
+docker build -t aitbc-explorer .
+
+# Run container
+docker run -p 3001:3001 aitbc-explorer
+```
+
+### Production Deployment
+```bash
+# Install with systemd
+sudo cp aitbc-explorer.service /etc/systemd/system/
+sudo systemctl enable aitbc-explorer
+sudo systemctl start aitbc-explorer
+
+# Configure nginx reverse proxy
+sudo cp nginx.conf /etc/nginx/sites-available/aitbc-explorer
+sudo ln -s /etc/nginx/sites-available/aitbc-explorer /etc/nginx/sites-enabled/
+sudo nginx -t && sudo systemctl reload nginx
+```
+
+### Environment Configuration
+```bash
+# Production environment
+export NODE_ENV=production
+export BLOCKCHAIN_RPC_URL=https://mainnet.aitbc.dev
+export EXPLORER_PORT=3001
+export LOG_LEVEL=info
+```
+
+## 📈 Roadmap
+
+### Upcoming Features
+- **WebSocket real-time updates**: Live blockchain monitoring
+- **Advanced charting**: More sophisticated analytics visualizations
+- **Custom dashboards**: User-configurable dashboard layouts
+- **Alert system**: Email and webhook notifications
+- **Multi-language support**: Internationalization
+- **Dark mode**: Dark theme support
+
+### Future Enhancements
+- **Mobile app**: Native mobile applications
+- **API authentication**: Secure API access with API keys
+- **Advanced filtering**: More sophisticated search options
+- **Performance analytics**: Detailed performance metrics
+- **Social features**: Share and discuss blockchain data
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+### Development Setup
+```bash
+# Clone repository
+git clone https://github.com/aitbc/blockchain-explorer.git
+cd blockchain-explorer
+
+# Create virtual environment
+python -m venv venv
+source venv/bin/activate
+
+# Install development dependencies
+pip install -r requirements-dev.txt
+
+# Run tests
+pytest
+
+# Start development server
+python main.py --reload
+```
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 📞 Support
+
+- **Documentation**: [Full documentation](https://docs.aitbc.dev/explorer)
+- **Issues**: [GitHub Issues](https://github.com/aitbc/blockchain-explorer/issues)
+- **Discord**: [AITBC Discord](https://discord.gg/aitbc)
+- **Email**: support@aitbc.dev
+
+---
+
+*Enhanced AITBC Blockchain Explorer - Bringing CLI power to the web interface*

docs/apps/blockchain/blockchain-node.md

@@ -0,0 +1,199 @@
+# Blockchain Node (Brother Chain)
+
+Production-ready blockchain node for AITBC with fixed supply and secure key management.
+
+## Status
+
+✅ **Operational** — Core blockchain functionality implemented.
+
+### Capabilities
+- PoA consensus with single proposer
+- Transaction processing (TRANSFER, RECEIPT_CLAIM)
+- 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
+- Multi-chain support (separate data directories per chain ID)
+
+## Architecture
+
+### Wallets & Supply
+- **Fixed supply**: All tokens minted at genesis; no further minting.
+- **Two wallets**:
+  - `aitbc1genesis` (treasury): holds the full initial supply (default 1 B AIT). This is the **cold storage** wallet; private key is encrypted in keystore.
+  - `aitbc1treasury` (spending): operational wallet for transactions; initially zero balance. Can receive funds from genesis wallet.
+- **Private keys** are stored in `keystore/*.json` using AES‑256‑GCM encryption. Password is stored in `keystore/.password` (mode 600).
+
+### Chain Configuration
+- **Chain ID**: `ait-mainnet` (production)
+- **Proposer**: The genesis wallet address is the block proposer and authority.
+- **Trusted proposers**: Only the genesis wallet is allowed to produce blocks.
+- **No admin endpoints**: The `/rpc/admin/mintFaucet` endpoint has been removed.
+
+## Quickstart (Production)
+
+### 1. Generate Production Keys & Genesis
+
+Run the setup script once to create the keystore, allocations, and genesis:
+
+```bash
+cd /opt/aitbc/apps/blockchain-node
+.venv/bin/python scripts/setup_production.py --chain-id ait-mainnet
+```
+
+This creates:
+- `keystore/aitbc1genesis.json` (treasury wallet)
+- `keystore/aitbc1treasury.json` (spending wallet)
+- `keystore/.password` (random strong password)
+- `data/ait-mainnet/allocations.json`
+- `data/ait-mainnet/genesis.json`
+
+**Important**: Back up the keystore directory and the `.password` file securely. Loss of these means loss of funds.
+
+### 2. Configure Environment
+
+Copy the provided production environment file:
+
+```bash
+cp .env.production .env
+```
+
+Edit `.env` if you need to adjust ports or paths. Ensure `chain_id=ait-mainnet` and `proposer_id` matches the genesis wallet address (the setup script sets it automatically in `.env.production`).
+
+### 3. Start the Node
+
+Use the production launcher:
+
+```bash
+bash scripts/mainnet_up.sh
+```
+
+This starts:
+- Blockchain node (PoA proposer)
+- RPC API on `http://127.0.0.1:8026`
+
+Press `Ctrl+C` to stop both.
+
+### Manual Startup (Alternative)
+
+```bash
+cd /opt/aitbc/apps/blockchain-node
+source .env.production  # or export the variables manually
+# Terminal 1: Node
+.venv/bin/python -m aitbc_chain.main
+# Terminal 2: RPC
+.venv/bin/bin/uvicorn aitbc_chain.app:app --host 127.0.0.1 --port 8026
+```
+
+## API Endpoints
+
+RPC API available at `http://127.0.0.1:8026/rpc`.
+
+### Blockchain
+- `GET /rpc/head` — Current chain head
+- `GET /rpc/blocks/{height}` — Get block by height
+- `GET /rpc/blocks-range?start=0&end=10` — Block range
+- `GET /rpc/info` — Chain information
+- `GET /rpc/supply` — Token supply (total & circulating)
+- `GET /rpc/validators` — List of authorities
+- `GET /rpc/state` — Full state dump
+
+### Transactions
+- `POST /rpc/sendTx` — Submit transaction (TRANSFER, RECEIPT_CLAIM)
+- `GET /rpc/transactions` — Latest transactions
+- `GET /rpc/tx/{tx_hash}` — Get transaction by hash
+- `POST /rpc/estimateFee` — Estimate fee
+
+### Accounts
+- `GET /rpc/getBalance/{address}` — Account balance
+- `GET /rpc/address/{address}` — Address details + txs
+- `GET /rpc/addresses` — List active addresses
+
+### Health & Metrics
+- `GET /health` — Health check
+- `GET /metrics` — Prometheus metrics
+
+*Note: Admin endpoints (`/rpc/admin/*`) are disabled in production.*
+
+## Multi‑Chain Support
+
+The node can run multiple chains simultaneously by setting `supported_chains` in `.env` as a comma‑separated list (e.g., `ait-mainnet,ait-testnet`). Each chain must have its own `data/<chain_id>/genesis.json` and (optionally) its own keystore. The proposer identity is shared across chains; for multi‑chain you may want separate proposer wallets per chain.
+
+## Keystore Management
+
+### Encrypted Keystore Format
+- Uses Web3 keystore format (AES‑256‑GCM + PBKDF2).
+- Password stored in `keystore/.password` (chmod 600).
+- Private keys are **never** stored in plaintext.
+
+### Changing the Password
+```bash
+# Use the keystore.py script to re‑encrypt with a new password
+.venv/bin/python scripts/keystore.py --name genesis --show --password <old> --new-password <new>
+```
+(Not yet implemented; currently you must manually decrypt and re‑encrypt.)
+
+### Adding a New Wallet
+```bash
+.venv/bin/python scripts/keystore.py --name mywallet --create
+```
+This appends a new entry to `allocations.json` if you want it to receive genesis allocation (edit the file and regenerate genesis).
+
+## Genesis & Supply
+
+- Genesis file is generated by `scripts/make_genesis.py`.
+- Supply is fixed: the sum of `allocations[].balance`.
+- No tokens can be minted after genesis (`mint_per_unit=0`).
+- To change the allocation distribution, edit `allocations.json` and regenerate genesis (requires consensus to reset chain).
+
+## Development / Devnet
+
+The old devnet (faucet model) has been removed. For local development, use the production setup with a throwaway keystore, or create a separate `ait-devnet` chain by providing your own `allocations.json` and running `scripts/make_genesis.py` manually.
+
+## Troubleshooting
+
+**Genesis missing**: Run `scripts/setup_production.py` first.
+
+**Proposer key not loaded**: Ensure `keystore/aitbc1genesis.json` exists and `keystore/.password` is readable. The node will log a warning but still run (block signing disabled until implemented).
+
+**Port already in use**: Change `rpc_bind_port` in `.env` and restart.
+
+**Database locked**: Delete `data/ait-mainnet/chain.db` and restart (only if you're sure no other node is using it).
+
+## 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
+│   └── models.py        # SQLModel definitions
+├── data/
+│   └── ait-mainnet/
+│       ├── genesis.json # Generated by make_genesis.py
+│       └── chain.db     # SQLite database
+├── keystore/
+│   ├── aitbc1genesis.json
+│   ├── aitbc1treasury.json
+│   └── .password
+├── scripts/
+│   ├── make_genesis.py  # Genesis generator
+│   ├── setup_production.py  # One‑time production setup
+│   ├── mainnet_up.sh    # Production launcher
+│   └── keystore.py      # Keystore utilities
+└── .env.production      # Production environment template
+```
+
+## Security Notes
+
+- **Never** expose RPC API to the public internet without authentication (production should add mTLS or API keys).
+- Keep keystore and password backups offline.
+- The node runs as the current user; ensure file permissions restrict access to the `keystore/` and `data/` directories.
+- In a multi‑node network, use Redis gossip backend and configure `trusted_proposers` with all authority addresses.