Bringing Foundry to zkEVM: A Maintainable Fork Strategy

Snapshot

  • Focus: Adapting Foundry, a Rust-based Ethereum development toolkit, for ZKsync’s architecture (zkEVM, custom compiler, distinct gas model).
  • Context: Foundry needed to be adapted to support EraVM features natively, enabling builders to use the tool in ZKsync ecosystem.
  • Who it’s for: Matter Labs, the team behind ZKsync, building the infrastructure for scalable zero-knowledge rollups.
  • Outcomes:
    1. Foundry ZKsync, a specialized fork of Foundry handling zkEVM compilation, deployment, and testing with ongoing upstream synchronization to maintain feature parity with foundry-rs.
    2. The Foundry Book for ZKsync, comprehensive documentation guiding developers through ZKsync-specific workflows.
    3. Extended Foundry cheatcodes for ZKsync-native features like Paymasters and Native Smart Accounts.
    4. Hands-on onboarding support for ecosystem projects of all sizes, including AAVE, EtherFi, and chain deployments like Sophon & Abstract.
    5. Supporting internal testing for era contracts.

Working with Moonsong Labs was a really smooth experience. The team was quite autonomous and didn’t require micromanagement, which made it easy to trust that things would get done. Communication was strong, they brought up blockers early and followed up when needed instead of letting things slip. Overall, they were organized, responsible, and easy to work with. I was very happy with this collaboration.

Igor Aleksanov, DevEx Lead at Matter Labs.

Context

ZKsync is an Ethereum Layer 2 that uses zero-knowledge proofs for scalability while anchored to Ethereum’s security. ZKsync Era uses EraVM, a ZK-optimized custom virtual machine, and incorporates native features such as account abstraction and paymaster.

EraVM introduced differences from EVM due to architectural optimizations for ZK proof generation. These differences meant standard Ethereum tooling, such as Foundry, could not work out-of-the-box.

The Challenge

The challenge was to bring Foundry’s developer experience to ZKsync without creating a hard-to-maintain fork:

  1. Cheatcode compatibility: Foundry’s cheatcodes are essential for testing. Reimplementing each cheatcode for zkVM would create a permanent maintenance burden and risk falling out of sync with upstream.
  2. Dual compiler orchestration: Foundry needed to invoke either solc or zksolc depending on context, while keeping the interface familiar to developers.
  3. Minimizing fork divergence: Every modification to Foundry’s core made upstream synchronization harder. The fork needed to remain maintainable as both Foundry and ZKsync evolved.
  4. Extending the interface for ZKsync-native features: Foundry was never designed for things like paymaster interactions or native account abstraction. These capabilities needed to be introduced in a way that felt familiar to developers already comfortable with the tool.

A naive approach would have scattered ZKsync-specific logic throughout the codebase, creating a fork that would quickly fall behind upstream and become impossible to maintain.

Our Approach

To explore options as part of the engagement, the Moonsong Labs team began by creating proof-of-concept implementations of different approaches for evaluation.

The work revealed that test code and contract execution could run on different VMs within the same test. Instead of porting cheatcodes to zkVM, the team built a dual-VM architecture: tests run on the EVM, where cheatcodes work natively, while contract calls route to the zkVM when targeting ZKsync.

This approach enabled Foundry ZKsync to support upstream cheatcode functionality, while introducing ZKsync-specific adjustments only where required. As a result, developers could leverage Foundry functionality while using EraVM in the ZKsync ecosystem.

The second insight emerged from the challenge of upstream merge maintenance. Each sync with foundry-rs took longer as ZKsync-specific logic spread throughout the codebase. To solve this, a strategy pattern was introduced that isolates ZKSync behavior into swappable objects for the Executor, Backend, and CheatcodeInspector. This reduced the footprint of changes in core Foundry code, making upstream merges manageable again.

Finally, Foundry ZKSync handles compiler orchestration by abstracting over solc and zksolc, invoking the right compiler based on context while keeping the developer interface familiar.

Execution

The implementation has been an ongoing effort spanning nearly three years, requiring not only initial design but continuous evolution and maintenance as both Foundry and ZKSync matured.

Foundation

  • Forked Foundry and established basic compilation support with zksolc integration
  • Built the initial bridge between Foundry’s execution model and the zkVM
  • Developed the Foundry Book for ZKSync to guide developers through ZKSync-specific workflows

Dual-VM architecture

  • Implemented seamless switching between EVM and zkVM within test execution
  • Enabled cheatcode support by routing test logic through the EVM while executing contract calls on zkVM
  • Added custom cheatcodes for ZKSync-native features like paymasters and native account abstraction
As an example, when a transaction is detected in the call or create hooks, a new ZKsync VM is initialized with defaults and executes the transaction. We track information needed for cheatcode constraints via the CheatcodeTracer.

Long-term maintainability

  • Introduced the strategy pattern to encapsulate ZKSync-specific behavior, reducing fork divergence
  • Established a sustainable upstream synchronization process with foundry-rs, maintaining regular upstream merges to keep pace with Foundry improvements.
  • Continued feature development as ZKSync’s capabilities expanded.
Upstream merges are a critical task that allows us to benefit from Foundry’s improvements and bug fixes while maintaining the fork customizations.

Ecosystem support and maintenance

  • Hands-on onboarding support for ecosystem projects of all sizes such as AAVE, EtherFi, and chain deployments like Sophon & Abstract.
  • Active issue and bug resolution.
  • Educational content, sessions and tutorials to onboard users to the tool and ecosystem.

Results

Foundry ZKSync brought the full Foundry developer experience to the ZKSync ecosystem:

  • Over 350 GitHub stars, reflecting active community adoption.
  • Adopted by leading projects in the ecosystem including AAVE, EtherFi, and Sophon and currently being used for testing the era contracts.
  • Cheatcode compatibility with upstream Foundry, maintained through sustainable synchronization that averages two merges per week with foundry-rs.

The foundry-zksync approach created a fork that can be maintained synchronized with upstream Foundry while providing native support for ZKsync’s unique features.