# ykshdja/smart-contract-analyzer-benchmark architecture

> Architecture diagram of the GitHub repository ykshdja/smart-contract-analyzer-benchmark, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ykshdja/smart-contract-analyzer-benchmark
- Repository: https://github.com/ykshdja/smart-contract-analyzer-benchmark

## Overview

1. This repository is best understood as two connected parts: a minimal live analysis app for Solidity code, and a larger offline evaluation workspace for comparing vulnerability scanners.

2. The runtime app boundary is very small. `frontend/index.html` is a static browser UI, and `backend/main.py` exposes the API over FastAPI/Uvicorn. The frontend sends Solidity source code to the backend’s `/analyze` endpoint and displays the returned findings.

3. The core analysis logic lives in `backend/analyzer.py`. The README describes it as pattern-based analysis, so the shipped product is not a compiler pipeline or symbolic executor; it is a lightweight rule matcher that returns structured vulnerability records such as type, severity, line, description, match, and context.

4. There is no obvious persistent application state, database, or message queue in the current tree. The main data flow is request/response: user code in, vulnerability list out.

5. The repository also contains a benchmark and comparison harness. Scripts like `evaluate_slither_auto.py`, `evaluate_mythril_*.py`, `evaluate_semgrep_*.py`, `evaluate_solhint_*.py`, `evaluate_aderyn_*.py`, and `evaluate_scrubd_sd.py` suggest the author runs multiple external analyzers against the same contract corpora and compares their outputs.

6. `compute_metrics.py` and `read_report.py` appear to post-process those runs into summary metrics and human-readable reports. The presence of `report.md` and `writeup.txt` indicates the repo is being used for research-style evaluation, not just an app demo.

7. The contract corpora are split across several folders: `contracts/`, `test_contracts/`, and `test_sample/`. These are likely the inputs used by both the manual analyzer and the evaluation scripts.

8. The directories `SCRUBD`, `sailfish`, `conkas`, and `semgrep-rules` look like tool-specific assets or vendored benchmark material. Architecturally, they act as external analysis sources/rule sets rather than part of the live backend.

9. The `mcore_*` directories with `.state_id` and `state_00000000.pkl` files are generated artifacts. They look like serialized intermediate state or cached results from one of the experiment pipelines, so they belong on the “offline outputs” side of the diagram.

10. The important architectural boundary is therefore: browser UI → FastAPI analysis service → pattern-based findings, plus a separate offline pipeline that feeds contracts into third-party analyzers, aggregates their results, and produces metrics/reports.

11. If you draw this repo, emphasize the simplicity of the production path and the breadth of the research/evaluation path. The repo is not a full platform; it is a prototype analyzer surrounded by experiment scripts, datasets, and result artifacts.

