Preventing Storage Collision in Solidity Upgradeable Contracts

What storage collision means

In Solidity, contract state variables are assigned to storage slots in declaration order. For a normal contract, that layout is fixed at deployment. For an upgradeable system, however, the proxy keeps the state while the implementation contract can change. If a new implementation declares variables in a different order, inserts a variable in the middle, or changes inheritance structure, the same storage slots may be interpreted differently.

That is storage collision: two different variables reading from or writing to the same slot.

Why it is dangerous

A collision can cause:

• owner becoming a token balance
• a boolean flag overwriting a mapping pointer
• a new variable silently corrupting old state
• an upgrade that appears successful but breaks core invariants

The worst part is that these failures are often not obvious immediately. The contract may still compile and deploy, but its runtime behavior becomes incorrect.

How Solidity assigns storage slots

Solidity stores value types sequentially, packing smaller values into the same 32-byte slot when possible. Dynamic types such as mappings, arrays, and strings use derived storage locations. In upgradeable contracts, the exact layout matters because the proxy always reads and writes the same storage space.

Consider this simplified contract:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

contract VaultV1 {
    address public owner;      // slot 0
    uint256 public totalDeposits; // slot 1
    bool public paused;        // slot 2 (packed depending on layout)
}

If a later version changes the order:

contract VaultV2 {
    uint256 public totalDeposits; // now slot 0
    address public owner;         // now slot 1
    bool public paused;           // now slot 2
}

The proxy still points to the same storage, but the new implementation interprets the old data differently. The old owner value is now read as totalDeposits, and the old totalDeposits becomes owner. That is a catastrophic collision.

Common causes of storage collision

1. Reordering variables

Changing the order of state variables is the most direct way to break layout compatibility.

2. Inserting variables in the middle

Adding a new variable before existing ones shifts all later slots.

3. Changing inheritance order

Base contracts contribute storage too. Reordering inherited contracts can change the final layout.

4. Modifying variable types

Changing uint128 to uint256, or address to bytes32, changes packing and slot usage.

5. Adding state to upgradeable base contracts

If a base contract is reused across multiple implementations, adding new state there can affect every child contract.

6. Using unstructured storage incorrectly

Manual slot management can be safe, but only if slot keys are unique and stable. Poorly chosen constants can collide with other libraries or modules.

A practical example of a broken upgrade

Suppose you deploy a proxy for a simple staking contract.

Version 1

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

contract StakingV1 {
    address public admin;
    uint256 public rewardRate;
    mapping(address => uint256) public stakes;

    function initialize(address _admin, uint256 _rewardRate) external {
        require(admin == address(0), "already initialized");
        admin = _admin;
        rewardRate = _rewardRate;
    }

    function stake(uint256 amount) external {
        stakes[msg.sender] += amount;
    }
}

Later, a developer adds a new variable at the top.

Version 2

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

contract StakingV2 {
    bool public emergencyMode;     // new slot added first
    address public admin;
    uint256 public rewardRate;
    mapping(address => uint256) public stakes;

    function setEmergencyMode(bool enabled) external {
        emergencyMode = enabled;
    }
}

Because emergencyMode is inserted before admin, the old admin value is now interpreted as a boolean, and the old rewardRate becomes the new admin. The contract may still function in a limited sense, but its state is corrupted.

Safe patterns for upgradeable storage

The main defense is to make storage layout changes predictable and append-only.

1. Append new variables only

When adding state in a new version, place new variables after all existing ones.

contract StakingV2Safe {
    address public admin;
    uint256 public rewardRate;
    mapping(address => uint256) public stakes;

    bool public emergencyMode; // appended safely
}

This preserves the original slot assignments.

2. Reserve storage gaps

A common pattern is to reserve unused slots for future variables. This allows you to add fields later without shifting existing layout.

contract StakingV1WithGap {
    address public admin;
    uint256 public rewardRate;
    mapping(address => uint256) public stakes;

    uint256[50] private __gap;
}

Later versions can consume part of the gap:

contract StakingV2WithGap {
    address public admin;
    uint256 public rewardRate;
    mapping(address => uint256) public stakes;

    bool public emergencyMode;
    uint256[49] private __gap;
}

The gap size decreases as new variables are added.

3. Keep inheritance order stable

