vyper-compiler

name	vyper-compiler
description	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.

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