chore[docs]: fix module/contract/interface terminology by lufa23 · Pull Request #4878 · vyperlang/vyper

lufa23 · 2026-03-09T13:44:54Z

What I did

Fixed inconsistent use of "module", "contract", and "interface" throughout the docs, based on feedback from @Sporarum. Changes are consistent with the direction of #4877.

How I did it

Replaced incorrect uses of "contract" with "module" where the text referred to source files. Fixed the inversion pattern that described "any contract is a valid module" — the correct relationship is that the entry-point module becomes a contract upon deployment.

How to verify it

Read the changed files and check terminology is consistent with the module/contract/interface distinctions.

Commit message

chore[docs]: fix module/contract/interface terminology
update docs to consistently distinguish between modules (source files),
contracts (deployed artifacts), and interfaces. fixes incorrect
inversion pattern which described any contract as a valid module. the
correct relationship is that the entry-point module becomes a contract
upon deployment.

charles-cooper · 2026-03-09T14:00:49Z

hm yea technically contract refers to a deployed artifact but it can also informally refer to a toplevel module (compilation target)

codecov · 2026-03-09T14:06:56Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.06%. Comparing base (2856eaa) to head (d7184ae).
⚠️ Report is 19 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #4878      +/-   ##
==========================================
+ Coverage   91.56%   92.06%   +0.49%     
==========================================
  Files         185      187       +2     
  Lines       26971    27132     +161     
  Branches     4739     4758      +19     
==========================================
+ Hits        24696    24978     +282     
+ Misses       1548     1437     -111     
+ Partials      727      717      -10

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

pcaversaccio

hmmmmmm, I'm not sure replacing "contract" with "module" everywhere improves the clarity of the docs tbh (reading the docs confused me here since what is a module really?; is it compileable? what about non-fully-to-bytecode-compileable module contracts? etc). While the terminology might be technically correct (up for debate), most devs still reason about deployed contracts rather than compilation modules. It's just a fact. Introducing "module" throughout the docs also raises the question of how it differs from a contract, and I don't see that concept clearly defined before it's used. This could make the docs harder to follow for users coming from Solidity or the broader Ethereum ecosystem tbh where "contract" is the standard term. It might be better to either keep "contract" in user-facing explanations or introduce a clear explanation of the module vs contract distinction before adopting the new terminology throughout the docs.

Sporarum

A couple comments on the changes

Note: I used "root module" in my comments to mean "the module we point the compiler at, which will become the contract"
I see you have used the concept of "entry point module", which also works for me

Sporarum · 2026-03-09T14:45:22Z

 #######################

-Vyper contracts are contained within files. Each file contains exactly one contract.
+Each Vyper source file contains exactly one module.


Missing explanation of what a contract is

The one from using-modules.rst is very good, I think its fine to reuse it
(might or might not require being adapted)

Sporarum · 2026-03-09T14:46:32Z

 .. _exceptions-common:

-Vyper raises one or more of the following exceptions when an issue is encountered while compiling a contract.
+Vyper raises one or more of the following exceptions when an issue is encountered while compiling a module.


I think all these still make more sense with contract

There's not really a meaning to compiling a single module
(other than it becoming the contract)

you're right, reverted with d7184ae

Sporarum · 2026-03-09T14:51:15Z



-This imports the defined interface from the vyper file at ``an_interface.vyi`` (or ``an_interface.json`` if using ABI json interface type) and ensures your current contract implements all the necessary external functions. If any interface functions are not included in the contract, it will fail to compile. This is especially useful when developing contracts around well-defined standards such as ERC20.
+This imports the defined interface from the vyper file at ``an_interface.vyi`` (or ``an_interface.json`` if using ABI json interface type) and ensures your current module implements all the necessary external functions. If any interface functions are not included in the module, it will fail to compile. This is especially useful when developing contracts around well-defined standards such as ERC20.


We should make it clear that implements is only ever useful when used from a root-module, since other modules can chose whether to exports external methods

Sporarum · 2026-03-09T14:53:08Z

 -----------------