Main entry points: [`contracts`](https://github.com/ykshdja/smart-contract-analyzer-benchmark/tree/main/contracts) (Contracts), [`semgrep-rules`](https://github.com/ykshdja/smart-contract-analyzer-benchmark/tree/main/semgrep-rules) (Tool assets), [`mcore___mt3ta8`](https://github.com/ykshdja/smart-contract-analyzer-benchmark/tree/main/mcore___mt3ta8) (Run state), [`evaluate_mythril_cd.py`](https://github.com/ykshdja/smart-contract-analyzer-benchmark/blob/main/evaluate_mythril_cd.py) (Mythril eval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Live analysis"]
  node_frontend_ui["Browser UI<br/>static frontend<br/>[index.html]"]
  node_api_service["API service<br/>FastAPI app<br/>[main.py]"]
  node_pattern_analyzer["Rule matcher<br/>pattern analysis<br/>[analyzer.py]"]
end

subgraph group_evaluation["Evaluation pipeline"]
  node_offline_runner["Run scripts<br/>pipeline driver<br/>[analyze_folder.py]"]
  node_offline_runner_direct["Direct runner<br/>pipeline driver"]
  node_slither_eval["Slither eval<br/>benchmark script"]
  node_mythril_eval["Mythril eval<br/>benchmark scripts"]
  node_mythril_fast_eval["Mythril fast<br/>benchmark script"]
  node_mythril_sd_eval["Mythril sd<br/>benchmark script"]
  node_semgrep_eval["Semgrep eval<br/>benchmark scripts"]
  node_semgrep_sd_eval["Semgrep sd<br/>benchmark script"]
  node_solhint_eval["Solhint eval<br/>benchmark scripts"]
  node_solhint_sd_eval["Solhint sd<br/>benchmark script"]
  node_aderyn_eval["Aderyn eval<br/>benchmark scripts"]
  node_aderyn_sd_eval["Aderyn sd<br/>benchmark script"]
  node_scrubd_eval["Scrubd eval<br/>benchmark script"]
  node_metrics["Metrics<br/>post-processing<br/>[compute_metrics.py]"]
  node_report_reader["Report reader<br/>post-processing<br/>[read_report.py]"]
  node_report_md["Report<br/>evaluation output<br/>[report.md]"]
end

subgraph group_assets["Datasets and assets"]
  node_contracts_corpus[("Contracts<br/>solidity corpus")]
  node_test_contracts_corpus[("Test contracts<br/>solidity corpus")]
  node_sample_corpus[("Samples")]
  node_tool_assets[("Tool assets<br/>external tool data")]
  node_generated_state[("Run state<br/>generated artifacts")]
end

node_frontend_ui -->|"submit code"| node_api_service
node_api_service -->|"analyze"| node_pattern_analyzer
node_pattern_analyzer -->|"return findings"| node_frontend_ui
node_offline_runner -->|"batch input"| node_contracts_corpus
node_offline_runner_direct -->|"batch input"| node_test_contracts_corpus
node_slither_eval -->|"benchmark"| node_contracts_corpus
node_mythril_eval -->|"benchmark"| node_contracts_corpus
node_semgrep_eval -->|"benchmark"| node_contracts_corpus
node_solhint_eval -->|"benchmark"| node_contracts_corpus
node_aderyn_eval -->|"benchmark"| node_contracts_corpus
node_scrubd_eval -->|"benchmark"| node_contracts_corpus
node_mythril_eval -->|"rules/data"| node_tool_assets
node_semgrep_eval -->|"rules/data"| node_tool_assets
node_metrics -->|"aggregate"| node_generated_state
node_report_reader -->|"read results"| node_generated_state
node_report_reader -->|"write report"| node_report_md
node_metrics -->|"summaries"| node_report_md
node_tool_assets -->|"produce"| node_generated_state

click node_frontend_ui "https://github.com/ykshdja/smart-contract-analyzer-benchmark/blob/main/frontend/index.html"
click node_api_service "https://github.com/ykshdja/smart-contract-analyzer-benchmark/blob/main/backend/main.py"
click node_pattern_analyzer "https://github.com/ykshdja/smart-contract-analyzer-benchmark/blob/main/backend/analyzer.py"
click node_offline_runner "https://github.com/ykshdja/smart-contract-analyzer-benchmark/blob/main/analyze_folder.py"
click node_offline_runner_direct "https://github.com/ykshdja/smart-contract-analyzer-benchmark/blob/main/analyze_folder_direct.py"
click node_slither_eval "https://github.com/ykshdja/smart-contract-analyzer-benchmark/blob/main/evaluate_slither_auto.py"
click node_mythril_eval "https://github.com/ykshdja/smart-contract-analyzer-benchmark/blob/main/evaluate_mythril_cd.py"
click node_mythril_fast_eval "https://github.com/ykshdja/smart-contract-analyzer-benchmark/blob/main/evaluate_mythril_cd_fast.py"
click node_mythril_sd_eval "https://github.com/ykshdja/smart-contract-analyzer-benchmark/blob/main/evaluate_mythril_sd.py"
click node_semgrep_eval "https://github.com/ykshdja/smart-contract-analyzer-benchmark/blob/main/evaluate_semgrep_cd.py"
click node_semgrep_sd_eval "https://github.com/ykshdja/smart-contract-analyzer-benchmark/blob/main/evaluate_semgrep_sd.py"
click node_solhint_eval "https://github.com/ykshdja/smart-contract-analyzer-benchmark/blob/main/evaluate_solhint_cd.py"
click node_solhint_sd_eval "https://github.com/ykshdja/smart-contract-analyzer-benchmark/blob/main/evaluate_solhint_sd.py"
click node_aderyn_eval "https://github.com/ykshdja/smart-contract-analyzer-benchmark/blob/main/evaluate_aderyn_cd.py"
click node_aderyn_sd_eval "https://github.com/ykshdja/smart-contract-analyzer-benchmark/blob/main/evaluate_aderyn_sd.py"
click node_scrubd_eval "https://github.com/ykshdja/smart-contract-analyzer-benchmark/blob/main/evaluate_scrubd_sd.py"
click node_metrics "https://github.com/ykshdja/smart-contract-analyzer-benchmark/blob/main/compute_metrics.py"
click node_report_reader "https://github.com/ykshdja/smart-contract-analyzer-benchmark/blob/main/read_report.py"
click node_report_md "https://github.com/ykshdja/smart-contract-analyzer-benchmark/blob/main/report.md"
click node_contracts_corpus "https://github.com/ykshdja/smart-contract-analyzer-benchmark/tree/main/contracts"
click node_test_contracts_corpus "https://github.com/ykshdja/smart-contract-analyzer-benchmark/tree/main/test_contracts"
click node_sample_corpus "https://github.com/ykshdja/smart-contract-analyzer-benchmark/tree/main/test_sample"
click node_tool_assets "https://github.com/ykshdja/smart-contract-analyzer-benchmark/tree/main/semgrep-rules"
click node_generated_state "https://github.com/ykshdja/smart-contract-analyzer-benchmark/tree/main/mcore___mt3ta8"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend_ui,node_api_service,node_pattern_analyzer toneBlue
class node_offline_runner,node_offline_runner_direct,node_slither_eval,node_mythril_eval,node_mythril_fast_eval,node_mythril_sd_eval,node_semgrep_eval,node_semgrep_sd_eval,node_solhint_eval,node_solhint_sd_eval,node_aderyn_eval,node_aderyn_sd_eval,node_scrubd_eval,node_metrics,node_report_reader,node_report_md toneAmber
class node_contracts_corpus,node_test_contracts_corpus,node_sample_corpus,node_tool_assets,node_generated_state toneMint
```

## Components

### Live analysis

Minimal browser-to-API path for analyzing Solidity source code.

- [Browser UI](https://github.com/ykshdja/smart-contract-analyzer-benchmark/blob/main/frontend/index.html): static frontend · Single-page HTML interface for submitting Solidity code and viewing findings. · `frontend/index.html`
- [API service](https://github.com/ykshdja/smart-contract-analyzer-benchmark/blob/main/backend/main.py): FastAPI app · Exposes the analysis endpoint and serves as the runtime boundary. · `backend/main.py`
- [Rule matcher](https://github.com/ykshdja/smart-contract-analyzer-benchmark/blob/main/backend/analyzer.py): pattern analysis · Core vulnerability detection logic that returns structured findings. · `backend/analyzer.py`

### Evaluation pipeline

Offline benchmarking, comparison, and report generation.

- [Run scripts](https://github.com/ykshdja/smart-contract-analyzer-benchmark/blob/main/analyze_folder.py): pipeline driver · Folder-level orchestration for batch analysis runs over contract corpora. · `analyze_folder.py`
- [Direct runner](https://github.com/ykshdja/smart-contract-analyzer-benchmark/blob/main/analyze_folder_direct.py): pipeline driver · Alternate batch runner for direct execution against corpora. · `analyze_folder_direct.py`
- [Slither eval](https://github.com/ykshdja/smart-contract-analyzer-benchmark/blob/main/evaluate_slither_auto.py): benchmark script · Runs Slither against the benchmark corpus for comparison. · `evaluate_slither_auto.py`
- [Mythril eval](https://github.com/ykshdja/smart-contract-analyzer-benchmark/blob/main/evaluate_mythril_cd.py): benchmark scripts · Runs Mythril in multiple modes to compare coverage and findings. · `evaluate_mythril_cd.py`
- [Mythril fast](https://github.com/ykshdja/smart-contract-analyzer-benchmark/blob/main/evaluate_mythril_cd_fast.py): benchmark script · Faster Mythril evaluation variant. · `evaluate_mythril_cd_fast.py`
- [Mythril sd](https://github.com/ykshdja/smart-contract-analyzer-benchmark/blob/main/evaluate_mythril_sd.py): benchmark script · Secondary Mythril evaluation variant. · `evaluate_mythril_sd.py`
- [Semgrep eval](https://github.com/ykshdja/smart-contract-analyzer-benchmark/blob/main/evaluate_semgrep_cd.py): benchmark scripts · Runs Semgrep against the benchmark corpus for comparison. · `evaluate_semgrep_cd.py`
- [Semgrep sd](https://github.com/ykshdja/smart-contract-analyzer-benchmark/blob/main/evaluate_semgrep_sd.py): benchmark script · Secondary Semgrep evaluation variant. · `evaluate_semgrep_sd.py`
- [Solhint eval](https://github.com/ykshdja/smart-contract-analyzer-benchmark/blob/main/evaluate_solhint_cd.py): benchmark scripts · Runs Solhint against the benchmark corpus for comparison. · `evaluate_solhint_cd.py`
- [Solhint sd](https://github.com/ykshdja/smart-contract-analyzer-benchmark/blob/main/evaluate_solhint_sd.py): benchmark script · Secondary Solhint evaluation variant. · `evaluate_solhint_sd.py`
- [Aderyn eval](https://github.com/ykshdja/smart-contract-analyzer-benchmark/blob/main/evaluate_aderyn_cd.py): benchmark scripts · Runs Aderyn against the benchmark corpus for comparison. · `evaluate_aderyn_cd.py`
- [Aderyn sd](https://github.com/ykshdja/smart-contract-analyzer-benchmark/blob/main/evaluate_aderyn_sd.py): benchmark script · Secondary Aderyn evaluation variant. · `evaluate_aderyn_sd.py`
- [Scrubd eval](https://github.com/ykshdja/smart-contract-analyzer-benchmark/blob/main/evaluate_scrubd_sd.py): benchmark script · Runs Scrubd against the benchmark corpus for comparison. · `evaluate_scrubd_sd.py`
- [Metrics](https://github.com/ykshdja/smart-contract-analyzer-benchmark/blob/main/compute_metrics.py): post-processing · Aggregates benchmark outputs into summary metrics. · `compute_metrics.py`
- [Report reader](https://github.com/ykshdja/smart-contract-analyzer-benchmark/blob/main/read_report.py): post-processing · Transforms run outputs into readable summaries and report material. · `read_report.py`
- [Report](https://github.com/ykshdja/smart-contract-analyzer-benchmark/blob/main/report.md): evaluation output · Human-readable benchmark report. · `report.md`

### Datasets and assets

Contract corpora, tool-specific resources, and generated experiment state.

- [Contracts](https://github.com/ykshdja/smart-contract-analyzer-benchmark/tree/main/contracts): solidity corpus · Primary contract set used for analysis and benchmarking. · `contracts`
- [Test contracts](https://github.com/ykshdja/smart-contract-analyzer-benchmark/tree/main/test_contracts): solidity corpus · Additional contract set used in experiments and comparisons. · `test_contracts`
- [Samples](https://github.com/ykshdja/smart-contract-analyzer-benchmark/tree/main/test_sample): solidity samples · Small sample set for quick checks or demonstrations. · `test_sample`
- [Tool assets](https://github.com/ykshdja/smart-contract-analyzer-benchmark/tree/main/semgrep-rules): external tool data · Vendored rulesets and tool-specific resources used by offline evaluations. · `semgrep-rules`
- [Run state](https://github.com/ykshdja/smart-contract-analyzer-benchmark/tree/main/mcore___mt3ta8): generated artifacts · Serialized intermediate states and cached outputs from experiment runs. · `mcore___mt3ta8`

## Connections

- Browser UI → API service: submit code · Browser sends Solidity source to the analysis API.
- API service → Rule matcher: analyze · API delegates request handling to the rule-based analyzer.
- Rule matcher → Browser UI: return findings · Structured vulnerability records are returned to the UI.
- Run scripts → Contracts: batch input · Runs the benchmark pipeline over the main contract corpus.
- Direct runner → Test contracts: batch input · Direct runner consumes the experimental contract set.
- Slither eval → Contracts: benchmark · Uses the shared corpus for comparison runs.
- Mythril eval → Contracts: benchmark · Feeds the corpus into Mythril evaluation modes.
- Semgrep eval → Contracts: benchmark · Feeds the corpus into Semgrep evaluation modes.
- Solhint eval → Contracts: benchmark · Feeds the corpus into Solhint evaluation modes.
- Aderyn eval → Contracts: benchmark · Feeds the corpus into Aderyn evaluation modes.
- Scrubd eval → Contracts: benchmark · Feeds the corpus into Scrubd evaluation runs.
- Mythril eval → Tool assets: rules/data · Uses external tool assets and rules where applicable.
- Semgrep eval → Tool assets: rules/data · Uses external Semgrep rulesets.
- Metrics → Run state: aggregate · Consumes serialized run artifacts to compute summary metrics.
- Report reader → Run state: read results · Reads generated experiment state for report preparation.
- Report reader → Report: write report · Produces the human-readable benchmark report.
- Metrics → Report: summaries · Metrics feed into the final report narrative.
- Tool assets → Run state: produce · Tool runs and assets contribute to cached intermediate state.
