feat: immutable variables

docs/scoping-and-declarations.rst

@@ -33,6 +33,23 @@ The compiler automatically creates getter functions for all public storage varia
 
 For public arrays, you can only retrieve a single element via the generated getter. This mechanism exists to avoid high gas costs when returning an entire array. The getter will accept an argument to specity which element to return, for example ``data(0)``.
 
+Declaring Immutable Variables
+--------------------------
+
+Variables can be marked as ``immutable`` during declaration:
+
+.. code-block:: python
+
+    DATA: immutable(uint256)
+
+    @external
+    def __init__(_data: uint256):
+        DATA = _data
+
+Variables declared as immutable are similar to constants, except they are assigned a value in the constructor of the contract. Immutable values must be assigned a value at construction and cannot be assigned a value after construction.
+
+The contract creation code generated by the compiler will modify the contract’s runtime code before it is returned by appending all values assigned to immutables to the runtime code returned by the constructor. This is important if you are comparing the runtime code generated by the compiler with the one actually stored in the blockchain.
+
 Tuple Assignment
 ----------------
 

tests/compiler/LLL/test_compile_lll.py

@@ -41,12 +41,13 @@ def test_lll_from_s_expression(get_contract_from_lll):
   (return
     0
     (lll ; just return 32 byte of calldata back
+      0
       (seq
           (calldatacopy 0 4 32)
           (return 0 32)
           stop
         )
-      0)))
+      )))
     """
     abi = [
         {

tests/grammar/vyper.lark

@@ -12,6 +12,7 @@ module: ( DOCSTRING
         | variable_def
         | event_def
         | function_def
+        | immutable_def
         | _NEWLINE )*
 
 
@@ -36,6 +37,10 @@ import: _IMPORT DOT* _import_path [import_alias]
 // NOTE: Temporary until decorators used
 constant_def: NAME ":" "constant" "(" type ")" "=" _expr
 
+// immutable definitions
+// NOTE: Temporary until decorators used
+immutable_def: NAME ":" "immutable" "(" type ")"
+
 variable: NAME ":" type
 // NOTE: Temporary until decorators used
 variable_with_getter: NAME ":" "public" "(" type ")"

tests/parser/features/test_immutable.py

@@ -0,0 +1,100 @@
+import pytest
+
+@pytest.mark.parametrize(
+    "typ,value",
+    [
+        ("uint256", 42),
+        ("int256", -(2 ** 200)),
+        ("int128", -(2 ** 126)),
+        ("address", "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE"),
+        ("bytes32", b"deadbeef" * 4),
+        ("bool", True),
+        ("String[10]", "Vyper hiss"),
+        ("Bytes[10]", b"Vyper hiss"),
+    ],
+)
+def test_value_storage_retrieval(typ, value, get_contract):
+    code = f"""
+VALUE: immutable({typ})
+
+@external
+def __init__(_value: {typ}):
+    VALUE = _value
+
+@view
+@external
+def get_value() -> {typ}:
+    return VALUE
+    """
+
+    c = get_contract(code, value)
+    assert c.get_value() == value
+
+
+def test_multiple_immutable_values(get_contract):
+    code = """
+a: immutable(uint256)
+b: immutable(address)
+c: immutable(String[64])
+
+@external
+def __init__(_a: uint256, _b: address, _c: String[64]):
+    a = _a
+    b = _b
+    c = _c
+
+@view
+@external
+def get_values() -> (uint256, address, String[64]):
+    return a, b, c
+    """
+    values = (3, "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", "Hello world")
+    c = get_contract(code, *values)
+    assert c.get_values() == list(values)
+
+
+def test_struct_immutable(get_contract):
+    code = """
+struct MyStruct:
+    a: uint256
+    b: uint256
+    c: address
+    d: int256
+
+my_struct: immutable(MyStruct)
+
+@external
+def __init__(_a: uint256, _b: uint256, _c: address, _d: int256):
+    my_struct = MyStruct({
+        a: _a,
+        b: _b,
+        c: _c,
+        d: _d
+    })
+
+@view
+@external
+def get_my_struct() -> MyStruct:
+    return my_struct
+    """
+    values = (100, 42, "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", -(2 ** 200))
+    c = get_contract(code, *values)
+    assert c.get_my_struct() == values
+
+
+def test_list_immutable(get_contract):
+    code = """
+my_list: immutable(uint256[3])
+
+@external
+def __init__(_a: uint256, _b: uint256, _c: uint256):
+    my_list = [_a, _b, _c]
+
+@view
+@external
+def get_my_list() -> uint256[3]:
+    return my_list
+    """
+    values = (100, 42, 23230)
+    c = get_contract(code, *values)
+    assert c.get_my_list() == list(values)

tests/parser/syntax/test_immutables.py

@@ -0,0 +1,108 @@
+import pytest
+
+from vyper import compile_code
+
+fail_list = [
+    # VALUE is not set in the constructor
+    """
+VALUE: immutable(uint256)
+
+@external
+def __init__():
+    pass
+    """,
+    # no `__init__` function, VALUE not set
+    """
+VALUE: immutable(uint256)
+
+@view
+@external
+def get_value() -> uint256:
+    return VALUE
+    """,
+    # VALUE given an initial value
+    """
+VALUE: immutable(uint256) = 3
+
+@external
+def __init__():
+    pass
+    """,
+    # setting value outside of constructor
+    """
+VALUE: immutable(uint256)
+
+@external
+def __init__():
+    VALUE = 0
+
+@external
+def set_value(_value: uint256):
+    VALUE = _value
+    """,
+    # modifying immutable multiple times in constructor
+    """
+VALUE: immutable(uint256)
+
+@external
+def __init__(_value: uint256):
+    VALUE = _value * 3
+    VALUE = VALUE + 1
+    """
+
+]
+
+
+@pytest.mark.parametrize("bad_code", fail_list)
+def test_compilation_fails_with_exception(bad_code):
+    with pytest.raises(Exception):
+        compile_code(bad_code)
+
+
+types_list = (
+    "uint256",
+    "int256",
+    "int128",
+    "address",
+    "bytes32",
+    "decimal",
+    "bool",
+    "Bytes[64]",
+    "String[10]",
+)
+
+
+@pytest.mark.parametrize("typ", types_list)
+def test_compilation_simple_usage(typ):
+    code = f"""
+VALUE: immutable({typ})
+
+@external
+def __init__(_value: {typ}):
+    VALUE = _value
+
+@view
+@external
+def get_value() -> {typ}:
+    return VALUE
+    """
+
+    assert compile_code(code)
+
+
+pass_list = [
+    # using immutable allowed in constructor
+    """
+VALUE: immutable(uint256)
+
+@external
+def __init__(_value: uint256):
+    VALUE = _value * 3
+    x: uint256 = VALUE + 1
+    """
+]
+
+
+@pytest.mark.parametrize("good_code", pass_list)
+def test_compilation_success(good_code):
+    assert compile_code(good_code)

vyper/ast/signatures/function_signature.py

@@ -1,5 +1,6 @@
 import math
 from dataclasses import dataclass
+from typing import Optional
 
 from vyper import ast as vy_ast
 from vyper.exceptions import StructureException
@@ -12,7 +13,7 @@
 # TODO move to context.py
 # TODO use dataclass
 class VariableRecord:
-    def __init__(
+    def __init__(  # type: ignore
         self,
         name,
         pos,
@@ -23,6 +24,8 @@ def __init__(
         blockscopes=None,
         defined_at=None,
         is_internal=False,
+        is_immutable=False,
+        data_offset: Optional[int] = None,
     ):
         self.name = name
         self.pos = pos
@@ -33,6 +36,8 @@ def __init__(
         self.blockscopes = [] if blockscopes is None else blockscopes
         self.defined_at = defined_at  # source code location variable record was defined.
         self.is_internal = is_internal
+        self.is_immutable = is_immutable
+        self.data_offset = data_offset  # location in data section
 
     def __repr__(self):
         ret = vars(self)

vyper/compiler/utils.py

@@ -10,7 +10,7 @@ def build_gas_estimates(lll_nodes: LLLnode) -> dict:
         and len(lll_nodes.args) > 0
         and lll_nodes.args[-1].value == "return"
     ):
-        lll_nodes = lll_nodes.args[-1].args[1].args[0]
+        lll_nodes = lll_nodes.args[-1].args[1].args[1]
 
     external_sub = next((i for i in lll_nodes.args if i.value == "with"), None)
     if external_sub:

vyper/lll/compile_lll.py

@@ -291,7 +291,7 @@ def _compile_to_assembly(code, withargs=None, existing_labels=None, break_dest=N
         endcode = mksymbol()
         o.extend([endcode, "JUMP", begincode, "BLANK"])
 
-        lll = _compile_to_assembly(code.args[0], {}, existing_labels, None, 0)
+        lll = _compile_to_assembly(code.args[1], {}, existing_labels, None, 0)
 
         # `append(...)` call here is intentional.
         # each sublist is essentially its own program with its
@@ -303,7 +303,7 @@ def _compile_to_assembly(code, withargs=None, existing_labels=None, break_dest=N
         o.append(lll)
 
         o.extend([endcode, "JUMPDEST", begincode, endcode, "SUB", begincode])
-        o.extend(_compile_to_assembly(code.args[1], withargs, existing_labels, break_dest, height))
+        o.extend(_compile_to_assembly(code.args[0], withargs, existing_labels, break_dest, height))
 
         # COPY the code to memory for deploy
         o.extend(["CODECOPY", begincode, endcode, "SUB"])

vyper/old_codegen/expr.py

@@ -316,6 +316,39 @@ def parse_Name(self):
             return LLLnode.from_list(
                 [obj], typ=BaseType(typ, is_literal=True), pos=getpos(self.expr)
             )
+        elif self.expr._metadata["type"].is_immutable:
+            # immutable variable
+            # need to handle constructor and outside constructor
+            var = self.context.globals[self.expr.id]
+            is_constructor = self.expr.get_ancestor(vy_ast.FunctionDef).get("name") == "__init__"
+            if is_constructor:
+                # store memory position for later access in parser.py in the variable record
+                memory_loc = self.context.new_variable(f"#immutable_{self.expr.id}", var.typ)
+                self.context.global_ctx._globals[self.expr.id].pos = memory_loc
+                # store the data offset in the variable record as well for accessing
+                data_offset = self.expr._metadata["type"].position.offset
+                self.context.global_ctx._globals[self.expr.id].data_offset = data_offset
+
+                return LLLnode.from_list(
+                    memory_loc,
+                    typ=var.typ,
+                    location="memory",
+                    pos=getpos(self.expr),
+                    annotation=self.expr.id,
+                    mutable=True,
+                )
+            else:
+                immutable_section_size = self.context.global_ctx.immutable_section_size
+                offset = self.expr._metadata["type"].position.offset
+                # TODO: resolve code offsets for immutables at compile time
+                return LLLnode.from_list(
+                    ["sub", "codesize", immutable_section_size - offset],
+                    typ=var.typ,
+                    location="code",
+                    pos=getpos(self.expr),
+                    annotation=self.expr.id,
+                    mutable=False,
+                )
 
     # x.y or x[5]
     def parse_Attribute(self):