Storage layout specifier docs

Author: matheusaaguiar

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,50 @@
+.. index:: ! custom storage layout, ! storage layout specifier, ! layout at, ! base slot
+
+.. _custom-storage-layout:
+
+*********************
+Custom Storage Layout
+*********************
+
+Contracts can define an arbitrary base slot for its own storage.
+The contract's state variables, including those inherited from base contracts,
+will be stored from the specified 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 0xABCD + 0x1234 { }
+
+As the previous example shows, this can be done by using ``layout at <base-slot-expression>``
+in the header of a contract definition.
+
+The layout specifier can be placed either before or after the inheritance specifier, and at most once.
+The ``base-slot-expression`` must be an :ref:`integer literal<rational_literals>` expression
+that can be evaluated at compile time and yield a value in the range of ``uint256``.
+
+In the case of a custom storage layout specification which places the contract near the storage end,
+the number of slots available for static objects is determined by ``max storage size - base slot`` and
+the compiler can detect whether the contract extends past the end.
+For dynamic typed variables, they are allocated in random locations of the storage, including those before
+the layout base slot.
+It is also important to mention that, in cases where the contract is near the end of storage, there are
+risks related to upgradeability and inline assembly access beyond allocated space.
+
+The location of a contract's state variable is determined by its position in the hierarchy tree.
+Inherited variables will be stored before the state variables declared by the contract itself and
+that changes the slots where they should be placed.
+Similarly, when a contract specifies a custom storage layout, not only its own storage variables are shifted,
+but also all other variables from contracts in the same inheritance tree.
+Thus, the storage layout can only be specified at the top most contract of the inheritance tree, assuring
+that all contracts of the tree have their layout base properly adjusted.
+
+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.
+
+Further details are explained later when :ref:`layout of storage variables<storage-inplace-encoding>` are described.
+
+.. warning::
+    The identifiers ``layout`` and ``at`` are not reserved keywords of the Solidity language, but
+    it is strongly recommended to avoid using them since that may change in the future.

docs/internals/layout_in_storage.rst

@@ -34,6 +34,61 @@ 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 which
+the state variables occupy are shifted according the value defined as the layout base.
+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 variable storage slots of the inheritance tree will be 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 a;
+        bool b;
+    }
+
+    contract A {
+        uint x;
+        uint transient y;
+        uint constant w = 10;
+        uint immutable z = 12;
+    }
+
+    contract B {
+        uint16 i;
+        uint16 j;
+        S s;
+        int8 k;
+    }
+
+    contract C is A, B layout at 42 {
+        uint8[10] register;
+        bool flag;
+    }
+
+In the example, the storage layout starts with the inherited
+state variable ``x`` stored at the specified base slot ``42``.
+Transient, constant and immutable variables are stored in separate
+locations and, thus, ``y``, ``w`` and ``z``don't interfere with the layout.
+The next variables ``i`` and ``j`` need 2 bytes each and can be packed in
+the next slot ``43``, at offsets ``0`` and ``2`` respectively.
+Since ``s`` is a struct, its two members are packed contiguously, demanding
+both 5 bytes.
+Even though they still could fit in slot ``43``, structs and static arrays
+always start a new slot as well as any other item after them.
+So, according to that ``s`` is placed at slot ``44`` and the next variable,
+``k`` at slot ``45``.
+Then, variable ``register`` which is an array of 10 positions, starts at slot ``46``
+and demands 80 bytes. Finally, variable, ``flag``, start at slot ``47``, because,
+as explained before, variables after structs and arrays always start a new slot.
+
 .. 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