chore[docs]: add docs for v0.4.0 features (#3947)

document new v0.4.0 features, including: - module system - internal function decorator now optional - `extcall` and `staticcall` keywords - testing (remove eth-tester references) - `@deploy` visibility - search path - archives, integrity hash - type annotations required for loop variables - new CLI options --------- Co-authored-by: tserg <[email protected]> Co-authored-by: Daniel Schiavini <[email protected]> Co-authored-by: El De-dog-lo <[email protected]>
vyperlang · May 28, 2024 · 2137652 · 2137652
1 parent 003d0c6
commit 2137652
Show file tree

Hide file tree

Showing 19 changed files with 510 additions and 255 deletions.
diff --git a/.gitignore b/.gitignore
@@ -49,4 +49,4 @@ vyper/vyper_git_commithash.txt
 *.spec
 
 # mac
-.DS_Store
+.DS_Store
diff --git a/docs/compiling-a-contract.rst b/docs/compiling-a-contract.rst
@@ -6,17 +6,19 @@ Command-Line Compiler Tools
 
 Vyper includes the following command-line scripts for compiling contracts:
 
-* ``vyper``: Compiles vyper contract files into ``IR`` or bytecode
+* ``vyper``: Compiles vyper contract or archive files
 * ``vyper-json``: Provides a JSON interface to the compiler
 
 .. note::
 
     The ``--help`` flag gives verbose explanations of how to use each of these scripts.
 
+.. _vyper-cli-command:
+
 vyper
 -----
 
-``vyper`` provides command-line access to the compiler. It can generate various outputs including simple binaries, ASTs, interfaces and source mappings.
+``vyper`` provides CLI access to the compiler. It can generate various outputs including simple binaries, ASTs, interfaces and source mappings.
 
 To compile a contract:
 
@@ -29,7 +31,7 @@ Include the ``-f`` flag to specify which output formats to return. Use ``vyper -
 
 .. code:: shell
 
-    $ vyper -f abi,abi_python,bytecode,bytecode_runtime,interface,external_interface,ast,annotated_ast,ir,ir_json,ir_runtime,hex-ir,asm,opcodes,opcodes_runtime,source_map,method_identifiers,userdoc,devdoc,metadata,combined_json,layout yourFileName.vy
+    $ vyper -f abi,abi_python,bytecode,bytecode_runtime,blueprint_bytecode,interface,external_interface,ast,annotated_ast,integrity,ir,ir_json,ir_runtime,asm,opcodes,opcodes_runtime,source_map,source_map_runtime,archive,solc_json,method_identifiers,userdoc,devdoc,metadata,combined_json,layout yourFileName.vy
 
 .. note::
     The ``opcodes`` and ``opcodes_runtime`` output of the compiler has been returning incorrect opcodes since ``0.2.0`` due to a lack of 0 padding (patched via `PR 3735 <https://github.com/vyperlang/vyper/pull/3735>`_). If you rely on these functions for debugging, please use the latest patched versions.
@@ -95,7 +97,6 @@ Importing Interfaces
 
 1. Interfaces defined in the ``interfaces`` field of the input JSON.
 2. Derived interfaces generated from contracts in the ``sources`` field of the input JSON.
-3. (Optional) The local filesystem, if a root path was explicitly declared via the ``-p`` flag.
 
 See :ref:`searching_for_imports` for more information on Vyper's import system.
 
@@ -121,7 +122,7 @@ Remix IDE
 Compiler Optimization Modes
 ===========================
 
-The vyper CLI tool accepts an optimization mode ``"none"``, ``"codesize"``, or ``"gas"`` (default). It can be set using the ``--optimize`` flag. For example, invoking ``vyper --optimize codesize MyContract.vy`` will compile the contract, optimizing for code size. As a rough summary of the differences between gas and codesize mode, in gas optimized mode, the compiler will try to generate bytecode which minimizes gas (up to a point), including:
+The Vyper CLI tool accepts an optimization mode ``"none"``, ``"codesize"``, or ``"gas"`` (default). It can be set using the ``--optimize`` flag. For example, invoking ``vyper --optimize codesize MyContract.vy`` will compile the contract, optimizing for code size. As a rough summary of the differences between gas and codesize mode, in gas optimized mode, the compiler will try to generate bytecode which minimizes gas (up to a point), including:
 
 * using a sparse selector table which optimizes for gas over codesize
 * inlining some constants, and
@@ -192,11 +193,50 @@ The following is a list of supported EVM versions, and changes in the compiler i
    - Functions marked with ``@nonreentrant`` are protected with TLOAD/TSTORE instead of SLOAD/SSTORE
    - The ``MCOPY`` opcode will be generated automatically by the compiler for most memory operations.
 
+.. _integrity-hash:
+
+Integrity Hash
+==============
+
+To help tooling detect whether two builds are the same, Vyper provides the ``-f integrity`` output, which outputs the integrity hash of a contract. The integrity hash is recursively defined as the sha256 of the source code with the integrity hashes of its dependencies (imports).
+
+.. _vyper-archives:
+
+Vyper Archives
+==============
+
+A Vyper archive is a compileable bundle of input sources and settings. Technically, it is a `ZIP file <https://en.wikipedia.org/wiki/ZIP_(file_format)>`_, with a special structure to make it useable as input to the compiler. It can use any suffix, but the convention is to use a ``.zip`` suffix or ``.vyz`` suffix. It must contain a ``MANIFEST/`` folder, with the following directory structure.
+
+::
+
+    MANIFEST
+    ├── cli_settings.txt
+    ├── compilation_targets
+    ├── compiler_version
+    ├── integrity
+    ├── searchpaths
+    └── settings.json
+
+* ``cli_settings.txt`` is a text representation of the settings that were used on the compilation run that generated this archive.
+* ``compilation_targets`` is a newline separated list of compilation targets. Currently only one compilation is supported
+* ``compiler_version`` is a text representation of the compiler version used to generate this archive
+* ``integrity`` is the :ref:`integrity hash <integrity-hash>` of the input contract
+* ``searchpaths`` is a newline-separated list of the search paths used on this compilation run
+* ``settings.json`` is a json representation of the settings used on this compilation run. It is 1:1 with ``cli_settings.txt``, but both are provided as they are convenient for different workflows (typically, manually vs automated).
+
+A Vyper archive file can be produced by requesting the ``-f archive`` output format. The compiler can also produce the archive in base64 encoded form using the ``--base64`` flag. The Vyper compiler can accept both ``.vyz`` and base64-encoded Vyper archives directly as input.
+
+.. code-block:: bash
+
+    $ vyper -f archive my_contract.vy -o my_contract.vyz  # write the archive to my_contract.vyz
+    $ vyper -f archive my_contract.vy --base64 > my_contract.vyz.b64  # write the archive, as base64-encoded text
+    $ vyper my_contract.vyz  # compile my_contract.vyz
+    $ vyper my_contract.vyz.b64  # compile my_contract.vyz.b64
 
 Compiler Input and Output JSON Description
 ==========================================
 
-Especially when dealing with complex or automated setups, the recommended way to compile is to use :ref:`vyper-json` and the JSON-input-output interface.
+JSON input/output is provided for compatibility with solidity, however, the recommended way is to use the aforementioned :ref:`Vyper archives <vyper-archives>`. So-called "standard json" input can be generated from a contract using the ``vyper -f solc_json`` output format.
 
 Where possible, the Vyper JSON compiler formats follow those of `Solidity <https://solidity.readthedocs.io/en/latest/using-the-compiler.html#compiler-input-and-output-json-description>`_.
 
@@ -205,7 +245,7 @@ Where possible, the Vyper JSON compiler formats follow those of `Solidity <https
 Input JSON Description
 ----------------------
 
-The following example describes the expected input format of ``vyper-json``. Comments are of course not permitted and used here *only for explanatory purposes*.
+The following example describes the expected input format of ``vyper-json``. (Comments are not normally permitted in JSON and are used here for explanatory purposes).
 
 .. code-block:: json
 
@@ -223,10 +263,10 @@ The following example describes the expected input format of ``vyper-json``. Com
             }
         },
         // Optional
-        // Interfaces given here are made available for import by the sources
+        // Sources given here are made available for import by the contracts
         // that are compiled. If the suffix is ".vy", the compiler will expect
-        // a contract-as-interface using proper Vyper syntax. If the suffix is
-        // "abi" the compiler will expect an ABI object.
+        // Vyper syntax. If the suffix is "abi" the compiler will expect an
+        // ABI object.
         "interfaces": {
             "contracts/bar.vy": {
                 "content": ""
@@ -245,6 +285,11 @@ The following example describes the expected input format of ``vyper-json``. Com
             // optional, whether or not the bytecode should include Vyper's signature
             // defaults to true
             "bytecodeMetadata": true,
+            // optional, whether to use the experimental venom pipeline
+            // defaults to false
+            "experimentalCodegen": false,
+            // the search paths to use for resolving imports
+            "search_paths": [],
             // The following is used to select desired outputs based on file names.
             // File names are given as keys, a star as a file name matches all files.
             // Outputs can also follow the Solidity format where second level keys

diff --git a/docs/constants-and-vars.rst b/docs/constants-and-vars.rst
@@ -101,6 +101,6 @@ Custom constants can be defined at a global level in Vyper. To define a constant
     TOTAL_SUPPLY: constant(uint256) = 10000000
     total_supply: public(uint256)
 
-    @external
+    @deploy
     def __init__():
         self.total_supply = TOTAL_SUPPLY
-Original file line number
+Diff line change
@@ Expand Up / @@ -49,4 +49,4 @@ vyper/vyper_git_commithash.txt @@
     *.spec
     # mac
-    .DS_Store
+    .DS_Store