-
Notifications
You must be signed in to change notification settings - Fork 43
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat: Migration guide for Foundry projects (#204)
What: - A migration guide for Foundry projects was added. It is short since 1) all the basic info is present on the getting started page 2) The discrepancies guide is not well-formed yet. - Existing guides have been updated with up-to-date info. - added some notes(note about foundry book, support section etc) --------- Co-authored-by: Dustin Brickwood <[email protected]> Co-authored-by: Sabrina <[email protected]>
- Loading branch information
3 people
authored
Sep 18, 2024
1 parent
1812e87
commit 1b43f03
Showing
10 changed files
with
1,120 additions
and
153 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,55 +1,83 @@ | ||
| --- | ||
| title: Overview | ||
| description: Learn about foundry-zksync. | ||
| description: Learn how to use Foundry ZKsync to build, test, and deploy smart contracts. Includes installation guides, and migration considerations. | ||
| --- | ||
|
|
||
| `foundry-zksync` is a specialized fork of [Foundry](https://github.com/foundry-rs/foundry), tailored for ZKsync. | ||
| [Foundry ZKsync](https://github.com/matter-labs/foundry-zksync) is a specialized fork of | ||
| [Foundry](https://github.com/foundry-rs/foundry), tailored for ZKsync. | ||
|
|
||
| It extends Foundry's capabilities for Ethereum app development to support ZKsync, allowing for the compilation, | ||
| deployment, testing, and interaction with smart contracts on ZKsync. | ||
| `foundry-zksync` introduces `--zksync` flag, or the use of `vm.zkVm(true)` to target the ZKsync VM. | ||
|
|
||
| This section covers everything | ||
| from installation to migration, ensuring that you’re equipped to begin using Foundry ZKsync effectively and efficiently. | ||
| For a more in-depth review of Foundry ZKsync please refer to the [Foundry ZKsync book on zksync.io](https://foundry-book.zksync.io/). | ||
|
|
||
| ::card-group | ||
| ::card | ||
| --- | ||
| title: Installation | ||
| icon: i-heroicons-cog-8-tooth-solid | ||
| to: /build/tooling/foundry/installation | ||
| --- | ||
| Set up your development environment with Foundry and ZKsync, ensuring you're ready to start building and testing your projects. | ||
| :: | ||
| ::card | ||
| --- | ||
| title: Getting Started | ||
| icon: i-heroicons-rocket-launch-solid | ||
| to: /build/tooling/foundry/getting-started | ||
| --- | ||
| Dive into the basics with a simple project setup, including running tests and deploying contracts on ZKsync. | ||
| :: | ||
| ::card | ||
| --- | ||
| title: Migration Guide | ||
| icon: i-heroicons-arrow-path-solid | ||
| to: /build/tooling/foundry/migration-guide/overview | ||
| --- | ||
| Step-by-step guide to migrating your existing projects to ZKsync using Foundry. | ||
| :: | ||
| ::card | ||
| --- | ||
| title: Testing | ||
| icon: i-heroicons-shield-exclamation-solid | ||
| to: /build/test-and-debug/foundry | ||
| --- | ||
| Learn best practices for testing your contracts with Foundry ZKsync | ||
| :: | ||
| :: | ||
|
|
||
| ### Status and Contribution | ||
|
|
||
| `foundry-zksync` is currently in its **alpha stage**, indicating ongoing development and potential for future enhancements. | ||
| Foundry ZKsync is currently in its **alpha stage**, indicating ongoing development and potential for future enhancements. | ||
| It is open-sourced, and contributions from the developer community are welcome. | ||
| For more details and contributions, visit the [GitHub repository](%%zk_git_repo_foundry-zksync%%). | ||
|
|
||
| ## Features and Limitations | ||
| ## Using Foundry with ZKsync | ||
|
|
||
| ### Features | ||
| To work with ZKsync, you only need to make a few minor adjustments to your existing | ||
| Foundry workflow. These changes ensure your smart contracts are fully compatible with ZKsync's zkEVM and reserved address space. | ||
|
|
||
| `foundry-zksync` offers a set of features designed to work with ZKsync, providing a comprehensive toolkit for smart contract deployment and interaction: | ||
| ### Differences | ||
|
|
||
| - **Smart Contract Deployment**: Easily deploy smart contracts to ZKsync mainnet, testnet, or a local test node. | ||
| - **Asset Bridging**: Bridge assets between L1 and L2, facilitating seamless transactions across layers. | ||
| - **Contract Interaction**: Call and send transactions to deployed contracts on %%zk_testnet_name%% or local test node. | ||
| - **Solidity Testing**: Write tests in Solidity 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. | ||
| - **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. | ||
| 1. **Compilation**: | ||
| - Contracts are compiled using both `solc` and `zksolc`. Foundry ZKsync manages this | ||
| automatically, but you should ensure the correct compiler versions are specified in your configuration (`foundry.toml`). | ||
|
|
||
| ### Limitations | ||
| 2. **Reserved Addresses**: | ||
| - ZKsync reserves addresses below `65536` for internal use. Ensure that any addresses you hardcode or use in tests are above this range. | ||
| - You can configure fuzz testing to avoid generating reserved addresses using the `no_zksync_reserved_addresses` option. | ||
|
|
||
| While `foundry-zksync` is **alpha stage**, there are some limitations to be aware of, but not limited to: | ||
| 3. **Fuzz Testing**: | ||
| - Fuzz tests can be configured to respect ZKsync's reserved address range. | ||
| You can use the `no_zksync_reserved_addresses = true` option in your test configuration to avoid manual filtering of invalid addresses. | ||
|
|
||
| - **Compile Time**: Some users may experience slow compiling. | ||
| - **Specific Foundry Features**: Currently features such as `--gas-report` or `--verify` may not work as intended. | ||
| We are actively working on providing support for these feature types. | ||
| - **Compiling Libraries**: Compiling non-inlinable libraries requires deployment and adding to configuration. | ||
| 4. **Running Tests on ZKsync**: | ||
| - To target ZKsync in your tests, you can enable ZKsync-specific behaviors by adding | ||
| `--zksync` to your `forge` commands or using `vm.zkVm(true)` in your test setup. | ||
|
|
||
| For more information please refer to [official docs](/build/tooling/hardhat/guides/compiling-libraries). | ||
| Foundry ZKsync simplifies developing and testing smart contracts on ZKsync with | ||
| minimal changes to your workflow. With the installation and migration guides, you’ll be able to start building quickly while benefiting from ZKsync's scalability. | ||
|
|
||
| ```toml | ||
| # In foundry.toml | ||
| libraries = [ | ||
| "src/MyLibrary.sol:MyLibrary:0xfD88CeE74f7D78697775aBDAE53f9Da1559728E4" | ||
| ] | ||
| ``` | ||
|
|
||
| ::callout{icon="i-heroicons-information-circle" color="blue"} | ||
| We are actively working to resolve limitations listed. Please check back on future releases for updates. | ||
| :: | ||
| For more details or to get started, check out the [Installation Guide](./installation) or dive into the [Getting Started](./getting-started) section. |
182 changes: 182 additions & 0 deletions
182
content/00.build/40.tooling/30.foundry/15.installation.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,182 @@ | ||
| --- | ||
| title: Installation | ||
| description: Learn how to install and configure Foundry for ZKsync | ||
| --- | ||
|
|
||
| This guide will walk you through installing Foundry ZKsync, a specialized toolchain | ||
| for developing, testing, and deploying smart contracts on ZKsync. You can install | ||
| Foundry ZKsync by using the `foundryup-zksync` installer, downloading precompiled binaries, or by building it from source. | ||
|
|
||
| ## Installing with `foundryup-zksync` | ||
|
|
||
| `foundryup-zksync` is the official installer for the Foundry ZKsync toolchain. | ||
| It allows you to easily install and manage the latest versions of `forge` and `cast`. | ||
|
|
||
| ::callout{icon="i-heroicons-information-circle-16-solid" color="amber"} | ||
| Please note that this installation overrides any existing forge and cast binaries in `~/.foundry`. | ||
| You can use forge without the `--zksync` flag for standard EVM chains. To revert to a previous installation, follow the instructions | ||
| on [Using foundryup on the official Foundry website](https://book.getfoundry.sh/getting-started/installation#using-foundryup). | ||
| :: | ||
|
|
||
| To install `foundryup-zksync`, follow these steps: | ||
|
|
||
| ### 1. Install via the provided script | ||
|
|
||
| ```bash | ||
| curl -L https://raw.githubusercontent.com/matter-labs/foundry-zksync/main/install-foundry-zksync | bash | ||
| ``` | ||
|
|
||
| By default, this will install the latest (nightly) precompiled versions | ||
| of `forge` and `cast`. To see more installation options, such as installing a specific version, run: | ||
|
|
||
| ```bash | ||
| foundryup-zksync --help | ||
| ``` | ||
|
|
||
| ### Important Notes | ||
|
|
||
| - Currently, only `forge` and `cast` are supported for ZKsync. Other commands retain their original behavior but may not work as intended. | ||
| - **Windows Users**: You need to use Git BASH or WSL, as `foundryup-zksync` does not support PowerShell or Cmd, | ||
| and we do not provide Windows executable binaries. Windows support is currently provided on a best-effort basis. | ||
|
|
||
| ## Precompiled Binaries | ||
|
|
||
| Precompiled binaries are available for download from the | ||
| [`foundry-zksync` GitHub releases page](https://github.com/matter-labs/foundry-zksync/releases). | ||
| We recommend using the latest nightly build to stay up-to-date with the latest features and fixes. | ||
|
|
||
| ### Available Binaries | ||
|
|
||
| - **macOS (Intel)**: [foundry_nightly_darwin_amd64.tar.gz](https://github.com/matter-labs/foundry-zksync/releases/download/nightly/foundry_nightly_darwin_amd64.tar.gz) | ||
| - **macOS (Apple)**: [foundry_nightly_darwin_arm64.tar.gz](https://github.com/matter-labs/foundry-zksync/releases/download/nightly/foundry_nightly_darwin_arm64.tar.gz) | ||
| - **Linux (Intel)**: [foundry_nightly_linux_amd64.tar.gz](https://github.com/matter-labs/foundry-zksync/releases/download/nightly/foundry_nightly_linux_amd64.tar.gz) | ||
| - **Linux (ARM)**: [foundry_nightly_linux_arm64.tar.gz](https://github.com/matter-labs/foundry-zksync/releases/download/nightly/foundry_nightly_linux_arm64.tar.gz) | ||
|
|
||
| To download and install one of these binaries, follow these steps: | ||
|
|
||
| ```bash | ||
| # Example for macOS Intel (amd64) | ||
| wget -qc https://github.com/matter-labs/foundry-zksync/releases/download/nightly/foundry_nightly_darwin_amd64.tar.gz -O - | tar -xz | ||
| # Move to a location in your PATH, for example: | ||
| sudo mv ./forge /usr/local/bin/ | ||
| sudo mv ./cast /usr/local/bin/ | ||
| ``` | ||
|
|
||
| Repeat for your platform, replacing the URL with the appropriate binary. | ||
|
|
||
| ## Building from Source | ||
|
|
||
| If you prefer to build Foundry ZKsync from source, follow these steps: | ||
|
|
||
| ### Prerequisites | ||
|
|
||
| - **Rust Compiler and Cargo**: The easiest way to install them is via [rustup.rs](https://rustup.rs/). | ||
| - **Nightly Rust**: Foundry ZKsync generally supports only a specific nightly version | ||
| of Rust, which is automatically set by the presence of a `rust-toolchain` file in the project. | ||
|
|
||
| ### Build Instructions | ||
|
|
||
| There are multiple ways to build from source: | ||
|
|
||
| #### Option 1: Using `foundryup-zksync` flags | ||
|
|
||
| To build from a specific branch or path: | ||
|
|
||
| ```bash | ||
| # Build from the main branch | ||
| foundryup-zksync --branch main | ||
|
|
||
| # Build from a local path | ||
| foundryup-zksync --path path/to/foundry-zksync | ||
| ``` | ||
|
|
||
| #### Option 2: Using Cargo | ||
|
|
||
| You can install the toolchain directly using Cargo: | ||
|
|
||
| ```bash | ||
| cargo install --git https://github.com/matter-labs/foundry-zksync --profile release --locked forge cast | ||
| ``` | ||
|
|
||
| #### Option 3: Manually building from a local clone | ||
|
|
||
| ```bash | ||
| # Clone the repository | ||
| git clone https://github.com/matter-labs/foundry-zksync.git | ||
| cd foundry-zksync | ||
|
|
||
| # Install Forge | ||
| cargo install --path ./crates/forge --profile release --force --locked | ||
|
|
||
| # Install Cast | ||
| cargo install --path ./crates/cast --profile release --force --locked | ||
| ``` | ||
|
|
||
| ## Installing for CI in GitHub Actions | ||
|
|
||
| To install Foundry ZKsync for CI pipelines, the latest precompiled binaries for your | ||
| architecture can be downloaded directly from the release page. Below is an example for a GitHub Actions workflow: | ||
|
|
||
| ```yaml | ||
| steps: | ||
| - name: Download binaries | ||
| run: | | ||
| wget -qc https://github.com/matter-labs/foundry-zksync/releases/download/nightly/foundry_nightly_linux_amd64.tar.gz -O - | tar -xz | ||
| ./forge -V && ./cast -V | ||
| ``` | ||
| ## Configuration | ||
| ### Using `foundry.toml` | ||
|
|
||
| Foundry is highly configurable through a `foundry.toml` file, located in the root of your project or any parent directory. | ||
| For a full list of configuration options, see the [config package documentation](https://github.com/matter-labs/foundry-zksync/blob/main/crates/config/README.md#all-options). | ||
|
|
||
| #### Profiles | ||
|
|
||
| You can organize configuration options using profiles. The default profile is named | ||
| `default`. See more about the [Default profile on `foundry-zksync` README](https://github.com/matter-labs/foundry-zksync/blob/main/crates/config/README.md#default-profile). | ||
|
|
||
| To switch profiles, use the `FOUNDRY_PROFILE` environment variable. You can also override specific settings using environment variables prefixed | ||
| with `FOUNDRY_` or `DAPP_`, such as `FOUNDRY_SRC`. | ||
|
|
||
| #### Initialization | ||
|
|
||
| The `forge init` command generates a basic `foundry.toml` file, which you can extend as needed. | ||
|
|
||
| #### Viewing Configuration | ||
|
|
||
| To view your current configuration: | ||
|
|
||
| - Run `forge config` to see all options. | ||
| - Run `forge config --basic` for a simplified view (as initialized with `forge init`). | ||
| - You can generate a new `foundry.toml` file with `forge config --basic > foundry.toml`. | ||
|
|
||
| By default, `forge config` displays the active profile and its values. It also accepts the same arguments as `forge build`. | ||
|
|
||
| #### Example `foundry.toml` for ZKsync | ||
|
|
||
| Here's an example configuration for ZKsync with `zksolc` settings: | ||
|
|
||
| ```toml | ||
| [profile.default] | ||
| src = 'src' | ||
| out = 'out' | ||
| libs = ['lib'] | ||
| [profile.default.zksync] | ||
| compile = true | ||
| fallback_oz = true | ||
| mode = '3' | ||
| ``` | ||
|
|
||
| ### Additional Configuration | ||
|
|
||
| You can find additional setup and configurations guides in the [official Foundry Book](https://book.getfoundry.sh/): | ||
|
|
||
| - [Setting up VSCode](https://book.getfoundry.sh/config/vscode) | ||
| - [Shell autocompletions](https://book.getfoundry.sh/config/shell-autocompletion) | ||
|
|
||
| ### Private key setup with Foundry keystore | ||
|
|
||
| :display-partial{ path="_partials/_foundry-create-keystore" } |
Oops, something went wrong.