README.md

---
license: mit
tags:
  - safetensors
  - zkaedi-prime
  - hamiltonian-dynamics
  - vulnerability-detection
  - two-field
  - custom-architecture
  - security
  - smart-contracts
  - evm
  - exploit-detection
  - bare-metal
pipeline_tag: other
---

# 🔱 Leviathan v2 — EVM Exploit Topology Classifier

**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

```
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)
```

| 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** |

## Validation Results

Trained and validated end-to-end with EVM execution manifolds:

| Contract / Pattern | Score | Verdict |
|---|---|---|
| Gnosis Multisig (safe baseline) | 0.0000 | CLEAN |
| SWC-107 Reentrancy | 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

weights_path = hf_hub_download("zkaedi/leviathan-v2", "leviathan_v2_session_trained.safetensors")
model = Leviathan.from_safetensors(weights_path)

# Score a 256x256 EVM manifold (auto-downsamples to 20x20)
score = model.predict_manifold(H_256, V_256)

# 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 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