Vyper Documentation

Vyper is a Pythonic smart contract language that compiles to Ethereum Virtual Machine (EVM) bytecode. It is designed with a focus on security, auditability, and simplicity. Key safety features include:

• Safety by default: Bounds and overflow checking on array accesses and arithmetic, and strong typing with explicit type conversions.
• Predictable execution: Decidable gas consumption, bounded loops (compile-time maximum iterations), and no recursion.
• Clean code reuse: Uses module imports instead of class inheritance, explicit extcall and staticcall keywords for external interactions, and support for pure functions.
• Decimal Fixed Point: Uses decimal fixed point numbers to ensure literals like 0.1 have exact representations, avoiding binary floating-point precision errors.

Venom is an SSA-based (Static Single Assignment) intermediate representation for Vyper, designed for the stack-based EVM.

Hierarchy: IRContext $\rightarrow$ IRFunction(s) $\rightarrow$ IRBasicBlock(s) $\rightarrow$ IRInstruction(s)

Key Characteristics:

• Variables: Prefixed with % and are immutable after assignment (SSA).
• Basic Blocks: Non-branching sequences of instructions terminated by specific jump or return instructions (jmp, jnz, djmp, ret, return, stop, or exit).
• Normalized Form: A constraint where no basic block possesses both multiple predecessors AND multiple successors.

VyperIR is a high-level assembly representation. Expressions in VyperIR have a "valency" of either 1 or 0:

• Valency 1: The expression returns a stack item.
• Valency 0: The expression does not return a stack item.

The grammar follows an (s_expr) structure including INT_LITERAL, IDENTIFIER, EVM_OPCODE, PSEUDO_OPCODE, with, set, seq, if, and repeat.

Deep verification is the process of reducing the 'verification gap'—the distance between a formally proven property and the actual code executing on-chain. It aims to bridge multiple layers of the stack: high-level security properties, source semantics, compiler correctness, and EVM execution semantics.

Key concepts include:

• Verification depth: How far a proof carries through the stack (from source semantics down to the EVM model).
• Verification breadth: The scope of behavior covered (functions, properties, and environment assumptions).

Currently, Vyper supports source-level verification, and work is ongoing to complete the compiler verification layer to connect source semantics to deployed bytecode.

Vyper features an experimental code generation pipeline that bypasses the legacy IR. The flow is:

1. AST: The Abstract Syntax Tree.
2. vyper/codegen_venom/: Translates the annotated Vyper AST directly into Venom SSA IR.
3. Venom IR: The intermediate representation.
4. Optimization: Optimization passes are run on the Venom IR.
5. Assembly: venom/venom_to_assembly.py emits EVM assembly.
6. Bytecode: The assembler in vyper/evm/assembler/ produces the final bytecode.

The default production pipeline follows these stages:

1. Parsing: vyper/ast/ (Pre-parser $\rightarrow$ Python AST $\rightarrow$ Vyper AST).
2. Semantics: vyper/semantics/ (Type checking, validation, and AST annotation).
3. Codegen: vyper/codegen/ (AST $\rightarrow$ s-expr IR).
4. IR/EVM: vyper/ir/ and vyper/evm/ (s-expr IR $\rightarrow$ assembly $\rightarrow$ bytecode).

An experimental Venom path is available via the --experimental-codegen flag, which uses vyper/codegen_venom/ (AST $\rightarrow$ Venom SSA IR) and vyper/venom/ (Venom IR optimization $\rightarrow$ assembly).

The Vyper compilation process follows this transformation sequence:

Source $\rightarrow$ pre_parser $\rightarrow$ Python AST $\rightarrow$ Vyper AST $\rightarrow$ semantic analysis $\rightarrow$ annotated AST.

• AST Phase: Handled by vyper/ast/. The parse_to_ast() function is the main entry point for converting source to the Vyper AST.
• Semantic Analysis Phase: Handled by vyper/semantics/.

The current default production pipeline uses a tree-shaped s-expression IR. The flow is:

1. AST: The Abstract Syntax Tree.
2. vyper/codegen/: Generates the s-expression IR (IRnode).
3. vyper/ir/compile_ir.py: Compiles the IR.
4. Assembly: Generates EVM assembly.
5. Bytecode: Produces the final bytecode.

Key Difference: Unlike the Venom pipeline which uses SSA basic blocks, the legacy IR uses tree-shaped s-expressions.

The Vyper compilation process follows these stages:

1. AST Generation: Source code is parsed into an abstract syntax tree via vyper.ast.
2. IR Generation: Contextualized AST nodes are converted into Intermediate Representation (IR) nodes via vyper.codegen.module.
3. Assembly Generation: IR nodes are converted into assembly instructions via vyper.compile_ir.
4. Bytecode Generation: Assembly instructions are converted into EVM bytecode via vyper.compile_ir.

Note that phases 3 and 4 can produce two distinct types of bytecode:

• Deployment bytecode: Used for deploying the contract onto the blockchain.
• Runtime bytecode: The actual on-chain code resulting from deployment.

The test suite is organized into unit and functional categories:

• tests/unit/: Isolated component tests (e.g., ast, semantics, compiler/venom, cli).
• tests/functional/: End-to-end compilation and execution tests (e.g., builtins, codegen, grammar, syntax, venom).
• tests/conftest.py: Contains shared pytest fixtures.
• tests/evm_backends/: Contains pluggable EVM execution backends.
• tests/venom_utils.py: Contains helpers for Venom tests.