Storage layout specifier docs #15892

matheusaaguiar · 2025-02-26T15:51:47Z

cameel · 2025-02-27T16:26:49Z

docs/contracts/storage-layout-specifier.rst

Layout of State Variables in Storage and Transient Storage should mention the specifier.

It should also say what happens when the base slot is close to the end of storage:

The compiler can detect collisions for things of static size and that dynamically sized stuff gets placed at random locations (so collisions are no more likely than at zero base slot)

Risks for upgradeability and inline assembly access beyond allocated space when things are placed at the very end.

docs/contracts/storage-layout-specifier.rst

cameel · 2025-02-27T16:58:48Z

docs/contracts/storage-layout-specifier.rst

+Contracts can define an arbitrary base slot for its own storage.
+The contract's state variables will be stored from the specified slot
+instead of the default slot zero.
+This can be done by using ``layout at <base-slot-expression>`` in the header of
+a contract definition, either after or before the inheritance specifier.
+It can be given at most once.
+The ``base-slot-expression`` must be an expression consisting of number literals
+that can be evaluated at compile time and yield in a rational value in the range of ``uint256``.
+As a general rule, any expression that can be used to specify the size of an array
+may also be used to indicate a slot.
+The layout of a contract without an explicit specification is identical to one with ``layout at 0``.
+The storage layout cannot be specified for abstract contracts, interfaces and libraries.
+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.


Please split this into paragraphs. Currently this will all render as one big clump of text, which will only grow as we keep adding more info (remember that the current implementation is very limited and will be extended).

I'd also start with a paragraph that gives as quick gist of the feature and an example. Only below that I'd add layers of detail: exact syntax, where it can be used, what expressions are allowed, behavior in corner cases.

Finally, minor details, like whether the identifiers are reserved should go into some note at the very end, because it's almost at the level of implementation detail and irrelevant to most users.

Please also comment in #14770 that this bit will have to be updated once we make layout and at keywords.

Finally, minor details, like whether the identifiers are reserved should go into some note at the very end, because it's almost at the level of implementation detail and irrelevant to most users.

Given that we are planning to make them reserved keywords, I'd even say we should put it in a warning, and not a note.

I've used a note, but no problem changing to a warning.
Not sure what should be.

I guess a warning is better, actually.

docs/contracts/storage-layout-specifier.rst

cameel · 2025-02-27T17:59:08Z

docs/contracts/storage-layout-specifier.rst

+In the next example, contract ``C`` inherits from contracts ``A`` and ``B``
+and also specifies a custom storage base slot. So, inherited state variables,
+starting from the top level contract ``A`` will be stored from slot ``42``.
+Thus, state variable ``y``, for instance, will be at slot ``43``, while
+state variable ``flag`` will be at slot ``45``.
+
+.. code-block:: solidity
+
+    // SPDX-License-Identifier: GPL-3.0
+    pragma solidity >=0.8.29 <0.9.0;
+    contract A {
+        uint x;
+    }
+
+    contract B {
+        address payable y;
+        mapping (address => bool) public map;
+    }
+
+    contract C is A, B layout at 0x1234 {
+        bool flag;
+    }


The details of how variables are laid out in presence of inheritance and how the layout specifier affects them should be explained in Layout of State Variables in Storage and Transient Storage. Here we should just generally say how it works and link to those details.

I see you moved it but did not add a link.

docs/contracts/storage-layout-specifier.rst

docs/contracts.rst

docs/contracts/storage-layout-specifier.rst

cameel · 2025-02-27T18:31:48Z

Please link to the issue in PR description.

nikola-matic · 2025-03-03T12:59:43Z

docs/contracts/storage-layout-specifier.rst

+Contracts can define an arbitrary base slot for its own storage.
+The contract's state variables will be stored from the specified slot
+instead of the default slot zero.
+This can be done by using ``layout at <base-slot-expression>`` in the header of
+a contract definition, either after or before the inheritance specifier.
+It can be given at most once.
+The ``base-slot-expression`` must be an expression consisting of number literals
+that can be evaluated at compile time and yield in a rational value in the range of ``uint256``.
+As a general rule, any expression that can be used to specify the size of an array
+may also be used to indicate a slot.
+The layout of a contract without an explicit specification is identical to one with ``layout at 0``.
+The storage layout cannot be specified for abstract contracts, interfaces and libraries.
+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.


Finally, minor details, like whether the identifiers are reserved should go into some note at the very end, because it's almost at the level of implementation detail and irrelevant to most users.

Given that we are planning to make them reserved keywords, I'd even say we should put it in a warning, and not a note.

docs/contracts/storage-layout-specifier.rst

nikola-matic · 2025-03-03T13:07:17Z

docs/contracts/storage-layout-specifier.rst

+a contract definition, either after or before the inheritance specifier.
+It can be given at most once.
+The ``base-slot-expression`` must be an expression consisting of number literals
+that can be evaluated at compile time and yield in a rational value in the range of ``uint256``.


Perhaps another section describing that the max number of available storage slots will be (uint256::max - user defined base slot address + 1), and that a revert will be triggered in case an attempt is made to exceed the maximum number of available slots.

Not a revert. A compilation error.

Co-authored-by: Kamil Śliwak <[email protected]> Co-authored-by: Nikola Matić <[email protected]>

cameel · 2025-03-05T13:51:26Z

docs/internals/layout_in_storage.rst

Note that this page still says that the storage always starts at zero:

