docs: update README with comprehensive test results, CLI documentation, and enhanced feature descriptions
- Update key capabilities to include GPU marketplace, payments, billing, and governance - Expand CLI section from basic examples to 12 command groups with 90+ subcommands - Add detailed test results table showing 208 passing tests across 6 test suites - Update documentation links to reference new CLI reference and coordinator API docs - Revise test commands to reflect actual test structure (
This commit is contained in:
oib
94
docs/guides/block-production-runbook.md
Normal file
94
docs/guides/block-production-runbook.md
Normal file
@@ -0,0 +1,94 @@
|
||||
# Block Production Operational Runbook
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
```
|
||||
Clients → RPC /sendTx → Mempool → PoA Proposer → Block (with Transactions)
|
||||
↓
|
||||
Circuit Breaker
|
||||
(graceful degradation)
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
| Setting | Default | Env Var | Description |
|
||||
|---------|---------|---------|-------------|
|
||||
| `block_time_seconds` | 2 | `BLOCK_TIME_SECONDS` | Block interval |
|
||||
| `max_block_size_bytes` | 1,000,000 | `MAX_BLOCK_SIZE_BYTES` | Max block size (1 MB) |
|
||||
| `max_txs_per_block` | 500 | `MAX_TXS_PER_BLOCK` | Max transactions per block |
|
||||
| `min_fee` | 0 | `MIN_FEE` | Minimum fee to accept into mempool |
|
||||
| `mempool_backend` | memory | `MEMPOOL_BACKEND` | "memory" or "database" |
|
||||
| `mempool_max_size` | 10,000 | `MEMPOOL_MAX_SIZE` | Max pending transactions |
|
||||
| `circuit_breaker_threshold` | 5 | `CIRCUIT_BREAKER_THRESHOLD` | Failures before circuit opens |
|
||||
| `circuit_breaker_timeout` | 30 | `CIRCUIT_BREAKER_TIMEOUT` | Seconds before half-open retry |
|
||||
|
||||
## Mempool Backends
|
||||
|
||||
### In-Memory (default)
|
||||
- Fast, no persistence
|
||||
- Lost on restart
|
||||
- Suitable for devnet/testnet
|
||||
|
||||
### Database-backed (SQLite)
|
||||
- Persistent across restarts
|
||||
- Shared between services via file
|
||||
- Set `MEMPOOL_BACKEND=database`
|
||||
|
||||
## Monitoring Metrics
|
||||
|
||||
### Block Production
|
||||
- `blocks_proposed_total` — Total blocks proposed
|
||||
- `chain_head_height` — Current chain height
|
||||
- `last_block_tx_count` — Transactions in last block
|
||||
- `last_block_total_fees` — Total fees in last block
|
||||
- `block_build_duration_seconds` — Time to build last block
|
||||
- `block_interval_seconds` — Time between blocks
|
||||
|
||||
### Mempool
|
||||
- `mempool_size` — Current pending transaction count
|
||||
- `mempool_tx_added_total` — Total transactions added
|
||||
- `mempool_tx_drained_total` — Total transactions included in blocks
|
||||
- `mempool_evictions_total` — Transactions evicted (low fee)
|
||||
|
||||
### Circuit Breaker
|
||||
- `circuit_breaker_state` — 0=closed, 1=open
|
||||
- `circuit_breaker_trips_total` — Times circuit breaker opened
|
||||
- `blocks_skipped_circuit_breaker_total` — Blocks skipped due to open circuit
|
||||
|
||||
### RPC
|
||||
- `rpc_send_tx_total` — Total transaction submissions
|
||||
- `rpc_send_tx_success_total` — Successful submissions
|
||||
- `rpc_send_tx_rejected_total` — Rejected (fee too low, validation)
|
||||
- `rpc_send_tx_failed_total` — Failed (mempool unavailable)
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Empty blocks (tx_count=0)
|
||||
1. Check mempool size: `GET /metrics` → `mempool_size`
|
||||
2. Verify transactions are being submitted: `rpc_send_tx_total`
|
||||
3. Check if fees meet minimum: `rpc_send_tx_rejected_total`
|
||||
4. Verify block size limits aren't too restrictive
|
||||
|
||||
### Circuit breaker open
|
||||
1. Check `circuit_breaker_state` metric (1 = open)
|
||||
2. Review logs for repeated failures
|
||||
3. Check database connectivity
|
||||
4. Wait for timeout (default 30s) for automatic half-open retry
|
||||
5. If persistent, restart the node
|
||||
|
||||
### Mempool full
|
||||
1. Check `mempool_size` vs `MEMPOOL_MAX_SIZE`
|
||||
2. Low-fee transactions are auto-evicted
|
||||
3. Increase `MEMPOOL_MAX_SIZE` or raise `MIN_FEE`
|
||||
|
||||
### High block build time
|
||||
1. Check `block_build_duration_seconds`
|
||||
2. Reduce `MAX_TXS_PER_BLOCK` if too slow
|
||||
3. Consider database mempool for large volumes
|
||||
4. Check disk I/O if using SQLite backend
|
||||
|
||||
### Transaction not included in block
|
||||
1. Verify transaction was accepted: check `tx_hash` in response
|
||||
2. Check fee is competitive (higher fee = higher priority)
|
||||
3. Check transaction size vs `MAX_BLOCK_SIZE_BYTES`
|
||||
4. Transaction may be queued — check `mempool_size`
|
||||
144
docs/guides/blockchain-node-deployment.md
Normal file
144
docs/guides/blockchain-node-deployment.md
Normal file
@@ -0,0 +1,144 @@
|
||||
# Blockchain Node Deployment Guide
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Python 3.11+
|
||||
- SQLite 3.35+
|
||||
- 512 MB RAM minimum (1 GB recommended)
|
||||
- 10 GB disk space
|
||||
|
||||
## Configuration
|
||||
|
||||
All settings via environment variables or `.env` file:
|
||||
|
||||
```bash
|
||||
# Core
|
||||
CHAIN_ID=ait-devnet
|
||||
DB_PATH=./data/chain.db
|
||||
PROPOSER_ID=ait-devnet-proposer
|
||||
BLOCK_TIME_SECONDS=2
|
||||
|
||||
# RPC
|
||||
RPC_BIND_HOST=0.0.0.0
|
||||
RPC_BIND_PORT=8080
|
||||
|
||||
# Block Production
|
||||
MAX_BLOCK_SIZE_BYTES=1000000
|
||||
MAX_TXS_PER_BLOCK=500
|
||||
MIN_FEE=0
|
||||
|
||||
# Mempool
|
||||
MEMPOOL_BACKEND=database # "memory" or "database"
|
||||
MEMPOOL_MAX_SIZE=10000
|
||||
|
||||
# Circuit Breaker
|
||||
CIRCUIT_BREAKER_THRESHOLD=5
|
||||
CIRCUIT_BREAKER_TIMEOUT=30
|
||||
|
||||
# Sync
|
||||
TRUSTED_PROPOSERS=proposer-a,proposer-b
|
||||
MAX_REORG_DEPTH=10
|
||||
SYNC_VALIDATE_SIGNATURES=true
|
||||
|
||||
# Gossip
|
||||
GOSSIP_BACKEND=memory # "memory" or "broadcast"
|
||||
GOSSIP_BROADCAST_URL= # Required for broadcast backend
|
||||
```
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
cd apps/blockchain-node
|
||||
pip install -e .
|
||||
```
|
||||
|
||||
## Running
|
||||
|
||||
### Development
|
||||
```bash
|
||||
uvicorn aitbc_chain.app:app --host 127.0.0.1 --port 8080 --reload
|
||||
```
|
||||
|
||||
### Production
|
||||
```bash
|
||||
uvicorn aitbc_chain.app:app \
|
||||
--host 0.0.0.0 \
|
||||
--port 8080 \
|
||||
--workers 1 \
|
||||
--timeout-keep-alive 30 \
|
||||
--access-log \
|
||||
--log-level info
|
||||
```
|
||||
|
||||
**Note:** Use `--workers 1` because the PoA proposer must run as a single instance.
|
||||
|
||||
### Systemd Service
|
||||
```ini
|
||||
[Unit]
|
||||
Description=AITBC Blockchain Node
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=aitbc
|
||||
WorkingDirectory=/opt/aitbc/apps/blockchain-node
|
||||
EnvironmentFile=/opt/aitbc/.env
|
||||
ExecStart=/opt/aitbc/venv/bin/uvicorn aitbc_chain.app:app --host 0.0.0.0 --port 8080 --workers 1
|
||||
Restart=always
|
||||
RestartSec=5
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
## Endpoints
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| GET | `/health` | Health check |
|
||||
| GET | `/metrics` | Prometheus metrics |
|
||||
| GET | `/rpc/head` | Chain head |
|
||||
| GET | `/rpc/blocks/{height}` | Block by height |
|
||||
| GET | `/rpc/blocks` | Latest blocks |
|
||||
| GET | `/rpc/tx/{hash}` | Transaction by hash |
|
||||
| POST | `/rpc/sendTx` | Submit transaction |
|
||||
| POST | `/rpc/importBlock` | Import block from peer |
|
||||
| GET | `/rpc/syncStatus` | Sync status |
|
||||
| POST | `/rpc/admin/mintFaucet` | Mint devnet funds |
|
||||
|
||||
## Monitoring
|
||||
|
||||
### Health Check
|
||||
```bash
|
||||
curl http://localhost:8080/health
|
||||
```
|
||||
|
||||
### Key Metrics
|
||||
- `poa_proposer_running` — 1 if proposer is active
|
||||
- `chain_head_height` — Current block height
|
||||
- `mempool_size` — Pending transactions
|
||||
- `circuit_breaker_state` — 0=closed, 1=open
|
||||
- `rpc_requests_total` — Total RPC requests
|
||||
- `rpc_rate_limited_total` — Rate-limited requests
|
||||
|
||||
### Alerting Rules (Prometheus)
|
||||
```yaml
|
||||
- alert: ProposerDown
|
||||
expr: poa_proposer_running == 0
|
||||
for: 1m
|
||||
|
||||
- alert: CircuitBreakerOpen
|
||||
expr: circuit_breaker_state == 1
|
||||
for: 30s
|
||||
|
||||
- alert: HighErrorRate
|
||||
expr: rate(rpc_server_errors_total[5m]) > 0.1
|
||||
for: 2m
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- **Proposer not producing blocks**: Check `poa_proposer_running` metric, review logs for DB errors
|
||||
- **Rate limiting**: Increase `max_requests` in middleware or add IP allowlist
|
||||
- **DB locked**: Switch to `MEMPOOL_BACKEND=database` for separate mempool DB
|
||||
- **Sync failures**: Check `TRUSTED_PROPOSERS` config, verify peer connectivity
|
||||
Reference in New Issue
Block a user