# Diagrams — SDD-09: Heimdallr
---
## Diagram 1 — The Reorganization + Cascade Architecture
```mermaid
flowchart TB
SRC[(smart contract source
Solidity · inheritance · modifiers)] --> REORG
subgraph REORG["Function-Level Reorganization"]
R1[decompose into functions]
R2[resolve inheritance]
R3[inline modifiers]
R4[reconstruct per-function context:
state read/written · external calls]
R1 --> R2 --> R3 --> R4
end
REORG --> S1
subgraph S1["Cascade Stage 1 — Cheap Checks"]
C1[pattern-based + structural
static-ish]
C1 --> CAND[candidate vulnerabilities
broad]
end
CAND --> S2
subgraph S2["Cascade Stage 2 — LLM Semantic Analysis"]
L1[per candidate: full reorganized context]
L1 --> CONF[confirm / reject with reasoning]
end
CONF --> S3
subgraph S3["Cascade Stage 3 — Exploit Reconstruction"]
E1[reconstruct the attack transaction chain]
E1 --> RECON[reconstructed attacks
17/20 on real exploits]
end
RECON --> FINDINGS([vulnerability findings
92.45% detection · $2.31/10K LOC])
style REORG fill:#1a1015,stroke:#5eead4,color:#e4e4e8
style S1 fill:#0d1b2a,stroke:#5eead4,color:#5eead4
style S2 fill:#0d1b2a,stroke:#5eead4,color:#5eead4
style S3 fill:#0d1b2a,stroke:#5eead4,color:#5eead4
```
**Reading**: Heimdallr's architecture is two load-bearing ideas in sequence. First, reorganization rewrites the contract into context-complete function units — the substrate transformation that lets the LLM reason at auditor depth instead of hallucinating over raw source. Second, a three-stage cascade spends the LLM budget only on survivors: cheap pattern checks produce candidates, LLM semantic analysis confirms or rejects, and exploit reconstruction runs only on the confirmed few. The $2.31/10K LOC cost is a direct payoff of how aggressively each stage filters. Reorganization is what makes the agent accurate; the cascade is what makes it affordable.
---
## Diagram 2 — Why Reorganization Matters (Raw Source vs Reorganized)
```mermaid
flowchart LR
subgraph RAW["LLM on Raw Source"]
RA1[ Solidity file: state vars,
events, modifiers, functions
inheritance across files ]
RA1 --> RA2[ LLM cannot hold
cross-function context ]
RA2 --> RA3[ shallow, hallucinated findings ]
end
subgraph REORG["LLM on Reorganized Units"]
RO1[ per function: full context
state read/written
external calls
modifiers inlined ]
RO1 --> RO2[ LLM reasons at
auditor depth ]
RO2 --> RO3[ 92.45% detection ]
end
RAW -.the load-bearing transformation.-> REORG
style RAW fill:#1a1015,stroke:#9494a0,color:#9494a0
style REORG fill:#0d1b2a,stroke:#5eead4,color:#5eead4
```
**Reading**: The same LLM produces dramatically different results depending on the substrate it reasons over. On raw source, the model cannot hold the cross-function context a vulnerability spans, so it hallucinates. On reorganized units — each function carrying its full state and external-call dependencies — the same model reasons at the depth a human auditor works. Reorganization is not a preprocessing convenience; it is the load-bearing idea that makes agent-based smart contract auditing work. No other harness in the roster performs this transformation.
---
## Diagram 3 — The Cascade as Cost Discipline (Why $2.31/10K LOC)
```mermaid
flowchart TB
ALL[all functions in contract
e.g., 100 functions] -->|Stage 1: cheap checks| CAND[candidates
e.g., 30 functions]
CAND -->|Stage 2: LLM semantic| CONF[confirmed
e.g., 8 functions]
CONF -->|Stage 3: reconstruction| RECON[reconstructed attacks
e.g., 5 functions]
ALL -. "naive alternative:
LLM on all 100" .-> EXPENSIVE[cost orders of
magnitude higher]
style ALL fill:#1a1015,stroke:#5eead4,color:#e4e4e8
style CAND fill:#0d1b2a,stroke:#5eead4,color:#5eead4
style CONF fill:#0d1b2a,stroke:#5eead4,color:#5eead4
style RECON fill:#0d1b2a,stroke:#5eead4,color:#5eead4
style EXPENSIVE fill:#1a1015,stroke:#9494a0,color:#9494a0
```
**Reading**: The $2.31/10K LOC cost is not a property of the model — it is a property of how few functions reach the expensive stages. Stage 1 (cheap, pattern-based) filters 100 functions down to ~30 candidates. Stage 2 (LLM semantic) filters those to ~8 confirmed. Only those ~8 reach stage 3 (reconstruction, the most expensive). The naive alternative — running the LLM on all 100 functions — costs orders of magnitude more and does not produce a better result. The cascade is the cost discipline; aggressive filtering at each stage is the lever.
---
## Diagram 4 — Heimdallr vs Static Tools vs General LLMs (Comparison)
```mermaid
flowchart TB
subgraph STATIC["Static Analyzers (Slither, Mythril)"]
ST1[cheap, pattern-based]
ST2[misses business logic
and multi-step flaws]
end
subgraph GENERAL["General LLM (no reorganization)"]
G1[reasons over raw source]
G2[hallucinates, shallow
~34% on DeFi vulns (SDD-11)]
end
subgraph HEIM["Heimdallr (reorganization + cascade)"]
H1[reorganized substrate]
H2[cascaded verification]
H3[92.45% detection · 17/20 reconstruction]
end
STATIC -.complementary.-> HEIM
GENERAL -.structure closes the gap.-> HEIM
style STATIC fill:#0d1b2a,stroke:#5eead4,color:#5eead4
style GENERAL fill:#1a1015,stroke:#9494a0,color:#9494a0
style HEIM fill:#0d1b2a,stroke:#5eead4,color:#5eead4
```
**Reading**: Heimdallr occupies a position no other approach reaches alone. Static analyzers are cheap and catch known patterns but miss the business-logic and multi-step vulnerabilities that cause the largest DeFi losses. A general LLM without reorganization reasons over raw source and scores dramatically lower on DeFi-specific flaws (SDD-11's 92% vs 34% gap). Heimdallr's structure — reorganization plus cascade, not a bigger model — is what closes the gap. In practice the three are complementary: static tools first for known patterns, Heimdallr for semantic depth, and the combination is stronger than any one alone.