Merge pull request #56 from matter-labs/tincho/general-improvements

General improvements

src/README.md

@@ -4,37 +4,39 @@
 
 **Foundry-ZKsync is a smart contract development toolchain for ZKsync**, built upon [Foundry](https://book.getfoundry.sh/).
 
-Foundry-ZKsync manages your dependencies, compiles your project, runs tests, deploys, and lets you interact with the chain from the command-line and via Solidity scripts.
+Foundry-ZKsync manages your dependencies, compiles your project, runs tests, deploys, and lets you interact with the chain from the command line and via Solidity scripts.
 
 > ⚠️ **Alpha Stage:** The project is in alpha, so you might encounter issues. For more information or reporting bugs, please visit the [Foundry-ZKsync GitHub repository](https://github.com/matter-labs/foundry-zksync).
 
 ## Sections
+
 **[Getting Started](getting-started/installation.md)**
 
-To get started with Foundry-ZKsync, install Foundry-ZKsync and set up your first project.
+To start with Foundry-ZKsync, install Foundry-ZKsync and set up your first project.
 
 **[Projects](projects/creating-a-new-project.md)**
 
-This section will give you an overview of how to create and work with existing projects.
+This section will give you an overview of creating and working with existing projects.
 
 **[ZKsync Specific](zksync-specifics)**
 
-This section will give you an the necessary information to write and run tests for zkEVM.
+This section will introduce the necessary information to write and run tests for zkEVM.
 
 **[Supported Commands Overview](supported-commands)**
 
-This section has a comprehensive review of all the Foundry commands actually supported in the Foundry-ZKSync tool.
+This section comprehensively reviews all the Foundry commands supported in the Foundry-ZKSync tool.
 
 > 📖 **Contributing**
 >
-> This book is actual work in progress as part of the global efforts to support Foundry in ZKSync. More information, sections and pages will be added as we the project progresses.
+> This book is actually a work in progress, part of the global effort to support Foundry in ZKSync. More information, sections, and pages will be added as the project progresses.
 >
 > Feedback and contributions are welcome. You can contribute to this book on [Foundry-ZKSync Book GitHub repository](https://github.com/matter-labs/foundry-zksync-book).
 >
-<br>
+> <br>
+
+**_For general information about Foundry, see the [Foundry Book](https://book.getfoundry.sh/)._**
 
-***For general information about Foundry, see the [Foundry Book](https://book.getfoundry.sh/).***
-<!--  
+<!--
 **[Forge Overview](forge)**
 
 The overview will give you all you need to know about how to use `forge` to develop, test, and deploy smart contracts.
@@ -71,7 +73,7 @@ Tutorials on building smart contracts with Foundry.
 - [Testing EIP-712 Signatures](./tutorials/testing-eip712.md)
 - [Solidity Scripting](./tutorials/solidity-scripting.md)
 - [Forking Mainnet with Cast and Anvil](./tutorials/forking-mainnet-with-cast-anvil.md)
-<!-- - [Incremental Adoption]() 
+<!-- - [Incremental Adoption]()
 
 
 **Contributing**
@@ -93,4 +95,4 @@ References, troubleshooting, and more.
 - [Miscellaneous](misc)
 
 <br>
--->
+-->

src/getting-started/installation.md

@@ -4,8 +4,8 @@
 
 ### Precompiled Binaries
 
-Precompiled binaries can be downloaded from the [GitHub releases page](https://github.com/matter-labs/foundry-zksync/releases). For easier management, we recommend using [Foundryup](#using-foundryup-zksync).
-Currently due to active development it's recommended to use the latest [nightly](https://github.com/matter-labs/foundry-zksync/releases/tag/nightly) from the releases page.
+Precompiled binaries can be downloaded from the [GitHub releases page](https://github.com/matter-labs/foundry-zksync/releases). We recommend using [Foundryup](#using-foundryup-zksync) for easier management.
+We are working on a polished versioning approach that will be released soon. However, we are also in a phase of active development.
 
 ### Using Foundryup-zksync
 
@@ -17,26 +17,26 @@ To install Foundryup-zksync, open your terminal and run the following command:
 curl -L https://raw.githubusercontent.com/matter-labs/foundry-zksync/main/install-foundry-zksync | bash
 ```
 
-This will install Foundryup-zksync. Simply follow the on-screen instructions, and the `foundryup-zksync` command will become available in your CLI.
+This will install Foundryup-zksync. Follow the on-screen instructions, and the `foundryup-zksync` command will become available in your CLI.
 
 Running `foundryup-zksync` automatically installs the latest nightly versions of the [precompiled binaries](#precompiled-binaries), including `forge` and `cast`. Additionally, it fetches the most recent version of the precompiled binary `anvil-zksync` from the [anvil-zksync releases](https://github.com/matter-labs/anvil-zksync/releases).
 
-For additional options, such as installing a specific version or commit, run `foundryup-zksync --help`.
+Run ' foundryup-zksync—- help ' for additional options, such as installing a specific version or commit.
 
 > ℹ️ **Note**
 >
-> Currently only `forge` and `cast` are supported for ZKsync. Other commands retain their original behavior but may not work as intended.
+> Only `forge` and `cast` are currently supported for ZKsync. Other commands retain their original behavior but may not work as intended.
 
 > ℹ️ **Note**
 >
-> If you're on Windows, you will need to install and use [Git BASH](https://gitforwindows.org/) or [WSL](https://learn.microsoft.com/en-us/windows/wsl/install),
-> as your terminal, since Foundryup-zksync currently does not support Powershell or Cmd. Windows support is currently provided as best-effort.
+> If you're on Windows, you will need to install and use [Git BASH](https://gitforwindows.org/) or [WSL](https://learn.microsoft.com/en-us/windows/wsl/install)
+> since Foundryup-zksync currently does not support Powershell or Cmd. Windows support is currently provided as best-effort.
 
 ### Building from Source
 
 #### Prerequisites
 
-You’ll need the [Rust](https://rust-lang.org) compiler and Cargo, Rust's package manager. The easiest way to install both is by using [`rustup.rs`](https://rustup.rs/).
+You’ll need the [Rust](https://rust-lang.org) compiler and Cargo, Rust's package manager. The easiest way to install both is using [`rustup.rs`](https://rustup.rs/).
 
 Foundry-ZKsync generally supports building only with the [configured](https://github.com/matter-labs/foundry-zksync/blob/main/rust-toolchain) nightly Rust version.
 The presence of `rust-toolchain` file automatically downloads the correct nightly rust version when commands are run from the Foundry-ZKsync directory.
@@ -52,7 +52,7 @@ foundryup-zksync --branch main
 foundryup-zksync --path path/to/foundry-zksync
 ```
 
-Alternatively, you can install via Cargo with the following command:
+Alternatively, you can install it via Cargo with the following command:
 
 ```sh
 cargo install --git https://github.com/matter-labs/foundry-zksync --profile release --locked forge cast

src/projects/working-on-an-existing-project.md

@@ -8,7 +8,7 @@ First, clone the project and run [`forge install`][install] inside the project d
 
 ```sh
 $ git clone https://github.com/PaulRBerg/foundry-template
-$ cd foundry-template 
+$ cd foundry-template
 $ forge install
 $ bun install # install Solhint, Prettier, and other Node.js deps
 ```
@@ -27,6 +27,10 @@ And to test, use [`forge test`][test]:
 {{#include ../output/foundry-template/forge-test:all}}
 ```
 
+> ℹ️ **Note**
+>
+> If you are already familiar with the foundry, you will notice the `—-zksync` flag; we’ll cover it in detail in the following sections.
+
 [paul]: https://github.com/PaulRBerg
 [template]: https://github.com/PaulRBerg/foundry-template
 [install]: ../reference/forge/forge-install.md

src/zksync-specifics/README.md

@@ -1,13 +1,36 @@
 # ZKSync Specifics
 
-- [Execution Overview](execution-overview.md)
-- [Compilation Overview](compilation-overview.md)
-- [Limitations](limitations/README.md)
-  - [General](limitations/general.md)
-  - [Compilation](limitations/compilation.md)
-  - [Broadcast](limitations/broadcast.md)
-  - [Cheatcodes](limitations/cheatcodes.md)
-- [Additional Cheatcodes](cheatcodes/README.md)
-  - [zkVm](cheatcodes/zkvm.md)
-- [Gas Overview](gas.md)
-- [Paymaster Overview](paymaster-overview.md)
+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.
+
+## Context
+
+Foundry-zkSync tests are initially [executed](execution-overview.md) in the EVM context (the traditional execution environment for Ethereum smart contracts). This is done to maintain compatibility with Ethereum tooling and to leverage Foundry features like [Cheatcodes](limitations/cheatcodes.md).
+
+![Features](../images/key-features.png)
+
+### Lifetime Execution
+
+A forge test begins execution in the EVM context but can switch to the EraVM context during the test for zkSync-specific features. Selecting the EraVM context ensures all calls and deployments are executed within zkSync.
+There are mainly three steps
+
+**Step 1)** Aggregate: [Dual compiling](compilation-overview.md) contracts
+
+![alt text](../images/lifetime/step-1.png)
+
+**Step 2)** Intercept: Overriding `CALL`s and `CREATE`s (see [limitations](limitations/README.md) for more details)
+
+![alt text](../images/lifetime/step-2.png)
+
+**Step 3)**: Assimilate: One-shot zkEVM execution (see [Standard Library](forge-zksync-std.md) for more details)
+
+![alt text](../images/lifetime/step-3.png)
+
+### Additional Information.
+
+It is essential before deep diving in to the details of how to run the tool. You significantly understand how [ZKsync](https://docs.zksync.io/) works.
+
+Don't hesitate to ask if you have specific questions regarding the tool or feature requests.
+
+### Having issues?
+
+If you have issues with the tool or don't know where to start, we strongly suggest you look at our [repo](https://github.com/matter-labs/foundry-zksync) and [closed issues](https://github.com/matter-labs/foundry-zksync/issues?q=is%3Aissue+is%3Aclosed), where we usually get deep dive into implementation details.

src/zksync-specifics/cheatcodes/README.md

@@ -1,11 +1,10 @@
 ## Additional Cheatcodes
 
-In addition to the existing [Cheatcodes](../../cheatcodes/README.md), there are additional cheatcodes to help within the ZKsync context.
-
+A few new cheatcodes have been added to the existing [Cheatcodes](../../cheatcodes/README.md) list to help within the ZKsync context,
 
 ### Cheatcodes Interface
 
-This is the extended Solidity interface for all ZKsync specific cheatcodes present in Forge.
+This is the extended Solidity interface for all ZKsync-specific cheatcodes present in Forge.
 
 ```solidity
 interface CheatCodesExt {
@@ -19,20 +18,23 @@ interface CheatCodesExt {
         bytes calldata zkDeployedBytecode
     ) external pure;
 
-    /// Enables/Disables use ZK-VM usage for transact/call and create instructions.
+    /// Enables/Disables use ZK-VM for transact/call and create instructions.
     function zkVm(bool enable) external pure;
 
     /// When running in zkEVM context, skips the next CREATE or CALL, executing it on the EVM instead.
-    /// All `CREATE`s executed within this skip, will automatically have `CALL`s to their target addresses
-    /// executed in the EVM, and need not be marked with this cheatcode at every usage location.
+    /// All `CREATE`s executed within this skip will automatically have `CALL`s to their target addresses
+    /// executed in the EVM and need not be marked with this cheatcode at every usage location.
     function zkVmSkip() external pure;
 
     /// Enables the use of a paymaster for the next transaction.
     function zkUsePaymaster(address paymaster, bytes calldata paymaster_input) external pure;
+
+    /// Marks a given contract as a factory dependency only for the next CREATE or CALL operation
+    function zkUseFactoryDep(string calldata name) external pure;
+
 }
 ```
 
-
 ### Usage
 
-Refer to the [forge-zksync-std](../forge-zksync-std.md) section on how to access these cheatcodes in your tests.
+Refer to the [forge-zksync-std](../forge-zksync-std.md) section on accessing these cheatcodes in your tests.

src/zksync-specifics/cheatcodes/zk-register-contract.md

@@ -17,11 +17,11 @@ function zkRegisterContract(
 
 Registers bytecodes for ZK-VM for transact/call and create instructions.
 
-This is especially useful if there are certain contracts already deployed on-chain (EVM or ZKsync). Since we compile with both `solc` and `zksolc` as defined in the [Dual Compilation](../compilation-overview.md#dual-compilation) section, if there's an already existing EVM bytecode that must be translated into its zkEVM counterpart, we need to define it with this cheatcode.
+This is especially useful if specific contracts are already deployed on-chain (EVM or ZKsync). Since we compile with both `solc` and `zksolc` as defined in the [Dual Compilation](../compilation-overview.md#dual-compilation) section, if there's an already existing EVM bytecode that must be translated into its zkEVM counterpart, we need to define it with this cheatcode.
 
-Such an operation must be carried out separately where the source of the pre-deployed contract must be obtained and compiled with zksolc. The artifact json will contain the `zkBytecodeHash` and `zkDeployedBytecode` parameters. The process is similar for obtaining EVM parameters with `solc` - `evmBytecodeHash`, `evmDeployedBytecode`, `evmBytecode`.
+Such an operation must be carried out separately. The source of the pre-deployed contract must be obtained and compiled with zksolc. The json artifact will contain the `zkBytecodeHash` and `zkDeployedBytecode` parameters. The process is similar for obtaining EVM parameters with `solc` - `evmBytecodeHash`, `evmDeployedBytecode`, and `evmBytecode`.
 
-The `name` parameter must be unique if possible and not clash with locally existing contracts.
+The `name` parameter must be unique and not clash with locally existing contracts.
 
 ### Examples
 
@@ -35,7 +35,7 @@ The `name` parameter must be unique if possible and not clash with locally exist
 /// }
 
 vmExt.zkVm(true);
-ILeetContract(address(65536)).leet();       // fails, as the contract was not found locally so not migrated to zkEVM
+ILeetContract(address(65536)).leet();       // fails, as the contract was not found locally, so not migrated to zkEVM
 
 
 vmExt.zkRegisterContract("LeetContract", 0x111.., 0x222.., 0x333..., 0x444..., 0x555...); // register LeetContract for migration

src/zksync-specifics/cheatcodes/zk-use-factory-dep.md

@@ -8,7 +8,7 @@ function zkUseFactoryDep(string calldata name) external pure;
 
 ### Description
 
-Marks a given contract as a factory dependency only for the next CREATE or CALL, unmarking it afterwards, similar to [`prank`](../../cheatcodes/prank.md).
+Marks a given contract as a factory dependency only for the next CREATE or CALL, unmarking it afterward, similar to [`prank`](../../cheatcodes/prank.md).
 
 This cheatcode is useful when deploying contracts through factories that do not directly depend on a given contract, as it allows explicitly marking this type of contract as a factory dependency, enabling the factory to deploy the contract.
 More information on factory dependencies can be found in the [official ZKsync docs](https://docs.zksync.io/build/developer-reference/ethereum-differences/contract-deployment#note-on-factory_deps).

src/zksync-specifics/cheatcodes/zk-use-paymaster.md

@@ -28,7 +28,7 @@ contract Test is TestExt {
 }
 ```
 
-The paymaster flow depends on the type of paymaster used. Here's an example of the simplest usage of a 'general' paymaster in Foundry:
+The paymaster flow depends on the type of paymaster used. Here's an example of the most straightforward usage of a 'general' paymaster in Foundry:
 
 1. Write a custom paymaster:
 

src/zksync-specifics/cheatcodes/zk-vm-skip.md

@@ -8,9 +8,8 @@ function zkVmSkip() external pure;
 
 ### Description
 
-When running in zkEVM context, skips the next CREATE or CALL, executing it on the EVM instead.
-All `CREATE`s executed within this skip, will automatically have `CALL`s to their target addresses
-executed in the EVM, and need not be marked with this cheatcode at every usage location.
+When running in zkEVM context, skips the next `CREATE` or `CALL`, executing it on the EVM instead.
+All `CREATE`s executed within this skip will automatically have `CALL`s to their target addresses executed in the EVM and need not be marked with this cheatcode at every usage location.
 
 Skipping the next operation in zkEVM does not involve [migrating](../execution-overview.md#execution-overview) storages as is done for [zkVm](./zk-vm.md) cheatcode.
 

src/zksync-specifics/cheatcodes/zk-vm.md

@@ -10,11 +10,11 @@ function zkVm(bool enable) external pure;
 
 Enables/Disables ZKsync context for transact/call and create instructions within a test or script execution.
 
-Switching VMs is a intensive process that translates the entire storage back-and-forth between EVM and zkEVM, and as such must be used sparingly in a test to switch between contexts. 
+Switching VMs is an intensive process that translates the entire storage back and forth between EVM and zkEVM. As such, it must be used sparingly in a test to switch between contexts. 
 
 See [Execution Overview](../execution-overview.md#execution-overview) for further details.
 
-See [zkVmSkip](./zk-vm-skip.md) for a one-off and much simpler operation.
+See [zkVmSkip](./zk-vm-skip.md) for a more straightforward one-off operation.
 
 ### Examples
 

src/zksync-specifics/compilation-overview.md

@@ -1,10 +1,15 @@
 ## Compilation Overview
 
-[zksolc](https://github.com/matter-labs/era-compiler-solidity/releases) is the compiler used by ZKsync 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)
+[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)
 
 ### Dual Compilation
 
-To allow switching back and forth between EVM and zkEVM as defined in the [Execution Overview](./execution-overview.md), we compile the same contract with `solc` and `zksolc`. This dual-compiled contract can then be freely translated between both environments as needed. As such every contract in Foundry ZKsync always has two bytecodes attached - EVM bytecode and zkEVM bytecode, which are not equivalent.
+To allow switching back and forth between EVM and zkEVM as defined in the [Execution Overview](./execution-overview.md), we compile the same contract with `solc` and `zksolc`. This dual-compiled contract can then be freely translated between both environments as needed. As such, every contract in Foundry ZKsync always has two bytecodes attached - EVM bytecode and zkEVM bytecode, which are not equivalent.
+
+> ℹ️ **Note**
+>
+> If you run the example listed in the [Getting Started](../getting-started/first-steps.md) section at the beginning of the book, you can check them out in the `out` and `zkout` folders
+
 
 ### Limitations
 

src/zksync-specifics/configuration-overview.md

@@ -1,10 +1,10 @@
 ## Configuration Overview
 
-Foundry-ZKsync adds additional configuration options that can be specified in the `foundry.toml`. 
+Foundry-ZKsync adds some new configuration options that can be specified in the `foundry.toml`. 
 
 These include the following:
 
-- [Project Configuration](../reference/config/project.md#zksync-settings)
+- [Project Configuration](../reference/config/project.md)
 - [Testing Configuration](../reference/config/testing.md)
   - [Fuzz](../reference/config/testing.md#no_zksync_reserved_addresses)
   - [Invariant](../reference/config/testing.md#no_zksync_reserved_addresses-1)

src/zksync-specifics/examples/README.md

@@ -1,4 +1,10 @@
 # ZKsync specific examples
 
-- [Paymaster Approval Based](paymaster-approval-based.md)
-- [General Flow Paymaster](general-paymaster.md)
+Here, you can see a few short examples of the tool running so you could experience the magic right away.
+
+- [Paymaster Approval Based](paymaster-approval-based.md): use of an approval-based paymaster contract
+- [General Flow Paymaster](general-paymaster.md): use of a general flow paymaster contract. 
+- [Ledger](ledger.md): use a Ledger device to interact with ZKsync network.
+- [Smart Account](smart-account.md): configuration and deployment of a multisig smart account.
+
+Enjoy!