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,38 @@ 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``.
+So, the inherited state variable ``x`` will be stored at the base slot ``0x1234``, followed by
+``y`` and ``map`` and terminating with ``flag``.
+Notice that, although their storage slots changes, their position in relation to each other
+remains the same, following the C3-linearized order.
+
+.. code-block:: solidity
+
+    // SPDX-License-Identifier: GPL-3.0
+    pragma solidity ^0.8.29;
+
+    contract A {
+        uint x;
+    }
+
+    contract B {
+        address payable y;
+        mapping (address => bool) public map;
+    }
+
+    contract C is A, B layout at 0x1234 {
+        bool flag;
+    }
+
 .. 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