oib/aitbc
1
0
Fork 0
Code Issues Pull Requests Actions 9 Packages Projects Releases Wiki Activity

chore: standardize configuration, logging, and error handling across blockchain node and coordinator API

Browse Source 
- Add infrastructure.md and workflow files to .gitignore to prevent sensitive info leaks
- Change blockchain node mempool backend default from memory to database for persistence
- Refactor blockchain node logger with StructuredLogFormatter and AuditLogger (consistent with coordinator)
- Add structured logging fields: service, module, function, line number
- Unify coordinator config with Database
This commit is contained in:
oib
2026-02-13 22:39:43 +01:00
parent 0cbd2b507c
commit 06e48ef34b
196 changed files with 4660 additions and 20090 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
docs/4_blockchain/0_readme.md Normal file
View File

@@ -0,0 +1,23 @@
# Blockchain Node Documentation
Run a blockchain node: validate transactions, produce blocks, maintain the AITBC ledger.
## Reading Order
| # | File | What you learn |
|---|------|----------------|
| 1 | [1_quick-start.md](./1_quick-start.md) | Get a node running in 10 minutes |
| 2 | [2_configuration.md](./2_configuration.md) | Node, RPC, P2P, mempool settings |
| 3 | [3_operations.md](./3_operations.md) | Start/stop, sync, peers, backups |
| 4 | [4_consensus.md](./4_consensus.md) | PoA consensus mechanism |
| 5 | [5_validator.md](./5_validator.md) | Become a validator, duties, rewards |
| 6 | [6_networking.md](./6_networking.md) | Firewall, NAT, bootstrap nodes |
| 7 | [7_monitoring.md](./7_monitoring.md) | Prometheus, dashboards, alerts |
| 8 | [8_troubleshooting.md](./8_troubleshooting.md) | Common issues and fixes |
| 9 | [9_upgrades.md](./9_upgrades.md) | Version upgrades, rollback |
| 10 | [10_api-blockchain.md](./10_api-blockchain.md) | RPC and WebSocket API reference |
## Related
- [Installation](../0_getting_started/2_installation.md) — Install all components
- [CLI Guide](../0_getting_started/3_cli.md) — `aitbc blockchain` commands

202
docs/4_blockchain/10_api-blockchain.md Normal file
View File

@@ -0,0 +1,202 @@
# Blockchain API Reference
Complete API reference for blockchain node operations.
## RPC Endpoints
### Get Block
```
GET /rpc/block/{height}
```
**Response:**
```json
{
"block": {
"header": {
"height": 100,
"timestamp": "2026-02-13T10:00:00Z",
"proposer": "ait-devnet-proposer-1",
"parent_hash": "0xabc123...",
"state_root": "0xdef456...",
"tx_root": "0xghi789..."
},
"transactions": [...],
"receipts": [...]
},
"block_id": "0xjkl012..."
}
```
### Get Transaction
```
GET /rpc/tx/{tx_hash}
```
**Response:**
```json
{
"tx": {
"hash": "0xabc123...",
"type": "transfer",
"from": "0x1234...",
"to": "0x5678...",
"value": 100,
"gas": 21000,
"data": "0x..."
},
"height": 100,
"index": 0
}
```
### Submit Transaction
```
POST /rpc/broadcast_tx_commit
```
**Request Body:**
```json
{
"tx": "0xabc123...",
"type": "transfer",
"from": "0x1234...",
"to": "0x5678...",
"value": 100,
"data": "0x..."
}
```
**Response:**
```json
{
"tx_response": {
"code": 0,
"data": "0x...",
"log": "success",
"hash": "0xabc123..."
},
"height": 100,
"index": 0
}
```
### Get Status
```
GET /rpc/status
```
**Response:**
```json
{
"node_info": {
"protocol_version": "v0.1.0",
"network": "ait-devnet",
"node_id": "12D3KooW...",
"listen_addr": "tcp://0.0.0.0:7070"
},
"sync_info": {
"latest_block_height": 1000,
"catching_up": false,
"earliest_block_height": 1
},
"validator_info": {
"voting_power": 1000,
"proposer": true
}
}
```
### Get Mempool
```
GET /rpc/mempool
```
**Response:**
```json
{
"size": 50,
"txs": [
{
"hash": "0xabc123...",
"fee": 0.001,
"size": 200
}
]
}
```
## WebSocket Endpoints
### Subscribe to Blocks
```
WS /rpc/block
```
**Message:**
```json
{
"type": "new_block",
"data": {
"height": 1001,
"hash": "0x...",
"proposer": "ait-devnet-proposer-1"
}
}
```
### Subscribe to Transactions
```
WS /rpc/tx
```
**Message:**
```json
{
"type": "new_tx",
"data": {
"hash": "0xabc123...",
"type": "transfer",
"from": "0x1234...",
"to": "0x5678...",
"value": 100
}
}
```
## Error Codes
| Code | Description |
|------|-------------|
| 0 | Success |
| 1 | Internal error |
| 2 | Invalid transaction |
| 3 | Invalid request |
| 4 | Not found |
| 5 | Conflict |
## Rate Limits
- 1000 requests/minute for RPC
- 100 requests/minute for writes
- 10 connections per IP
## Next
- [Quick Start](./1_quick-start.md) — Get started
- [Configuration](./2_configuration.md) - Configure your node
- [Operations](./3_operations.md) — Day-to-day ops

