Merge remote-tracking branch 'origin/develop' into breaking

docs/contracts/constant-state-variables.rst

@@ -1,11 +1,49 @@
 .. index:: ! constant
 
-************************
-Constant State Variables
-************************
+**************************************
+Constant and Immutable State Variables
+**************************************
 
-State variables can be declared as ``constant``. In this case, they have to be
-assigned from an expression which is a constant at compile time. Any expression
+State variables can be declared as ``constant`` or ``immutable``.
+In both cases, the variables cannot be modified after the contract has been constructed.
+For ``constant`` variables, the value has to be fixed at compile-time, while
+for ``immutable``, it can still be assigned at construction time.
+
+The compiler does not reserve a storage slot for these variables, and every occurrence is
+replaced by the respective value.
+
+Not all types for constants and immutables are implemented at this time. The only supported types are
+`strings <strings>`_ (only for constants) and `value types <value-types>`_.
+
+::
+
+    pragma solidity >0.6.4 <0.7.0;
+
+    contract C {
+        uint constant X = 32**22 + 8;
+        string constant TEXT = "abc";
+        bytes32 constant MY_HASH = keccak256("abc");
+        uint immutable decimals;
+        uint immutable maxBalance;
+        address immutable owner = msg.sender;
+
+        constructor(uint _decimals, address _reference) public {
+            decimals = _decimals;
+            // Assignments to immutables can even access the environment.
+            maxBalance = _reference.balance;
+        }
+
+        function isBalanceTooHigh(address _other) public view returns (bool) {
+            return _other.balance > maxBalance;
+        }
+    }
+
+
+Constant
+========
+
+For ``constant`` variables, the value has to be a constant at compile time and it has to be
+assigned where the variable is declared. Any expression
 that accesses storage, blockchain data (e.g. ``now``, ``address(this).balance`` or
 ``block.number``) or
 execution data (``msg.value`` or ``gasleft()``) or makes calls to external contracts is disallowed. Expressions
@@ -18,18 +56,17 @@ The reason behind allowing side-effects on the memory allocator is that it
 should be possible to construct complex objects like e.g. lookup-tables.
 This feature is not yet fully usable.
 
-The compiler does not reserve a storage slot for these variables, and every occurrence is
-replaced by the respective constant expression (which might be computed to a single value by the optimizer).
+Immutable
+=========
 
-Not all types for constants are implemented at this time. The only supported types are
-value types and strings.
+Variables declared as ``immutable`` are a bit less restricted than those
+declared as ``constant``: Immutable variables can be assigned an arbitrary
+value in the constructor of the contract or at the point of their declaration.
+They cannot be read during construction time and can only be assigned once.
 
-::
-
-    pragma solidity >=0.4.0 <0.8.0;
-
-    contract C {
-        uint constant X = 32**22 + 8;
-        string constant TEXT = "abc";
-        bytes32 constant MY_HASH = keccak256("abc");
-    }
+The contract creation code generated by the compiler will modify the
+contract's runtime code before it is returned by replacing all references
+to immutables by the values assigned to the them. This is important if
+you are comparing the
+runtime code generated by the compiler with the one actually stored in the
+blockchain.