# fuzzland/ityfuzz architecture

> Architecture diagram of the GitHub repository fuzzland/ityfuzz, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fuzzland/ityfuzz
- Repository: https://github.com/fuzzland/ityfuzz

## Overview

##### Main Components
- Fuzzing Engine Core (Rust):
– This is the heart of the system and contains multiple submodules:
▪ EVM Fuzzer: Located in src/evm with further subcomponents such as bytecode analyzer, concolic engine, middlewares (cheatcode, reentrancy, coverage, etc.), oracle modules and producers.
▪ Move Fuzzer: Found in src/move with its input handling, corpus initializer, minimizer, and oracle functionalities.
▪ Common components: General fuzzers (src/fuzzers), main entry point (src/main.rs), scheduler, logger, state management, and mutation utilities.
– It leverages LibAFL as the fuzzing engine and includes power scheduling and symbolic execution features.

- Client Interaction / API Layers:
– Server: The ‘server’ directory (app.js, package.json) represents a web server (likely REST or WebSocket based) that might provide an API for triggering or controlling fuzzing operations.
– UI layer: The ‘ui’ directory contains Python scripts (e.g., backend.py, wrapper.py) and static assets (HTML, CSS, JS), suggesting a front-end interface for users to initiate fuzz runs, monitor progress, and view results.

- Onchain Interaction & Integration Testing:
– Onchain Scripts: The ‘onchain_scripts’ folder includes Python scripts for tasks such as debugging, evaluating, and interacting with live blockchain data (e.g., reading target block numbers, interfacing with Etherscan).
– Integration Tests and Benchmarks: Found under tests (both in evm and move categories) and benches, which are critical to validate the fuzzer’s effectiveness against known vulnerabilities.

- Build and Deployment Infrastructure:
– Docker, GitHub workflows, and Makefile.toml indicate that the project is containerized and CI/CD pipelines are in place. These files help with building, testing, and releasing the project.
– Additional scripts under .github or ci.py add to automated testing / deployment strategies.

##### Interactions and Data Flow
– Fuzzing Engine (Rust core) receives smart contract inputs (provided either offchain or via onchain forking) and processes them via its EVM and Move pipelines.
– External blockchain APIs and flashloan support are called by modules (especially when fuzzing against onchain state).
– The output (vulnerabilities, exploit details, debugging info) is sent to the UI layer or logged for further analysis.

– From smart contract source inputs to the fuzzing process.
– From the fuzzing engine to API endpoints and to the UI.
– From external resources (e.g., Ethereum or Polygon RPC URLs, Etherscan API) into the fuzzing engine.

- Interaction between core components (e.g., communication from the scheduler (management of fuzzing tasks) through concolic and symbolic execution modules).

##### Architectural Patterns and Technologies
- The project clearly uses modular design principles:
– Separation of concerns between the EVM-specific processing and the Move-specific processing.
– Usage of middleware components in the EVM pipeline for tasks like cheatcode handling, reentrancy detection, and bytecode management.
- Integration of LibAFL as a foundational library for fuzzing.
- The deployment infrastructure (Dockerfile, GitHub workflows) should be depicted on the periphery to emphasize CI/CD practices.

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Inputs Layer
    subgraph "External Inputs"
        extSC("Smart Contracts"):::external
        extBN("Blockchain Networks"):::external
        extAPI("External APIs"):::external
    end

    %% Fuzzing Engine Core (Rust)
    subgraph "Fuzzing Engine Core (Rust)"
        core("Rust Core"):::rust
        evm("EVM Fuzzer"):::rust
        move("Move Fuzzer"):::rust
        common("Common Utilities"):::rust
    end

    %% Client & API Layer
    subgraph "Client & API Layer"
        api("API Server (Node.js)"):::nodejs
        ui("UI Layer (Python)"):::python
    end

    %% Supporting & Integration
    subgraph "Supporting & Integration"
        onchain("Onchain Scripts"):::python
        tests("Integration Tests"):::ci
        cicd("CI/CD Pipeline"):::ci
    end

    %% Data Flow Connections
    extSC -->|"triggers"| core
    extBN -->|"feeds"| core
    extAPI -->|"provides_data"| core

    core -->|"orchestrates"| evm
    core -->|"orchestrates"| move
    core -->|"uses"| common

    core -->|"reports_to"| api

    onchain -->|"interacts_with"| core
    tests -->|"validates"| core
    cicd -->|"deploys_to"| core
    cicd -->|"deploys_to"| api
    cicd -->|"deploys_to"| ui

    api -->|"serves"| ui

    %% Click Events
    click core "https://github.com/fuzzland/ityfuzz/blob/master/src/main.rs"
    click evm "https://github.com/fuzzland/ityfuzz/tree/master/src/evm"
    click move "https://github.com/fuzzland/ityfuzz/tree/master/src/move"
    click common "https://github.com/fuzzland/ityfuzz/tree/master/src/fuzzers"
    click api "https://github.com/fuzzland/ityfuzz/blob/master/server/app.js"
    click ui "https://github.com/fuzzland/ityfuzz/blob/master/ui/backend.py"
    click onchain "https://github.com/fuzzland/ityfuzz/tree/master/onchain_scripts"
    click tests "https://github.com/fuzzland/ityfuzz/tree/master/tests"
    click cicd "https://github.com/fuzzland/ityfuzz/tree/master/Dockerfile"

    %% Styles
    classDef rust fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef nodejs fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef python fill:#FFFF99,stroke:#000,stroke-width:1px;
    classDef external fill:#FFB6C1,stroke:#000,stroke-width:1px;
    classDef ci fill:#FFA500,stroke:#000,stroke-width:1px;
```
