feat(engine): create engine rust package for detectors and orchestration

2026-05-04 11:19:08 -07:00 · 2026-03-25 22:27:26 -03:00
parent 86335e8467
commit b8c196f8eb
8 changed files with 2315 additions and 0 deletions
--- a/engine/README.md
+++ b/engine/README.md
@@ -0,0 +1,116 @@
+# stealth-engine
+
+Detects Bitcoin UTXO privacy vulnerabilities by analysing a wallet's transaction
+history on a Bitcoin Core node via JSON-RPC.
+
+The library receives a pre-built `WalletHistory` (via any `BlockchainGateway`
+implementation), indexes it into a `TxGraph`, then runs independent
+vulnerability detectors through `TxGraph::detect_all()`. Results are returned
+as a structured `Report` that serialises to JSON.
+
+Primary public scanning API: `TxGraph::detect_all(...)`.
+
+## Detected vulnerabilities
+
+| #   | Vulnerability                           | Default severity |
+| --- | --------------------------------------- | ---------------- |
+| 1   | Address reuse                           | HIGH             |
+| 2   | Common-input-ownership heuristic (CIOH) | HIGH – CRITICAL  |
+| 3   | Dust UTXO reception                     | MEDIUM – HIGH    |
+| 4   | Dust spent alongside normal inputs      | HIGH             |
+| 5   | Identifiable change outputs             | MEDIUM           |
+| 6   | UTXOs born from consolidation txs       | MEDIUM           |
+| 7   | Mixed script types in inputs            | HIGH             |
+| 8   | Cross-origin cluster merge              | HIGH             |
+| 9   | UTXO age / lookback-depth spread        | LOW              |
+| 10  | Exchange-origin batch withdrawal        | MEDIUM           |
+| 11  | Tainted UTXO merge                      | HIGH             |
+| 12  | Behavioural fingerprinting              | MEDIUM           |
+
+## Prerequisites
+
+- **Rust** >= 1.93.1
+- **Bitcoin Core** (`bitcoind`) >= 0.29.0 — must be on your `PATH`
+
+### Installing Bitcoin Core
+
+```bash
+# macOS (Homebrew)
+brew install bitcoin
+
+# Ubuntu / Debian
+sudo apt install bitcoind
+
+# Or download from https://bitcoincore.org/en/download/
+```
+
+Verify it is available:
+
+```bash
+bitcoind --version
+```
+
+## Usage
+
+Add the crate to your `Cargo.toml`:
+
+```toml
+[dependencies]
+stealth-engine = "0.1.0"
+```
+
+```rust,ignore
+use stealth_engine::gateway::BlockchainGateway;
+use stealth_engine::TxGraph;
+use stealth_bitcoincore::BitcoinCoreRpc;
+
+// Connect to a wallet-loaded bitcoind
+let gateway = BitcoinCoreRpc::from_url(
+    "http://127.0.0.1:8332",
+    Some("user".into()),
+    Some("pass".into()),
+).unwrap();
+let history = gateway.scan_wallet("my_wallet").unwrap();
+
+let graph = TxGraph::from_wallet_history(history);
+let report = graph.detect_all(&Default::default(), None, None);
+
+for finding in &report.findings {
+    println!("{}: {}", finding.severity, finding.vulnerability_type);
+}
+```
+
+## Running the tests
+
+The integration tests spin up a temporary `bitcoind` in regtest mode
+(via [`corepc-node`](https://crates.io/crates/corepc-node)).
+No external setup is required — just ensure `bitcoind` is on your `PATH`.
+
+```bash
+# Run all tests (unit + all regtest integration tests)
+cargo test -p stealth-engine
+
+# Run a single test with output
+cargo test -p stealth-engine detect_address_reuse -- --nocapture
+```
+
+> **Note:** The integration tests create ephemeral regtest nodes that are
+> automatically cleaned up. Each test takes a few seconds due to block mining.
+
+## Project structure
+
+```
+core/
+├── Cargo.toml
+├── src/
+│   ├── lib.rs        # Crate root and re-exports
+│   ├── engine.rs     # AnalysisEngine — canonical scan entry point
+│   ├── graph.rs      # TxGraph — indexed wallet transaction view
+│   └── detect.rs     # all vulnerability detectors + detect_all()
+└── tests/
+    └── integration.rs  # all regtest integration tests
+```
+
+## License
+
+[MIT](../LICENSE)