# Diagrams — SDD-11: Purpose-Built DeFi AI Systems

---

## Diagram 1 — The Three Pillars of Specificity (General LLM → Domain Agent)

```mermaid
flowchart TB
    GEN["THE GENERAL LLM (the 34% baseline)<br/>reasons from text · no domain tools · no encoded patterns<br/>guesses at DeFi-native failure modes"]
    GEN -->|add three pillars of specificity| PILLARS
    subgraph PILLARS["Three Pillars of Specificity"]
        P1["Pillar 1 — DOMAIN TOOLING (graft)<br/>Foundry (fork/fuzz/invariant) · Tenderly · RPCs · DeFi SDKs<br/>agent EXECUTES hypotheses, not just describes"]
        P2["Pillar 2 — DOMAIN KNOWLEDGE ENCODING<br/>attack-pattern templates:<br/>oracle manipulation · flash-loan economics<br/>MEV (sandwich/front-run) · compositional risk<br/>structured expertise the base model lacks"]
        P3["Pillar 3 — DOMAIN-SPECIFIC VERIFICATION<br/>fork chain → replay attack → confirm loss<br/>(EVMbench Exploit standard, SDD-10)<br/>a finding is a demonstrated tx, not a claim"]
    end
    PILLARS --> AGENT
    AGENT["THE PURPOSE-BUILT DEFI AGENT (the 92%)<br/>domain tools + encoded patterns + execution verification<br/>reasons about DeFi-native failure modes at auditor depth"]

    style GEN fill:#1a1015,stroke:#9494a0,color:#9494a0
    style PILLARS fill:#0d1b2a,stroke:#5eead4,color:#5eead4
    style AGENT fill:#0d1b2a,stroke:#5eead4,color:#5eead4
```

**Reading**: The 92% vs 34% gap is not a model-size story — it is a domain-specificity story. A general LLM, however large, was not trained to reason about DeFi-native failure modes at depth. Closing the gap does not require retraining the base model; it requires adding three external pillars. Domain tooling lets the agent execute (fork, replay) rather than describe. Encoded attack-pattern knowledge gives it the finite, learnable shapes of DeFi attacks. Execution verification makes every finding a demonstrated transaction. The pillars compound — each alone is insufficient — and together they turn a text reasoner into an auditor.

---

## Diagram 2 — DeFi-Native Failure Modes (Where the Gap Compounds)

```mermaid
flowchart LR
    subgraph GENERAL["General LLM Strengths (gap narrows)"]
        G1[missing access-control modifier]
        G2[standard reentrancy]
        G3[integer overflow]
    end
    subgraph DEFI["DeFi-Native Classes (gap widens to 92 vs 34)"]
        D1[oracle manipulation<br/>flash-loan → skew → liquidate]
        D2[flash-loan economics<br/>atomic single-tx capital inversion]
        D3[MEV<br/>sandwich · front-running]
        D4[compositional risk<br/>A→B integration vuln]
    end
    GENERAL -. "general training covers these" .-> DEFI
    DEFI -. "absent from training at depth" .-> GAP[domain agent wins here]

    style GENERAL fill:#0d1b2a,stroke:#5eead4,color:#5eead4
    style DEFI fill:#0d1b2a,stroke:#5eead4,color:#5eead4
    style GAP fill:#1a1015,stroke:#5eead4,color:#e4e4e8
```

**Reading**: The 92% vs 34% gap is not uniform — it compounds on DeFi-native classes. On general vulnerabilities (a missing modifier, standard reentrancy, integer issues), the gap narrows because the general training data covers these. On DeFi-native failure modes — oracle manipulation, flash-loan economics, MEV, compositional risk — the gap widens, because these are absent from general training at reasoning depth. This is the decision frame: if your target is general smart-contract security, a general LLM may suffice; if your target is DeFi-specific risk, the domain agent is the only reliable path.

---

## Diagram 3 — The Hybrid Architecture (Per-Task, Not All-or-Nothing)

```mermaid
flowchart TB
    TASK[incoming task] --> ROUTE{route by capability needed}
    ROUTE -->|breadth task: triage, explain, report, test-gen| GENPATH[General LLM<br/>sufficient quality<br/>lower cost]
    ROUTE -->|DeFi-specific detection: oracle, flash-loan, MEV, composition| DOMPATH[Domain Agent<br/>3 pillars<br/>92% detection]
    GENPATH --> MERGE[combined output]
    DOMPATH --> MERGE
    MERGE --> RESULT[deliverable:<br/>general findings + demonstrated DeFi attacks]

    style TASK fill:#1a1015,stroke:#5eead4,color:#e4e4e8
    style ROUTE fill:#1a1015,stroke:#5eead4,color:#e4e4e8
    style GENPATH fill:#0d1b2a,stroke:#5eead4,color:#5eead4
    style DOMPATH fill:#0d1b2a,stroke:#5eead4,color:#5eead4
    style MERGE fill:#0d1b2a,stroke:#5eead4,color:#5eead4
```

**Reading**: The pragmatic architecture is hybrid and per-task. Not every capability needs the 92% — triage, explanation, report generation, and test scaffolding run fine on the general LLM at lower cost. Deep detection on DeFi-specific classes needs the domain agent's three pillars. The router sends each task to the right engine; the outputs merge into a single deliverable (general findings plus demonstrated DeFi attacks). Making the hybrid explicit — rather than paying the domain-agent cost on every capability — is the cost-optimization decision. The specialist handles the high-risk depth; the generalist handles the breadth.

---

## Diagram 4 — The Build Decision Framework (When to Specialize)

```mermaid
flowchart TB
    Q1{Is the target domain<br/>DeFi-specific risk?}
    Q1 -->|no, general smart-contract| GENERAL[General LLM + good prompt<br/>sufficient — don't specialize]
    Q1 -->|yes, DeFi-specific| Q2{What is the cost of<br/>a missed vulnerability?}
    Q2 -->|low value / quick check| GENERAL
    Q2 -->|high value protocol| Q3{Is the base model<br/>the same?}
    Q3 -->|yes — pillars are external| BUILD[Build the domain agent<br/>3 pillars (tool/knowledge/verification)<br/>no retraining needed]
    Q3 -->|want a from-scratch DeFi model| TRAIN[Retrain / fine-tune<br/>rarely justified — pillars<br/>capture most of the gain]

    style Q1 fill:#1a1015,stroke:#5eead4,color:#e4e4e8
    style Q2 fill:#1a1015,stroke:#5eead4,color:#e4e4e8
    style Q3 fill:#1a1015,stroke:#5eead4,color:#e4e4e8
    style GENERAL fill:#0d1b2a,stroke:#5eead4,color:#5eead4
    style BUILD fill:#0d1b2a,stroke:#5eead4,color:#5eead4
    style TRAIN fill:#1a1015,stroke:#9494a0,color:#9494a0
```

**Reading**: The build decision is a decision tree, not a default. If the target is general smart-contract security (not DeFi-specific), the general LLM with a good prompt is sufficient — do not specialize. If the target is DeFi-specific risk, weigh the cost of a missed vulnerability: low-value quick checks accept the 34%; high-value protocols justify the domain agent. And critically — the base model is the same; the three pillars are external. Retraining or fine-tuning a from-scratch DeFi model is rarely justified, because the pillars (tooling, knowledge, verification) capture most of the 92% gain at a fraction of the training cost. This is the pragmatic path the diagram is meant to steer toward.