# troublor/nyx architecture

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

- Interactive diagram: https://gitdiagram.com/troublor/nyx
- Repository: https://github.com/troublor/nyx

## Overview

##### Project type and purpose
- Nyx is a research tool (Python-based CLI) for detecting exploitable front-running vulnerabilities in Ethereum smart contracts.
- It implements a two-phase analysis:
- Phase1: Static pruning on a “hybrid flow graph (HFG)” to filter out non-interfering function pairs.
- Phase2: Symbolic validation via a custom symbolic execution engine to confirm profit-making front-running scenarios.

##### File structure
Top-level layout:
- README.md, SP2024.pdf (paper), pyproject.toml, .pylintrc, .gitignore
- examples/ — sample smart-contract project (HashPuzzle) with its config, metadata, and src
- nyx/main.py — CLI entry point
- nyx/analyze/ — phase1 modules: graph construction, pruning, interference analysis
- nyx/engine/ & nyx/engine2/ — two symbolic execution engine versions plus environment, executor, state & value models
- nyx/hfg/ — hybrid flow graph builder, inter- and intra-contract analysis
- nyx/galaxy/ — contract grouping, repository abstraction, attack scenario definitions
- nyx/lib/ — core utilities: abstract interpretation, solidity AST parsing, asset models (ERC20, ERC721, etc.), Z3 integration, logging, test utilities
- nyx/nyx.egg-info/ — packaging metadata

##### Extract architectural insights from the README
- Two-phase pipeline: static HFG-based prune followed by symbolic execution.
- Output: JSON report listing all function-pair analyses and vulnerability verdicts.
- Dependencies (implicitly): Python 3, Z3, solidity compiler (solc), Slither (optional), standard JSON I/O.

a. Main components
1) CLI / Orchestrator (nyx/main.py)
2) Parser & HFG Builder (nyx/hfg)
3) Static Analyzer (nyx/analyze)
4) Symbolic Execution Engine (nyx/engine and engine2)
5) Contract Asset Models & Utility Library (nyx/lib)
6) Contract Grouping & Attack Models (nyx/galaxy)
7) Input Source (examples/ or user-supplied contract directory)
8) Output Reporter (result.json)

b. Relationships and data flows
- CLI loads target contract code → hands off to Parser/HFG Builder → produces a graph representation.
- Graph → static analyzer modules → pruned function-pair list.
- Pruned pairs → symbolic engine → symbolic state exploration via Z3.
- Asset models (ERC tokens, Ether) and utility libraries support both phases.
- Attack definitions in galaxy augment the symbolic engine with profit-making scenarios.
- Final verdicts collected by CLI → written to result.json.

c. Architectural patterns & design principles
- Modular pipeline separating parsing, static analysis, and symbolic execution.
- Clear layering:
– Presentation/Orchestration (CLI)
– Domain model (HFG, contracts, assets)
– Analysis engines (static and symbolic)
– Utility services (logging, Z3, JSON I/O)
- Dependency injection of asset models and solver interfaces.
- Test harness built around each module (unit tests in analyze, engine, hfg, lib).

d. Key technologies & frameworks
- Python 3 (pyproject.toml)
- Z3 theorem prover (via nyx/lib/z3.py)
- Solidity compiler & AST parsing (nyx/lib/solc_ast.py)
- Slither integration (nyx/lib/slither_util.py)
- Standard JSON, logging modules

## Diagram (Mermaid)

