From f7806bba699a32488a6e5f11e51929a45c37cd5b Mon Sep 17 00:00:00 2001 From: Dustin Brickwood Date: Wed, 18 Sep 2024 07:34:10 -0500 Subject: [PATCH] chore: adds link to book and reorg (#582) * chore: adds link to book and reorg * fix: update typo --- README.md | 183 ++++++++++++++++++------------------------------------ 1 file changed, 59 insertions(+), 124 deletions(-) diff --git a/README.md b/README.md index c2d991209..5c4c2ba13 100644 --- a/README.md +++ b/README.md @@ -1,80 +1,14 @@ -## Foundry with zkSync Era v0.2-alpha +## Foundry with ZKsync Era v0.2-alpha -This repository enhances Foundry to support zkSync Era, enabling Solidity-based compilation, deployment, testing, and interaction with smart contracts on zkSync Era. +This repository enhances Foundry to support ZKsync, enabling Solidity-based compilation, deployment, testing, and interaction with smart contracts on ZKsync. > 🔧 **Fork Notice:** This is a Foundry fork with added zkSync support. > -> ⚠️ **Alpha Stage:** The project is in alpha, so you might encounter issues. For more information, please review [Limitations](#limitations) section. +> ⚠️ **Alpha Stage:** The project is in alpha, so you might encounter issues. > -> 🐞 **Found an Issue?** Please report it to help us improve. - -### Changes Made - -To use for zkSync environments, include `--zksync` when running `forge` or `vm.zkVm(true)` in tests. The modifications include: - -1. **Compilation:** `solc` and `zksolc` are used for compiling. The resulting bytecodes are combined into `DualCompiledContract` and managed through `Executor` to `CheatcodeTracer`. -2. **EVM Interactions:** - - EVM calls are standard except for `address.balance` and `block.timestamp`/`block.number`, which pull data from zkSync (ZK-storage and ZK-specific context, respectively). -3. **Transaction Handling:** - - `CALL` and `CREATE` operations are captured and converted to zkSync transactions. This process includes fetching zkSync-equivalent bytecode, managing account nonces, and marking EOA appropriately to comply with zkSync requirements. -4. **Execution and State Management:** - - zkSync VM processes the transaction and returns state changes, which are applied to `journaled_state`. Results are relayed back. -5. **Logging:** - - `console.log()` outputs within zkSync VM are captured and displayed in Foundry. - - `ZK_DEBUG_RESOLVE_HASHES` and `ZK_DEBUG_SHOW_OUTPUTS` env variable may be set to `true` to display zkSync VM call logs with resolved selector hashes (requires Internet connection), and the call outputs, respectively. -6. **Fuzzing** - - Adds config option `no_zksync_reserved_addresses`. Since zkSync reserves addresses below 2^16 as system addresses, a fuzz test would've required a broad `vm.assume` and many `vm.excludeSender` calls to exclude these. This is not only cumbersome but could also trigger `proptest`'s global `max_global_rejects` failure. When this option is set to `true` the `proptest` generation itself ensures that no invalid addresses are generated, and thus need not be filtered adding up to the `max_test_rejects` count. - -## 📊 Features & Limitations - -### Features - -`Foundry-zksync` offers a set of features designed to work with zkSync Era, providing a comprehensive toolkit for smart contract deployment and interaction: -- **Fast & flexible compilation pipeline** - - Automatic Solidity compiler version detection & installation - - **Incremental compilation & caching**: Only changed files are re-compiled - - Parallel compilation - - Non-standard directory structures support (e.g. [Hardhat repos](https://twitter.com/gakonst/status/1461289225337421829)) -- **Tests are written in Solidity** (like in DappTools) -- **Fast fuzz testing** with shrinking of inputs & printing of counter-examples -- **Fast remote RPC forking mode**, leveraging Rust's async infrastructure like tokio -- **Flexible debug logging** - - DappTools-style, using `DsTest`'s emitted logs - - Hardhat-style, using the popular `console.sol` contract -- **Portable (5-10MB) & easy to install** without requiring Nix or any other package manager -- **Fast CI** with the [Foundry GitHub action][foundry-gha]. - -- **Smart Contract Deployment**: Easily deploy smart contracts to zkSync Era mainnet, testnet, or a local test node. -- **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. - -Forge is quite fast at both compiling (leveraging [ethers-solc]) and testing. - -### Limitations - -While `foundry-zksync` is **alpha stage**, there are some limitations to be aware of: - -- **Compile Time**: Some users may experience slower compile times. -- **Compiling Libraries**: Compiling non-inlinable libraries requires deployment and adding to configuration or the command line with the `--libraries` argument. For more information please refer to [official docs](https://docs.zksync.io/build/developer-reference/ethereum-differences/libraries). - - ``` - libraries = [ - "src/MyLibrary.sol:MyLibrary:0xfD88CeE74f7D78697775aBDAE53f9Da1559728E4" - ] - ``` -- **Create2 Address Derivation**: There are differences in Create2 Address derivation compared to Ethereum. [Read the details](https://docs.zksync.io/build/developer-reference/ethereum-differences/evm-instructions#create-create2). -- **Contract Verification**: Currently contract verification via the `--verify` flag do not work as expected but will be added shortly. -- **Specific Foundry Features**: Currently features such as `--gas-report`, `--coverage` may not work as intended. We are actively working on providing support for these feature types. -- **Solc Compatibility**: `zksolc` requires a `solc` binary to be run as a child process. The version/path to use for each can be specified by the `zksolc` and `solc` options in `foundry.toml`. Not all `solc` versions are supported by all `zksolc` versions, compiling with a `solc` version higher than the one supported may lead to unexpected errors. [Read the docs](https://docs.zksync.io/zk-stack/components/compiler/toolchain/solidity.html#limitations) about version limitations and check the [zksolc changelog](https://github.com/matter-labs/era-compiler-solidity/blob/main/CHANGELOG.md) to see the latest supported `solc` version. -- **Windows Compatibility**: Windows is not officially supported yet. The reported issues would be investigated on a best-effort basis. - -For the most effective use of our library, we recommend familiarizing yourself with these features and limitations. +> 🐞 **Found an Issue?** Please report it to help us improve by opening an issue or submitting a pull request. +> +> 📚 **Foundry ZKsync Book:** For detailed information, including installation instructions, usage examples, and advanced guides, please refer to the [Foundry ZKsync Book](https://foundry-book.zksync.io/). ## Quick Install @@ -102,6 +36,58 @@ forge --version This should return the installed version of `forge`, confirming that `foundry-zksync` is installed properly on your system. +## Quickstart + +In an empty directory, run the following command: + +```bash +forge init +``` + +Let's check out what forge generated for us: + +```bash +$ tree . -d -L 1 +. +├── lib +├── script +├── src +└── test +``` + +#### Compiling contracts + +We can build the project with `forge build --zksync`: + +```bash +$ forge build --zksync +Compiling smart contracts... +Compiled Successfully +``` + +#### Listing missing libraries + +To scan missing non-inlinable libraries, you can build the project using the `--zk-detect-missing-libraries` flag. This will give a list of the libraries that need to be deployed and their addresses +provided via the `libraries` option for the contracts to compile. +Metadata about the libraries will be saved in `.zksolc-libraries-cache/missing_library_dependencies.json`. + +#### Running Tests + +You can run the tests using `forge test --zksync`. + +The command and its expected output are shown below: + +```bash +forge test --zksync + +Ran 2 tests for test/Counter.t.sol:CounterTest +[PASS] testFuzz_SetNumber(uint256) (runs: 256, μ: 8737, ~: 8737) +[PASS] test_Increment() (gas: 8702) +Suite result: ok. 2 passed; 0 failed; 0 skipped; finished in 3.57s (3.56s CPU time) + +Ran 1 test suite in 3.57s (3.57s CPU time): 2 tests passed, 0 failed, 0 skipped (2 total tests) +``` + ## 📝 Development Prerequisites Ensure you have the necessary tools and environments set up for development: @@ -170,57 +156,6 @@ To install all the tools in the suite: cargo build --release ``` -## Quickstart - -In an empty directory, run the following command: -``` -forge init -``` - -Let's check out what forge generated for us: - -``` -$ tree . -d -L 1 -. -├── lib -├── script -├── src -└── test -``` - -#### Compiling contracts - -We can build the project with `forge build --zksync`: -``` -$ forge build --zksync -Compiling smart contracts... -Compiled Successfully -``` - -#### Listing missing libraries - -To scan missing non-inlinable libraries, you can build the project using the `--zk-detect-missing-libraries-flag`. This will give a list of the libraries that need to be deployed and their addresses -provided via the `libraries` option for the contracts to compile. -Metadata about the libraries will be saved in `.zksolc-libraries-cache/missing_library_dependencies.json`. - - -#### Running Tests - -You can run the tests using `forge test --zksync`. - -The command and its expected output are shown below: - -```bash -$ forge test --zksync - -Ran 2 tests for test/Counter.t.sol:CounterTest -[PASS] testFuzz_SetNumber(uint256) (runs: 256, μ: 8737, ~: 8737) -[PASS] test_Increment() (gas: 8702) -Suite result: ok. 2 passed; 0 failed; 0 skipped; finished in 3.57s (3.56s CPU time) - -Ran 1 test suite in 3.57s (3.57s CPU time): 2 tests passed, 0 failed, 0 skipped (2 total tests) -``` - ## Configuration ### Using `foundry.toml` @@ -237,7 +172,7 @@ To see your current configuration, run `forge config`. To see only basic options By default `forge config` shows the currently selected foundry profile and its values. It also accepts the same arguments as `forge build`. An example `foundry.toml` for zkSync with zksolc configurations may look like: -``` +```bash [profile.default] src = 'src' out = 'out'