add cheatcodes, configuration, forge-zksync-std (#18)

src/SUMMARY.md

@@ -21,17 +21,21 @@
 - [Overview](./zksync-specifics/README.md)
 - [Execution Overview](./zksync-specifics/execution-overview.md)
 - [Compilation Overview](./zksync-specifics/compilation-overview.md)
+- [Configuration Overview](./zksync-specifics/configuration-overview.md)
 - [Limitations](./zksync-specifics/limitations/README.md)
   - [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)
+- [Forge-ZKSync Standard Library](./zksync-specifics/forge-zksync-std.md)
 - [Additional Cheatcodes](./zksync-specifics/cheatcodes/README.md)
-  - [zkVm](./zksync-specifics/cheatcodes/zkvm.md)
+  - [zkRegisterContract](./zksync-specifics/cheatcodes/zk-register-contract.md)
+  - [zkVm](./zksync-specifics/cheatcodes/zk-vm.md)
+  - [zkVmSkip](./zksync-specifics/cheatcodes/zk-vm-skip.md)
 
-# Supported Commands Overview
+# Supported Commands
 - [Command List](./supported-commands/README.md)
 
 # Forge Overview
@@ -40,7 +44,8 @@
 - [Tests](./forge/tests.md)
   - [Writing Tests](./forge/writing-tests.md)
   - [Cheatcodes](./forge/cheatcodes.md)
-  - [Forge Standard Library Overview](./forge/forge-std.md)
+  - [Forge Standard Library](./forge/forge-std.md)
+  - [Forge ZKsync Standard Library](./forge/forge-zksync-std.md)
   - [Understanding Traces](./forge/traces.md)
   - [Fork Testing](./forge/fork-testing.md)
   - [Replaying Failures](./forge/replay-testing.md)
@@ -58,7 +63,7 @@
 - [Gas Tracking](./forge/gas-tracking.md)
   - [Gas Reports](./forge/gas-reports.md)
   - [Gas Snapshots](./forge/gas-snapshots.md)
-- [Debugger](./forge/debugger.md)
+<!-- - [Debugger](./forge/debugger.md) -->
 
 # Cast Overview
 
@@ -69,17 +74,15 @@
 - [Anvil](./anvil/README.md)
 - [Chisel](./chisel/README.md)
 
-<!-- Hide Configuration for now
-
 # Configuration
 
 - [Configuring with `foundry.toml`](./config/README.md)
-- [Continuous Integration](./config/continuous-integration.md)
-- [Integrating with VSCode](./config/vscode.md)
-- [Shell Autocompletion](./config/shell-autocompletion.md)
-- [Static Analyzers](./config/static-analyzers.md)
-- [Integrating with Hardhat](./config/hardhat.md)
-- [Vyper support](./config/vyper.md)
+<!-- - [Continuous Integration](./config/continuous-integration.md) -->
+<!-- - [Integrating with VSCode](./config/vscode.md) -->
+<!-- - [Shell Autocompletion](./config/shell-autocompletion.md) -->
+<!-- - [Static Analyzers](./config/static-analyzers.md) -->
+<!-- - [Integrating with Hardhat](./config/hardhat.md) -->
+<!-- - [Vyper support](./config/vyper.md) -->
 
 
 <!-- Hide Tutorials for now
@@ -97,14 +100,12 @@
 <!-- - [Incremental Adoption]() !-->
 
 
-<!-- Hide Appendix for now
-
 # Appendix
 
-- [FAQ](./faq.md)
-- [Help us improve Foundry](./contributing.md)
+<!-- - [FAQ](./faq.md) -->
+<!-- - [Help us improve Foundry](./contributing.md) -->
 - [References](./reference/README.md)
-  - [CLI Reference](./reference/cli/README.md) <!-- CLI_REFERENCE START 
+  <!-- - [CLI Reference](./reference/cli/README.md)
     - [`forge`](./reference/cli/forge.md)
       - [`forge bind`](./reference/cli/forge/bind.md)
       - [`forge bind-json`](./reference/cli/forge/bind-json.md)
@@ -387,22 +388,20 @@
       - [cast wallet vanity](./reference/cast/cast-wallet-vanity.md)
       - [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)
+      - [cast wallet list](./reference/cast/cast-wallet-list.md) -->
   <!-- - [`anvil` Reference](./reference/anvil/README.md) -->
   <!-- - [`chisel` Reference](./reference/chisel/README.md) -->
-
-<!-- Hide References for now
-
   - [Config Reference](./reference/config/README.md)
     - [Overview](./reference/config/overview.md)
     - [Project](./reference/config/project.md)
     - [Solidity Compiler](./reference/config/solidity-compiler.md)
     - [Testing](./reference/config/testing.md)
-    - [In-line Configuration Testing](./reference/config/inline-test-config.md)
-    - [Formatter](./reference/config/formatter.md)
-    - [Documentation Generator](./reference/config/doc-generator.md)
-    - [Etherscan](./reference/config/etherscan.md)
-  - [Cheatcodes Reference](./cheatcodes/README.md)
+    <!-- - [In-line Configuration Testing](./reference/config/inline-test-config.md) -->
+    <!-- - [Formatter](./reference/config/formatter.md) -->
+    <!-- - [Documentation Generator](./reference/config/doc-generator.md) -->
+    <!-- - [Etherscan](./reference/config/etherscan.md) -->
+  <!-- [Cheatcodes Reference](./cheatcodes/README.md) -->
+    <!--
     - [Environment](./cheatcodes/environment.md)
       - [`warp`](./cheatcodes/warp.md)
       - [`roll`](./cheatcodes/roll.md)
@@ -503,9 +502,10 @@
     - [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)
+      - [zkVm](./zksync-specifics/cheatcodes/zk-vm.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)
       - [`fail`](./reference/forge-std/fail.md)
       - [`assertTrue`](./reference/forge-std/assertTrue.md)
@@ -566,7 +566,7 @@
     - [Script Utils](./reference/forge-std/script-utils.md)
       - [`computeCreateAddress`](./reference/forge-std/compute-create-address.md)
       - [`deriveRememberKey`](./reference/forge-std/derive-remember-key.md)
-    - [Console Logging](./reference/forge-std/console-log.md)
-  - [DSTest Reference](./reference/ds-test.md)
-- [Miscellaneous](./misc/README.md)
-  - [Struct encoding](./misc/struct-encoding.md)
+    - [Console Logging](./reference/forge-std/console-log.md) -->
+  <!-- - [DSTest Reference](./reference/ds-test.md)  --> -->
+<!-- - [Miscellaneous](./misc/README.md) -->
+  <!-- - [Struct encoding](./misc/struct-encoding.md) -->

src/forge/forge-zksync-std.md

@@ -0,0 +1,5 @@
+## Forge ZKsync Standard Library Overview
+
+Forge ZKsync Standard Library is an addition to the [Forge Standard Library](./forge-std.md) that adds further collection of helpful contracts that make writing tests easier, faster, and more user-friendly for the ZKsync ecosystem.
+
+Refer to this [section](../zksync-specifics/forge-zksync-std.md) for more details.

src/reference/config/README.md

@@ -4,7 +4,7 @@
 - [Project](./project.md)
 - [Solidity Compiler](./solidity-compiler.md)
 - [Testing](./testing.md)
-- [In-line test configuration](./inline-test-config.md)
+<!-- - [In-line test configuration](./inline-test-config.md)
 - [Formatter](./formatter.md)
 - [Documentation Generator](./doc-generator.md)
-- [Etherscan](./etherscan.md)
+- [Etherscan](./etherscan.md) -->

src/reference/config/project.md

@@ -72,3 +72,104 @@ The path to the broadcast transaction logs, relative to the root of the project.
 - Environment: `FOUNDRY_FORCE` or `DAPP_FORCE`
 
 Whether or not to perform a clean build, discarding the cache.
+
+
+### ZKsync Settings
+
+Additional zksync settings can be defined on the profile of choice by specifying `profile.<name>.zksync` section.
+
+For example to define the settings on `profile.default`:
+
+```toml
+[profile.default]
+# ...Normal foundry settings...
+
+[profile.default.zksync]
+# ...ZKSync specific settings...
+```
+
+##### `compile`
+
+- Type: boolean
+- Default: false
+
+Compile contracts for zkEVM.
+
+##### `startup`
+
+- Type: boolean
+- Default: true (will only have effect if `compile = true`)
+
+Requires `compile = true` to have an effect.   
+Enable ZKsync context on startup. This applies to tests, scripts, and any other commands that need to switch immediately to zkEVM on startup.
+
+##### `zksolc`
+
+- Type: string
+- Default: <latest-version>
+
+The zksolc version to use for compilation.
+
+##### `solc_path`
+
+- Type: string
+- Default: <default-zksolc-solc>
+
+The `solc` path to use during `zksolc` compilation.
+
+##### `bytecode_hash`
+
+- Type: boolean
+- Default: "none" 
+
+Whether to include the metadata hash for zksolc compiled bytecode.
+
+##### `fallback_oz`
+
+- Type: boolean
+- Default: false 
+
+Allow compiler to recompile using `optimizer_mode = 'z'` if contracts won't fit in the EraVM bytecode size limitations.
+
+##### `enable_eravm_extensions`
+
+- Type: boolean
+- Default: false
+
+Enable EraVM extensions (e.g. system-mode). This allows compilation of ZKsync-specific simulations.
+
+##### `force_evmla`
+
+- Type: boolean
+- Default: false 
+
+Force compilation via EVMLA instead of Yul codegen pipeline.
+
+##### `avoid_contracts`
+
+- Type: array of strings
+- Default: []
+
+List of glob patterns to avoid compiling with zksolc.
+
+##### `optimizer`
+
+- Type: boolean
+- Default: true 
+
+Enable optimizer on zksolc.
+
+##### `optimizer_mode`
+
+- Type: string
+- Default: '3'
+
+The zksolc optimizer mode (0 | 1 | 2 | 3 | s | z).
+
+##### `optimizer_details`
+
+- Type: object
+- Default: {}
+
+Allows specifying additional zksolc [Optimizer Details](https://github.com/matter-labs/era-compiler-solidity/blob/main/era-compiler-solidity/src/solc/standard_json/input/settings/optimizer/details.rs#L10).
+

src/reference/config/testing.md

@@ -386,6 +386,13 @@ The flag indicating whether to include push bytes values.
 
 The flag indicates whether to display console logs in fuzz tests or not. Note that in order to enable displaying console logs, you'll need to set `show_logs = true` and then use `forge test -vv` or set `verbosity >= 2`.
 
+##### `no_zksync_reserved_addresses`
+
+- Type: boolean
+- Default: false
+
+Avoid generating [reserved](../../zksync-specifics/limitations/general.md#reserved-address-range) ZKsync addresses within the fuzzer. This avoids having to use `vm.assume(addr > 65535)` during fuzzing that can ignore too many inputs causing `max_test_rejects` to trigger.
+
 
 ### Invariant
 
@@ -473,3 +480,11 @@ The flag indicating whether to include push bytes values. See also [fuzz.include
 - Environment: `FOUNDRY_INVARIANT_SHRINK_RUN_LIMIT`
 
 The maximum number of attempts to shrink a failed the sequence. Shrink process is disabled if set to 0.
+
+
+##### `no_zksync_reserved_addresses`
+
+- Type: boolean
+- Default: false
+
+Avoid generating [reserved](../../zksync-specifics/limitations/general.md#reserved-address-range) ZKsync addresses within the invariant test. This avoids having to use `vm.assume(addr > 65535)` during invariant testing that can ignore too many inputs causing `max_test_rejects` to trigger.

src/supported-commands/README.md

@@ -1,4 +1,4 @@
-##  Foundry-ZKSync supported commands
+##  Foundry-ZKSync Supported Commands
 
 This is a comprehensive review of all the Foundry commands actually supported in the actual stage of development.
 

src/zksync-specifics/cheatcodes/README.md

@@ -8,11 +8,28 @@ In addition to the existing [Cheatcodes](../../cheatcodes/README.md), there are
 This is the extended Solidity interface for all ZKsync specific cheatcodes present in Forge.
 
 ```solidity
-interface CheatCodes {
-    /// Existing forge cheatcodes
-    ...
+interface CheatCodesExt {
+    /// Registers bytecodes for ZK-VM for transact/call and create instructions.
+    function zkRegisterContract(
+        string calldata name,
+        bytes32 evmBytecodeHash,
+        bytes calldata evmDeployedBytecode,
+        bytes calldata evmBytecode,
+        bytes32 zkBytecodeHash,
+        bytes calldata zkDeployedBytecode
+    ) external pure;
 
     /// Enables/Disables use ZK-VM usage 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.
+    function zkVmSkip() external pure;
 }
 ```
+
+
+### Usage
+
+Refer to the [forge-zksync-std](../forge-zksync-std.md) section on how to access these cheatcodes in your tests.

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

@@ -0,0 +1,44 @@
+## `zkRegisterContract`
+
+### Signature
+
+```solidity
+function zkRegisterContract(
+    string calldata name,
+    bytes32 evmBytecodeHash,
+    bytes calldata evmDeployedBytecode,
+    bytes calldata evmBytecode,
+    bytes32 zkBytecodeHash,
+    bytes calldata zkDeployedBytecode
+) external pure;
+```
+
+### Description
+
+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.
+
+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`.
+
+The `name` parameter must be unique if possible and not clash with locally existing contracts.
+
+### Examples
+
+```solidity
+// LeetContract is pre-deployed on EVM on address(65536)
+
+/// interface ILeetContract {
+///     function leet() public {
+///         // do something
+///     }
+/// }
+
+vmExt.zkVm(true);
+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
+vmExt.zkVm(true);
+ILeetContract(address(65536)).leet();       // succeeds, as the contract was registered via cheatcode, so migrated to zkEVM
+```