Upload README.md with huggingface_hub

README.md

@@ -12,145 +12,101 @@ tags:
   - evm
   - exploit-detection
   - cnn
+  - solidity
 pipeline_tag: other
 ---
 
-# 🔱 Leviathan v2 — EVM Exploit Topology Classifier
+# 🔱 LEVIATHAN v2 — EVM Exploit Topology Classifier
 
-**Bare-metal CNN that classifies Ethereum smart contract execution manifolds as THREAT or CLEAN, refined through ZKAEDI PRIME bistable attractor dynamics.**
-
-## Pipeline
-
-```
-EVM Trace (debug_traceTransaction / Foundry / eth_getCode)
-    → Hilbert-Encoded 256×256 Manifold (2-channel)
-        → Downsample to 20×20
-            → CNN (264,897 params)
-                → PRIME Bistable Refinement (T=256)
-                    → THREAT / CLEAN (committed verdict)
-```
-
-## Two-Channel Input
-
-| Channel | Field | Source |
-|---------|-------|--------|
-| 0 (H) | Opcode energy density | EVM opcode frequencies mapped via Hilbert curve |
-| 1 (V) | Stack depth / state mutation | Call depth × storage write intensity |
-
-The 256×256 manifold is generated by `manifold_forge.py` or `evm_trace_ingester.py`, then downsampled to 20×20 for the CNN.
+**Bare-metal CNN on Hilbert-encoded 2-channel EVM execution manifolds. Classifies exploit topologies as THREAT or CLEAN via convolutional pattern recognition + ZKAEDI PRIME bistable attractor refinement.**
 
 ## Architecture
 
 ```
-Conv2d(2→16, 3×3, no pad) → ReLU
-Conv2d(16→16, 3×3, no pad) → ReLU
-Flatten → 4096
-Linear(4096→64) → ReLU
-Linear(64→1) → raw logit
+256x256 EVM Manifold (Hilbert-encoded)
+    | area-average downsample
+20x20 input tensor (2 channels)
+    |
+Conv2d(2->16, 3x3) -> ReLU     -> 18x18x16
+Conv2d(16->16, 3x3) -> ReLU    -> 16x16x16
+    | flatten
+4096
+    |
+Linear(4096->64) -> ReLU
+Linear(64->1)    -> raw score
+    |
+ZKAEDI PRIME Bistable Refinement (T=256 iterations)
+    |
+THREAT / CLEAN / UNCERTAIN
 ```
 
-| Layer | Shape | Params |
-|-------|-------|--------|
+| Layer | Shape | Parameters |
+|-------|-------|------------|
 | conv_net.0 | (16, 2, 3, 3) + bias | 304 |
 | conv_net.2 | (16, 16, 3, 3) + bias | 2,320 |
 | fc.1 | (64, 4096) + bias | 262,208 |
 | fc.3 | (1, 64) + bias | 65 |
 | **Total** | | **264,897** |
 
-## PRIME Bistable Attractor Refinement
+## Channel Semantics
+
+| Channel | Field | Source |
+|---------|-------|--------|
+| 0 | H (activator) | Opcode energy density — gas cost per execution step |
+| 1 | V (inhibitor) | Stack depth / state mutation intensity |
+
+## Manifold Encoding
 
-Raw CNN scores pass through the ZKAEDI PRIME recursive Hamiltonian:
+EVM traces mapped to 256x256 via **Hilbert curve**: spatial locality = execution locality. Gaussian smoothing (sigma=1.5) for coherence. Long traces wrap with accumulation.
+
+## PRIME Bistable Refinement
 
 ```
-H_t = H_{t-1} + η·H_{t-1}·σ(γ·H_{t-1}) + ε·N(0, 1+β|H_{t-1}|)
+H_{t+1} = H_t + eta * H_t * sigma(gamma * H_t) + eps * N(0, 1 + beta * |H_t|)
 ```
 
-With **η=3.50** the system is deeply bistable:
-- **Negative attractor** H* = −3.054 → CLEAN committed
-- **Positive attractor** H* > 0 → THREAT committed
-- Uncertain scores (near 0.5) are forced to one attractor, eliminating ambiguity
-
-Jacobian stability verified: J = 0.346 < 1.
+Parameters: eta=3.50, gamma=0.30, beta=0.10, sigma=0.05, T=256
 
-Thresholds: P < 0.10 → BENIGN committed | P > 0.90 → THREAT committed
+Fixed points (analytically derived): H* = -3.054 (CLEAN) and H* = +3.054 (THREAT). Jacobian J=0.346 < 1 (stable).
 
