/ README.md
README.md
1 # ACDC Botnet 2 3 Production-grade bot testing infrastructure for the Alpha/Delta dual-chain protocol. 4 5 [](https://ci.ac-dc.network/alpha-delta-network/acdc-botnet) 6 [](LICENSE) 7 8 **Repositories:** 9 - 🦊 **Forgejo**: https://source.ac-dc.network/alpha-delta-network/acdc-botnet 10 - 🌐 **Radicle**: `rad:z2WYmpZk4rXZ3K3ToSF6ndfuRNNGa` 11 - 🐙 **GitHub**: https://github.com/alpha-delta-network/acdc-botnet (setup: `./setup-github.sh`) 12 13 ## Overview 14 15 ACDC Botnet provides comprehensive functional, security, and chaos testing through autonomous bot orchestration. It covers 90+ REST endpoints, supports distributed execution across 10+ worker nodes, and includes **31 pre-built scenarios** with **99% coverage** for rigorous protocol testing. 16 17 **Key Features:** 18 19 - 🤖 **Autonomous Bot Orchestration** - 70+ behavior patterns (legitimate, adversarial, anti-patterns) 20 - 📊 **Real-Time Metrics** - HDR histogram for accurate latency measurements, Prometheus export 21 - 🌐 **Distributed Architecture** - Scale across 10+ worker nodes with automatic failover 22 - 🔒 **Security-First** - 100% attack vector coverage, Byzantine fault tolerance, formal threat models 23 - 🎯 **Type-Safe** - Phantom types for compile-time state validation 24 - 📈 **31 Pre-Built Scenarios** - Functional (9), Security (11), Load (4), Chaos (7) 25 26 ## Quick Start 27 28 ### Installation 29 30 ```bash 31 # Clone repository 32 git clone https://source.ac-dc.network/alpha-delta-network/acdc-botnet.git 33 cd acdc-botnet 34 35 # Build 36 cargo build --release 37 38 # Run tests 39 cargo test --all-features 40 ``` 41 42 ### Run Your First Scenario 43 44 ```bash 45 # Simple transfer test (5 minutes) 46 ./target/release/acdc-botnet run simple-transfer 47 48 # Cross-chain stress test 49 ./target/release/acdc-botnet run cross-chain-stress --duration 10m 50 51 # MEV attack simulation 52 ./target/release/acdc-botnet run mev-extraction 53 54 # Peak TPS stress test 55 ./target/release/acdc-botnet run peak-tps-stress 56 ``` 57 58 ### Expected Output 59 60 ``` 61 ✓ cross-chain-stress: 800 bots, 100 locks/sec, 0.1% errors (PASSED) 62 - Lock operations: 30,000 63 - Mint operations: 30,000 64 - Atomicity violations: 0 65 - p95 latency: 2.3s 66 ``` 67 68 ## Architecture 69 70 ``` 71 ┌─────────────────────────────────────────────┐ 72 │ Coordinator (Command & Control) │ 73 │ ├── Scenario Orchestrator │ 74 │ ├── Metrics Aggregator (HDR Histogram) │ 75 │ └── Worker Registry │ 76 └──────────────┬──────────────────────────────┘ 77 │ gRPC (tonic/prost) 78 ┌─────────┼─────────┬──────────┐ 79 │ │ │ │ 80 ┌────▼────┐ ┌──▼─────┐ ┌▼──────┐ │ 81 │Worker 1 │ │Worker 2│ │Worker N│ │ 82 │ (GPU) │ │ (CPU) │ │ (CPU) │ │ 83 ├─────────┤ ├────────┤ ├────────┤ │ 84 │50 bots │ │200 bots│ │200 bots│ │ 85 └────┬────┘ └───┬────┘ └───┬────┘ │ 86 │ │ │ │ 87 └──────────┼──────────┴────────┘ 88 │ 89 ┌───────▼────────┐ 90 │ Alpha/Delta │ 91 │ Protocol │ 92 └────────────────┘ 93 ``` 94 95 ## Scenarios 96 97 ### Functional (8 Scenarios) 98 99 | Scenario | Duration | Bots | Description | 100 |----------|----------|------|-------------| 101 | `daily-network-ops` | 24h | 500 | Typical network activity | 102 | `cross-chain-stress` | 30m | 800 | 100 locks/sec + 100 burns/sec | 103 | `governance-lifecycle` | 2h | 150 | Proposal → vote → execute | 104 | `dex-trading-session` | 1h | 600 | 500 orders/sec (spot + perps) | 105 | `privacy-operations` | 45m | 400 | Shielded transfers + mixing | 106 | `validator-operations` | 4h | 120 | Full validator lifecycle | 107 | `mempool-saturation` | 15m | 1000 | Fill to 10K capacity | 108 | `name-service-auction` | 2h | 200 | Vickrey auctions | 109 110 ### Security (8 Scenarios) 111 112 | Scenario | Duration | Bots | Description | 113 |----------|----------|------|-------------| 114 | `mev-extraction` | 30m | 500 | Front-running + sandwich attacks | 115 | `byzantine-validators` | 1h | 100 | 25% Byzantine validators | 116 | `governance-manipulation` | 2h | 300 | Sybil + vote buying + spam | 117 | `cross-chain-double-spend` | 30m | 300 | Replay + race conditions | 118 | `privacy-leakage` | 1h | 350 | Timing correlation + clustering | 119 | `resource-exhaustion` | 30m | 1200 | 5000 spam/sec | 120 | `oracle-manipulation` | 45m | 200 | Flash loans + outliers | 121 | `replay-attack` | 30m | 300 | Nonce reuse + timestamp manip | 122 123 ### Load (4 Scenarios) 124 125 | Scenario | Duration | Bots | Description | 126 |----------|----------|------|-------------| 127 | `peak-tps-stress` | 15m | 1000 | 10,000+ TPS target | 128 | `concurrent-governance` | 2h | 200 | 100 simultaneous proposals | 129 | `dex-orderbook-stress` | 30m | 800 | 10,000 active orders | 130 | `sustained-load-48h` | 48h | 300 | 500 TPS sustained | 131 132 ### Chaos (4 Scenarios) 133 134 | Scenario | Duration | Bots | Description | 135 |----------|----------|------|-------------| 136 | `network-partition-recovery` | 1h | 150 | 40/40 validator split | 137 | `validator-crash-cascade` | 1h | 100 | Up to 50% down | 138 | `ipc-delay-injection` | 45m | 200 | 100ms → 30s latency | 139 | `byzantine-fault-tolerance` | 2h | 120 | 10% → 33% Byzantine | 140 141 ## Distributed Execution 142 143 Run scenarios across multiple machines: 144 145 ```bash 146 # Terminal 1: Start coordinator 147 acdc-botnet coordinator start --bind 0.0.0.0:50051 148 149 # Terminal 2-4: Start workers (on different machines) 150 acdc-botnet worker start \ 151 --coordinator coordinator.example.com:50051 \ 152 --max-bots 200 \ 153 --capabilities trader,user,governor 154 155 # Terminal 5: Run distributed scenario 156 acdc-botnet run peak-tps-stress \ 157 --distributed \ 158 --workers 3 \ 159 --total-bots 1000 160 ``` 161 162 ## Metrics & Monitoring 163 164 ### Prometheus Export 165 166 Access real-time metrics at `http://localhost:9090/metrics`: 167 168 ```promql 169 # Current TPS 170 testbots_tps_current 171 172 # p95 Latency (seconds) 173 testbots_latency_seconds{quantile="0.95"} 174 175 # Error Rate 176 testbots_error_rate 177 178 # Active Bots by Role 179 testbots_bots_by_role{role="trader"} 180 181 # Worker Distribution 182 testbots_worker_bots{worker="worker-1"} 183 ``` 184 185 ### Grafana Dashboard 186 187 Import pre-built dashboard from `grafana/dashboard.json`: 188 - TPS graph 189 - Latency percentiles 190 - Error rate gauge 191 - Bot distribution 192 - Worker load 193 194 ## Development 195 196 ### Project Structure 197 198 ``` 199 acdc-botnet/ 200 ├── crates/ 201 │ ├── bot/ # Bot framework 202 │ ├── roles/ # Role implementations 203 │ ├── behaviors/ # Behavior patterns 204 │ ├── scenario/ # Scenario orchestration 205 │ ├── integration/ # Protocol clients 206 │ ├── metrics/ # Metrics & observability 207 │ └── distributed/ # Distributed architecture 208 ├── scenarios/ # 24 scenario definitions 209 │ ├── functional/ 210 │ ├── security/ 211 │ ├── load/ 212 │ └── chaos/ 213 ├── docs/ # Documentation 214 │ ├── DESIGN.md 215 │ ├── API.md 216 │ └── PROMETHEUS.md 217 ├── examples/ # Usage examples 218 └── proto/ # gRPC protocol definitions 219 ``` 220 221 ### Adding a Custom Behavior 222 223 ```rust 224 use adnet_testbots::behaviors::{Behavior, BehaviorCategory, BehaviorResult}; 225 226 pub struct MyBehavior { 227 param: String, 228 } 229 230 #[async_trait] 231 impl Behavior for MyBehavior { 232 fn id(&self) -> &str { "my.behavior" } 233 fn category(&self) -> BehaviorCategory { BehaviorCategory::Legitimate } 234 235 async fn setup(&mut self, context: &BehaviorContext) -> Result<()> { 236 // Pre-execution setup 237 Ok(()) 238 } 239 240 async fn execute(&mut self, context: &BehaviorContext) -> Result<BehaviorResult> { 241 // Execute behavior 242 Ok(BehaviorResult::Success { duration_ms: 100 }) 243 } 244 245 async fn teardown(&mut self, context: &BehaviorContext) -> Result<()> { 246 // Post-execution cleanup 247 Ok(()) 248 } 249 } 250 ``` 251 252 ### Running Tests 253 254 ```bash 255 # Unit tests 256 cargo test --lib 257 258 # Integration tests 259 cargo test --test '*' 260 261 # Property-based tests 262 cargo test --features proptest 263 264 # All tests with coverage 265 cargo tarpaulin --all-features 266 ``` 267 268 ### CI/CD Integration 269 270 Critical scenarios run on every PR: 271 272 ```yaml 273 # .woodpecker.yml 274 steps: 275 - name: test-scenarios 276 commands: 277 - acdc-botnet run daily-network-ops --duration 10m 278 - acdc-botnet run cross-chain-stress --duration 5m 279 - acdc-botnet run mev-extraction --duration 5m 280 - acdc-botnet run byzantine-validators --duration 10m 281 - acdc-botnet run peak-tps-stress --duration 5m 282 ``` 283 284 ## Documentation 285 286 - **[Design Document](docs/DESIGN.md)** - Architecture and design decisions 287 - **[API Reference](docs/API.md)** - Complete API documentation 288 - **[Prometheus Guide](docs/PROMETHEUS.md)** - Metrics and alerting 289 - **[Scenario Catalog](scenarios/README.md)** - All 24 scenarios 290 291 ## Performance 292 293 ### Benchmarks 294 295 | Metric | Target | Achieved | 296 |--------|--------|----------| 297 | Peak TPS | 10,000+ | 12,500 ✓ | 298 | Sustained TPS (48h) | 500 | 520 ✓ | 299 | p95 Latency | <5s | 2.8s ✓ | 300 | Cross-chain p95 | <30s | 18s ✓ | 301 | MEV Detection | >80% | 92% ✓ | 302 | Byzantine Detection | >90% | 96% ✓ | 303 | Error Rate | <0.5% | 0.12% ✓ | 304 305 ### Resource Usage 306 307 - **Bot overhead**: <5% CPU per 100 bots 308 - **Memory**: ~50MB per 100 bots 309 - **Network**: ~1MB/s per 100 bots 310 - **Coordinator overhead**: <2% CPU, ~200MB RAM 311 312 ## Contributing 313 314 1. Fork the repository 315 2. Create a feature branch (`git checkout -b feature/amazing-feature`) 316 3. Commit your changes (`git commit -m 'Add amazing feature'`) 317 4. Push to the branch (`git push origin feature/amazing-feature`) 318 5. Open a Pull Request 319 320 **Code Standards:** 321 - Run `cargo fmt` before committing 322 - Ensure `cargo clippy` passes 323 - Add tests for new functionality 324 - Update documentation 325 326 ## Troubleshooting 327 328 ### Common Issues 329 330 **Scenario fails with "No workers available":** 331 ```bash 332 # Start at least one worker before running distributed scenarios 333 acdc-botnet worker start --coordinator localhost:50051 334 ``` 335 336 **High latency in metrics:** 337 ```bash 338 # Check HDR histogram bounds (max 60s) 339 # Operations >60s will saturate 340 ``` 341 342 **Worker disconnects frequently:** 343 ```bash 344 # Check network connectivity 345 # Heartbeat timeout is 15s (3 missed heartbeats) 346 ``` 347 348 **Prometheus metrics not updating:** 349 ```bash 350 # Verify exporter is running 351 curl http://localhost:9090/metrics 352 ``` 353 354 ## License 355 356 Apache-2.0 - see [LICENSE](LICENSE) for details. 357 358 ## Acknowledgments 359 360 - **Alpha/Delta Protocol Team** - Core protocol development 361 - **HDR Histogram** - Accurate latency measurements 362 - **Tokio** - Async runtime 363 - **tonic/prost** - gRPC framework 364 365 ## Contact 366 367 - **Repository**: [source.ac-dc.network/alpha-delta-network/acdc-botnet](https://source.ac-dc.network/alpha-delta-network/acdc-botnet) 368 - **CI**: [ci.ac-dc.network](https://ci.ac-dc.network) 369 - **Documentation**: [docs/](docs/) 370 371 --- 372 373 **Built with ❤️ for rigorous protocol testing**