If your contract uses multiple inheritance, do not reorder base contracts between versions unless you fully understand the resulting layout.

4. Prefer composition over deep inheritance

Complex inheritance trees make layout harder to reason about. Smaller, flatter contracts are easier to upgrade safely.

5. Use dedicated storage libraries for complex systems

For modular protocols, use namespaced storage patterns so each module owns a fixed storage slot. This is especially useful for diamond-style architectures or large systems with many facets.

Storage gap vs namespaced storage

Both approaches reduce collision risk, but they solve different problems.

When to use a storage gap

Use a storage gap when you expect incremental upgrades to a single contract family, such as a token, vault, or governance module.

When to use namespaced storage

Use namespaced storage when multiple modules may evolve independently and you want to avoid accidental overlap between them.

Example: namespaced storage with a fixed slot

A common pattern is to store all module state in a struct located at a unique slot.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

library VaultStorage {
    bytes32 internal constant STORAGE_SLOT =
        keccak256("example.vault.storage.v1");

    struct Layout {
        address admin;
        uint256 rewardRate;
        bool emergencyMode;
    }

    function layout() internal pure returns (Layout storage l) {
        bytes32 slot = STORAGE_SLOT;
        assembly {
            l.slot := slot
        }
    }
}

contract Vault {
    function setAdmin(address newAdmin) external {
        VaultStorage.Layout storage s = VaultStorage.layout();
        s.admin = newAdmin;
    }

    function admin() external view returns (address) {
        return VaultStorage.layout().admin;
    }
}

This pattern keeps all vault state under one explicit slot namespace. If another module uses a different storage slot constant, the two cannot collide accidentally.

Best practices for safe upgrades

Treat storage layout as part of the public interface

Even though storage is not exposed in the ABI, it is part of the contract’s upgrade contract. Any change to layout should be reviewed as carefully as an external function change.

Freeze variable order after deployment

Once a contract is live behind a proxy, never reorder or remove state variables in existing storage regions.

Add new variables only at the end

This is the simplest and safest rule for most projects.

Avoid changing types in place

If a variable needs a new type, introduce a new variable and migrate data explicitly in an upgrade function.

Audit inherited storage carefully

Base contracts, abstract contracts, and imported modules all contribute to the final layout. Review the entire inheritance tree, not just the child contract.

Use automated storage layout checks

Modern tooling can compare storage layouts between versions and flag incompatible changes before deployment. Make layout checks part of CI.

Document reserved gaps and consumed slots

If you use storage gaps, track how many slots remain and which version consumed them. This prevents accidental overuse.

Test upgrades on forked state

Deploy the old implementation, populate state, upgrade to the new one, and verify that all critical values remain intact.

What to test before upgrading

A good upgrade test suite should verify:

• existing addresses remain unchanged
• balances and accounting values are preserved
• mappings still return the same entries
• access control roles are intact
• initialization state is not overwritten
• newly added variables default to expected values

A simple integration test can catch many layout mistakes by comparing pre-upgrade and post-upgrade storage-dependent behavior.

Red flags during code review

Watch for these patterns in upgradeable Solidity code:

• new state variables inserted above old ones
• base contract order changed
• imported upgradeable modules updated without layout review
• manual assembly storage slots without a unique namespace
• removed variables without a migration strategy
• multiple contracts writing to the same custom storage slot

If any of these appear, treat the change as high risk.

A practical upgrade checklist

Before deploying a new implementation:

1. Compare storage layouts with the previous version.
2. Confirm all existing variables keep their original slot positions.
3. Ensure new variables are appended or isolated in a namespace.
4. Review inheritance order and imported base contracts.
5. Run upgrade tests against real or forked state.
6. Verify initialization and migration logic cannot overwrite live data.
7. Document the change for future maintainers.

Conclusion

Storage collision is one of the most important risks in Solidity upgradeable contract development because it can corrupt state without producing obvious compile-time errors. The safest approach is to keep storage layout stable, append new variables only at the end, reserve gaps for future growth, and use namespaced storage for modular systems.

If you treat storage layout as a first-class design constraint, your upgrade path becomes much safer and easier to maintain.

Learn more with useful resources

• OpenZeppelin Upgrades Documentation
• Solidity Storage Layout Documentation
• EIP-1967: Proxy Storage Slots