This repository provides Foundry functionality in Solidity for compiling, deploying, testing, and interacting with smart contracts on zkSync Era.
What is foundry?
Foundry is a blazing fast, portable and modular toolkit for Ethereum application development written in Rust.
Foundry consists of:
- Forge: Ethereum testing framework (like Truffle, Hardhat and DappTools).
- Cast: Swiss army knife for interacting with EVM smart contracts, sending transactions and getting chain data.
- Anvil: Local Ethereum node, akin to Ganache, Hardhat Network.
- Chisel: Fast, utilitarian, and verbose solidity REPL.
Need help getting started with Foundry? Read the 📖 Foundry Book (WIP)!
- zkForge: zkSync testing framework (like Hardhat and DappTools).
- zkCast: Swiss army knife for interacting with zkEVM smart contracts, sending transactions and getting chain data.
Need help getting started with Foundry-zkSync? Read the 📖 Usage Guides (WIP)!
Please note that foundry-zksync
is still in its alpha stage. Some features might not be fully supported yet and may not work as intended. However, it is open-sourced, and contributions are welcome!
Foundry-zksync
offers a set of features designed to work with zkSync Era, providing a comprehensive toolkit for smart contract deployment and interaction:
- Smart Contract Deployment: Easily deploy smart contracts to zkSync Era mainnet, testnet, or a local test node.
- Asset Bridging: Bridge assets between L1 and L2, facilitating seamless transactions across layers.
- Contract Interaction: Call and send transactions to deployed contracts on zkSync Era testnet or local test node.
- Solidity Testing: Write tests in Solidity, similar to DappTools, for a familiar testing environment.
- Fuzz Testing: Benefit from fuzz testing, complete with shrinking of inputs and printing of counter-examples.
- Remote RPC Forking: Utilize remote RPC forking mode, leveraging Rust's asynchronous infrastructure like tokio.
- Flexible Debug Logging: Choose your debugging style:
- DappTools-style: Utilize DsTest's emitted logs for debugging.
- Hardhat-style: Leverage the popular console.sol contract.
- Configurable Compiler Options: Tailor compiler settings to your needs, including LLVM optimization modes.
While foundry-zksync
is alpha stage, there are some limitations to be aware of:
-
Cheat Codes Support: Not all cheat codes are fully supported. View the list of supported cheat codes.
-
Compile Time: Some users may experience slower compile times.
-
Compiling Libraries: Compiling non-inlinable libraries requires deployment and adding to configuration. For more information please refer to official docs.
libraries = [ "src/MyLibrary.sol:MyLibrary:0xfD88CeE74f7D78697775aBDAE53f9Da1559728E4" ]
-
Create2 Address Derivation: There are differences in Create2 Address derivation compared to Ethereum. Read the details.
-
Specific Foundry Features: Currently features such as
--gas-report
may not work as intended. We are actively working on providing support for these feature types.
For the most effective use of our library, we recommend familiarizing yourself with these features and limitations.
- Install Rust with the following command:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
The current implementation makes use of nightly-2023-09-30
. Please be sure to have the proper toolchain installed:
# rustup install nightly-2023-09-30-<YOUR-TARGET>
rustup install nightly-2023-09-30-aarch64-apple-darwin
Each tool within our suite can be installed individually, or you can install the entire suite at once.
Run the following command:
cargo install --path ./crates/zkforge --profile local --force --locked
This installs zkforge
to ~/.cargo/bin
, making it available as an executable.
Run the following command:
cargo install --path ./crates/zkcast --profile local --force --locked
This installs zkcast
to ~/.cargo/bin
, allowing it to be used as an executable.
To install all the tools in the suite:
cargo build --release
Run:
zkforge init hello_foundry
Let's check out what zkforge generated for us:
$ cd hello_foundry
$ tree . -d -L 1
.
├── abis
├── broadcast
├── interfaces
├── lib
├── script
├── src
├── test
We can build the project with zkforge zkbuild:
$ zkforge zkbuild
Compiling smart contracts...
Compiled Successfully
In case missing libraries are detected during the compilation, we can deploy them using the following command:
$ zkforge zkcreate --deploy-missing-libraries --private-key <PRIVATE_KEY> --rpc-url <RPC_URL> --chain <CHAIN_ID>
After deployment is done, the configuration file will be updated and contracts will be automatically compiled again.
You can run the tests using zkforge test
.
The command and its expected output are shown below:
$ zkforge test
Running 2 tests for Counter.t.sol:CounterTest
[PASS] testFuzz_SetNumber(uint256) (runs: 256, μ: 9223372034707527035, ~: 9223372034707527076)
[PASS] test_Increment() (gas: 9223372034707527339)
Test result: ok. 2 passed; 0 failed; 0 skipped; finished in 5.15s
Ran 1 test suites: 2 tests passed, 0 failed, 0 skipped (2 total tests)
Foundry is designed to be very configurable. You can configure Foundry using a file called foundry.toml
in the root of your project, or any other parent directory. See config package for all available options.
Configuration can be arbitrarily namespaced by profiles. The default profile is named default
(see "Default Profile").
You can select another profile using the FOUNDRY_PROFILE
environment variable. You can also override parts of your configuration using FOUNDRY_
or DAPP_
prefixed environment variables, like FOUNDRY_SRC
.
zkforge init
creates a basic, extendable foundry.toml
file.
To see your current configuration, run zkforge config
. To see only basic options (as set with zkforge init
), run zkforge config --basic
. This can be used to create a new foundry.toml
file with zkforge config --basic > foundry.toml
.
By default zkforge config
shows the currently selected foundry profile and its values. It also accepts the same arguments as zkforge build
. An example foundry.toml
for zkSync with zksolc configurations may look like:
[profile.default]
src = 'src'
out = 'out'
libs = ['lib']
[profile.zksync]
src = 'src'
libs = ['lib']
fallback_oz = true
mode = "3"
You can find additional setup and configurations guides in the Foundry Book:
See our contributing guidelines.
Make sure that:
- You are using zksync specific methods (
zkcreate
notcreate
,zksend
notsend
). - You set the correct
--rpc-url
. - You have the proper contract address - the bytecodes in zkSync Era are different to in EVM - so the resulting contracts will be deployed at different addresses.
If you get errors like (code: -32601, message: Method not found, data: None)
- you are probably using a send
method instead of zksend
.
- Foundry is a clean-room rewrite of the testing framework DappTools. None of this would have been possible without the DappHub team's work over the years.
- Matthias Seitz: Created ethers-solc which is the backbone of our compilation pipeline, as well as countless contributions to ethers, in particular the
abigen
macros. - Rohit Narurkar: Created the Rust Solidity version manager svm-rs which we use to auto-detect and manage multiple Solidity versions.
- Brock Elmore: For extending the VM's cheatcodes and implementing structured call tracing, a critical feature for debugging smart contract calls.
- All the other contributors to the ethers-rs & foundry repositories and chatrooms.
- Moonsong Labs: Implemented era-cheatcodes, and resolved a number of different challenges to enable zkSync support.