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

Had to adjust gas costs during merge.

docs/assembly.rst

@@ -163,7 +163,8 @@ If an opcode takes arguments (always from the top of the stack), they are given
 Note that the order of arguments can be seen to be reversed in non-functional style (explained below).
 Opcodes marked with ``-`` do not push an item onto the stack (do not return a result),
 those marked with ``*`` are special and all others push exactly one item onto the stack (their "return value").
-Opcodes marked with ``F``, ``H``, ``B`` or ``C`` are present since Frontier, Homestead, Byzantium or Constantinople, respectively.
+Opcodes marked with ``F``, ``H``, ``B``, ``C`` or ``I`` are present since Frontier, Homestead,
+Byzantium, Constantinople or Istanbul, respectively.
 
 In the following, ``mem[a...b)`` signifies the bytes of memory starting at position ``a`` up to
 but not including position ``b`` and ``storage[p]`` signifies the storage contents at position ``p``.
@@ -259,6 +260,8 @@ In the grammar, opcodes are represented as pre-defined identifiers.
 +-------------------------+-----+---+-----------------------------------------------------------------+
 | balance(a)              |     | F | wei balance at address a                                        |
 +-------------------------+-----+---+-----------------------------------------------------------------+
+| selfbalance()           |     | I | equivalent to balance(address()), but cheaper                   |
++-------------------------+-----+---+-----------------------------------------------------------------+
 | caller                  |     | F | call sender (excluding ``delegatecall``)                        |
 +-------------------------+-----+---+-----------------------------------------------------------------+
 | callvalue               |     | F | wei sent together with the current call                         |
@@ -325,6 +328,8 @@ In the grammar, opcodes are represented as pre-defined identifiers.
 | log4(p, s, t1, t2, t3,  | `-` | F | log with topics t1, t2, t3, t4 and data mem[p...(p+s))          |
 | t4)                     |     |   |                                                                 |
 +-------------------------+-----+---+-----------------------------------------------------------------+
+| chainid                 |     | I | ID of the executing chain (EIP 1344)                            |
++-------------------------+-----+---+-----------------------------------------------------------------+
 | origin                  |     | F | transaction sender                                              |
 +-------------------------+-----+---+-----------------------------------------------------------------+
 | gasprice                |     | F | gas price of the transaction                                    |

docs/security-considerations.rst

@@ -254,6 +254,61 @@ if you want all overflows to cause a revert.
 
 Code such as ``require((balanceOf[_to] + _value) >= balanceOf[_to])`` can also help you check if values are what you expect.
 
+.. _clearing-mappings:
+
+Clearing Mappings
+=================
+
+The Solidity type ``mapping`` (see :ref:`mapping-types`) is a storage-only key-value data structure that
+does not keep track of the keys that were assigned a non-zero value.
+Because of that, cleaning a mapping without extra information about the written
+keys is not possible.
+If a ``mapping`` is used as the base type of a dynamic storage array, deleting
+or popping the array will have no effect over the ``mapping`` elements.
+The same happens, for example, if a ``mapping`` is used as the type of a member
+field of a ``struct`` that is the base type of a dynamic storage array.
+The ``mapping`` is also ignored in assignments of structs or arrays containing
+a ``mapping``.
+
+::
+
+    pragma solidity >=0.5.0 <0.7.0;
+
+    contract Map {
+        mapping (uint => uint)[] array;
+
+        function allocate(uint _newMaps) public {
+            array.length += _newMaps;
+        }
+
+        function writeMap(uint _map, uint _key, uint _value) public {
+            array[_map][_key] = _value;
+        }
+
+        function readMap(uint _map, uint _key) public view returns (uint) {
+            return array[_map][_key];
+        }
+
+        function eraseMaps() public {
+            delete array;
+        }
+    }
+
+Consider the example above and the following sequence of calls: ``allocate(10)``,
+``writeMap(4, 128, 256)``.
+At this point, calling ``readMap(4, 128)`` returns 256.
+If we call ``eraseMaps``, the length of state variable ``array`` is zeroed, but
+since its ``mapping`` elements cannot be zeroed, their information stays alive
+in the contract's storage.
+After deleting ``array``, calling ``allocate(5)`` allows us to access
+``array[4]`` again, and calling ``readMap(4, 128)`` returns 256 even without
+another call to ``writeMap``.
+
+If your ``mapping`` information must be deleted, consider using a library similar to
+`iterable mapping <https://github.com/ethereum/dapp-bin/blob/master/library/iterable_mapping.sol>`_,
+allowing you to traverse the keys and delete their values in the appropriate
+``mapping``.
+
 Minor Details
 =============
 

docs/types/mapping-types.rst

@@ -17,7 +17,8 @@ byte-representation is all zeros, a type's :ref:`default value <default-value>`.
 mapping, only its ``keccak256`` hash is used to look up the value.
 
 Because of this, mappings do not have a length or a concept of a key or
-value being set.
+value being set, and therefore cannot be erased without extra information
+regarding the assigned keys (see :ref:`clearing-mappings`).
 
 Mappings can only have a data location of ``storage`` and thus
 are allowed for state variables, as storage reference types

docs/using-the-compiler.rst

@@ -122,7 +122,8 @@ at each version. Backward compatibility is not guaranteed between each version.
    - Shifting operators use shifting opcodes and thus need less gas.
 - ``petersburg`` (**default**)
    - The compiler behaves the same way as with constantinople.
-- ``istanbul`` (**experimental**)
+- ``istanbul``
+   - Opcodes ``chainid`` and ``selfbalance`` are available in assembly.
 - ``berlin`` (**experimental**)