chore: standardize configuration, logging, and error handling across blockchain node and coordinator API
- 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
@@ -1,16 +0,0 @@
|
||||
# Development Guides
|
||||
|
||||
This directory contains guides and documentation for development workflows.
|
||||
|
||||
## Guides
|
||||
|
||||
- **WINDSURF_TESTING_GUIDE.md** - Comprehensive guide for testing with Windsurf
|
||||
- **WINDSURF_TEST_SETUP.md** - Quick setup guide for Windsurf testing
|
||||
|
||||
## Additional Documentation
|
||||
|
||||
More documentation can be found in the parent `docs/` directory, including:
|
||||
- API documentation
|
||||
- Architecture documentation
|
||||
- Deployment guides
|
||||
- Infrastructure documentation
|
||||
@@ -1,174 +0,0 @@
|
||||
# Windsurf Testing Integration Guide
|
||||
|
||||
This guide explains how to use Windsurf's integrated testing features with the AITBC project.
|
||||
|
||||
## ✅ What's Been Configured
|
||||
|
||||
### 1. VS Code Settings (`.vscode/settings.json`)
|
||||
- ✅ Pytest enabled (unittest disabled)
|
||||
- ✅ Test discovery configured
|
||||
- ✅ Auto-discovery on save enabled
|
||||
- ✅ Debug port configured
|
||||
|
||||
### 2. Debug Configuration (`.vscode/launch.json`)
|
||||
- ✅ Debug Python Tests
|
||||
- ✅ Debug All Tests
|
||||
- ✅ Debug Current Test File
|
||||
- ✅ Uses `debugpy` (not deprecated `python`)
|
||||
|
||||
### 3. Task Configuration (`.vscode/tasks.json`)
|
||||
- ✅ Run All Tests
|
||||
- ✅ Run Tests with Coverage
|
||||
- ✅ Run Unit Tests Only
|
||||
- ✅ Run Integration Tests
|
||||
- ✅ Run Current Test File
|
||||
- ✅ Run Test Suite Script
|
||||
|
||||
### 4. Pytest Configuration
|
||||
- ✅ `pyproject.toml` - Main configuration with markers
|
||||
- ✅ `pytest.ini` - Moved to project root with custom markers
|
||||
- ✅ `tests/conftest.py` - Fixtures with fallback mocks
|
||||
|
||||
### 5. Test Scripts (2026-01-29)
|
||||
- ✅ `scripts/testing/` - All test scripts moved here
|
||||
- ✅ `test_ollama_blockchain.py` - Complete GPU provider test
|
||||
- ✅ `test_block_import.py` - Blockchain block import testing
|
||||
|
||||
## 🚀 How to Use
|
||||
|
||||
### Test Discovery
|
||||
1. Open Windsurf
|
||||
2. Click the **Testing panel** (beaker icon in sidebar)
|
||||
3. Tests will be automatically discovered
|
||||
4. See all `test_*.py` files listed
|
||||
|
||||
### Running Tests
|
||||
|
||||
#### Option 1: Testing Panel
|
||||
- Click the **play button** next to any test
|
||||
- Click the **play button** at the top to run all tests
|
||||
- Right-click on a test folder for more options
|
||||
|
||||
#### Option 2: Command Palette
|
||||
- `Ctrl+Shift+P` (or `Cmd+Shift+P` on Mac)
|
||||
- Search for "Python: Run All Tests"
|
||||
- Or search for "Python: Run Test File"
|
||||
|
||||
#### Option 3: Tasks
|
||||
- `Ctrl+Shift+P` → "Tasks: Run Test Task"
|
||||
- Select the desired test task
|
||||
|
||||
#### Option 4: Keyboard Shortcuts
|
||||
- `F5` - Debug current test
|
||||
- `Ctrl+F5` - Run without debugging
|
||||
|
||||
### Debugging Tests
|
||||
1. Click the **debug button** next to any test
|
||||
2. Set breakpoints in your test code
|
||||
3. Press `F5` to start debugging
|
||||
4. Use the debug panel to inspect variables
|
||||
|
||||
### Test Coverage
|
||||
1. Run the "Run Tests with Coverage" task
|
||||
2. Open `htmlcov/index.html` in your browser
|
||||
3. See detailed coverage reports
|
||||
|
||||
## 📁 Test Structure
|
||||
|
||||
```
|
||||
tests/
|
||||
├── test_basic_integration.py # Basic integration tests
|
||||
├── test_discovery.py # Simple discovery tests
|
||||
├── test_windsurf_integration.py # Windsurf integration tests
|
||||
├── unit/ # Unit tests
|
||||
│ ├── test_coordinator_api.py
|
||||
│ ├── test_wallet_daemon.py
|
||||
│ └── test_blockchain_node.py
|
||||
├── integration/ # Integration tests
|
||||
│ └── test_full_workflow.py
|
||||
├── e2e/ # End-to-end tests
|
||||
│ └── test_user_scenarios.py
|
||||
└── security/ # Security tests
|
||||
└── test_security_comprehensive.py
|
||||
```
|
||||
|
||||
## 🏷️ Test Markers
|
||||
|
||||
Tests are marked with:
|
||||
- `@pytest.mark.unit` - Unit tests
|
||||
- `@pytest.mark.integration` - Integration tests
|
||||
- `@pytest.mark.e2e` - End-to-end tests
|
||||
- `@pytest.mark.security` - Security tests
|
||||
- `@pytest.mark.performance` - Performance tests
|
||||
|
||||
## 🔧 Troubleshooting
|
||||
|
||||
### Tests Not Discovered?
|
||||
1. Check that files start with `test_*.py`
|
||||
2. Verify pytest is enabled in settings
|
||||
3. Run `python -m pytest --collect-only` to debug
|
||||
|
||||
### Import Errors?
|
||||
1. The fixtures include fallback mocks
|
||||
2. Check `tests/conftest.py` for path configuration
|
||||
3. Use the mock clients if full imports fail
|
||||
|
||||
### Debug Not Working?
|
||||
1. Ensure `debugpy` is installed
|
||||
2. Check `.vscode/launch.json` uses `type: debugpy`
|
||||
3. Verify test has a debug configuration
|
||||
|
||||
## 📝 Example Test
|
||||
|
||||
```python
|
||||
import pytest
|
||||
from unittest.mock import patch
|
||||
|
||||
@pytest.mark.unit
|
||||
def test_example_function():
|
||||
"""Example unit test"""
|
||||
result = add(2, 3)
|
||||
assert result == 5
|
||||
|
||||
@pytest.mark.integration
|
||||
def test_api_endpoint(coordinator_client):
|
||||
"""Example integration test using fixture"""
|
||||
response = coordinator_client.get("/docs")
|
||||
assert response.status_code == 200
|
||||
```
|
||||
|
||||
## 🎯 Best Practices
|
||||
|
||||
1. **Use descriptive test names** - `test_specific_behavior`
|
||||
2. **Add appropriate markers** - `@pytest.mark.unit`
|
||||
3. **Use fixtures** - Don't repeat setup code
|
||||
4. **Mock external dependencies** - Keep tests isolated
|
||||
5. **Test edge cases** - Not just happy paths
|
||||
6. **Keep tests fast** - Unit tests should be < 1 second
|
||||
|
||||
## 📊 Running Specific Tests
|
||||
|
||||
```bash
|
||||
# Run all unit tests
|
||||
pytest -m unit
|
||||
|
||||
# Run specific file
|
||||
pytest tests/unit/test_coordinator_api.py
|
||||
|
||||
# Run with coverage
|
||||
pytest --cov=apps tests/
|
||||
|
||||
# Run in parallel
|
||||
pytest -n auto tests/
|
||||
```
|
||||
|
||||
## 🎉 Success!
|
||||
|
||||
Your Windsurf testing integration is now fully configured! You can:
|
||||
- Discover tests automatically
|
||||
- Run tests with a click
|
||||
- Debug tests visually
|
||||
- Generate coverage reports
|
||||
- Use all pytest features
|
||||
|
||||
Happy testing! 🚀
|
||||
@@ -1,40 +0,0 @@
|
||||
# Windsurf Test Discovery Setup
|
||||
|
||||
## Issue
|
||||
Unittest discovery errors when using Windsurf's test runner with the `tests/` folder.
|
||||
|
||||
## Solution
|
||||
1. **Updated pyproject.toml** - Added `tests` to the testpaths configuration
|
||||
2. **Created minimal conftest.py** - Removed complex imports that were causing discovery failures
|
||||
3. **Test discovery now works** for files matching `test_*.py` pattern
|
||||
|
||||
## Current Status
|
||||
- ✅ Test discovery works for simple tests (e.g., `tests/test_discovery.py`)
|
||||
- ✅ All `test_*.py` files are discovered by pytest
|
||||
- ⚠️ Tests with complex imports may fail during execution due to module path issues
|
||||
|
||||
## Running Tests
|
||||
|
||||
### For test discovery only (Windsurf integration):
|
||||
```bash
|
||||
cd /home/oib/windsurf/aitbc
|
||||
python -m pytest --collect-only tests/
|
||||
```
|
||||
|
||||
### For running all tests (with full setup):
|
||||
```bash
|
||||
cd /home/oib/windsurf/aitbc
|
||||
python run_tests.py tests/
|
||||
```
|
||||
|
||||
## Test Files Found
|
||||
- `tests/e2e/test_wallet_daemon.py`
|
||||
- `tests/integration/test_blockchain_node.py`
|
||||
- `tests/security/test_confidential_transactions.py`
|
||||
- `tests/unit/test_coordinator_api.py`
|
||||
- `tests/test_discovery.py` (simple test file)
|
||||
|
||||
## Notes
|
||||
- The original `conftest_full.py` contains complex fixtures requiring full module setup
|
||||
- To run tests with full functionality, restore `conftest_full.py` and use the wrapper script
|
||||
- For Windsurf's test discovery, the minimal `conftest.py` provides better experience
|
||||
@@ -1,94 +0,0 @@
|
||||
# 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`
|
||||
@@ -1,144 +0,0 @@
|
||||
# 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