upgradeability-governance

Use ERC-7201 namespaced storage for state isolation, protect _authorizeUpgrade() with an explicit role like UPGRADER_ROLE behind a multisig or timelock, and write Foundry tests proving state persists across the upgrade and unauthorized upgrades revert.

ERC-7201 namespaced storage places each contract's state at a deterministic, uniquely derived storage slot to prevent collisions between implementation versions. It is preferred over __gap arrays as the primary collision mitigation strategy in upgradeable contracts.

Implementation contracts must not use constructors for state setup; they use initializer or reinitializer functions instead. The implementation's constructor should only call _disableInitializers() to prevent the logic contract itself from being initialized.

Required Foundry tests verify the initializer runs once, state persists after upgrade, old storage slot values remain correct, and unauthorized upgrade attempts revert. Fuzz or invariant tests across the upgrade boundary are recommended.

tx.origin identifies the original externally owned account of a transaction chain, making it vulnerable to phishing-style intermediary contract attacks. Admin gating must use msg.sender with explicit role checks such as UPGRADER_ROLE instead.