Foundry with zkSync Era v0.1
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)!
Foundry-zkSync adds:
- zkForge: zkSync testing framework (like Truffle, 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)!
⚠️ Caution
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!
📊 Features & Limitations
✅ Features | 🚫 Limitations |
---|---|
Compile smart contracts with the zksolc compiler. | Can't find test/ directory |
Deploy smart contracts to zkSync Era mainnet, testnet, or local test node. | script command lacks zksolc support. |
Bridge assets L1 <-> L2. | Cheat codes are not supported. |
Call deployed contracts on zkSync Era testnet or local test node. | Lacks advanced testing methods (e.g., variant testing). |
Send transactions to deployed contracts on zkSync Era testnet or local test node. | |
Simple 'PASS / FAIL' testing. |
📝 Prerequisites
💾 Installation
Each tool within our suite can be installed individually, or you can install the entire suite at once.
zkforge
🛠️
Installing 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.
zkcast
📡
Installing 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.
Installing the Entire Suite 📦
To install all the tools in the suite:
cargo build --release
Quickstart
Run:
zkforge init --template https://github.com/dutterbutter/hello-foundry-zksync
Let's check out what zkforge generated for us:
$ cd hello-foundry-zksync
$ tree . -d -L 1
.
├── abis
├── broadcast
├── interfaces
├── lib
├── script
├── src
├── test
Compiling contracts
We can build the project with zkforge zkbuild:
$ zkforge zkbuild
Compiling smart contracts...
Child -> Bytecode Hash: 010000410c1f3728a3887d9bc854d978ce441ccef394319cb26c58e0ba90df46
Counter -> Bytecode Hash: 0100003bc44686be52940f3f2bd8a0feef17700663cba9edb978886c08123811
Greeter -> Bytecode Hash: 0100008f03cbc9c98bb0a883736bf9c1d8801b74928ed78148ddbd5445defddf
StepChild -> Bytecode Hash: 010000239f712c49b5804a34b1f995e034d853e2c6d2edcb60646f1bf9f057f2
Compiler run completed with warnings
TwoUserMultisig -> Bytecode Hash: 01000757a0867b6d7aba75853f126e7780bd893ae384a4718a2a03a6b53a5ee1
AAFactory -> Bytecode Hash: 0100007b76ee1ed575d19043b0b995632ac07ae996aefbbc8238f490f492c793
SimpleFactory -> Bytecode Hash: 0100021b7653e052f7f8218197d79e28de792ff243a30711fb63251644d47524
Compiled Successfully
Running Tests
You can run the tests using zkforge test
.
❗Known issue of not being able to find tests in the
/tests/
directory.
The command and its expected output are shown below:
$ zkforge test
Running 2 tests for Counter.sol:ContractBTest
[PASS] test_CannotSubtract43() (gas: 9223372034707517612)
[PASS] test_NumberIs42() (gas: 9223372034707517612)
Test result: ok. 2 passed; 0 failed; 0 skipped; finished in 43.08ms
Running 1 test for Counter.sol:OwnerUpOnlyTest
[PASS] test_IncrementAsOwner() (gas: 9223372034707517612)
Test result: ok. 1 passed; 0 failed; 0 skipped; finished in 43.46ms
Running 2 tests for Counter.sol:CounterTest
[PASS] test_Increment() (gas: 9223372034707517612)
[PASS] test_Increment_twice() (gas: 9223372034707517612)
Test result: ok. 2 passed; 0 failed; 0 skipped; finished in 47.81ms
Ran 3 test suites: 5 tests passed, 0 failed, 0 skipped (5 total tests)
Configuration
foundry.toml
Using 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
.
DappTools Compatibility
You can re-use your .dapprc
environment variables by running source .dapprc
before using a Foundry tool.
Additional Configuration
You can find additional setup and configurations guides in the Foundry Book:
Contributing
See our contributing guidelines.
Troubleshooting
Verify arguments
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.
'Method not found' when calling 'send'
If you get errors like (code: -32601, message: Method not found, data: None)
- you are probably using a send
method instead of zksend
.
'Could not get solc: Unknown version provided', 'checksum not found'
These errors might show up on the Mac with ARM chip (M1, M2) due to the fact that most recent solc compilers are not auto-downloaded there.
There are 2 workarounds:
- Use an older compiler by adding
--use 0.8.19
flag to thezk-build
command. - Download the compiler manually and then use the
--offline
mode. (Download the compiler into ~/.svm/VERSION/solc-VERSION -- for example ~/.svm/0.8.20/solc-0.8.20).
You can get the latest compiler version for MacOs AARCH here: https://github.com/ethers-rs/solc-builds/tree/master/macosx/aarch64
You might have to remove the zkout
directory (that holds the compilation artifacts) and in some rare scenarios also cleanup the installed solc versions (by removing ~/.svm/
directory)
solc
versions >0.8.19 are not supported, found 0.8.20
This means that our zksync compiler doesn't support that version of solidity yet.
In such case, please remove the artifacts (by removing zkout
directory) and re-run with the older version of solidity (--use 0.8.19
) for example.
You might also have to remove the ~/.svm/0.8.20/solc-0.8.20
file.
Acknowledgements
- 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.