Sigvex
EVMSimulation3 min read

Upgrade Simulator

Simulate a proxy upgrade from current to next implementation, checking storage layout, selectors, and issues before execution.

Open Upgrade SimulatorAll guides
upgradeproxystorage

What it is

A simulator that takes a proxy and two implementations (current and next), runs the upgrade, and produces three panels: Issues Found, Storage Layout Comparison, and Selector Comparison.

Why it exists

Proxy upgrades introduce two classes of silent bug — storage-layout collisions and selector drift. Running the upgrade in a sandbox and surfacing those comparisons catches the bugs before the real upgrade is pushed on-chain.

Who uses it

  • Auditor — verifies that a proposed upgrade is safe.
  • Protocol engineer — checks their own upgrade locally before proposing it.

How to open it

  1. Sidebar → Simulation → Upgrade Simulator.
  2. From /tools → Upgrade Simulator.
  3. Direct URL — /upgrade-simulator.

Using the page

  1. Simulation Parameters — pick the proxy contract (Source) and the new implementation (Target). The Target supports two modes: Workspace asset and Bytecode. Optionally add comma-separated Test Selectors.
  2. Simulate Upgrade — runs the simulation.
  3. Verdict card — shows Upgrade Safe or Issues Detected.
  4. Issues Found — structured list of detected issues.
  5. Storage Layout Comparison — side-by-side slot view of Current Implementation and New Implementation, with a Storage Collisions sub-table when applicable.
  6. Selector Comparison — Preserved / Removed / Added selector summary and tables.

Inputs and outputs

Input Source Required
Source — proxy contract Workspace picker yes
Target (new implementation) Workspace picker or bytecode textarea yes
Test Selectors Comma-separated text input no
Output Format Destination
Verdict (safe / issues) In-page card HTML
Issues list In-page HTML
Storage comparison In-page table HTML
Selector comparison In-page table HTML

Controls reference

  • Workspace asset / Bytecode — toggle for the Target input mode.
  • Simulate Upgrade — runs the upgrade simulation.
  • Retry — shown in the error state; reruns with the current parameters.

Limits

  • Requires a signed-in account.
  • EVM proxies only.
  • The simulator models storage and selector semantics; it does not replay full mainnet state — use a forking tool for deep execution checks.

Troubleshooting

Symptom or error Cause Action
“Simulation Failed” state One of the addresses is missing or not a contract Verify addresses and retry.
Storage Layout Comparison empty Implementations have identical layouts None — a clean result is valid.
Selector Comparison empty Implementations expose identical ABIs None — a clean result is valid.