The Upgrade Simulator dry-runs a proxy upgrade before it happens. You give it the proxy and the two implementations — current and next — and it runs the upgrade in a sandbox, then tells you whether the new implementation is storage-compatible and whether any selectors moved.
Why it exists
Proxy upgrades fail silently in two classic ways: the new implementation’s storage layout collides with the old one, so existing state is read from the wrong slots, or a selector changes and a function that used to work stops routing. Both are catastrophic and both are invisible until someone hits them in production. Running the upgrade here and comparing the two sides catches them before the real upgrade goes on-chain.
Who uses it
- Auditor — verifies that a proposed upgrade is safe to approve.
- Protocol engineer — checks their own upgrade before proposing it.
How to open it
- Sidebar → Simulation → Upgrade Simulator.
- From Tools → Upgrade Simulator.
- Direct URL —
/upgrade-simulator.
Running a simulation
Pick the proxy as the source and the new implementation as the target — the target can be a workspace asset or pasted bytecode — and optionally list specific test selectors to check. Simulate Upgrade runs it and returns a verdict of Upgrade Safe or Issues Detected, backed by three panels: a structured Issues Found list, a Storage Layout Comparison that puts the two implementations’ slots side by side (with a storage-collisions sub-table when there are any), and a Selector Comparison showing which selectors were preserved, removed, or added.
Limits
- Requires a signed-in account, and works on EVM proxies.
- It models storage and selector semantics — it does not replay full mainnet state, so pair it with the fork sandbox for deep execution checks. An empty comparison panel is a clean result, not a failure.
Related pages
- Upgrade Semantic Diff — a faster bytecode-level diff of what changed.
- Dependency Map — re-check external dependencies after an upgrade.