-The optimization mode can be one of ``"none"``, ``"codesize"``, or ``"gas"`` (default). For example, adding the following line to a contract will cause it to try to optimize for codesize:
+The optimization mode can be one of ``"none"``, ``"codesize"``, or ``"gas"`` (default). For example, adding the following line to a module will cause it to try to optimize for codesize:


What happens when pragmas are used in non-root modules ?

Sporarum · 2026-03-09T14:56:12Z

 -----------------------------

-When looking for a file to import, Vyper will first search relative to the same folder as the contract being compiled. It then checks for the file in the provided search paths, in the precedence provided. Vyper checks for the file name with a ``.vy`` suffix first, then ``.vyi``, then ``.json``.
+When looking for a file to import, Vyper will first search relative to the same folder as the module being compiled. It then checks for the file in the provided search paths, in the precedence provided. Vyper checks for the file name with a ``.vy`` suffix first, then ``.vyi``, then ``.json``.


I think the wording should be clearer, are paths relative to the root-module, or the current module ?

(I'm pretty sure it's the current module, but it should be clear from this paragraph)

Sporarum · 2026-03-09T14:57:53Z

 ===========================

-The simplest way to define a module is to write a contract. In Vyper, any contract is a valid module! For example, the following contract is also a valid module.
+Any ``.vy`` file is a module. When a module is the entry point of compilation, it becomes a contract upon deployment. For example, the following module can be both deployed directly and imported by other modules.


Perfect explanation !

Sporarum · 2026-03-09T15:06:59Z

hm yea technically contract refers to a deployed artifact but it can also informally refer to a toplevel module (compilation target)

Yes I think we should be more explicit on this, since "contract" can mean either the root module only, or multiple modules (the deployed artifact) depending on the context

Even more so since with #4730 we might have modules which are not valid contracts (toplevel modules)

Sporarum · 2026-03-09T15:18:18Z

most devs still reason about deployed contracts rather than compilation modules.

how it differs from a contract, and I don't see that concept clearly defined before it's used.

I agree, we should expand more on the distinction between modules and contracts, but I would the docs where already confusing in this regard before !
Since it was never clear what it meant to be a module (semantically)

I would however like to see some of the structure a bit more modified than just renaming things. In particular I think a (potentially shalow) definition of modules and contracts should come fairly early.

This could make the docs harder to follow for users coming from Solidity

I disagree, Solidity already has a concept of contract which can use source from other files, so the structure is actually very similar
To my understanding the main difference is that they have keywords like contract which distinguish contracts/modules, whereas we use where the compiler is pointed at

Sporarum · 2026-03-09T15:21:26Z

I clicked "close with comment" instead of deleting a message I was writing ...

fubuloubu

Some minor suggestions

fubuloubu · 2026-03-25T18:12:52Z

 =========================

-You can define an interface for your contract with the ``implements`` statement:
+You can define an interface for your module with the ``implements`` statement:


Suggested change

You can define an interface for your module with the ``implements`` statement:

You can define an interface that your module must satisfy with the ``implements`` statement:

fubuloubu · 2026-03-25T18:14:19Z

 =====================

-Vyper has a built-in format option to allow you to easily export a Vyper interface from a pre-existing contract.
+Vyper has a built-in format option to allow you to easily export a Vyper interface from a pre-existing module.


Should this be "top-level" module, artifact, etc. (Stay "contract"?)

fubuloubu · 2026-03-25T18:16:17Z



-In the above examples, the contract will only compile with Vyper versions ``0.4.x``.
+In the above examples, the module will only compile with Vyper versions ``0.4.x``.


Wonder if file would actually be clearer here (or module file)

fubuloubu · 2026-03-25T18:17:16Z

 * state (variables), which may be tightly coupled with that functionality 

-Modules can be added to contracts by importing them from a ``.vy`` file. Any ``.vy`` file is a valid module which can be imported into another contract! This is a very powerful feature which allows you to assemble contracts via other contracts as building blocks.
+Modules can be imported from any ``.vy`` file. Any ``.vy`` file is a valid module which can be imported into another module. When the entry-point module is compiled and deployed, it becomes a contract.


