Installation

Validium Network has integrated zkSync Foundry as its development framework. Discover the steps to install and configure Foundry for zkSync effectively.

---

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.

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.

To install foundryup-zksync, follow these steps:

1. Install via the provided script

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:

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. 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
• macOS (Apple): foundry_nightly_darwin_arm64.tar.gz
• Linux (Intel): foundry_nightly_linux_amd64.tar.gz
• Linux (ARM): foundry_nightly_linux_arm64.tar.gz

To download and install one of these binaries, follow these steps:

# 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.
• 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:

# 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:

cargo install --git https://github.com/matter-labs/foundry-zksync --profile release --locked forge cast

Option 3: Manually building from a local clone

# 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:

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.

Profiles

You can organize configuration options using profiles. The default profile is named default. See more about the Default profile on foundry-zksync README.

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:

[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:

• Setting up VSCode
• Shell autocompletions

Private key setup with Foundry keystore

Follow these steps to securely store your wallet's private key to use it in Foundry projects:

1. Extract Your Private Key: If you are using the local era node, use a private key from the available rich accounts. Otherwise, find your personal wallet's private key. For MetaMask users, here's how to export your wallet's private key.
2. Create a Foundry keystore: Create a keystore and import your private key by running

cast wallet import myKeystore --interactive
# enter your PK when prompted, provide a password, and copy the returned address

It'll return an address (keystore address).

Note that the name myKeystore is arbitrary and can be updated. For our docs, we've chosen this name for consistency. If you decide to use another name, be sure to reference it when using cast.

Using the keystore

When running commands that require a private key, like forge create or cast send, use --account myKeystore --sender <KEYSTORE_ADDRESS>. This will require you to enter the keystore password you provided before.