EVM Mirror: Mind the gap between audit and deployment
Is your onchain contract actually the audited code?
For every deployment and upgrade, teams need to verify that the code running onchain is the code they reviewed, approved, and audited.
A smart contract audit reviews a codebase at a specific point in time. Auditors read a particular Git commit, evaluate the risks, and issue findings against that version of the code.
But users don’t interact with a Git commit. They interact with deployed bytecode.
In practice, three separate artifacts exist:
- An audited Git commit
- A deployed contract
- Verified source code on a block explorer
The audit report tells you which Git commit the auditors reviewed. The block explorer tells you which source code compiles to the bytecode deployed onchain.
That gap matters because audits have become one of the industry’s primary trust signals, while deployed contracts remain live attack surfaces. As exploits become more frequent and attacker tooling improves, the industry needs stronger ways to verify that the code reviewed is the code actually running onchain.
For teams operating across multiple deployments, networks, and upgrade cycles, that verification step quickly becomes unmanageable.
Why we built EVM Mirror
We first encountered this challenge while managing deployments across multiple chains and releases.
At Aragon, this became a recurring operational problem. We deploy and upgrade contracts across more than 15 supported chains, and each new release or plugin adds another set of contracts that need to be checked against the code we reviewed. The same problem also shows up in our security council work with external protocols such as Taiko: when we review upgrades, validate proposals, or act as an independent signer, we need a reliable way to confirm that our assessment maps to the code actually running onchain.
Existing tools helped. In particular, Lido’s DiffyScan was a practical approach that helped us address part of the challenge. We used it extensively and it solved an important problem.
Our requirements eventually grew beyond what DiffyScan was designed for. We needed a tool that could work across arbitrary contracts, multiple chains, and automated verification pipelines without requiring repository-specific configuration.
That led us to build EVM Mirror.
EVM Mirror in three commands
EVM Mirror is designed around a simple idea: compare verified onchain source code against a source of truth you already trust.
That source can be a Git checkout, an installed package, a release artifact, or any local directory. The tool is intentionally agnostic to how your code is managed.
mirror verify
mirror verify compares one or more deployed contracts against a local source directory.
Rather than checking only a root contract, it compares the complete set of verified source files returned by the block explorer, including imported libraries and dependencies.
This makes it possible to verify that a deployment matches the codebase you expect.
mirror diff
mirror diff compares two deployed contracts against each other.
This is particularly useful when reviewing upgrades, validating governance proposals, or assessing changes introduced by a new deployment.
For security reviews and protocol due diligence, understanding exactly what changed is often as important as understanding what was deployed.
mirror clone
It pulls the verified source files from the block explorer, writes them into a buildable project structure, and generates a foundry.toml with the compiler and optimizer settings used for the deployed contract.
Common dependency imports are also mapped into the expected Foundry layout. For example, @openzeppelin/... imports are mapped to lib/@openzeppelin/..., so the project can be built locally with forge build with minimal setup.
This is useful when reviewing deployed contracts, reproducing builds, or starting an investigation from verified onchain source rather than a repository.
Built for real deployment environments
EVM Mirror is designed to work across the messy reality of deployed contracts, not only simple single-chain examples.
Proxy support
All commands support proxy-aware analysis through --follow-proxy, allowing comparisons and verification to be performed against implementation contracts rather than proxy addresses.
Multi-chain support
EVM Mirror supports a growing set of EVM networks, including Ethereum, Optimism, Arbitrum, Base, Polygon, zkSync, and others.
Where available, the tool uses Etherscan’s multi-chain API and falls back to compatible explorer infrastructure such as Routescan and Blockscout.
Built for minimal trust
EVM Mirror ships as a standalone Deno binary with a deliberately small permission surface.
It uses read-only file-system access and network access to perform verification and retrieval operations. No package installation, container environment, or external runtime dependencies are required.
For tooling that often sits close to deployment and security workflows, minimizing supply-chain complexity is a worthwhile design goal in itself.
Try it
Audits are only as useful as the confidence they provide.
Verifying that deployed contracts match audited code should be straightforward, repeatable, and easy to automate.
EVM Mirror is an open-source tool built to help close that gap. Open source on GitHub: github.com/aragon/evm-mirror