Vyper Compiler
Pythonic smart contract language targeting the EVM. v0.4.x, Python 3.11+.
Quick Commands
uv sync # install deps (per-worktree .venv, recommended, includes dev group)
uv run vyper contract.vy # compile a contract
uv run vyper -f ir_runtime contract.vy # inspect Venom IR
uv run vyper -f asm contract.vy # inspect assembly
uv run ./quicktest.sh # run tests (`-nauto -m "not fuzzing"` by default via setup.cfg)
uv run make lint # enforces code style (same as CI)
Prefix all commands with uv run — it activates the local .venv per invocation, which is necessary in non-interactive shells. Each worktree gets its own .venv, so no cross-contamination.
Alternative: pip install . --group dev + PYTHONPATH=. prefix on every command. Never pip install -e . — it creates an egg-link in site-packages that permanently points the venv at one worktree, breaking all others.
Compilation Pipeline
Source (.vy)
│
├─ vyper/ast/ → Parse to AST (pre_parser → Python AST → Vyper AST)
├─ vyper/semantics/ → Type check, validate, annotate AST
├─ vyper/codegen/ → AST → s-expr IR (default production pipeline)
├─ vyper/ir/ → s-expr IR → assembly → bytecode
└─ vyper/evm/ → Assembly → bytecode
Experimental Venom path (--experimental-codegen):
├─ vyper/codegen_venom/ → AST → Venom SSA IR
└─ vyper/venom/ → Venom IR optimization passes → assembly
Orchestrated by vyper/compiler/phases.py (CompilerData). Each phase is lazy.
Directory Map
| Directory |
Purpose |
vyper/ast/ |
Parsing, AST nodes, pre-parser. See AST README |
vyper/semantics/ |
Type system, analysis, validation. See Semantics README |
vyper/codegen/ |
AST → s-expr IR (default production pipeline) |
vyper/ir/ |
s-expr IR → assembly → bytecode. See IR README |
vyper/codegen_venom/ |
AST → Venom IR (experimental, --experimental-codegen) |
vyper/venom/ |
Venom SSA IR: passes, analysis, assembly emission. See Venom README |
vyper/compiler/ |
Pipeline orchestration, settings, output formats. See Compiler README |
vyper/builtins/ |
Built-in functions and interfaces |
vyper/evm/ |
EVM opcodes, assembler |
vyper/cli/ |
CLI entry points (vyper, vyper-ir, venom) |
tests/unit/ |
Unit tests (ast, semantics, compiler, venom) |
tests/functional/ |
Functional tests (builtins, codegen, grammar, syntax, venom) |
Topic Deep-Dives
- Venom IR — SSA IR design, passes, optimization, working with Venom code
- Semantics & Frontend — Type system, analysis phases, namespace, validation
- Code Generation — Legacy IR, Venom codegen, the two pipelines
- Testing — Test structure, fixtures, running tests, writing new tests
- Contributing — Commit message standards, PR workflow, code style summary
Code Style
Enforced by make lint (also what CI runs). Includes black, flake8, isort, mypy.
- Line length: 100
- No inline imports; standard library → third-party → local
- snake_case for variables (
tmp = ...), DromedaryCase (aka upper camelCase) for classes (ExprAnalyzer), type classes end in T (e.g. IntegerT, ModuleT)
Key Entry Points
| What |
Where |
| Main compile function |
vyper.compiler.compile_code() |
| Pipeline phases |
vyper.compiler.phases.CompilerData |
| AST parsing |
vyper.ast.parse.parse_to_ast() |
| Semantic analysis |
vyper.semantics.analyze_module() |
| Legacy codegen |
vyper.codegen.module |
| AST → Venom IR |
vyper.codegen_venom.module |
| Venom → assembly |
vyper.venom.generate_assembly_experimental() |
| CLI entry |
vyper.cli.vyper_compile |
1---2name: vyper-compiler3description: Vyper smart contract compiler internals. Use when working on the Vyper compiler codebase — compilation pipeline, Venom IR, semantic analysis, code generation, testing, or contributing. Triggers on vyper compiler development, Venom passes, AST/semantics changes, codegen work, or test writing.4---56# Vyper Compiler78Pythonic smart contract language targeting the EVM. v0.4.x, Python 3.11+.910## Quick Commands1112```bash13uv sync # install deps (per-worktree .venv, recommended, includes dev group)14uv run vyper contract.vy # compile a contract15uv run vyper -f ir_runtime contract.vy # inspect Venom IR16uv run vyper -f asm contract.vy # inspect assembly17uv run ./quicktest.sh # run tests (`-nauto -m "not fuzzing"` by default via setup.cfg)18uv run make lint # enforces code style (same as CI)19```2021Prefix all commands with `uv run` — it activates the local `.venv` per invocation, which is necessary in non-interactive shells. Each worktree gets its own `.venv`, so no cross-contamination.2223Alternative: `pip install . --group dev` + `PYTHONPATH=.` prefix on every command. **Never `pip install -e .`** — it creates an egg-link in site-packages that permanently points the venv at one worktree, breaking all others.2425## Compilation Pipeline2627```28Source (.vy)29 │30 ├─ vyper/ast/ → Parse to AST (pre_parser → Python AST → Vyper AST)31 ├─ vyper/semantics/ → Type check, validate, annotate AST32 ├─ vyper/codegen/ → AST → s-expr IR (default production pipeline)33 ├─ vyper/ir/ → s-expr IR → assembly → bytecode34 └─ vyper/evm/ → Assembly → bytecode35```3637Experimental Venom path (`--experimental-codegen`):38```39 ├─ vyper/codegen_venom/ → AST → Venom SSA IR40 └─ vyper/venom/ → Venom IR optimization passes → assembly41```4243Orchestrated by `vyper/compiler/phases.py` (`CompilerData`). Each phase is lazy.4445## Directory Map4647| Directory | Purpose |48|-----------|---------|49| `vyper/ast/` | Parsing, AST nodes, pre-parser. See [AST README](../vyper/ast/README.md) |50| `vyper/semantics/` | Type system, analysis, validation. See [Semantics README](../vyper/semantics/README.md) |51| `vyper/codegen/` | AST → s-expr IR (default production pipeline) |52| `vyper/ir/` | s-expr IR → assembly → bytecode. See [IR README](../vyper/ir/README.md) |53| `vyper/codegen_venom/` | AST → Venom IR (experimental, `--experimental-codegen`) |54| `vyper/venom/` | Venom SSA IR: passes, analysis, assembly emission. See [Venom README](../vyper/venom/README.md) |55| `vyper/compiler/` | Pipeline orchestration, settings, output formats. See [Compiler README](../vyper/compiler/README.md) |56| `vyper/builtins/` | Built-in functions and interfaces |57| `vyper/evm/` | EVM opcodes, assembler |58| `vyper/cli/` | CLI entry points (`vyper`, `vyper-ir`, `venom`) |59| `tests/unit/` | Unit tests (ast, semantics, compiler, venom) |60| `tests/functional/` | Functional tests (builtins, codegen, grammar, syntax, venom) |6162## Topic Deep-Dives6364- **[Venom IR](venom.md)** — SSA IR design, passes, optimization, working with Venom code65- **[Semantics & Frontend](semantics.md)** — Type system, analysis phases, namespace, validation66- **[Code Generation](codegen.md)** — Legacy IR, Venom codegen, the two pipelines67- **[Testing](testing.md)** — Test structure, fixtures, running tests, writing new tests68- **[Contributing](contributing.md)** — Commit message standards, PR workflow, code style summary6970## Code Style7172Enforced by `make lint` (also what CI runs). Includes `black`, `flake8`, `isort`, `mypy`.7374- Line length: 10075- No inline imports; standard library → third-party → local76- snake_case for variables (`tmp = ...`), DromedaryCase (aka upper camelCase) for classes (`ExprAnalyzer`), type classes end in `T` (e.g. `IntegerT`, `ModuleT`)7778## Key Entry Points7980| What | Where |81|------|-------|82| Main compile function | `vyper.compiler.compile_code()` |83| Pipeline phases | `vyper.compiler.phases.CompilerData` |84| AST parsing | `vyper.ast.parse.parse_to_ast()` |85| Semantic analysis | `vyper.semantics.analyze_module()` |86| Legacy codegen | `vyper.codegen.module` |87| AST → Venom IR | `vyper.codegen_venom.module` |88| Venom → assembly | `vyper.venom.generate_assembly_experimental()` |89| CLI entry | `vyper.cli.vyper_compile` |
vyperlang