54
docs/4_blockchain/1_quick-start.md Normal file
View File

@@ -0,0 +1,54 @@
# Node Quick Start
**10 minutes** — Install, configure, and sync a blockchain node.
## Prerequisites
| Resource | Minimum |
|----------|---------|
| CPU | 4 cores |
| RAM | 16 GB |
| Storage | 100 GB SSD |
| Network | 100 Mbps stable |
## 1. Install
```bash
cd /home/oib/windsurf/aitbc
python -m venv .venv && source .venv/bin/activate
pip install -e .
```
## 2. Initialize & Configure
```bash
aitbc-chain init --name my-node --network ait-devnet
```
Edit `~/.aitbc/chain.yaml`:
```yaml
node:
name: my-node
data_dir: ./data
rpc:
bind_host: 0.0.0.0
bind_port: 8080
p2p:
bind_port: 7070
bootstrap_nodes:
- /dns4/node-1.aitbc.com/tcp/7070/p2p/...
```
## 3. Start & Verify
```bash
aitbc-chain start
aitbc-chain status # node info + sync progress
curl http://localhost:8080/rpc/health # RPC health check
```
## Next
- [2_configuration.md](./2_configuration.md) — Full config reference
- [3_operations.md](./3_operations.md) — Day-to-day ops
- [7_monitoring.md](./7_monitoring.md) — Prometheus + dashboards

87
docs/4_blockchain/2_configuration.md Normal file
View File

@@ -0,0 +1,87 @@
# Blockchain Node Configuration
Configure your blockchain node for optimal performance.
## Configuration File
Location: `~/.aitbc/chain.yaml`
## Node Configuration
```yaml
node:
name: my-node
network: ait-devnet # or ait-mainnet
data_dir: /opt/blockchain-node/data
log_level: info
```
## RPC Configuration
```yaml
rpc:
enabled: true
bind_host: 0.0.0.0
bind_port: 8080
cors_origins:
- http://localhost:3000
- http://localhost:8000
rate_limit: 1000 # requests per minute
```
## P2P Configuration
```yaml
p2p:
enabled: true
bind_host: 0.0.0.0
bind_port: 7070
bootstrap_nodes:
- /dns4/node-1.aitbc.com/tcp/7070/p2p/...
max_peers: 50
min_peers: 5
```
## Mempool Configuration
```yaml
mempool:
backend: database # or memory
max_size: 10000
min_fee: 0
eviction_interval: 60
```
## Database Configuration
```yaml
database:
adapter: postgresql # or sqlite
url: postgresql://user:pass@localhost/aitbc_chain
pool_size: 10
max_overflow: 20
```
## Validator Configuration
```yaml
validator:
enabled: true
key: <VALIDATOR_PRIVATE_KEY>
block_time: 2 # seconds
max_block_size: 1000000 # bytes
max_txs_per_block: 500
```
## Environment Variables
```bash
export AITBC_CHAIN_DATA_DIR=/opt/blockchain-node/data
export AITBC_CHAIN_RPC_PORT=8080
export AITBC_CHAIN_P2P_PORT=7070
```
## Next
- [Quick Start](./1_quick-start.md) — Get started
- [Operations](./3_operations.md) — Day-to-day ops
- [Consensus](./4_consensus.md) — Consensus mechanism

102
docs/4_blockchain/3_operations.md Normal file
View File

