How troublor/nyx works
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