```mermaid
graph TB
    %% Presentation Layer
    subgraph "Presentation / Orchestration"
        CLI["CLI Orchestrator\n(nyx/main.py)"]:::core
    end

    %% Parser & HFG Builder
    subgraph "Parser & HFG Builder"
        Flow["flow.py"]:::core
        HFG["hybrid_flow_graph.py"]:::core
        InterC["inter_contract.py"]:::core
        IntraC["intra_contract.py"]:::core
        MsgCG["msg_call_graph.py"]:::core
    end

    %% Static Analyzer Phase 1
    subgraph "Static Analyzer (Phase1)"
        Config["config.py"]:::core
        Controller["controller.py"]:::core
        Group["group.py"]:::core
        Observe["observe.py"]:::core
        Prune["prune.py"]:::core
        Profit["profit.py"]:::core
        Validate["validate.py"]:::core
    end

    %% Symbolic Execution Engines
    subgraph "Symbolic Execution Engine v1"
        Env1["env.py"]:::core
        Exec1["executor.py"]:::core
        SymVal1["sym_value.py"]:::core
        Summ1["summary.py"]:::core
    end

    subgraph "Symbolic Execution Engine v2"
        Ctrl2["controller.py"]:::core
        Eng2["engine.py"]:::core
        Env2["env.py"]:::core
        State2["state.py"]:::core
        Msg2["msg_call.py"]:::core
        Trans2["transfer.py"]:::core
        Val2["value.py"]:::core
        Var2["variable.py"]:::core
        SumB2["summary_builder.py"]:::core
        Summ2["summary.py"]:::core
    end

    %% Asset & Utility Library
    subgraph "Asset & Utility Library"
        AbsInt["abstract_interpretation.py"]:::lib
        SolcAST["solc_ast.py"]:::lib
        Slither["slither_util.py"]:::lib
        Z3Lib["z3.py"]:::lib
        Log["log.py"]:::lib
        Solidity["solidity.py"]:::lib
        Signal["signal.py"]:::lib
        Types["types.py"]:::lib
        TestUtil["test_util.py"]:::lib
        ERC20["assets/erc20.py"]:::lib
        ERC721["assets/erc721.py"]:::lib
        ERC1155["assets/erc1155.py"]:::lib
        ERC777["assets/erc777.py"]:::lib
        Ether["assets/ether.py"]:::lib
        WETH9["assets/weth9.py"]:::lib
        TransferLib["assets/transfer.py"]:::lib
        GenABI["assets/gen_abi.py"]:::lib
    end

    %% Attack Models
    subgraph "Contract Grouping & Attack Models"
        Attack["Attack.py"]:::lib
        ContractGroup["ContractGroup.py"]:::lib
        ContractRepo["ContractRepo.py"]:::lib
    end

    %% External Dependencies
    Z3["Z3 Theorem Prover"]:::external
    Solc["Solidity Compiler (solc)"]:::external

    %% Output
    Reporter["JSON Reporter\n(result.json)"]:::core

    %% Data Flows
    CLI -->|"load contracts"| Flow
    Flow -->|"HFG graph"| Config
    Flow --> HFG
    Flow --> InterC
    Flow --> IntraC
    Flow --> MsgCG
    Config --> Controller
    HFG --> Controller
    Controller --> Group
    Controller --> Observe
    Controller --> Prune
    Prune --> Profit
    Profit --> Validate
    Validate -->|"pruned pairs"| Env1
    Validate --> Env2
    Env1 --> Exec1
    Exec1 --> SymVal1
    SymVal1 --> Summ1
    Env2 --> Eng2
    Eng2 --> State2
    State2 --> Msg2
    Msg2 --> Trans2
    Trans2 --> Val2
    Val2 --> Var2
    Var2 --> SumB2
    SumB2 --> Summ2
    Summ1 --> Reporter
    Summ2 --> Reporter

    %% Library injections
    AbsInt --> Controller
    SolcAST --> Controller
    Slither --> Controller
    Z3Lib --> Exec1
    Z3Lib --> Eng2
    Log --> CLI
    Solidity --> Flow
    Signal --> Flow
    Types --> Validate
    TestUtil -.-> Controller

    ERC20 --> Exec1
    ERC721 --> Exec1
    ERC1155 --> Exec1
    ERC777 --> Exec1
    Ether --> Exec1
    WETH9 --> Exec1
    TransferLib --> Exec1
    GenABI --> Exec1

    ERC20 --> Eng2
    ERC721 --> Eng2
    ERC1155 --> Eng2
    ERC777 --> Eng2
    Ether --> Eng2
    WETH9 --> Eng2
    TransferLib --> Eng2
    GenABI --> Eng2

    Attack --> Eng2
    ContractGroup --> Flow
    ContractRepo --> Flow

    Solc -.-> SolcAST
    Z3 -.-> Z3Lib

    Reporter -.-> pyproject
    Reporter -.-> pylintrc

    %% Packaging & Config
    subgraph "Packaging & Config"
        pyproject["pyproject.toml"]:::config
        pylintrc[".pylintrc"]:::config
        Gitignore[".gitignore"]:::config
        Readme["README.md"]:::config
    end

    %% Click events
    click CLI "https://github.com/troublor/nyx/blob/main/nyx/main.py"
    click Flow "https://github.com/troublor/nyx/blob/main/nyx/hfg/flow.py"
    click HFG "https://github.com/troublor/nyx/blob/main/nyx/hfg/hybrid_flow_graph.py"
    click InterC "https://github.com/troublor/nyx/blob/main/nyx/hfg/inter_contract.py"
    click IntraC "https://github.com/troublor/nyx/blob/main/nyx/hfg/intra_contract.py"
    click MsgCG "https://github.com/troublor/nyx/blob/main/nyx/hfg/msg_call_graph.py"
    click Config "https://github.com/troublor/nyx/blob/main/nyx/analyze/config.py"
    click Controller "https://github.com/troublor/nyx/blob/main/nyx/analyze/controller.py"
    click Group "https://github.com/troublor/nyx/blob/main/nyx/analyze/group.py"
    click Observe "https://github.com/troublor/nyx/blob/main/nyx/analyze/observe.py"
    click Prune "https://github.com/troublor/nyx/blob/main/nyx/analyze/prune.py"
    click Profit "https://github.com/troublor/nyx/blob/main/nyx/analyze/profit.py"
    click Validate "https://github.com/troublor/nyx/blob/main/nyx/analyze/validate.py"
    click Env1 "https://github.com/troublor/nyx/blob/main/nyx/engine/env.py"
    click Exec1 "https://github.com/troublor/nyx/blob/main/nyx/engine/executor.py"
    click SymVal1 "https://github.com/troublor/nyx/blob/main/nyx/engine/sym_value.py"
    click Summ1 "https://github.com/troublor/nyx/blob/main/nyx/engine/summary.py"
    click Ctrl2 "https://github.com/troublor/nyx/blob/main/nyx/engine2/controller.py"
    click Eng2 "https://github.com/troublor/nyx/blob/main/nyx/engine2/engine.py"
    click Env2 "https://github.com/troublor/nyx/blob/main/nyx/engine2/env.py"
    click State2 "https://github.com/troublor/nyx/blob/main/nyx/engine2/state.py"
    click Msg2 "https://github.com/troublor/nyx/blob/main/nyx/engine2/msg_call.py"
    click Trans2 "https://github.com/troublor/nyx/blob/main/nyx/engine2/transfer.py"
    click Val2 "https://github.com/troublor/nyx/blob/main/nyx/engine2/value.py"
    click Var2 "https://github.com/troublor/nyx/blob/main/nyx/engine2/variable.py"
    click SumB2 "https://github.com/troublor/nyx/blob/main/nyx/engine2/summary_builder.py"
    click Summ2 "https://github.com/troublor/nyx/blob/main/nyx/engine2/summary.py"
    click AbsInt "https://github.com/troublor/nyx/blob/main/nyx/lib/abstract_interpretation.py"
    click SolcAST "https://github.com/troublor/nyx/blob/main/nyx/lib/solc_ast.py"
    click Slither "https://github.com/troublor/nyx/blob/main/nyx/lib/slither_util.py"
    click Z3Lib "https://github.com/troublor/nyx/blob/main/nyx/lib/z3.py"
    click Log "https://github.com/troublor/nyx/blob/main/nyx/lib/log.py"
    click Solidity "https://github.com/troublor/nyx/blob/main/nyx/lib/solidity.py"
    click Signal "https://github.com/troublor/nyx/blob/main/nyx/lib/signal.py"
    click Types "https://github.com/troublor/nyx/blob/main/nyx/lib/types.py"
    click TestUtil "https://github.com/troublor/nyx/blob/main/nyx/lib/test_util.py"
    click ERC20 "https://github.com/troublor/nyx/blob/main/nyx/lib/assets/erc20.py"
    click ERC721 "https://github.com/troublor/nyx/blob/main/nyx/lib/assets/erc721.py"
    click ERC1155 "https://github.com/troublor/nyx/blob/main/nyx/lib/assets/erc1155.py"
    click ERC777 "https://github.com/troublor/nyx/blob/main/nyx/lib/assets/erc777.py"
    click Ether "https://github.com/troublor/nyx/blob/main/nyx/lib/assets/ether.py"
    click WETH9 "https://github.com/troublor/nyx/blob/main/nyx/lib/assets/weth9.py"
    click TransferLib "https://github.com/troublor/nyx/blob/main/nyx/lib/assets/transfer.py"
    click GenABI "https://github.com/troublor/nyx/blob/main/nyx/lib/assets/gen_abi.py"
    click Attack "https://github.com/troublor/nyx/blob/main/nyx/galaxy/Attack.py"
    click ContractGroup "https://github.com/troublor/nyx/blob/main/nyx/galaxy/ContractGroup.py"
    click ContractRepo "https://github.com/troublor/nyx/blob/main/nyx/galaxy/ContractRepo.py"
    click pyproject "https://github.com/troublor/nyx/blob/main/pyproject.toml"
    click pylintrc "https://github.com/troublor/nyx/blob/main/.pylintrc"
    click Gitignore "https://github.com/troublor/nyx/blob/main/.gitignore"
    click Readme "https://github.com/troublor/nyx/blob/main/README.md"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef lib fill:#98FB98,stroke:#000,stroke-width:1px
    classDef external fill:#FFD580,stroke:#000,stroke-width:1px
    classDef config fill:#E0E0E0,stroke:#000,stroke-width:1px
    classDef test stroke-dasharray: 5 5;color:#666;font-style:italic
```