@@ -0,0 +1,102 @@
# Node Operations
Day-to-day operations for blockchain nodes.
## Starting the Node
```bash
# Start in foreground (for testing)
aitbc-chain start
# Start as daemon
aitbc-chain start --daemon
# Start with custom config
aitbc-chain start --config /path/to/config.yaml
```
## Stopping the Node
```bash
# Graceful shutdown
aitbc-chain stop
# Force stop
aitbc-chain stop --force
```
## Node Status
```bash
aitbc-chain status
```
Shows:
- Block height
- Peers connected
- Mempool size
- Last block time
## Checking Sync Status
```bash
aitbc-chain sync-status
```
Shows:
- Current height
- Target height
- Sync progress percentage
- Estimated time to sync
## Managing Peers
### List Peers
```bash
aitbc-chain peers list
```
### Add Peer
```bash
aitbc-chain peers add /dns4/new-node.example.com/tcp/7070/p2p/...
```
### Remove Peer
```bash
aitbc-chain peers remove <PEER_ID>
```
## Backup & Restore
### Backup Data
```bash
aitbc-chain backup --output /backup/chain-backup.tar.gz
```
### Restore Data
```bash
aitbc-chain restore --input /backup/chain-backup.tar.gz
```
## Log Management
```bash
# View logs
aitbc-chain logs --tail 100
# Filter by level
aitbc-chain logs --level error
# Export logs
aitbc-chain logs --export /var/log/aitbc-chain.log
```
## Next
- [Quick Start](./1_quick-start.md) — Get started
- [Configuration](./2_configuration.md) - Configure your node
- [Consensus](./4_consensus.md) — Consensus mechanism

65
docs/4_blockchain/4_consensus.md Normal file
View File

@@ -0,0 +1,65 @@
# Consensus Mechanism
Understand AITBC's proof-of-authority consensus mechanism.
## Overview
AITBC uses a Proof-of-Authority (PoA) consensus mechanism with:
- Fixed block time: 2 seconds
- Authority set of validated proposers
- Transaction finality on each block
## Block Production
### Proposer Selection
Proposers take turns producing blocks in a round-robin fashion. Each proposer gets a fixed time slot.
### Block Structure
```json
{
"header": {
"height": 100,
"timestamp": "2026-02-13T10:00:00Z",
"proposer": "ait-devnet-proposer-1",
"parent_hash": "0xabc123...",
"state_root": "0xdef456...",
"tx_root": "0xghi789..."
},
"transactions": [...],
"receipts": [...]
}
```
## Consensus Rules
1. **Block Time**: 2 seconds minimum
2. **Block Size**: 1 MB maximum
3. **Transactions**: 500 maximum per block
4. **Fee**: Minimum 0 (configurable)
## Validator Requirements
| Requirement | Value |
|-------------|-------|
| Uptime | 99% minimum |
| Latency | < 100ms to peers |
| Stake | 1000 AITBC |
## Fork Selection
Longest chain rule applies:
- Validators always extend the longest known chain
- Reorgs occur only on conflicting blocks within the last 10 blocks
## Finality
Blocks are considered final after:
- 1 confirmation for normal transactions
- 3 confirmations for high-value transactions
## Next
- [Quick Start](./1_quick-start.md) — Get started
- [Validator Operations](./5_validator.md) - Validator guide
- [Networking](./6_networking.md) - P2P networking

95
docs/4_blockchain/5_validator.md Normal file
View File

@@ -0,0 +1,95 @@
# Validator Operations
Guide for running a validator node in the AITBC network.
## Becoming a Validator
### Requirements
| Requirement | Value |
|-------------|-------|
| Stake | 1000 AITBC |
| Node uptime | 99%+ |
| Technical capability | Must run node 24/7 |
| Geographic distribution | One per region preferred |
### Registration
```bash
aitbc-chain validator register --stake 1000
```
### Activate Validator Status
```bash
aitbc-chain validator activate
```
## Validator Duties
### Block Production
Validators take turns producing blocks:
- Round-robin selection
- Fixed 2-second block time
- Missed blocks result in reduced rewards
### Transaction Validation
- Verify transaction signatures
- Check sender balance
- Validate smart contract execution
### Network Participation
- Maintain P2P connections
- Propagate blocks to peers
- Participate in consensus votes
## Validator Rewards
### Block Rewards
| Block Position | Reward |
|----------------|--------|
| Proposer | 1 AITBC |
| Validator (any) | 0.1 AITBC |
### Performance Bonuses
- 100% uptime: 1.5x multiplier
- 99-100% uptime: 1.2x multiplier
- <99% uptime: 1.0x multiplier
## Validator Monitoring
```bash
# Check validator status
aitbc-chain validator status
# View performance metrics
aitbc-chain validator metrics
# Check missed blocks
aitbc-chain validator missed-blocks
```
## Validator Slashing
### Slashing Conditions
| Violation | Penalty |
|-----------|---------|
| Double signing | 5% stake |
| Extended downtime | 1% stake |
| Invalid block | 2% stake |
### Recovery
- Partial slashing can be recovered
- Full slashing requires re-registration
## Next
- [Quick Start](./1_quick-start.md) — Get started
- [Consensus](./4_consensus.md) — Consensus mechanism
- [Monitoring](./7_monitoring.md) — Monitoring

