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 compiler from Solidity to zkEVM bytecode.
Supported platforms:
- Linux: x86_64
MUSL-based static builds do not depend on system libraries and can be run on any recent Linux distribution. - MacOS 11+: x86_64, arm64 (M1, M2)
- 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.
-
Install some tools system-wide:
1.a.apt install cmake ninja-build clang-13 lld-13 parallelon a Debian-based Linux, with optionalmusl-toolsif you need amuslbuild.
1.b.pacman -S cmake ninja clang lld parallelon an Arch-based Linux.
1.c. On MacOS, install the HomeBrew package manager (being careful to install it as the appropriate user), thenbrew install cmake ninja coreutils parallel. Install your choice of a recent LLVM/Clang compiler, e.g. via Xcode, Apple’s Command Line Tools, or your preferred package manager.
1.d. Their equivalents with other package managers. -
Currently we are not pinned to any specific version of Rust, so just install the latest stable build for your platform.
Also install themusltarget if you are compiling on Linux in order to distribute the binary:
rustup target add x86_64-unknown-linux-musl -
Download a version of the solc compiler.
If it is not named exactlysolcand in your$PATH, see the--solcoption below. -
Check out or clone the appropriate branch of this repository.
-
Go to the project root and run
git checkout <ref>with the tag, branch, or commit you want to build. -
Install the zkEVM LLVM framework builder:
6.a.cargo install compiler-llvm-builderon MacOS, or Linux for personal use.
6.b.cargo install compiler-llvm-builder --target x86_64-unknown-linux-muslon Linux for distribution.The builder is not the zkEVM LLVM framework itself; it is just a tool that clones our repository and runs the sequence of build commands. By default it is installed in
~/.cargo/bin/, which is recommended to be added to your$PATH. Executezkevm-llvm --helpfor more information.
If you need a specific branch of zkEVM LLVM, change it in theLLVM.lockfile at the root of this repository. -
Run the builder to clone and build the zkevm LLVM framework at this repository root:
7.1.zkevm-llvm clone
7.2.zkevm-llvm build -
Build the Solidity compiler executable:
8.a.cargo build --releaseon MacOS or Linux for personal use.
8.b.cargo build --release --target x86_64-unknown-linux-muslon Linux for distribution. -
If you need to move the built binary elsewhere, grab it from the build directory:
9.a. On MacOS or Linux for the default target:./target/release/zksolc
9.b. On Linux, if you are building for the targetx86_64-unknown-linux-musl:./target/x86_64-unknown-linux-musl/release/zksolc
Check ./target/*/zksolc --help for the compiler usage.
The solc compiler must be available in $PATH, or the --solc option must be used instead.
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.
Print the version and exit.
Specify the input file paths.
Multiple Solidity files can be passed in the default Solidity mode.
Yul and LLVM IR modes currently support only a single file.
Set the given path as the root of the source tree instead of the root of the filesystem.
Passed to solc without changes.
Make an additional source directory available to the default import callback. Use multiple times if required. Only use if the base path has a non-empty value.
Passed to solc without changes.
Allow a given path for imports. For multiple paths, separate with commas.
Passed to solc without changes.
Create one file per component and contract/file at the specified directory, if given.
Overwrite existing files (used together with -o).
Set the LLVM optimization parameter -O[0 | 1 | 2 | 3 | s | z].
Use 3 for best performance and z for minimal size.
Disable the solc Yul/EVMLA optimizer.
Use it if your project uses the MSIZE instruction, or in other cases.
Beware that it will prevent libraries from being inlined.
Specify the path to the solc executable. By default, the one in ${PATH} is used.
In Yul mode, solc is used for source code validation, as zksolc assumes that the input Yul is valid.
In LLVM IR mode, solc is unused.
Specify addresses of deployable libraries. Syntax: name_1=address_1[,name_N=address_N]*.
Addresses are interpreted as hexadecimal strings prefixed with 0x.
Output a single JSON document containing the specified information.
Available arguments: abi, hashes, metadata, devdoc, userdoc, storage-layout, ast, asm, bin, bin-runtime.
Switch to standard JSON input/output mode. Read from stdin, write the result to stdout.
This is the default used by the Hardhat plugin.
Switch to the Yul mode.
Only one input Yul file is allowed.
Cannot be used with the combined and standard JSON modes.
Switch to LLVM IR mode.
Only one input LLVM IR file is allowed.
Cannot be used with combined and standard JSON modes.
Switch to zkEVM assembly mode.
Only one input zkEVM assembly file is allowed.
Cannot be used with combined and standard JSON modes.
Force use of the EVM legacy assembly pipeline.
Useful for early versions of solc 0.8.x, where Yul was considered highly experimental and contained more bugs than today.
Enable system contract compilation mode.
In this mode, zkEVM extensions are enabled. For example, calls to addresses 0xFFFF and less are substituted with special
zkEVM instructions. In the Yul mode, the verbatim_* and throw instructions become available.
Set the metadata hash mode.
The only supported value is none that disables appending the metadata hash.
Is enabled by default.
Output zkEVM assembly of the contracts.
Output zkEVM bytecode of the contracts.
Dump all IR (Yul, EVMLA, LLVM IR, assembly) to files in the specified directory.
Only for testing and debugging.
Set the verify-each option in LLVM.
Only for testing and debugging.
Set the debug-logging option in LLVM.
Only for testing and debugging.
- If you get a “failed to authenticate when downloading repository… if the git CLI succeeds then net.git-fetch-with-cli may help here” error,
then prepending the
cargocommand withCARGO_NET_GIT_FETCH_WITH_CLI=truemay help. - On MacOS,
git config --global credential.helper osxkeychainfollowed by cloning a repository manually with a personal access token may help. - 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
The Solidity 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.
zkSync Era compiler toolchain documentation
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.