-## Benchmark Results
+## Validated Results
 
-| Contract | Score | Verdict |
-|----------|-------|---------|
+| Contract / Pattern | Score | Verdict |
+|--------------------|-------|---------|
 | Gnosis Multisig (baseline) | 0.0000 | CLEAN |
 | SWC-107 Reentrancy | 1.0000 | THREAT |
-| SWC-112 Delegatecall | 1.0000 | THREAT |
+| SWC-112 Delegatecall Abuse | 1.0000 | THREAT |
 | SWC-101 Integer Overflow | 1.0000 | THREAT |
-| Cross-Function Reentrancy | 1.0000 | THREAT |
+| Cross-function Reentrancy | 1.0000 | THREAT |
 | Flash Loan Manipulation | 1.0000 | THREAT |
 
-6/6 correct. Zero false positives, zero false negatives on validation set.
-
 ## Usage
 
 ```python
 from leviathan import Leviathan
 
-model = Leviathan.from_safetensors("leviathan_v2_session_trained.safetensors")
-
-# Classify a 256×256 manifold (from manifold_forge.py or evm_trace_ingester.py)
-result = model.classify_manifold(H_256, V_256)
-# → {"raw_score": 0.9987, "refined_score": 0.9999, "verdict": "THREAT", "confidence": "COMMITTED"}
+model = Leviathan.from_huggingface("zkaedi/leviathan-v2")
 
-# Full pipeline: global + regional scan + PRIME refinement
-pipeline = model.full_pipeline(H_256, V_256)
-# → {"verdict": "THREAT", "threat_regions": [...], "threat_region_count": 5}
+# Full audit: CNN + PRIME refinement
+result = model.audit(H_256x256, V_256x256)
+# {"verdict": "THREAT", "committed": True, "refined_score": 0.9998, ...}
 
-# Also supports raw float32 binary format (from leviathan.c)
-model = Leviathan.from_bin("leviathan_weights.bin")
+# From raw EVM trace
+result = model.audit_trace(opcode_energies, stack_depths)
 ```
 
-## Integration with ZKAEDI Security Pipeline
+## ZKAEDI Security Pipeline
 
 ```
 Solidity Code
-  → gemma-2-9b-solidity-merged (vulnerability energy signatures)
-    → prime-swarm-hunter (12-agent temporal compound detection)
-      → evm_trace_ingester.py (EVM trace → 256×256 manifold)
-        → LEVIATHAN v2 (this model — CNN topology classification)
-          → PRIME refinement (bistable attractor commitment)
-            → solidity-vuln-auditor-7b (final audit report)
+  -> gemma-2-9b-solidity-merged      (vulnerability signatures)
+    -> prime-swarm-hunter              (12-agent compound detection)
+      -> evm_trace_ingester            (trace -> 256x256 manifold)
+        -> LEVIATHAN v2                (CNN topology classification)
+          -> PRIME refinement           (bistable commitment)
+            -> solidity-vuln-auditor-7b (final audit report)
 ```
 
-### As a tool for your HF models
-
-```python
-from gradio_client import Client
-import json
-
-# Step 1: Swarm detects compound vulns
-swarm = Client("zkaedi/prime-swarm-hunter")
-swarm_result = json.loads(swarm.predict("defi_lending_pool", 300, 150, 42, api_name="/api_preset"))
-
-# Step 2: Leviathan classifies the execution manifold
-from leviathan import Leviathan
-lev = Leviathan.from_safetensors("leviathan_v2_session_trained.safetensors")
-verdict = lev.classify_manifold(H_manifold, V_manifold)
-
-# Step 3: Combined audit result
-audit = {
-    "compound_vulns": swarm_result["compound_findings"],
-    "topology_verdict": verdict["verdict"],
-    "risk_score": swarm_result["summary"]["risk_score"],
-}
-```
-
-## Companion Files
-
-| File | Purpose |
-|------|---------|
-| `leviathan.py` | Pure NumPy inference (this repo) |
-| `leviathan.c` | 622-line bare-metal C inference engine |
-| `manifold_forge.py` | Exploit manifold generator (5 SWC classes, Hilbert encoding) |
-| `weights_to_bin.py` | `.safetensors` → raw float32 binary converter |
-| `evm_trace_ingester.py` | EVM trace → 256×256 manifold (3 input modes) |
-
 ## Author
 
 **ZKAEDI** — Offensive Healer