107
docs/4_blockchain/6_networking.md Normal file
View File

@@ -0,0 +1,107 @@
# Networking Configuration
Configure P2P networking for your blockchain node.
## Network Settings
### Firewall Configuration
```bash
# Allow P2P port
sudo ufw allow 7070/tcp
# Allow RPC port
sudo ufw allow 8080/tcp
# Allow from specific IPs
sudo ufw allow from 10.0.0.0/8 to any port 8080
```
### Port Forwarding
If behind a NAT, configure port forwarding:
- External port 7070 → Internal IP:7070
- External port 8080 → Internal IP:8080
## Bootstrap Nodes
### Default Bootstrap Nodes
```yaml
p2p:
bootstrap_nodes:
- /dns4/node-1.aitbc.com/tcp/7070/p2p/12D3KooW...
- /dns4/node-2.aitbc.com/tcp/7070/p2p/12D3KooW...
- /dns4/node-3.aitbc.com/tcp/7070/p2p/12D3KooW...
```
### Adding Custom Bootstrap Nodes
```bash
aitbc-chain p2p add-bootstrap /dns4/my-node.example.com/tcp/7070/p2p/...
```
## Peer Management
### Connection Limits
```yaml
p2p:
max_peers: 50
min_peers: 5
outbound_peers: 10
inbound_peers: 40
```
### Peer Scoring
Nodes are scored based on:
- Latency
- Availability
- Protocol compliance
- Block propagation speed
## NAT Traversal
### Supported Methods
| Method | Description |
|--------|-------------|
| AutoNAT | Automatic NAT detection |
| Hole Punching | UDP hole punching |
| Relay | TURN relay fallback |
### Configuration
```yaml
p2p:
nat:
enabled: true
method: auto # auto, hole_punching, relay
external_ip: 203.0.113.1
```
## Troubleshooting
### Check Connectivity
```bash
aitbc-chain p2p check-connectivity
```
### List Active Connections
```bash
aitbc-chain p2p connections
```
### Debug Mode
```bash
aitbc-chain start --log-level debug
```
## Next
- [Quick Start](./1_quick-start.md) — Get started
- [Configuration](./2_configuration.md) - Configure your node
- [Operations](./3_operations.md) — Day-to-day ops

89
docs/4_blockchain/7_monitoring.md Normal file
View File

@@ -0,0 +1,89 @@
# Node Monitoring
Monitor your blockchain node performance and health.
## Dashboard
```bash
aitbc-chain dashboard
```
Shows:
- Block height
- Peers connected
- Mempool size
- CPU/Memory/GPU usage
- Network traffic
## Prometheus Metrics
```bash
# Enable metrics
aitbc-chain metrics --port 9090
```
Available metrics:
- `aitbc_block_height` - Current block height
- `aitbc_peers_count` - Number of connected peers
- `aitbc_mempool_size` - Transactions in mempool
- `aitbc_block_production_time` - Block production time
- `aitbc_cpu_usage` - CPU utilization
- `aitbc_memory_usage` - Memory utilization
## Alert Configuration
### Set Alerts
```bash
# Low peers alert
aitbc-chain alert --metric peers --threshold 3 --action notify
# High mempool alert
aitbc-chain alert --metric mempool --threshold 5000 --action notify
# Sync delay alert
aitbc-chain alert --metric sync_delay --threshold 100 --action notify
```
### Alert Actions
| Action | Description |
|--------|-------------|
| notify | Send notification |
| restart | Restart node |
| pause | Pause block production |
## Log Monitoring
```bash
# Real-time logs
aitbc-chain logs --tail
# Search logs
aitbc-chain logs --grep "error" --since "1h"
# Export logs
aitbc-chain logs --export /var/log/aitbc-chain/
```
## Health Checks
```bash
# Run health check
aitbc-chain health
# Detailed report
aitbc-chain health --detailed
```
Checks:
- Disk space
- Memory
- P2P connectivity
- RPC availability
- Database sync
## Next
- [Quick Start](./1_quick-start.md) — Get started
- [Configuration](./2_configuration.md) - Configure your node
- [Operations](./3_operations.md) — Day-to-day ops

