Upload README.md with huggingface_hub

README.md

@@ -11,102 +11,115 @@ tags:
   - smart-contracts
   - evm
   - exploit-detection
-  - cnn
-  - solidity
+  - bare-metal
 pipeline_tag: other
 ---
 
-# 🔱 LEVIATHAN v2 — EVM Exploit Topology Classifier
+# 🔱 Leviathan v2 — EVM Exploit Topology Classifier
 
-**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.**
+**Bare-metal CNN that classifies EVM execution traces as THREAT or CLEAN using two-field Hamiltonian manifolds.**
+
+Leviathan ingests raw Ethereum Virtual Machine traces, encodes them as 2-channel 256×256 spatial manifolds via Hilbert curve mapping, downsamples to the CNN's 20×20 receptive field, and outputs a binary exploit score. A ZKAEDI PRIME bistable attractor refinement layer then commits the score to BENIGN or THREAT.
 
 ## Architecture
 
 ```
-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
+EVM Trace (opcodes + stack depth)
+  ↓
+Hilbert-Curve Encoder → 256×256 Manifold
+  Channel 0: Opcode energy density (H activator field)
+  Channel 1: Stack depth / state mutation intensity (V inhibitor field)
+  ↓
+Downsample → 20×20
+  ↓
+Conv2d(2, 16, 3×3) → ReLU
+Conv2d(16, 16, 3×3) → ReLU
+  ↓
+Flatten → 4096
+  ↓
+Linear(4096, 64) → ReLU
+Linear(64, 1) → Raw Score
+  ↓
+PRIME Bistable Attractor Refinement
+  η=3.50, γ=0.30, β=0.10, σ=0.05, T=256 iterations
+  Negative fixed point H*=−3.054 → BENIGN committed
+  Positive attractor → THREAT committed
+  ↓
+Output: 0.0 (CLEAN) ... 1.0 (THREAT)
 ```
 
-| Layer | Shape | Parameters |
-|-------|-------|------------|
+| Component | 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** |
 
-## 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
-
-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+1} = H_t + eta * H_t * sigma(gamma * H_t) + eps * N(0, 1 + beta * |H_t|)
-```
-
-Parameters: eta=3.50, gamma=0.30, beta=0.10, sigma=0.05, T=256
+## Validation Results
 
-Fixed points (analytically derived): H* = -3.054 (CLEAN) and H* = +3.054 (THREAT). Jacobian J=0.346 < 1 (stable).
-
-## Validated Results
+Trained and validated end-to-end with EVM execution manifolds:
 
 | Contract / Pattern | Score | Verdict |
-|--------------------|-------|---------|
-| Gnosis Multisig (baseline) | 0.0000 | CLEAN |
+|---|---|---|
+| Gnosis Multisig (safe baseline) | 0.0000 | CLEAN |
 | SWC-107 Reentrancy | 1.0000 | THREAT |
-| SWC-112 Delegatecall Abuse | 1.0000 | THREAT |
+| SWC-112 Delegatecall | 1.0000 | THREAT |
 | SWC-101 Integer Overflow | 1.0000 | THREAT |
 | Cross-function Reentrancy | 1.0000 | THREAT |
 | Flash Loan Manipulation | 1.0000 | THREAT |
 
+PRIME refinement thresholds: P < 0.10 = BENIGN committed, P > 0.90 = THREAT committed.
+
 ## Usage
 
 ```python
+from huggingface_hub import hf_hub_download
 from leviathan import Leviathan
 
-model = Leviathan.from_huggingface("zkaedi/leviathan-v2")
+weights_path = hf_hub_download("zkaedi/leviathan-v2", "leviathan_v2_session_trained.safetensors")
+model = Leviathan.from_safetensors(weights_path)
 
-# Full audit: CNN + PRIME refinement
-result = model.audit(H_256x256, V_256x256)
-# {"verdict": "THREAT", "committed": True, "refined_score": 0.9998, ...}
+# Score a 256x256 EVM manifold (auto-downsamples to 20x20)
+score = model.predict_manifold(H_256, V_256)
 
-# From raw EVM trace
-result = model.audit_trace(opcode_energies, stack_depths)
+# Full audit with PRIME bistable attractor refinement
+result = model.audit(H_256, V_256)
+print(result["verdict"])     # "THREAT" or "BENIGN"
+print(result["confidence"])  # 0.0 - 1.0
 ```
 
 ## ZKAEDI Security Pipeline
 
 ```
 Solidity Code
-  -> 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)
+  → gemma-2-9b-solidity-merged (vulnerability signatures)
+    → prime-swarm-hunter (12-agent temporal compound detection)
+      → evm_trace_ingester.py (EVM trace → 256×256 manifold)
+        → LEVIATHAN v2 (CNN: THREAT/CLEAN classification)
+          → PRIME refinement (bistable attractor commitment)
+            → solidity-vuln-auditor-7b (final audit report)
 ```
 
+## Companion Files
+
+| File | Purpose |
+|---|---|
+| `leviathan.c` | 622-line bare-metal C inference engine |
+| `manifold_forge.py` | Exploit manifold generator (5 classes, Hilbert encoding) |
+| `weights_to_bin.py` | safetensors to raw float32 binary for C engine |
+| `evm_trace_ingester.py` | 3 modes: RPC trace, Foundry, static bytecode |
+
+## PRIME Refinement Mathematics
+
+```
+H_t = H_0 + η·H_{t-1}·σ(γ·H_{t-1}) + ε·N(0, 1+β|H_{t-1}|)
+```
+
+With η=3.50 the system has two stable fixed points:
+H* = -3.054 (BENIGN, Jacobian J=0.346 < 1) and positive attractor (THREAT).
+Scores near 0.5 converge to one attractor over T=256 iterations.
+
 ## Author
 
 **ZKAEDI** — Offensive Healer