# foundry-zksync - ZKSync Ethereum Development Framework

## Docs

- [Foundry Benchmarks](/benchmarks): This page shows the latest performance benchmarks for Foundry across different repositories. The benchmarks are automatically updated from the [Foundry repository](https://github.com/foundry-rs/foundry/blob/master/benches/LATEST.md).
- [Compilation Overview](/compilation-overview): [zksolc](https://github.com/matter-labs/era-compiler-solidity/releases) is the compiler ZKsync uses to convert solidity code to zkEVM-compatible bytecode. It uses the same input format as solc but the output bytecodes and their respective hashes. Internally, it uses a custom-compiled [solc](https://github.com/matter-labs/era-solidity/releases)
- [Configuration Overview](/configuration-overview): Foundry-ZKsync adds some new configuration options that can be specified in the `foundry.toml`.
- [Execution Overview](/execution-overview): A forge test begins its execution on the EVM, hence the need to compile `solc` artifacts (see: [solc](https://github.com/matter-labs/era-solidity)).
During test execution, the test can switch over to ZKsync context in multiple ways.
- [Forge-ZKsync Standard Library](/forge-zksync-std): [`forge-std`](https://github.com/foundry-rs/forge-std) exports the most common constructs that allow users to write tests. However, in Foundry ZKsync, we've added some new cheatcodes (or anything we deem helpful in the future). To allow users to access these interfaces, [`forge-zksync-std`](https://github.com/Moonsong-Labs/forge-zksync-std) is provided as an add-on to `forge-std`.
- [Gas Overview](/gas): Foundry has an `isolate` mode for the EVM, in which all `CALL`/`CREATE` operations at the root level of a test (i.e., with depth 1) are intercepted and treated as independent transactions. This allows for accounting for the actual transaction gas, including, for example, the fixed 21000 gas cost charged to the user.
- [ZKSync Specifics](/overview): This section covers the specific parts of ZKSync foundry, how it works, insight into compilation, and custom cheatcodes to help work with contracts specifically in ZKSync.
- [Paymaster Overview](/paymaster-overview): Paymasters in the ZKsync ecosystem represent a groundbreaking approach to handling transaction fees. They are special accounts designed to subsidize transaction costs for other accounts, potentially making certain transactions free for end-users. This feature is handy for dApp developers looking to improve their platform's accessibility and user experience by covering transaction fees on behalf of their users.
- [v1.3.6](/releases): September 16, 2025
- [Foundry v1.3.6](/releases): Foundry v1.3.6 is a bugfix release for forge.
- [Additional Cheatcodes](/cheatcodes/overview): A few new cheatcodes have been added to the existing [Cheatcodes](/reference/cheatcodes/overview) list to help within the ZKsync context,
- [zkRegisterContract](/cheatcodes/zk-register-contract): Registers bytecodes for ZK-VM for transact/call and create instructions. This cheatcode allows you to manually register the mapping between EVM and zkEVM bytecodes for contracts.
- [zkUseFactoryDep](/cheatcodes/zk-use-factory-dep): Marks a given contract as a factory dependency only for the next CREATE or CALL operation. Factory dependencies are contracts that may be deployed by other contracts during execution.
- [zkUsePaymaster](/cheatcodes/zk-use-paymaster): Enables the use of a paymaster for the next transaction. The paymaster will pay for the gas costs of the subsequent operation.
- [zkVmSkip](/cheatcodes/zk-vm-skip): When running in zkEVM context, skips the next CREATE or CALL, executing it on the EVM instead.
- [zkVm](/cheatcodes/zk-vm): Enables or disables the use of ZK-VM for transact/call and create instructions.
- [Deploy-time linking with zksolc](/developer-guide/linking): Contrary to `solc`, unlinked bytecode in `zksolc` contains their link references using the ELF format, thus a simple text search & replace is not sufficient.
- [Nonces](/developer-guide/nonces): Nonces in EVM are generally 8-bytes long and are incremented for both external transactions and `CREATE` opcodes.
- [ZKsync Developer Guide](/developer-guide/overview): ZKsync specific caveats for developers.
- [Using the zkUsePaymaster Cheatcode in General Flow Paymaster Contracts](/examples/general-paymaster): This example covers the use of a general flow paymaster contract.
For this example, we will use the `GaslessPaymaster` contract from the paymaster example repository [here](https://github.com/matter-labs/paymaster-examples).
- [Ledger Integration Example](/examples/ledger): This example demonstrates how to use a Ledger hardware wallet to interact with the ZKsync network through foundry-zksync.
- [ZKsync Specific Examples](/examples/overview): Here, you can see a few short examples of the tool running so you could experience the magic right away.
- [Using the zkUsePaymaster Cheatcode in Approval-Based Paymaster Contracts](/examples/paymaster-approval-based): This example covers the use of an approval-based paymaster contract. The paymaster contract used is the testnet paymaster of ZKsync documented [here](https://docs.zksync.io/build/start-coding/quick-start/paymasters-introduction).
- [Smart Account Example](/examples/smart-account): This example demonstrates the configuration and deployment of a multisig smart account on ZKsync.
- [Linting](/forge/linting): `forge lint` is a command that analyzes Solidity source files in your project to identify potential issues, and enforce coding standards It helps maintain code quality and consistency across your codebase.
- [Deterministic deployment using CREATE2 on ZKsync](/guides/deterministic-deployments-using-create2): Enshrined into the EVM as part of the Constantinople fork of 2019, CREATE2 is an opcode that started its journey as EIP-1014. CREATE2 allows you to deploy smart contracts to deterministic addresses, based on parameters controlled by the deployer. As a result, it's often mentioned as enabling "counterfactual" deployments, where you can interact with an addresses that haven't been created yet because CREATE2 guarantees known code can be placed at that address. This is in contrast to the CREATE opcode, where the address of the deployed contract is a function of the deployer's nonce. With CREATE2, you can use the same deployer account to deploy contracts to the same address across multiple networks, even if the address has varying nonces.
- [Prompting](/introduction/prompting): One of the fastest ways to build smart contracts is by using AI to assist with writing boilerplate code, implementing complex testing patterns, and following security best practices. When building, iterating on, or debugging smart contracts using AI tools and Large Language Models (LLMs), a well-structured and extensive prompt helps provide the model with clearer guidelines and examples that can dramatically improve output quality.
- [General Limitations](/limitations/general): These limitations apply at all times when working within the ZKsync context.
- [Limitations](/limitations/overview): Adapting existing EVM contracts to work within a zkEVM environment requires significant modifications to their underlying code. These changes are primarily due to the fundamental [incompatibility](https://docs.zksync.io/build/developer-reference/era-vm) between EVM and zkEVM and, as such, cannot be ignored or circumvented in any way. These constraints are usually enforced by the zkEVM's [bootloader](https://docs.zksync.io/zk-stack/components/zksync-evm/bootloader), and can lead to panics if ignored.
- [Trace Limitations](/limitations/traces): Tracing and debugging capabilities have limitations in the zkEVM environment.
- [Nightly (2025-09-16)](/releases/nightly): September 16, 2025
- [Foundry v1.3.5](/releases/stable): Foundry v1.3.5 is a bugfix release for cast state overrides.
- [Using cast with ZKSync](/zksync-specifics/cast): ℹ️ **Note**
- [Compilation Overview](/zksync-specifics/compilation-overview): [zksolc](https://github.com/matter-labs/era-compiler-solidity/releases) is the compiler ZKsync uses to convert solidity code to zkEVM-compatible bytecode. It uses the same input format as solc but the output bytecodes and their respective hashes. Internally, it uses a custom-compiled [solc](https://github.com/matter-labs/era-solidity/releases)
- [Configuration Overview](/zksync-specifics/configuration-overview): Foundry-ZKsync adds some new configuration options that can be specified in the `foundry.toml`.
- [Execution Overview](/zksync-specifics/execution-overview): A forge test begins its execution on the EVM, hence the need to compile `solc` artifacts (see: [solc](https://github.com/matter-labs/era-solidity)).
During test execution, the test can switch over to ZKsync context in multiple ways.
- [Forge-ZKsync Standard Library](/zksync-specifics/forge-zksync-std): [`forge-std`](https://github.com/foundry-rs/forge-std) exports the most common constructs that allow users to write tests. However, in Foundry ZKsync, we've added some new cheatcodes (or anything we deem helpful in the future). To allow users to access these interfaces, [`forge-zksync-std`](https://github.com/Moonsong-Labs/forge-zksync-std) is provided as an add-on to `forge-std`.
- [Gas Overview](/zksync-specifics/gas): Foundry has an `isolate` mode for the EVM, in which all `CALL`/`CREATE` operations at the root level of a test (i.e., with depth 1) are intercepted and treated as independent transactions. This allows for accounting for the actual transaction gas, including, for example, the fixed 21000 gas cost charged to the user.
- [ZKSync Specifics](/zksync-specifics/overview): This section covers the specific parts of ZKSync foundry, how it works, insight into compilation, and custom cheatcodes to help work with contracts specifically in ZKSync.
- [Paymaster Overview](/zksync-specifics/paymaster-overview): Paymasters in the ZKsync ecosystem represent a groundbreaking approach to handling transaction fees. They are special accounts designed to subsidize transaction costs for other accounts, potentially making certain transactions free for end-users. This feature is handy for dApp developers looking to improve their platform's accessibility and user experience by covering transaction fees on behalf of their users.
- [Invariant Testing](/forge/advanced-testing/invariant-testing): Invariant testing allows for a set of invariant expressions to be tested against randomized sequences of pre-defined function calls from pre-defined contracts. After each function call is performed, all defined invariants are asserted.
- [Gas Section Snapshots](/forge/gas-tracking/gas-section-snapshots): Forge can capture gas snapshots over arbitrary sections inside of your test functions. This can be useful to get a granular measurement of how much gas your logic is consuming as both external calls and internal gas usage are measured.
- [Forge-ZKsync Standard Library](/forge/tests/forge-zksync-std): [`forge-std`](https://github.com/foundry-rs/forge-std) exports the most common constructs that allow users to write tests. However, in Foundry ZKsync, we've added some new cheatcodes (or anything we deem helpful in the future). To allow users to access these interfaces, [`forge-zksync-std`](https://github.com/Moonsong-Labs/forge-zksync-std) is provided as an add-on to `forge-std`.
- [Additional Cheatcodes](/zksync-specifics/cheatcodes/overview): A few new cheatcodes have been added to the existing [Cheatcodes](/reference/cheatcodes/overview) list to help within the ZKsync context,
- [Deploy-time linking with zksolc](/zksync-specifics/developer-guide/linking): Contrary to `solc`, unlinked bytecode in `zksolc` contains their link references using the ELF format, thus a simple text search & replace is not sufficient.
- [Nonces](/zksync-specifics/developer-guide/nonces): Nonces in EVM are generally 8-bytes long and are incremented for both external transactions and `CREATE` opcodes.
- [ZKsync Developer Guide](/zksync-specifics/developer-guide/overview): ZKsync specific caveats for developers.
- [Using the zkUsePaymaster Cheatcode in General Flow Paymaster Contracts](/zksync-specifics/examples/general-paymaster): This example covers the use of a general flow paymaster contract.
For this example, we will use the `GaslessPaymaster` contract from the paymaster example repository [here](https://github.com/matter-labs/paymaster-examples).
- [ZKsync Specific Examples](/zksync-specifics/examples/overview): Here, you can see a few short examples of the tool running so you could experience the magic right away.
- [Using the zkUsePaymaster Cheatcode in Approval-Based Paymaster Contracts](/zksync-specifics/examples/paymaster-approval-based): This example covers the use of an approval-based paymaster contract. The paymaster contract used is the testnet paymaster of ZKsync documented [here](https://docs.zksync.io/build/start-coding/quick-start/paymasters-introduction).
- [Limitations](/zksync-specifics/limitations/overview): Adapting existing EVM contracts to work within a zkEVM environment requires significant modifications to their underlying code. These changes are primarily due to the fundamental [incompatibility](https://docs.zksync.io/build/developer-reference/era-vm) between EVM and zkEVM and, as such, cannot be ignored or circumvented in any way. These constraints are usually enforced by the zkEVM's [bootloader](https://docs.zksync.io/zk-stack/components/zksync-evm/bootloader), and can lead to panics if ignored.