153
docs/4_blockchain/8_troubleshooting.md Normal file
View File

@@ -0,0 +1,153 @@
# Troubleshooting
Common issues and solutions for blockchain nodes.
## Common Issues
### Node Won't Start
```bash
# Check logs
tail -f ~/.aitbc/logs/chain.log
# Common causes:
# - Port already in use
# - Corrupted database
# - Invalid configuration
```
**Solutions:**
```bash
# Kill existing process
sudo lsof -i :8080
sudo kill $(sudo lsof -t -i :8080)
# Reset database
rm -rf ~/.aitbc/data/chain.db
aitbc-chain init
# Validate config
aitbc-chain validate-config
```
### Sync Stuck
```bash
# Check sync status
aitbc-chain sync-status
# Force sync from scratch
aitbc-chain reset --hard
# Check peer connectivity
aitbc-chain p2p connections
```
**Solutions:**
```bash
# Add more peers
aitbc-chain p2p add-bootstrap /dns4/new-peer.example.com/tcp/7070/p2p/...
# Clear peer database
rm -rf ~/.aitbc/data/peers.db
# Restart with fresh sync
aitbc-chain start --sync-mode full
```
### P2P Connection Issues
```bash
# Check connectivity
aitbc-chain p2p check-connectivity
# Test port forwarding
curl http://localhost:8080/rpc/net_info
```
**Solutions:**
```bash
# Open firewall
sudo ufw allow 7070/tcp
sudo ufw allow 8080/tcp
# Check NAT configuration
aitbc-chain p2p nat-status
# Use relay mode
aitbc-chain start --p2p-relay-enabled
```
### High Memory Usage
```bash
# Check memory usage
htop | grep aitbc-chain
# Check database size
du -sh ~/.aitbc/data/
```
**Solutions:**
```bash
# Prune old data
aitbc-chain prune --keep-blocks 10000
# Reduce peer count
# Edit config: max_peers: 25
# Enable compression
aitbc-chain start --db-compression
```
### RPC Not Responding
```bash
# Check RPC status
curl http://localhost:8080/rpc/health
# Check if RPC is enabled
aitbc-chain status | grep RPC
```
**Solutions:**
```bash
# Restart with RPC enabled
aitbc-chain start --rpc-enabled
# Check CORS settings
# Edit config: rpc.cors_origins
# Increase rate limits
# Edit config: rpc.rate_limit: 2000
```
## Diagnostic Commands
```bash
# Full system check
aitbc-chain doctor
# Network diagnostics
aitbc-chain diagnose network
# Database diagnostics
aitbc-chain diagnose database
# Log analysis
aitbc-chain logs --analyze
```
## Getting Help
```bash
# Generate debug report
aitbc-chain debug-report > debug.txt
# Share on Discord or GitHub Issues
```
## Next
- [Quick Start](./1_quick-start.md) — Get started
- [Configuration](./2_configuration.md) - Configure your node
- [Operations](./3_operations.md) — Day-to-day ops

77
docs/4_blockchain/9_upgrades.md Normal file
View File

@@ -0,0 +1,77 @@
# Node Upgrades
Guide for upgrading your blockchain node.
## Upgrade Process
### Check Current Version
```bash
aitbc-chain version
```
### Check for Updates
```bash
aitbc-chain check-update
```
### Upgrade Steps
```bash
# 1. Backup data
aitbc-chain backup --output /backup/chain-$(date +%Y%m%d).tar.gz
# 2. Stop node gracefully
aitbc-chain stop
# 3. Upgrade software
pip install --upgrade aitbc-chain
# 4. Review migration notes
cat CHANGELOG.md
# 5. Start node
aitbc-chain start
```
## Version-Specific Upgrades
### v0.1.0 → v0.2.0
```bash
# Database migration required
aitbc-chain migrate --from v0.1.0
```
### v0.2.0 → v0.3.0
```bash
# Configuration changes
aitbc-chain migrate-config --from v0.2.0
```
## Rollback Procedure
```bash
# If issues occur, rollback
pip install aitbc-chain==0.1.0
# Restore from backup
aitbc-chain restore --input /backup/chain-YYYYMMDD.tar.gz
# Start old version
aitbc-chain start
```
## Upgrade Notifications
```bash
# Enable upgrade alerts
aitbc-chain alert --metric upgrade_available --action notify
```
## Next
- [Quick Start](./1_quick-start.md) — Get started
- [Operations](./3_operations.md) — Day-to-day ops
- [Monitoring](./7_monitoring.md) — Monitoring