Except for dynamically-sized arrays and mappings (see below), data is stored contiguously item after item starting with the first state variable, which is stored in slot ``0``. For each variable,

Please also check if there's anything in the rest of the text that needs updating too.

nikola-matic · 2025-03-05T13:49:48Z

docs/contracts/custom-storage-layout.rst

+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 given at most once and can be either after or before the inheritance specifier.


Suggested change

The layout specifier can given at most once and can be either after or before the inheritance specifier.

The layout specifier can be placed either before or after the inheritance specifier, and at most once.

nikola-matic · 2025-03-05T13:51:21Z

docs/contracts/custom-storage-layout.rst

+
+The layout specifier can given at most once and can be either after or before the inheritance specifier.
+The ``base-slot-expression`` must be an :ref:`integer literal<rational_literals>` expression
+that can be evaluated at compile time and yield in a value in the range of ``uint256``.


Suggested change

that can be evaluated at compile time and yield in a value in the range of ``uint256``.

that can be evaluated at compile time and yield a value in the range of ``uint256``.

Could even change to must yield a value in the range of uint256, otherwise a compilation error will occur.

nikola-matic · 2025-03-05T13:51:35Z

docs/contracts/custom-storage-layout.rst

+The ``base-slot-expression`` must be an :ref:`integer literal<rational_literals>` expression
+that can be evaluated at compile time and yield in a value in the range of ``uint256``.
+
+In the case of a a custom storage layout specification which places the contract near the storage end,


Suggested change

In the case of a a custom storage layout specification which places the contract near the storage end,

In the case of a custom storage layout specification which places the contract near the storage end,

nikola-matic · 2025-03-05T13:56:59Z

docs/contracts/custom-storage-layout.rst

+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.
+
+.. note::


Promote to warning? We're almost certainly going to reserve these for 0.9.0.

cameel · 2025-03-05T14:01:20Z

docs/internals/layout_in_storage.rst

+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 inherent 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;
+    }


It's a bit odd to add an example that addresses just the storage layout and nothing else. I think it would be better to have one that shows most the elements described above. I'd add more variables to it and after just show what the resulting storage slots, offsets and sizes are.

The example should incorporate:

storage, transient storage, constants and immutables live in separate spaces

packing

arrays and structs start a new slot and items after them as well

elements of structs/arrays

inherited variables are packed too

multiple inheritance

custom layout

matheusaaguiar added the documentation 📖 label Feb 26, 2025

matheusaaguiar added this to the 0.8.29 milestone Feb 26, 2025

matheusaaguiar marked this pull request as draft February 26, 2025 15:52

matheusaaguiar force-pushed the storageLayoutSpecifierDocs branch from 50ba958 to 88792ee Compare February 26, 2025 17:14

matheusaaguiar self-assigned this Feb 26, 2025

cameel requested changes Feb 27, 2025

View reviewed changes

matheusaaguiar mentioned this pull request Feb 27, 2025

Support for arbitrary contract storage base location #15727

Open

nikola-matic reviewed Mar 3, 2025

View reviewed changes

matheusaaguiar and others added 2 commits March 4, 2025 18:49

Storage layout specifier docs

aaf10b1

Apply suggestions from code review

74f84d3

Co-authored-by: Kamil Śliwak <[email protected]> Co-authored-by: Nikola Matić <[email protected]>

matheusaaguiar force-pushed the storageLayoutSpecifierDocs branch from 803a4b2 to 74f84d3 Compare March 4, 2025 21:49

fixup! Apply suggestions from code review

8c93ccf

cameel reviewed Mar 5, 2025

View reviewed changes

nikola-matic reviewed Mar 5, 2025

View reviewed changes

cameel reviewed Mar 5, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Storage layout specifier docs #15892

Storage layout specifier docs #15892

matheusaaguiar commented Feb 26, 2025 •

edited by cameel

Loading

cameel Feb 27, 2025

cameel Feb 27, 2025

cameel Feb 27, 2025 •

edited

Loading

cameel Feb 27, 2025

nikola-matic Mar 3, 2025

matheusaaguiar Mar 4, 2025

matheusaaguiar Mar 4, 2025

cameel Feb 27, 2025

cameel Mar 5, 2025

cameel commented Feb 27, 2025

nikola-matic Mar 3, 2025

nikola-matic Mar 3, 2025

cameel Mar 5, 2025

cameel Mar 5, 2025 •

edited

Loading

nikola-matic Mar 5, 2025

nikola-matic Mar 5, 2025

nikola-matic Mar 5, 2025

nikola-matic Mar 5, 2025

cameel Mar 5, 2025

	The layout specifier can given at most once and can be either after or before the inheritance specifier.
	The layout specifier can be placed either before or after the inheritance specifier, and at most once.

	that can be evaluated at compile time and yield in a value in the range of ``uint256``.
	that can be evaluated at compile time and yield a value in the range of ``uint256``.

	In the case of a a custom storage layout specification which places the contract near the storage end,
	In the case of a custom storage layout specification which places the contract near the storage end,

Storage layout specifier docs #15892

Are you sure you want to change the base?

Storage layout specifier docs #15892

Conversation

matheusaaguiar commented Feb 26, 2025 • edited by cameel Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cameel Feb 27, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cameel commented Feb 27, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cameel Mar 5, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

matheusaaguiar commented Feb 26, 2025 •

edited by cameel

Loading

cameel Feb 27, 2025 •

edited

Loading

cameel Mar 5, 2025 •

edited

Loading