ZKsync Era: Vyper Compiler

ZKsync Era is a layer 2 rollup that uses zero-knowledge proofs to scale Ethereum without compromising on security or decentralization. As it’s EVM-compatible (with Solidity/Vyper), 99% of Ethereum projects can redeploy without needing to refactor or re-audit any code. ZKsync Era also uses an LLVM-based compiler that will eventually enable developers to write smart contracts in popular languages such as C++ and Rust.

This repository contains the ZKsync Vyper compiler.

System Requirements

Supported platforms:

• Linux: x86_64, ARM64
  • Users are encouraged to adopt GNU libc builds, which offer the same compatibility and are substantially faster.
  • musl-based builds are deprecated, but still supported to preserve tooling compatibility.
• MacOS 11+: x86_64, ARM64 (Apple silicon)
• Windows: x86_64
  • Only Windows 10 has been tested so far, but other versions should be OK as well.

We recommend at least 4 GB of RAM available for the build process.

Delivery Methods

1. Install via npm:
   • Use ZKsync CLI to obtain a compiler package and prepare a project environment. After the installation you can modify a hardhat configuration file in the project and specify zkvyper version there. Use npx hardhat compile or yarn hardhat compile to compile. @matterlabs/hardhat-zksync-vyper package will be used from npm repo.
2. Download prebuilt binaries:
   • Download v0.3.3, v0.3.9, or v0.3.10 of the Vyper compiler and zkvyper binaries directly from GitHub. Use the CLI or Hardhat to compile contracts.
3. Build binaries from sources:
   • Build binaries using the guide below. Use the CLI or Hardhat to compile contracts.

Building

1. Install the system prerequisites.

• Linux (Debian):

  Install the following packages:

  apt install cmake ninja-build curl git libssl-dev pkg-config clang lld

  Additionally install musl-tools if you are building for the x86_64-unknown-linux-musl or aarch64-unknown-linux-musl targets.

• Linux (Arch):

  Install the following packages:

  pacman -Syu which cmake ninja curl git pkg-config clang lld

• MacOS:

  • Install the HomeBrew package manager.

  • Install the following packages:

    brew install cmake ninja coreutils

  • Install your choice of a recent LLVM/Clang compiler, e.g. via Xcode, Apple’s Command Line Tools, or your preferred package manager.

2. Install Rust.

• Follow the latest official instructions:

  curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
  . ${HOME}/.cargo/env

  Currently we are not pinned to any specific version of Rust, so just install the latest stable build for your platform.

• If you would like to use musl binaries on Linux, install the target for your platform:

  For x86_64:

  rustup target add x86_64-unknown-linux-musl

  For arm64(aarch64):

  rustup target add aarch64-unknown-linux-musl

3. Download `vyper` compiler.

Download v0.3.3, v0.3.9, or v0.3.10 of the Vyper compiler.

If it is not named exactly vyper in your $PATH, see the --vyper option below.

4. Clone and checkout repository.

Use the following commands to clone and checkout the ZKsync Vyper compiler repository:

git clone https://github.com/matter-labs/era-compiler-vyper.git
cd era-compiler-vyper
git checkout <ref>

Replace <ref> with the tag, branch, or commit you want to build or skip this step to use default branch of the repository.

5. Install the ZKsync LLVM framework builder.

• Install the builder using cargo:

  cargo install compiler-llvm-builder

  The builder is not the ZKsync LLVM framework itself, but a tool that clones its repository and runs a sequence of build commands. By default it is installed in ~/.cargo/bin/, which is recommended to be added to your $PATH.

6. Build the ZKsync LLVM framework.

• Clone and build the ZKsync LLVM framework using the zksync-llvm tool:

  zksync-llvm clone
  zksync-llvm build

  The build artifacts will end up in the ./target-llvm/target-final/ directory. You may set the LLVM_SYS_170_PREFIX shell variable to the absolute path to that directory to use this build as a compiler dependency. If built with the --enable-tests option, test tools will be in the ./target-llvm/build-final/ directory, along with copies of the build artifacts. For all supported build options, run zksync-llvm build --help.

  If you need a specific branch of ZKsync LLVM framework, change it in the LLVM.lock file at the root of the repository.

• If you are building on Linux for distribution targeting x86_64-unknown-linux-musl or aarch64-unknown-linux-musl, use the following commands:

  zksync-llvm clone --target-env musl
  zksync-llvm build --target-env musl

You could use --use-ccache option to speed up the build process if you have ccache installed. For more information and available build options, run zksync-llvm build --help.

7. Build the Vyper compiler executable.

cargo build --release

• On Linux with musl:

  For x86_64:

  cargo build --release --target x86_64-unknown-linux-musl

  For ARM64 (aarch64):

  cargo build --release --target aarch64-unknown-linux-musl

  The resulting binary will be in the ./target/release/zkvyper directory. For *-musl targets, the binary will be in the ./target/x86_64-unknown-linux-musl/release/zkvyper or ./target/aarch64-unknown-linux-musl/release/zkvyper directory.

Usage

Check ./target/*/zkvyper --help for compiler usage.

A supported version of the Vyper compiler must be available in $PATH, or its path must be passed explicitly with the --vyper option.

Supported versions:

• 0.3.3
• 0.3.9
• 0.3.10

For big projects it is more convenient to use the compiler via the Hardhat plugin. For single-file contracts, or small projects, the CLI suffices.

Unit testing

For running unit tests, zkvyper itself must also be available in $PATH, because it calls itself recursively to allow compiling each contract in a separate process. To successfully run unit tests:

1. Run cargo build --release.
2. Move the binary from ./target/release/zkvyper to a directory from $PATH, or add the target directory itself to $PATH.
3. Run cargo test.

CLI testing

For running command line interface tests, zkvyper itself and vyper must also be available in $PATH, because it calls itself recursively to allow compiling each contract in a separate processes. To successfully run CLI tests:

1. Go to cli-tests.
2. Make npm i.
3. Add vyper and zkvyper to $PATH.
4. Run npm test.

Troubleshooting

• Unset any LLVM-related environment variables you may have set, especially LLVM_SYS_<version>_PREFIX (see e.g. https://crates.io/crates/llvm-sys and https://llvm.org/docs/GettingStarted.html#local-llvm-configuration). To make sure: set | grep LLVM

License

The Vyper compiler is distributed under the terms of either

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Resources

• ZKsync Era compiler toolchain documentation
• Vyper v0.3.3 documentation
• Vyper v0.3.9 documentation
• Vyper v0.3.10 documentation
• Vyper LLL IR

Some parts of the Vyper documentation may be outdated. Please contact the Vyper team for assistance.

Official Links

• Website
• GitHub
• Twitter
• Twitter for Devs
• Discord

Disclaimer

ZKsync Era has been through extensive testing and audits, and although it is live, it is still in alpha state and will undergo further audits and bug bounty programs. We would love to hear our community's thoughts and suggestions about it! It's important to note that forking it now could potentially lead to missing important security updates, critical features, and performance improvements.