Zkutils comments (#81)

* zk_utils comment

* update developer comments for zkutils and zksolc

* update doc

* Update README.md

* Update README.md

README.md

@@ -10,8 +10,8 @@ Currently only Hardhat has developed functionality for zkSync. The purpose of th
 - [**Quick Start / Installation**](https://github.com/matter-labs/foundry-zksync#quick-start--installation)
 - [**v0.0 Feature Set**](https://github.com/matter-labs/foundry-zksync#feature-set)
 - [**Environment Variables**](https://github.com/matter-labs/foundry-zksync#environment-variables)
-- [**Blockchain Interaction**](https://github.com/matter-labs/foundry-zksync/blob/main/README.md#blockchain-interaction)
-- [**Bridging Assets**](https://github.com/matter-labs/foundry-zksync#bridging-assets-with-cast-zk-send)
+- [**Blockchain Interaction**](https://github.com/matter-labs/foundry-zksync#blockchain-interaction)
+- [**Bridging Assets**](https://github.com/matter-labs/foundry-zksync#bridging-assets-l1--l2)
 - [**Compilation**](https://github.com/matter-labs/foundry-zksync#compilation)
 - [**Deployment**](https://github.com/matter-labs/foundry-zksync#deployment)
 - [**Contract Interaction**](https://github.com/matter-labs/foundry-zksync#contract-interaction)
@@ -43,7 +43,7 @@ $ cargo build -p foundry-cli
 ```
 ---
 
-## Version 0.0
+## Version 0.0 (Linux & Mac)
 
 We need to establish the functionality we want for release v0.0 of this implementation. Below we will specify the exact features to accomplish our v0.0 release.
 
@@ -66,7 +66,7 @@ By providing the following environment variables in the `.env` file at the `PROJ
 # ETH_RPC_URL can be used to replace --rpc-url in command line 
 ETH_RPC_URL=http://localhost:3050
 
-# ZKSYNC_RPC_URL can be used to replace --l2-url in command line 
+# ZKSYNC_RPC_URL can be used to replace --l2-url in command line for zk-deposit
 ZKSYNC_RPC_URL=https://zksync2-testnet.zksync.dev
 
 # CHAIN can be used to replace --chain in command line  
@@ -216,8 +216,8 @@ Bridging options:
   -a, --amount <AMOUNT> Amount of token to bridge. Required value when bridging
 ```
 
-```
-#### Example Usage
+
+#### Example Usage:
 ```bash
 ../foundry-zksync/target/debug/zkcast zk-send --withdraw 0x36615Cf349d7F6344891B1e7CA7C72883F5dc049 --amount 1000000 --rpc-url http://localhost:3050 --private-key 7726827caac94a7f9e1b160f7ea819f172f7b6f9d2a97f992c38edeab82d4110 --chain 270
 ```
@@ -284,7 +284,13 @@ Example terminal output:
 
 ![image](https://user-images.githubusercontent.com/76663878/236305625-8c7519e2-0c5e-492f-a4bc-3b019a95e34f.png)
 
+NOTE: Currently, until `forge remappings` are implemented, import paths must be relative to the contract importing it:
+![image](https://github.com/matter-labs/foundry-zksync/assets/76663878/490b34f4-e286-42a7-8570-d4b228ec10c7)
+
+In this example, `SimpleFactory.sol` is in the `src/is-system/` folder.
+
 ---
+
 ## Deployment
 
 ***v0.0*** ***Command***:
@@ -528,7 +534,7 @@ constructor(bytes32 _aaBytecodeHash) {
         aaBytecodeHash = _aaBytecodeHash;
     }
 ```
-`Note: `aaBytecodeHash` = BytecodeHash of "TwoUserMultiSig.sol"`
+Note: `aaBytecodeHash` = Bytecode hash of `TwoUserMultiSig.sol`
 
 #### To deploy a contract that deploys other contracts it is necessary to provide the bytecodes of the children contracts in the `factory-deps` field of the transaction. This can be accomplished by using the `--factory-deps` flag and providing the full contract path in the format: `<path>:<contractname>`
 

cli/src/cmd/cast/zk_utils.rs

@@ -1,19 +1,29 @@
-/// This module handles transactions related to ZkSync. It defines the
-/// CLI arguments for the `cast zk-send` command and provides functionality for sending
-/// transactions and withdrawing from Layer 2 to Layer 1.
+/// The `zk_utils` module provides utility functions specifically designed for interacting with zkSync,
+/// an Ethereum layer 2 scaling solution.
 ///
-/// The module contains the following components:
-/// - `ZkSendTxArgs`: Struct representing the command line arguments for the `cast zk-send` subcommand.
-///     It includes parameters such as the destination address, function signature, function arguments,
-///     withdraw flag, token to bridge, amount to bridge, transaction options, and Ethereum options.
-/// - `ZkSendTxArgs` implementation: Defines methods to run the subcommand and print the transaction receipt.
-/// - Helper functions:
-///     - `print_receipt`: Prints the receipt of the transaction, including transaction hash, gas used,
-///         effective gas price, block number, and deployed contract address.
-///     - `get_to_address`: Retrieves the recipient address of the transaction.
-///     - `parse_decimal_u256`: Parses a decimal string into a U256 number.
-///     - `decode_hex`: Decodes a hexadecimal string into a byte vector.
-
+/// This module encapsulates various functionalities related to zkSync, including retrieving the RPC URL for Ethereum,
+/// parsing and attaching a default port to a URL string, obtaining the private key, retrieving the chain configuration,
+/// and creating a signer for zkSync transactions.
+///
+/// Functions in this module:
+///
+/// - `get_rpc_url`: Retrieves the RPC URL for Ethereum. Returns `Result<String>` with the RPC URL if successful, or an error
+///   message if the RPC URL was not provided.
+///
+/// - `get_url_with_port`: Parses a URL string and attaches a default port if one is not specified. Returns an `Option<String>`
+///   with the parsed URL if successful, or `None` if the input was not a valid URL.
+///
+/// - `get_private_key`: Gets the private key from the Ethereum options. Returns `Result<H256>` with the private key as `H256`
+///   if successful, or an error message if the private key was not provided.
+///
+/// - `get_chain`: Gets the chain from the Ethereum options. Returns `Result<Chain>` with the chain configuration if successful,
+///   or an error message if the chain was not provided.
+///
+/// - `get_signer`: Creates a signer from the private key and the chain. Returns a `Signer<PrivateKeySigner>` instance for signing
+///   transactions on the zkSync network.
+///
+/// - `decode_hex`: Decodes a hexadecimal string into a byte vector. Returns `Result<Vec<u8>>` with the decoded byte vector
+///   if successful, or a `ParseIntError` if the decoding fails.
 pub mod zk_utils {
     use eyre::Result;
     use foundry_config::Chain;

cli/src/cmd/forge/zksolc.rs

@@ -1,27 +1,29 @@
-/// This module provides a comprehensive interface for compiling Solidity contracts using the ZkSolc
-/// compiler. The ZkSolc compiler is designed for zero-knowledge proofs, making it an invaluable tool
-/// for privacy-focused smart contracts.
+/// This module provides the implementation of the ZkSolc compiler for Solidity contracts.
+/// ZkSolc is a specialized compiler that supports zero-knowledge (ZK) proofs for smart contracts.
 ///
-/// # Key Components:
-/// - `ZkSolc`: Represents the main entity in this module.
-///     - Manages project details, including paths and configurations.
-///     - Stores the compiler path.
-///     - Contains the `compile` method which compiles contracts in the project's 'sources' directory
-///       and its subdirectories.
-/// - `ZkSolcOpts`: A utility struct that allows users to specify options for creating `ZkSolc`.
+/// The `ZkSolc` struct represents an instance of the compiler, and it is responsible for compiling
+/// Solidity contracts and handling the output. It uses the `solc` library to interact with the Solidity compiler.
 ///
-/// # Functionality:
-/// - `ZkSolc::new`: Constructs a new `ZkSolc` instance using the provided `ZkSolcOpts` and project
-///   configurations.
-/// - `ZkSolc::compile`: Responsible for compiling the contracts. It performs the following operations:
-///     - Configures the Solidity compiler.
-///     - Parses JSON input.
-///     - Builds compiler arguments.
-///     - Handles the output of the compiler, including errors and warnings.
+/// The `ZkSolc` struct provides the following functionality:
 ///
-/// # Error Handling:
-/// - The methods in this module return the `Result` type from the `anyhow` crate.
-/// - This allows for flexible and easy-to-use error handling.
+/// - Configuration: It allows configuring the compiler path, system mode, and force-evmla options through
+///   the `ZkSolcOpts` struct.
+///
+/// - Compilation: The `compile` method initiates the compilation process. It collects the source files,
+///   parses the JSON input, builds compiler arguments, runs the compiler, and handles the output.
+///
+/// - Error and Warning Handling: The compiler output is checked for errors and warnings, and they are
+///   displayed appropriately. If errors are encountered, the process will exit with a non-zero status code.
+///
+/// - JSON Input Generation: The `parse_json_input` method generates the JSON input required by the compiler
+///   for each contract. It configures the Solidity compiler, saves the input to the artifacts directory, and
+///   handles the output.
+///
+/// - Source Management: The `get_versioned_sources` method retrieves the project sources, resolves the graph
+///   of sources and versions, and returns the sources grouped by Solc version.
+///
+/// - Artifact Path Generation: The `build_artifacts_path` and `build_artifacts_file` methods construct the
+///   path and file for saving the compiler output artifacts.
 use ansi_term::Colour::{Red, Yellow};
 use anyhow::{Error, Result};
 use ethers::prelude::{artifacts::Source, Solc};
@@ -93,7 +95,6 @@ pub struct ZkSolcOpts {
 /// In this example, the `ZkSolc` compiler is initialized with the provided compiler path and
 /// project configurations. The `compile` method is then invoked to compile the contracts, and any
 /// resulting errors are handled accordingly.
-// FIXME: let's add some more comments to the fields (and are you sure that all of them have to be public?)
 #[derive(Debug)]
 pub struct ZkSolc {
     project: Project,
@@ -446,7 +447,6 @@ impl ZkSolc {
         }
 
         if has_error {
-            // FIXME: avoid 'exits' (that's like 'panic') - instead try to return an error -- allowing more flexibility.
             exit(1);
         } else if has_warning {
             println!("Compiler run completed with warnings");

cli/src/cmd/forge/zksolc_manager.rs

@@ -270,8 +270,6 @@ impl ZkSolcManagerBuilder {
         let version = self.version.to_string();
         let download_url = self.download_url.to_owned();
         let compiler = self.get_compiler()?;
-        // FIXME: PathBuf (like String) - is more like a builder.. so when you 'built' your compiler's path
-        // you might want it to be just a 'path'  (by calling 'as_path()')
         let compilers_path = home_path.to_owned();
 
         let solc_version = parse_version(&version)?;