← Back to Work

Engineering Case Study

AI Smart Contract Analyst

Blockchain Security · AI Infrastructure

Deterministic-first Solidity analysis with grounded AI-assisted security explanations.

Live Tool Public Source Deterministic-First AI Grounding
Launch Analyzer → Source →

Engineering Problem

LLMs can explain Solidity well, but asking an LLM to directly “audit this contract” can produce unsupported findings, inconsistent severity, and hallucinated vulnerabilities.

The engineering goal was to separate security detection from AI interpretation.

The deterministic analysis layer owns findings and severity. AI receives only normalized findings and bounded evidence and is used to explain those findings — not invent new ones.

Architecture

Analysis is a staged pipeline. Detector output is authoritative; the AI layer is optional and downstream.

Input Solidity Source
Parse Parser / AST
Extract Structural Extraction
Detect Deterministic + Heuristic Detectors
Normalize Normalized Security Findings + Bounded Evidence
Explain Optional Grounded AI Explanation
Output Analysis Report

AI cannot create findings or change detector severity. If the AI provider fails, the deterministic report still returns.

Deterministic Analysis

V1 security detectors are heuristic/static pattern checks over parsed Solidity structure and source evidence:

  • tx-origin — tx.origin authorization patterns
  • selfdestruct — selfdestruct / suicide usage
  • delegatecall — delegatecall usage
  • low-level-call — low-level call / staticcall / callcode
  • privileged-function — privileged / admin function surfaces
  • floating-pragma — floating Solidity pragma
  • unrestricted-mint-admin — unrestricted mint / admin heuristics
  • unchecked-external-call — unchecked external-call return handling

Separately, ERC-20 / ERC-721-like token interface indicators are reported in their own list. They are not security findings and do not contribute to severity counts.

Normalized Finding Model

Findings are structured objects rather than free-form model text. Typical fields include:

  • detector ID
  • severity
  • confidence
  • category
  • title / description
  • remediation
  • evidence / source span
  • affected symbols

Keeping findings normalized means additional analysis engines (for example a future Slither worker) can emit into the same reporting layer without redesigning the UI or AI grounding contract.

Grounded AI Layer

When AI interpretation is enabled and a server-side provider key is configured:

  • Full Solidity source is not sent to the AI provider
  • AI receives normalized findings and bounded evidence snippets
  • AI must cite existing finding IDs
  • Unknown finding IDs are rejected / sanitized
  • AI cannot modify deterministic severity
  • Deterministic analysis continues if AI fails or is unavailable

Grounding reduces unsupported invention relative to “audit this source” prompts. It does not make hallucination impossible.

Security / Hardening

  • 500 KB input limit
  • Plain-text Solidity only
  • No Solidity execution in V1
  • No shell / solc execution in V1
  • Server-side API keys only (never NEXT_PUBLIC_)
  • Bounded AI payload
  • In-memory rate limiting (stricter for AI-enabled requests)
  • Security headers / CSP (production omits unsafe-eval)
  • No full-source logging — privacy-safe request metadata only
  • Safe AI failure behavior (deterministic report still returned)

Example Analysis

The default demo contract (ExampleVault) intentionally contains security issues for demonstration:

HIGH

Unrestricted mint-style function (unrestricted-mint-admin)

MEDIUM

tx.origin authorization (tx-origin)

The analyzer recognizes tx.origin as an authorization-related guard for the purpose of suppressing an “unrestricted withdraw” false positive, while independently flagging tx.origin as insecure.

Design principle: guard presence does not imply guard safety.

Engineering Stack

  • TypeScript
  • Next.js
  • Solidity AST Parsing
  • Zod
  • Node.js
  • OpenAI API
  • pnpm workspaces
  • Vercel

Testing

The current test suite includes 84 passing tests covering:

  • Parser / structural extraction
  • Security detectors
  • Token-interface indicators
  • AI grounding / citation sanitization
  • API hardening helpers
  • Regression fixtures (including ExampleVault)

Limitations / Next Steps

Current limitations:

  • Heuristic / static analysis — not a professional security audit
  • No full dataflow analysis
  • No formal verification
  • No runtime / EVM simulation
  • No Slither integration yet
  • No verified-source / address analysis yet
  • In-memory rate limits are per-instance on serverless

Possible future architecture (not implemented):

  • Slither worker emitting into the same finding model
  • Verified contract / address analysis
  • Proxy detection
  • Deeper call / dataflow analysis

Launch

Live Tool · Public Source · Deterministic-First · Optional AI

Launch Analyzer → View Source →