Vyper 0.4.0: Mandatory @external/@internal Decorators Break Legacy Contracts

Answer

In Vyper 0.4.0 every function must be explicitly marked with either @external or @internal. The compiler will reject any function lacking a decorator, and any function that was implicitly public in 0.3.x will become invisible unless you add the appropriate annotation. The safest path is to perform a systematic, automated scan, annotate every missing decorator, then run the full test suite to confirm that public API behavior is unchanged.

Why the change matters

• Implicit public visibility was removed, so functions that callers (including tests or tooling) invoked without a decorator will now fail to compile.
• Unannotated functions that were meant to be internal can unintentionally become public if you default to @external during bulk updates.
• The new module system requires explicit imports, so shared logic that previously lived in a flat file may need restructuring.

Recommended Migration Steps

1. Static analysis pass: Run vyper --strict-visibility on the entire codebase. This flags every function that still relies on implicit visibility.

   vyper --strict-visibility --source-dir ./contracts
   

2. Generate a diff‑ready patch: Use a small Python script that parses the compiler output and injects @external into every unannotated function that is called from the contract’s public API. For functions that are only used internally, annotate with @internal.

   import re, pathlib
   # Simplified example – adjust regex for your code style
   for file in pathlib.Path("./contracts").rglob("*.vy"):
       text = file.read_text()
       def annotate(match):
           return f"@external\n{match.group(0)}"
       new_text = re.sub(r"^def ", annotate, text, flags=re.MULTILINE)
       file.write_text(new_text)
   

3. Review the patch: Use git diff to ensure only visibility annotations changed. Pay special attention to functions that interact with other contracts or are called via low‑level call.

   git diff --stat
   

4. Re‑run strict‑visibility check to confirm no gaps remain.

   vyper --strict-visibility --source-dir ./contracts
   

5. Run the test suite (unit, integration, and any external tooling tests). If any tests fail, inspect the failing function to determine whether it should be @external or @internal.

   pytest tests/ -v
   

6. Optional: migrate shared logic to modules.
   • Create a module file (e.g., utils.vy) that contains shared functions.
   • Import it in contracts with from utils import * or specific names.
   • Re‑run vyper --modules to validate module imports.
7. Final verification.
   • Compile the contracts with vyper --output-bytecode and inspect the bytecode selectors to ensure internal functions are not exposed.
   • Deploy to a testnet and run a smoke test that calls every public function.

Addressing the Unresolved Questions

Efficient automatic annotation

The script above performs a bulk annotation, but you must manually verify that functions intended to be internal are not marked @external. A pragmatic approach is to start with @external for all missing decorators, run the test suite, and then flip any that fail to @internal.

Impact on testing/tooling

Tests or scripts that call functions by name (e.g., via contract_instance.function_name()) will now compile only if the function is annotated. If a test previously invoked a function that was implicitly public, you’ll need to add the decorator and update any import paths if modules were introduced.

Modules vs. flattened logic

Modules reduce duplication and make shared logic easier to maintain, but they require a refactor of state variables and function signatures. If your codebase is small or the shared logic is trivial, flattening may be acceptable. For larger projects, the module system offers better long‑term maintainability and aligns with 0.4.x best practices.

Ask for a Missing Diagnostic Detail

To fine‑tune the annotation strategy, could you share a snippet of a function that is currently unannotated but is used internally? That will help determine whether it should be @internal or @external in the migrated code.