chore: adds link to book and reorg (#582)

* chore: adds link to book and reorg * fix: update typo
matter-labs · Sep 18, 2024 · f7806bb · f7806bb
1 parent bc065c0
commit f7806bb
Showing 1 changed file with 59 additions and 124 deletions.
diff --git 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'