add trace and event sections, hide unsupported sections (#12)

* add trace and event sections, hide unsupported sections

* commit missing files

* update trace and compilation section

src/SUMMARY.md

@@ -25,14 +25,15 @@
   - [General](./zksync-specifics/limitations/general.md)
   - [Compilation](./zksync-specifics/limitations/compilation.md)
   - [Broadcast](./zksync-specifics/limitations/broadcast.md)
+  - [Events](./zksync-specifics/limitations/events.md)
+  - [Traces](./zksync-specifics/limitations/traces.md)
   - [Cheatcodes](./zksync-specifics/limitations/cheatcodes.md)
 - [Additional Cheatcodes](./zksync-specifics/cheatcodes/README.md)
   - [zkVm](./zksync-specifics/cheatcodes/zkvm.md)
 
 # Supported Commands Overview
 - [Command List](./supported-commands/README.md)
 
-<!--
 # Forge Overview
 
 - [Overview of Forge](forge/README.md)
@@ -53,7 +54,7 @@
     <!--  - [Mutation Testing]() 
     <!-- - [Linting and Formatting]() 
     <!-- - [Generating Documentation]() 
-<!-- - [Deploying and Verifying](./forge/deploying.md)
+- [Deploying and Verifying](./forge/deploying.md)
 - [Gas Tracking](./forge/gas-tracking.md)
   - [Gas Reports](./forge/gas-reports.md)
   - [Gas Snapshots](./forge/gas-snapshots.md)
@@ -63,13 +64,10 @@
 
 - [Overview of Cast](./cast/README.md)
 
-# Anvil Overview
+# Not Supported
 
-- [Overview of Anvil](./anvil/README.md)
-
-# Chisel Overview
-
-- [Overview of Chisel](./chisel/README.md)
+- [Anvil](./anvil/README.md)
+- [Chisel](./chisel/README.md)
 
 # Configuration
 
@@ -84,14 +82,14 @@
 # Tutorials
 
 - [Best Practices](./tutorials/best-practices.md)
-- [Creating an NFT with Solmate](./tutorials/solmate-nft.md)
-- [Docker and Foundry](./tutorials/foundry-docker.md)
-- [Testing EIP-712 Signatures](./tutorials/testing-eip712.md)
-- [Solidity Scripting](./tutorials/solidity-scripting.md)
-- [Deterministic deployment using CREATE2](./tutorials/create2-tutorial.md)
-- [Forking Mainnet with Cast and Anvil](./tutorials/forking-mainnet-with-cast-anvil.md)
-- [Learning Foundry Videos](./tutorials/learn-foundry.md)
-<!-- - [Incremental Adoption]() 
+<!-- - [Creating an NFT with Solmate](./tutorials/solmate-nft.md) -->
+<!-- - [Docker and Foundry](./tutorials/foundry-docker.md) -->
+<!-- - [Testing EIP-712 Signatures](./tutorials/testing-eip712.md) -->
+<!-- - [Solidity Scripting](./tutorials/solidity-scripting.md) -->
+<!-- - [Deterministic deployment using CREATE2](./tutorials/create2-tutorial.md) -->
+<!-- - [Forking Mainnet with Cast and Era Test Node](./tutorials/forking-mainnet-with-cast-anvil.md) -->
+<!-- - [Learning Foundry Videos](./tutorials/learn-foundry.md) -->
+<!-- - [Incremental Adoption]() !-->
 
 # Appendix
 
@@ -382,8 +380,8 @@
       - [cast wallet verify](./reference/cast/cast-wallet-verify.md)
       - [cast wallet import](./reference/cast/cast-wallet-import.md)
       - [cast wallet list](./reference/cast/cast-wallet-list.md)
-  - [`anvil` Reference](./reference/anvil/README.md)
-  - [`chisel` Reference](./reference/chisel/README.md)
+  <!-- - [`anvil` Reference](./reference/anvil/README.md) -->
+  <!-- - [`chisel` Reference](./reference/chisel/README.md) -->
   - [Config Reference](./reference/config/README.md)
     - [Overview](./reference/config/overview.md)
     - [Project](./reference/config/project.md)
@@ -493,6 +491,8 @@
     - [Snapshots](./cheatcodes/snapshots.md)
     - [RPC](./cheatcodes/rpc.md)
     - [Files](./cheatcodes/fs.md)
+    - [ZKsync](./zksync-specifics/cheatcodes/README.md)
+      - [zkVm](./zksync-specifics/cheatcodes/zkvm.md)
   - [Forge Standard Library Reference](./reference/forge-std/README.md)
     - [Std Logs](./reference/forge-std/std-logs.md)
     - [Std Assertions](./reference/forge-std/std-assertions.md)

src/anvil/README.md

@@ -2,30 +2,6 @@
 
 Anvil is a local testnet node shipped with Foundry. You can use it for testing your contracts from frontends or for interacting over RPC.
 
-Anvil is part of the Foundry suite and is installed alongside `forge`, `cast`, and `chisel`. If you haven't installed Foundry yet, see [Foundry installation](../getting-started/installation.md). 
-
-> Note: If you have an older version of Foundry installed, you'll need to re-install `foundryup` in order for Anvil to be downloaded.
-
-### How to use Anvil
-
-To use Anvil, simply type `anvil`. You should see a list of accounts and private keys available for use, as well as the address and port that the node is listening on. 
-
-Anvil is highly configurable. You can run `anvil -h` to see all the configuration options.
-
-Some basic options are:
-
-```bash
-#  Number of dev accounts to generate and configure. [default: 10]
-anvil -a, --accounts <ACCOUNTS>
-
-# The EVM hardfork to use. [default: latest]
-anvil --hardfork <HARDFORK>
-
-# Port number to listen on. [default: 8545]
-anvil  -p, --port <PORT>
-```
-
-> 📚 **Reference**
->
-> See the [`anvil` Reference](../reference/anvil/) for in depth information on Anvil and its capabilities.
+Officially we do not support anvil for ZKsync related operations.
 
+An alternative to anvil is current recommended in [ZKsync Era In-Memory Node](https://github.com/matter-labs/era-test-node)

src/chisel/README.md

@@ -3,21 +3,4 @@
 Chisel is an advanced Solidity REPL shipped with Foundry. It can be used to quickly test the behavior of Solidity snippets
 on a local or forked network.
 
-Chisel is part of the Foundry suite and is installed alongside `forge`, `cast`, and `anvil`. If you haven't installed Foundry
-yet, see [Foundry installation](../getting-started/installation.md). 
-
-> Note: If you have an older version of Foundry installed, you'll need to re-install `foundryup` in order for Chisel to be downloaded.
-
-### How to use Chisel
-
-To use Chisel, simply type `chisel`. From there, start writing Solidity code! Chisel will offer verbose feedback on each input.
-
-Chisel can be used both within and outside of a foundry project. If the binary is executed in a Foundry project root, Chisel will
-inherit the project's configuration options.
-
-To see available commands, type `!help` within the REPL.
-
-> 📚 **Reference**
->
-> See the [`chisel` Reference](../reference/chisel/) for in depth information on Chisel and its capabilities.
-
+Officially we do not support chisel for ZKsync related operations.

src/forge/cheatcodes.md

@@ -1,5 +1,10 @@
 ## Cheatcodes
 
+
+> 🚨 **Important**
+>
+> See [Cheatcode Limitations](../zksync-specifics/limitations/cheatcodes.md) when using cheatcodes in ZKsync context.
+
 Most of the time, simply testing your smart contracts outputs isn't enough. To manipulate the state of the blockchain, as well as test for specific reverts and events, Foundry is shipped with a set of cheatcodes.
 
 Cheatcodes allow you to change the block number, your identity, and more. They are invoked by calling specific functions on a specially designated address: `0x7109709ECfa91a80626fF3989D68f67F5b1DD12D`.

src/forge/debugger.md

@@ -1,5 +1,10 @@
 ## Debugger
 
+> 🚨 **Important**
+>
+> Debugger in not officially supported for ZKsync.
+>
+
 Forge ships with an interactive debugger.
 
 The debugger is accessible on [`forge debug`](../reference/forge/forge-debug.md) and on [`forge test`](../reference/forge/forge-test.md).

src/forge/deploying.md

@@ -11,7 +11,7 @@ To deploy a contract, you must provide a RPC URL (env: `ETH_RPC_URL`) and the pr
 To deploy `MyContract` to a network:
 
 ```sh
-$ forge create --rpc-url <your_rpc_url> --private-key <your_private_key> src/MyContract.sol:MyContract
+$ forge create --zksync --rpc-url <your_rpc_url> --private-key <your_private_key> src/MyContract.sol:MyContract
 compiling...
 success.
 Deployer: 0xa735b3c25f...
@@ -44,7 +44,8 @@ contract MyToken is ERC20 {
 Additionally, we can tell Forge to verify our contract on Etherscan, Sourcify or Blockscout, if the network is supported, by passing `--verify`.
 
 ```sh
-$ forge create --rpc-url <your_rpc_url> \
+$ forge create --zksync \
+    --rpc-url <your_rpc_url> \
     --constructor-args "ForgeUSD" "FUSD" 18 1000000000000000000000 \
     --private-key <your_private_key> \
     --etherscan-api-key <your_etherscan_api_key> \
@@ -78,6 +79,7 @@ Here's how to verify it:
 
 ```bash
 forge verify-contract \
+    --zksync \
     --chain-id 11155111 \
     --num-of-optimizations 1000000 \
     --watch \
@@ -100,7 +102,7 @@ If the `--watch` flag was not supplied, you can check
 the verification status with the [`forge verify-check`](../reference/forge/forge-verify-check.md) command:
 
 ```bash
-$ forge verify-check --chain-id 11155111 <GUID> <your_etherscan_api_key>
+$ forge verify-check --zksync --chain-id 11155111 <GUID> <your_etherscan_api_key>
 Contract successfully verified.
 ```
 

src/forge/fork-testing.md

@@ -7,6 +7,8 @@ Forge supports testing in a forked environment with two different approaches:
 
 Which approach to use? Forking mode affords running an entire test suite against a specific forked environment, while forking cheatcodes provide more flexibility and expressiveness to work with multiple forks in your tests. Your particular use case and testing strategy will help inform which approach to use.
 
+Note that ZKsync context will be set accordingly based on the fork url, so the `--zksync` flag need not be passed.
+
 ### Forking Mode
 
 To run all tests in a forked environment, such as a forked Ethereum mainnet, pass an RPC URL via the `--fork-url` flag:

src/forge/gas-reports.md

@@ -1,5 +1,9 @@
 ## Gas Reports
 
+> 🚨 **Important**
+>
+> Gas reports may not be entirely accurate in the ZKsync context. This is mostly due to the additional overhead to executing each `CREATE` or `CALL` in its own zkEVM which has additional bootloader gas costs.
+
 Forge can produce gas reports for your contracts. You can configure which contracts output gas reports via the `gas_reports` field in `foundry.toml`.
 
 To produce reports for specific contracts:

src/forge/gas-snapshots.md

@@ -1,5 +1,9 @@
 ## Gas Snapshots
 
+> 🚨 **Important**
+>
+> Gas snapshots may not be entirely accurate in the ZKsync context. This is mostly due to the > additional overhead to executing each `CREATE` or `CALL` in its own zkEVM which has additional bootloader gas costs.
+
 Forge can generate gas snapshots for all your test functions. This can
 be useful to get a general feel for how much gas your contract will consume,
 or to compare gas usage before and after various optimizations.

src/forge/gas-tracking.md

@@ -1,5 +1,9 @@
 ## Gas Tracking
 
+> 🚨 **Important**
+>
+> Gas tracking may not be entirely accurate in the ZKsync context. This is mostly due to the additional overhead to executing each `CREATE` or `CALL` in its own zkEVM which has additional bootloader gas costs.
+
 Forge can help you estimate how much gas your contract will consume.
 
 Currently, Forge ships with two different tools for this job, but they may be merged in the future:

src/forge/tests.md

@@ -40,4 +40,4 @@ The default behavior for `forge test` is to only display a summary of passing an
 
 Forge can re-run your tests when you make changes to your files using `forge test --watch`.
 
-By default, only changed test files are re-run. If you want to re-run all tests on a change, you can use `forge test --watch --run-all`.
+By default, only changed test files are re-run. If you want to re-run all tests on a change, you can use `forge test --zksync --watch --run-all`.

src/forge/traces.md

@@ -36,6 +36,8 @@ The gas usage (marked in square brackets) is for the entirety of the function ca
 
 The gas unaccounted for is due to some extra operations happening between calls, such as arithmetic and store reads/writes.
 
+
+
 Forge will try to decode as many signatures and values as possible, but sometimes this is not possible. In these cases, the traces will appear like so:
 
 ```ignore
@@ -51,3 +53,12 @@ Some traces might be harder to grasp at first glance. These include:
 - `InvalidFEOpcode` means that an undefined bytecode value has been encountered during execution. The EVM catches the unknown bytecode and returns the `INVALID` opcode instead, of value `0xFE`. You can find out more [here](https://www.evm.codes/#fe).
 
 For a deeper insight into the various traces, you can explore the [revm source code](https://github.com/bluealloy/revm/blob/main/crates/interpreter/src/instruction_result.rs).
+
+### ZKsync Limitations
+
+In addition to the above anomalies of incorrect gas and un-decodable traces, there are additional caveats within the ZKsync context:
+
+* The events emitted from within the zkEVM will not show on traces. See [events](../zksync-specifics/limitations/events.md) in zkEVM.
+* The system call traces from within the zkEVM's bootloader are currently ignored in order to simplify the trace output.
+* Executing each `CREATE` or `CALL` in its own zkEVM has additional bootloader gas costs, which may sometimes not be accounted in the traces. The ignored bootloader system calls, have a heuristic in-place to sum up their gas usage to the nearest non-system parent call, but this may also not add up accurately.
+

src/projects/creating-a-new-project.md

@@ -1,6 +1,6 @@
 ## Creating a New Project
 
-To start a new project with Foundry, use [`forge init`](../reference/forge/forge-init.md):
+To start a new project with Foundry-ZKsync, use [`forge init`](../reference/forge/forge-init.md):
 
 ```sh
 {{#include ../output/hello_foundry/forge-init:command}}
@@ -35,6 +35,6 @@ And run the tests:
 {{#include ../output/hello_foundry/forge-test:all}}
 ```
 
-You'll notice that two new directories have popped up: `out` and `cache`.
+You'll notice that two new directories have popped up: `out`, `zkout` and `cache`.
 
-The `out` directory contains your contract artifact, such as the ABI, while the `cache` is used by `forge` to only recompile what is necessary.
+The `out` directory contains your EVM contract artifact, such as the ABI, the `zkout` directory contains the zkEVM contract artifacts, while the `cache` is used by `forge` to only recompile what is necessary.

src/tutorials/forking-mainnet-with-cast-anvil.md

@@ -1,4 +1,4 @@
-## Forking Mainnet with Cast and Anvil
+## Forking Mainnet with Cast and Era Test Node
 
 ### Introduction
 

src/zksync-specifics/limitations/compilation.md

@@ -32,4 +32,49 @@ Error: assembly-to-bytecode conversion: assembly parse error Label DEFAULT_UNWIN
 for either PC or constant at offset 65947 that is more than 65535 addressable space
 ```
 
-As an attempt the same contract can be compiled with `--zk-force-evmla=true`, but if it doesn't help then the contract must be split into smaller units.
+#### Solution
+
+There are three possible solutions to address this issue:
+
+1. **Compilation with `--zk-force-evmla=true`:**
+
+    You can attempt to compile the contract using ZKsync's EVM legacy architecture by adding the `--zk-force-evmla=true` flag. This can sometimes bypass the contract size limit by compiling in a different mode.
+
+    Example command:
+    ```bash
+    forge build --zk-force-evmla=true --zksync
+    ```
+
+1. **Compilation with `--zk-fallback-oz=true`:**
+
+    If the contract size still exceeds the limit, try compiling with optimization level `-Oz` by using the `--zk-fallback-oz=true` flag. This tells the compiler to fall back to `-Oz` optimization when the bytecode is too large, potentially reducing the contract size further.
+
+    Example command:
+    ```bash
+    forge build --zk-fallback-oz=true --zksync
+    ```
+
+1. **Split the Contract into Smaller Units**
+
+    If neither of the above flags resolves the issue, the contract must be refactored into smaller, modular contracts. This involves separating your logic into different contracts and using contract inheritance or external contract calls to maintain functionality.
+
+    **Before (single large contract):**
+    ```solidity
+    contract LargeContract {
+        function largeFunction1() public { /* complex logic */ }
+        function largeFunction2() public { /* complex logic */ }
+        // Additional large functions and state variables...
+    }
+    ```
+    **After (multiple smaller contracts):**
+    ```solidity
+    contract ContractPart1 {
+        function part1Function() public { /* logic from largeFunction1 */ }
+    }
+    contract ContractPart2 {
+        function part2Function() public { /* logic from largeFunction2 */ }
+    }
+    contract MainContract is ContractPart1, ContractPart2 {
+        // Logic to combine the functionalities of both parts
+    }
+    ```