Merge pull request #15892 from ethereum/storageLayoutSpecifierDocs

Storage layout specifier docs

Author: ekpyron

docs/contracts.rst

@@ -23,6 +23,7 @@ There is no "cron" concept in Ethereum to call a function at a particular event
 .. include:: contracts/transient-storage.rst
 
 .. include:: contracts/constant-state-variables.rst
+.. include:: contracts/custom-storage-layout.rst
 .. include:: contracts/functions.rst
 
 .. include:: contracts/events.rst

docs/contracts/custom-storage-layout.rst

@@ -0,0 +1,57 @@
+.. index:: ! custom storage layout, ! storage layout specifier, ! layout at, ! base slot
+
+.. _custom-storage-layout:
+
+*********************
+Custom Storage Layout
+*********************
+
+A contract can define an arbitrary location for its storage using the ``layout`` specifier.
+The contract's state variables, including those inherited from base contracts,
+start from the specified base slot instead of the default slot zero.
+
+.. code-block:: solidity
+
+    // SPDX-License-Identifier: GPL-3.0
+    pragma solidity ^0.8.29;
+
+    contract C layout at 0xAAAA + 0x11 {
+        uint[3] x; // Occupies slots 0xAABB..0xAABD
+    }
+
+As the above example shows, the specifier uses the ``layout at <base-slot-expression>`` syntax
+and is located in the header of a contract definition.
+
+The layout specifier can be placed either before or after the inheritance specifier, and can appear at most once.
+The ``base-slot-expression`` must be an :ref:`integer literal<rational_literals>` expression
+that can be evaluated at compilation time and yields a value in the range of ``uint256``.
+
+A custom layout cannot make contract's storage "wrap around".
+If the selected base slot would push the static variables past the end of storage,
+the compiler will issue an error.
+Note that the data areas of dynamic arrays and mappings are not affected by this check because
+their layout is not linear.
+Regardless of the base slot used, their locations are calculated in a way that always puts them
+within the range of ``uint256`` and their sizes are not known at compilation time.
+
+While there are no other limits placed on the base slot, it is recommended to avoid locations that are
+too close to the end of the address space.
+Leaving too little space may complicate contract upgrades or cause problems for contracts that store
+additional values past their allocated space using inline assembly.
+
+The storage layout can only be specified for the topmost contract of an inheritance tree, and
+affects locations of all the storage variables in all the contracts in that tree.
+Variables are laid out according to the order of their definitions and the
+positions of their contracts in the :ref:`linearized inheritance hierarchy<multi-inheritance>`
+and a custom base slot preserves their relative positions, shifting them all by the same amount.
+
+The storage layout cannot be specified for abstract contracts, interfaces and libraries.
+Also, it is important to note that it does *not* affect transient state variables.
+
+For details about storage layout and the effect of the layout specifier on it see
+:ref:`layout of storage variables<storage-inplace-encoding>`.
+
+.. warning::
+    The identifiers ``layout`` and ``at`` are not yet reserved as keywords in the language.
+    It is strongly recommended to avoid using them since they will become reserved in a future
+    breaking release.

docs/internals/layout_in_storage.rst

@@ -34,6 +34,110 @@ by the above rules, state variables from different contracts do share the same s
 The elements of structs and arrays are stored after each other, just as if they were given
 as individual values.
 
+If a contract specifies a :ref:`custom storage layout<custom-storage-layout>`, the slots assigned
+to static storage variables are shifted according the value defined as the layout base.
+Locations of dynamic arrays and mappings are also indirectly affected by this due to shifting
+of the static slots they are based on.
+The custom layout is specified in the most derived contract and, following the order explained
+above, starting from the most base-ward contract's variables, all storage slots are adjusted.
+
+In the following example, contract ``C`` inherits from contracts ``A`` and ``B`` and also
+specifies a custom storage base slot.
+The result is that all storage variable slots of the inheritance tree are adjusted according to
+the value specified by ``C``.
+
+.. code-block:: solidity
+
+    // SPDX-License-Identifier: GPL-3.0
+    pragma solidity ^0.8.29;
+
+    struct S {
+        int32 x;
+        bool y;
+    }
+
+    contract A {
+        uint a;
+        uint128 transient b;
+        uint constant c = 10;
+        uint immutable d = 12;
+    }
+
+    contract B {
+        uint8[] e;
+        mapping(uint => S) f;
+        uint16 g;
+        uint16 h;
+        bytes16 transient i;
+        S s;
+        int8 k;
+    }
+
+    contract C is A, B layout at 42 {
+        bytes21 l;
+        uint8[10] m;
+        bytes5[8] n;
+        bytes5 o;
+    }
+
+In the example, the storage layout starts with the inherited
+state variable ``a`` stored directly inside the base slot (slot ``42``).
+Transient, constant and immutable variables are stored in separate
+locations, and thus, ``b``, ``i``, ``c`` and ``d`` have no effect on the storage layout.
+Then we get to the dynamic array ``e`` and mapping ``f``.
+They both reserve a whole slot whose address will be used to :ref:`calculate<storage-hashed-encoding>`
+the location where their data is actually stored.
+The slot cannot be shared with any other variable, because the resulting addresses must be unique.
+The next two variables, ``g`` and ``h``, need 2 bytes each and can be packed together into
+slot ``45``, at offsets ``0`` and ``2`` respectively.
+Since ``s`` is a struct, its two members are packed contiguously, each taking up 5 bytes.
+Even though they both would still fit in slot ``45``, structs and arrays always start a new slot.
+Therefore, ``s`` is placed in slot ``46`` and the next variable, ``k``, in slot ``47``.
+Base contracts, on the other hand, can share slots with derived ones, so ``l`` does not require an new one.
+Then variable ``m``, which is an array of 10 items, gets into slot ``48`` and takes up 10 bytes.
+``n`` is an array as well, but due to the size of its items, cannot fill its first slot perfectly
+and spills over to the next one.
+Finally, variable ``o`` ends up in slot ``51``, even though it is of the same type as items of ``n``.
+As explained before, variables after structs and arrays always start a new slot.
+
+Putting it all together, the storage and transient storage layouts of contract ``C`` can be illustrated as follows:
+
+- Storage:
+  ::
+
+      42 [aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa]
+      43 [eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee]
+      44 [ffffffffffffffffffffffffffffffff]
+      45 [                            hhgg]
+      46 [                           yxxxx]
+      47 [          lllllllllllllllllllllk]
+      48 [                      mmmmmmmmmm]
+      49 [  nnnnnnnnnnnnnnnnnnnnnnnnnnnnnn]
+      50 [                      nnnnnnnnnn]
+      51 [                           ooooo]
+
+- Transient storage:
+  ::
+
+      00 [iiiiiiiiiiiiiiiibbbbbbbbbbbbbbbb]
+
+Note that the storage specifier affects ``A`` and ``B`` only as a part of ``C``'s inheritance hierarchy.
+When deployed independently, their storage starts at ``0``:
+
+- Storage layout of ``A``:
+  ::
+
+      00 [aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa]
+
+- Storage layout of ``B``:
+  ::
+
+      00 [eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee]
+      01 [ffffffffffffffffffffffffffffffff]
+      02 [                            hhgg]
+      03 [                           yxxxx]
+      04 [                               k]
+
 .. warning::
     When using elements that are smaller than 32 bytes, your contract's gas usage may be higher.
     This is because the EVM operates on 32 bytes at a time. Therefore, if the element is smaller
@@ -463,4 +567,4 @@ Transient Storage Layout
           "numberOfBytes": "32"
         }
       }
-    }
+    }