Rollback safety limits when an upgraded Solidity contract changes its storage layout

Rollback Safety Limits

Append-only layout changes are the primary condition for rollback safety. If V2 only adds state variables to the end of the storage layout, rolling back to V1 is safe because the V1 bytecode simply ignores the higher-indexed slots written by V2. However, this is not a complete guarantee of safety; structural changes to the contract hierarchy or type modifications can still break rollback compatibility.

Likely Explanations and Edge Cases

While adding variables is generally safe, the following scenarios can cause V1 to misinterpret state after a rollback from V2:

• Inheritance Shifts: Changing the order of base contracts or adding a new base contract in the middle of the inheritance chain shifts the starting slot of all subsequent child variables. V1 will read the wrong slots for its variables.
• Type Mutations: Changing a variable's type (e.g., uint256 to uint128) in V2 may cause V1 to read overlapping or corrupted data if the packing logic changed.
• Struct Modifications: Adding a field to the middle of a struct shifts all subsequent fields within that struct's storage area.
• Mapping/Array Collisions: While mappings use hashed slots and are generally safe, changing the type of a mapping key or value in V2 will cause V1 to read the data incorrectly upon rollback.

Validation and Gap Management

The OpenZeppelin Upgrades plugin is designed to validate forward compatibility (V1 $\rightarrow$ V2). It does not provide a native "downgrade" validation tool. To verify rollback safety, you must manually compare the storage layouts.

Regarding __gap arrays: Shrinking a gap is the correct way to add variables to a base contract without shifting child layouts. If a base contract has a uint256[50] __gap and you add two uint256 variables, you must reduce the gap to uint256[48]. This ensures the total slot count for the base contract remains constant, keeping child contract offsets stable across both V1 and V2.

Verification Steps

1. Compare Layouts: Use the Solidity compiler to generate and compare the JSON storage maps for both versions:

   solc --storage-layout ContractV1.sol
   solc --storage-layout ContractV2.sol

2. State-Change Test: Deploy V1 to a local network, upgrade to V2, write data to the new V2 variables, and then point the proxy back to the V1 implementation. Verify that V1's original variables remain intact and readable.

Diagnostic Detail Needed: Does your V2 upgrade involve changing the inheritance order or adding new base contracts? If so, append-only variable additions will not be sufficient to ensure rollback safety.