Merge pull request #15721 from ethereum/document-internal-function-pointer-stability-guarantees

Document internal function pointer stability guarantees

Author: cameel

docs/control-structures.rst

@@ -239,6 +239,8 @@ to limit the amount of gas.
 If the creation fails (due to out-of-stack, not enough balance or other problems),
 an exception is thrown.
 
+.. _salted-contract-creations:
+
 Salted contract creations / create2
 -----------------------------------
 

docs/introduction-to-smart-contracts.rst

@@ -537,6 +537,7 @@ operations, loops should be preferred over recursive calls. Furthermore,
 only 63/64th of the gas can be forwarded in a message call, which causes a
 depth limit of a little less than 1000 in practice.
 
+.. _delegatecall:
 .. index:: delegatecall, library
 
 Delegatecall and Libraries

docs/ir-breaking-changes.rst

@@ -258,6 +258,8 @@ hiding new and different behavior in existing code.
 Internals
 =========
 
+.. _internal-function-pointers-in-ir:
+
 Internal function pointers
 --------------------------
 
@@ -276,6 +278,12 @@ The ID ``0`` is reserved for uninitialized function pointers which then cause a
 In the old code generator, internal function pointers are initialized with a special function that always causes a panic.
 This causes a storage write at construction time for internal function pointers in storage.
 
+.. note::
+    The compiler is free to omit internal functions that are never explicitly referenced by name.
+    As a consequence, assigning to a function type variable in inline assembly does not guarantee
+    that the assigned value will be included in the internal dispatch.
+    The function must also be explicitly referenced elsewhere in the code.
+
 Cleanup
 -------
 

docs/security-considerations.rst

@@ -371,6 +371,16 @@ If your ``mapping`` information must be deleted, consider using a library simila
 `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``.
 
+Internal Function Pointers in Upgradeable Contracts
+===================================================
+
+Updating the code of your contract may :ref:`invalidate the values of variables of internal function
+types<function-type-value-stability-across-contract-updates>`.
+Consider such values ephemeral and avoid storing them in state variables.
+If you do, you must ensure that they never persist across code updates and are never used by
+other contracts having access to the same storage space as a result of a delegatecall or account
+abstraction.
+
 Minor Details
 =============
 

docs/types/value-types.rst

@@ -728,7 +728,7 @@ that has the same data representation as the input, whereas ``toUFixed256x18`` r
 Function Types
 --------------
 
-Function types are the types of functions. Variables of function type
+Function types are the types of functions. Variables of a function type
 can be assigned from functions and function parameters of function type
 can be used to pass functions to and return functions from function calls.
 Function types come in two flavours - *internal* and *external* functions:
@@ -743,6 +743,20 @@ contract internally.
 External functions consist of an address and a function signature and they can
 be passed via and returned from external function calls.
 
+Note that public functions of the current contract can be used both as an
+internal and as an external function. To use ``f`` as an internal function,
+just use ``f``, if you want to use its external form, use ``this.f``.
+
+If a function type variable is not initialised, calling it results
+in a :ref:`Panic error<assert-and-require>`. The same happens if you call a function after using ``delete``
+on it.
+
+.. note::
+    Lambda or inline functions are planned but not yet supported.
+
+Declaration syntax
+^^^^^^^^^^^^^^^^^^
+
 Function types are notated as follows:
 
 .. code-block:: solidity
@@ -759,7 +773,8 @@ omitted. Note that this only applies to function types. Visibility has
 to be specified explicitly for functions defined in contracts, they
 do not have a default.
 
-Conversions:
+Conversions
+^^^^^^^^^^^
 
 A function type ``A`` is implicitly convertible to a function type ``B`` if and only if
 their parameter types are identical, their return types are identical,
@@ -788,18 +803,10 @@ Which makes it possible to assign a ``payable`` function pointer to a ``non-paya
 function pointer ensuring both types behave the same way, i.e, both cannot be used
 to send ether.
 
-If a function type variable is not initialised, calling it results
-in a :ref:`Panic error<assert-and-require>`. The same happens if you call a function after using ``delete``
-on it.
-
 If external function types are used outside of the context of Solidity,
 they are treated as the ``function`` type, which encodes the address
 followed by the function identifier together in a single ``bytes24`` type.
 
-Note that public functions of the current contract can be used both as an
-internal and as an external function. To use ``f`` as an internal function,
-just use ``f``, if you want to use its external form, use ``this.f``.
-
 A function of an internal type can be assigned to a variable of an internal function type regardless
 of where it is defined.
 This includes private, internal and public functions of both contracts and libraries as well as free
@@ -828,7 +835,8 @@ Libraries are excluded because they require a ``delegatecall`` and use :ref:`a d
 convention for their selectors <library-selectors>`.
 Functions declared in interfaces do not have definitions so pointing at them does not make sense either.
 
-Members:
+Members
+^^^^^^^
 
 External (or public) functions have the following members:
 
@@ -843,6 +851,59 @@ External (or public) functions have the following members:
   respectively. See :ref:`External Function Calls <external-function-calls>` for
   more information.
 
+.. _function-type-value-stability-across-contract-updates:
+
+Value stability across contract updates
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+An important aspect to consider when using values of function types is whether the value will
+remain valid if the underlying code changes.
+
+The state of the blockchain is not completely immutable and there are multiple ways to place
+different code under the same address:
+
+- Directly deploying different code using :ref:`salted contract creation<salted-contract-creations>`.
+- Delegating to a different contract via :ref:`DELEGATECALL<delegatecall>`
+  (upgradeable code behind a proxy contract is a common example of this).
+- Account abstraction as defined by `EIP-7702 <https://eips.ethereum.org/EIPS/eip-7702>`_.
+
+External function types can be considered as stable as contract's ABI, which makes them very portable.
+Their ABI representation always consists of a contract address and a function selector and it is
+perfectly safe to store them long-term or pass them between contracts.
+While it is possible for the referenced function to change or disappear, a direct external call
+would be affected the same way, so there is no additional risk in such use.
+
+In case of internal functions, however, the value is an identifier that is strongly tied to
+contract's bytecode.
+The actual representation of the identifier is an implementation detail and may change between
+compiler versions or even :ref:`between different backends<internal-function-pointers-in-ir>`.
+Values assigned under a given representation are deterministic (i.e. guaranteed to remain the same
+as long as the source code is the same) but are easily affected by changes such as adding, removing
+or reordering of functions.
+The compiler is also free to remove internal functions that are never used, which may affect other identifiers.
+Some representations, e.g. one where identifiers are simply jump targets, may be affected by
+virtually any change, even one completely unrelated to internal functions.
+
+To counter this, the language limits the use of internal function types outside of the context in
+which they are valid.
+This is why internal function types cannot be used as parameters of external functions (or in any
+other way that is exposed in contract's ABI).
+However, there are still situations where it is up to the user to decide whether their use is safe or not.
+For example long-term storage of such values in state variables is discouraged, but may be safe if
+the contract code is never going to be updated.
+It is also always possible to side-step any safeguards by using inline assembly.
+Such use always needs careful consideration.
+
+.. note::
+    The removal of unused internal functions only takes into account explicit references to
+    such functions by name.
+    Implicit references, such as assigning a new value to a function type variable in inline assembly
+    may still lead to the removal of the function if it is not also referenced explicitly elsewhere
+    in the source.
+
+Examples
+^^^^^^^^
+
 Example that shows how to use the members:
 
 .. code-block:: solidity
@@ -966,6 +1027,3 @@ Another example that uses external function types:
             exchangeRate = response;
         }
     }
-
-.. note::
-    Lambda or inline functions are planned but not yet supported.