Storage layout в Solidity — это правило, по которому компилятор раскладывает переменные контракта по 32-байтным storage-слотам Ethereum. Если вы используете прокси-архитектуру (апгрейдируемые контракты), storage layout — главный источник катастроф: вы обновляете логику (implementation), но хранилище остаётся прежним. Если новая версия ожидает “другую раскладку”, вы получаете storage collision — ситуация, когда одна переменная начинает читать/писать в слот другой переменной. Итог может быть любым: от “сломались балансы” до “пользователь стал админом”.

Связанные страницы: storage layout (детально), памятка/чек-лист storage layout, риски DELEGATECALL и прокси.

1) Что такое storage в EVM и как компилятор кладёт данные

1.1 Storage-слот = 32 байта

Storage в EVM — это “постоянная память” контракта. Она адресуется слотами по 32 байта. Простая интуиция:

• каждая переменная (или её часть) в итоге оказывается в одном или нескольких слотах;
• мелкие типы могут упаковываться (packing) в один слот, если стоят подряд;
• динамические структуры (mapping, dynamic array, string/bytes) используют хэш-адресацию в storage.

1.2 Почему layout “приклеивается” навсегда в прокси

В прокси-паттернах (Transparent/UUPS и т.п.) прокси хранит состояние в своём storage и делегирует выполнение кода в implementation через DELEGATECALL. Это значит:

• код меняется (implementation),
• storage остаётся на месте (в прокси),
• а чтение/запись storage в новой версии происходит по тем же номерам слотов.

Если новая версия изменила порядок/типы/наследование так, что переменные “съехали” — код начнёт интерпретировать старые данные как новые переменные. Это и есть причина, почему апгрейды “убиваются” layout-ошибками.

2) Базовая модель: что можно менять, а что почти всегда нельзя

Ниже — не “юридические” правила, а практический опыт того, что ломает апгрейды чаще всего.

2.1 Почти всегда нельзя (классические причины storage collision)

• Удалять переменные из середины (или из базового контракта в наследовании).
• Менять порядок существующих переменных.
• Менять тип переменной (например, uint256 → uint128, address → bytes32 и т.п.).
• Менять структуру наследования, если это сдвигает слоты (переставлять базовые контракты местами).
• Вставлять новую переменную “в середину” между уже существующими (даже если кажется, что “место есть”).

2.2 Обычно можно (если понимать упаковку и наследование)

• Добавлять новые переменные в конец (после всех существующих) — самый безопасный путь.
• Добавлять новые поля в конец struct — осторожно, но обычно допустимо, если struct хранится в storage как единая структура и вы понимаете, где он используется (особенно если struct — значение в mapping или элемент массива).
• Добавлять новые функции/ивенты — не влияет на storage layout, если не добавляете новые state-переменные.

3) Упаковка (packing): почему “я добавил bool и всё сломалось”

Solidity умеет упаковывать переменные меньших типов в один слот, если они стоят рядом. Пример: несколько uint128 или bool/uint8 подряд могут попасть в один слот.

Это создаёт тонкую ловушку апгрейдов:

• вы думаете, что “добавили маленькую переменную”,
• а компилятор перераспределил упаковку,
• и часть битов “старой” переменной теперь читается как другая.

Поэтому правило “добавлять только в конец” должно применяться с учётом упаковки: добавление в конец безопаснее, чем добавление между мелкими типами, но всё равно нужно проверять layout-компиляцией.

4) Mapping, динамические массивы и строки: почему они обычно “стабильнее”

Динамические структуры (mapping, dynamic array, bytes/string) используют хэш-слоты: “база” лежит в одном слоте, а элементы — по вычисляемым адресам (через keccak256). Это делает их устойчивее к “сдвигу” внутренних элементов при апгрейдах, но есть нюансы:

• если вы меняете тип значения в mapping (например, mapping(address => uint256) → mapping(address => struct)), это может сломать интерпретацию уже записанных данных;
• если вы меняете struct, который лежит в mapping — данные старых полей должны оставаться по прежним слотам, а новые поля добавляются в конец struct.

То есть “stable” — не значит “можно всё”. Это значит, что у структуры есть предсказуемая адресация, но совместимость формата данных всё равно критична.

5) Прокси-слоты и EIP-1967: почему нельзя хранить implementation в обычной переменной

В прокси-паттернах есть специальные слоты (часто по EIP-1967) для адреса implementation и админа. Они выбираются так, чтобы не пересекаться со “слотами переменных” вашей логики.

Практический вывод:

• нельзя “изобретать свой прокси” без понимания reserved slots;
• нельзя хранить служебные адреса в обычных state-переменных, если это меняет layout при апгрейдах;
• нельзя смешивать разные прокси-стандарты, если вы не уверены, как они резервируют слоты.

6) Gap-паттерн: зачем в upgradeable контрактах “пустые массивы”

В upgradeable контрактах часто встречается “storage gap” — зарезервированный массив, например:

uint256[50] private __gap;

Идея простая: вы заранее оставляете “свободные слоты”, чтобы в будущих версиях можно было добавлять переменные в пределах этого запаса, не меняя layout наследования и не рискуя сдвигом в базовых контрактах.

Это особенно актуально, когда у вас сложное наследование и вы хотите безопасно добавлять поля на разных уровнях иерархии.

7) Самые частые сценарии “убийства апгрейда” (и как их распознать)

8) Чек-лист безопасного апгрейда (для команды и аудита)

• Добавляю state-переменные только в конец (и осознанно отношусь к packing).
• Не меняю типы/порядок/наследование существующих переменных.
• Проверяю storage layout до деплоя (diff layout старой и новой версии компиляцией).
• Initializer закрыт и корректно версионируется (reinitializer при необходимости).
• Апгрейд защищён: кто может апгрейдить, есть ли задержка, есть ли пауза.
• Тестирую миграции состояния на форке/тестнете: старый state → апгрейд → проверка инвариантов.
• Документирую изменения и фиксирую версию layout как часть релиза.

FAQ

Полезные ссылки

• Storage layout в Solidity: детальный разбор
• Памятка: storage layout и безопасные апгрейды
• DELEGATECALL и риски прокси
• Как читать аудит смарт-контракта