This seems very important, maybe consider listing higher?

Also I haven't see "entry-point module" defined yet, I see it below I'm "Using Modules"

rafael-abuawad

Interesting approach, but I don't think it is going to be useful, especially because the word 'contract' is engraved so deeply in EVM development. Maybe adding a new section on modules would be better

rafael-abuawad · 2026-03-27T18:22:04Z

 ==============================

-Interfaces can be added to contracts either through inline definition, or by importing them from a separate file.
+Interfaces can be added to a module either through inline definition, or by importing them from a separate file.


modules would be better

Suggested change

Interfaces can be added to a module either through inline definition, or by importing them from a separate file.

Interfaces can be added to modules either through inline definition, or by importing them from a separate file.

rafael-abuawad · 2026-03-27T18:23:50Z

 #######################

-Vyper contracts are contained within files. Each file contains exactly one contract.
+Each Vyper source file contains exactly one module.


I think since this is really early in the docs, we should start using the word modules as a synonym, keeping the original and adding the word module

Suggested change

Each Vyper source file contains exactly one module.

Vyper contracts (or modules) are contained within files. Each file contains exactly one contract.

Something in that line

The goal of this PR is specifically to make the two concepts more distinct !

And in particular "Each file contains exactly one contract." is incorrect.
That is especially true with the upcoming abstract modules, which are not valid contracts

lufa23 added 3 commits March 6, 2026 20:18

docs: fix module/contract/interface terminology

9ee4fe6

docs: fix module/contract inversion pattern

6540781

docs: fix remaining module/contract violations

1e0147a

charles-cooper requested review from Sporarum and pcaversaccio March 9, 2026 14:00

pcaversaccio reviewed Mar 9, 2026

View reviewed changes

Sporarum reviewed Mar 9, 2026

View reviewed changes

Sporarum closed this Mar 9, 2026

Sporarum reopened this Mar 9, 2026

docs: revert module→contract in compiler-exceptions.rst

d7184ae

fubuloubu approved these changes Mar 25, 2026

View reviewed changes

rafael-abuawad reviewed Mar 27, 2026

View reviewed changes



		This imports the defined interface from the vyper file at ``an_interface.vyi`` (or ``an_interface.json`` if using ABI json interface type) and ensures your current contract implements all the necessary external functions. If any interface functions are not included in the contract, it will fail to compile. This is especially useful when developing contracts around well-defined standards such as ERC20.
		This imports the defined interface from the vyper file at ``an_interface.vyi`` (or ``an_interface.json`` if using ABI json interface type) and ensures your current module implements all the necessary external functions. If any interface functions are not included in the module, it will fail to compile. This is especially useful when developing contracts around well-defined standards such as ERC20.

	You can define an interface for your module with the ``implements`` statement:
	You can define an interface that your module must satisfy with the ``implements`` statement:



		In the above examples, the contract will only compile with Vyper versions ``0.4.x``.
		In the above examples, the module will only compile with Vyper versions ``0.4.x``.

	Interfaces can be added to a module either through inline definition, or by importing them from a separate file.
	Interfaces can be added to modules either through inline definition, or by importing them from a separate file.

	Each Vyper source file contains exactly one module.
	Vyper contracts (or modules) are contained within files. Each file contains exactly one contract.

Uh oh!

Conversation

lufa23 commented Mar 9, 2026

What I did

How I did it

How to verify it

Commit message

Uh oh!

charles-cooper commented Mar 9, 2026

Uh oh!

codecov Bot commented Mar 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

pcaversaccio left a comment

Choose a reason for hiding this comment

Uh oh!

Sporarum left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lufa23 Mar 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Sporarum commented Mar 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Sporarum commented Mar 9, 2026

Uh oh!

Sporarum commented Mar 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

fubuloubu left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rafael-abuawad left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

codecov Bot commented Mar 9, 2026 •

edited

Loading

lufa23 Mar 25, 2026 •

edited

Loading

Sporarum commented Mar 9, 2026 •

edited

Loading

Sporarum commented Mar 9, 2026 •

edited

Loading