hardhat-zksync-solc

This plugin is used to provide a convenient interface for compiling Solidity smart contracts before deploying them to ZKsync Era.

Learn more about the latest updates in the changelog.

Prerequisite

To use hardhat-zksync-solc in your project, ensure the following:

• Node.js version 18 or higher is installed.
• Hardhat version 2.16.0 or higher is installed as a dependency.

Installation

@matterlabs/hardhat-zksync-solc

Add the latest version of this plugin to your project with the following command:

yarn add -D @matterlabs/hardhat-zksync-solc

Configuration

Import the package in the hardhat.config.ts file:

import "@matterlabs/hardhat-zksync-solc";

Any configuration parameters should be added inside a zksolc property in the hardhat.config.ts file:

zksolc: {
    version: "latest", // optional.
    settings: {
      compilerPath: "zksolc",  // optional. Ignored for compilerSource "docker". Can be used if compiler is located in a specific folder
      libraries:{}, // optional. References to non-inlinable libraries
      missingLibrariesPath: "./.zksolc-libraries-cache/missingLibraryDependencies.json", // optional. This path serves as a cache that stores all the libraries that are missing or have dependencies on other libraries. A `hardhat-zksync-deploy` plugin uses this cache later to compile and deploy the libraries, especially when the `deploy-zksync:libraries` task is executed
      enableEraVMExtensions: false, // optional.  Enables Yul instructions available only for ZKsync system contracts and libraries
      forceEVMLA: false, // optional. Falls back to EVM legacy assembly if there is a bug with Yul
      optimizer: {
        enabled: true, // optional. True by default
        mode: '3', // optional. 3 by default, z to optimize bytecode size
        fallback_to_optimizing_for_size: false, // optional. Try to recompile with optimizer mode "z" if the bytecode is too large
      },
      suppressedWarnings: ['txorigin', 'sendtransfer'], // Suppress specified warnings. Currently supported: txorigin, sendtransfer
      suppressedErrors: ['txorigin', 'sendtransfer'], // Suppress specified errors. Currently supported: txorigin, sendtransfer
      experimental: {
        dockerImage: '', // deprecated
        tag: ''   // deprecated
      },
      contractsToCompile: [] //optional. Compile only specific contracts
    }
},

• version is the zksolc compiler version. Compiler versions can be found in the following repository.
• compilerSource indicates the compiler source and can be either binary (default) or docker (deprecated). If there isn't a compiler binary already installed, the plugin will automatically download it.
• compilerPath (optional) is a field with the path to the zksolc binary. By default, the binary in $PATH is used.
• libraries if your contract uses non-inlinable libraries as dependencies, they have to be defined here. Learn more about compiling libraries here
• missingLibrariesPath (optional) serves as a cache that stores all the libraries that are missing or have dependencies on other libraries. A hardhat-zksync-deploy plugin uses this cache later to compile and deploy the libraries, especially when the deploy-zksync:libraries task is executed. Defaults to ./.zksolc-libraries-cache/missingLibraryDependencies.json.
• enableEraVMExtensions - required if contracts use enables Yul instructions available only for ZKsync system contracts and libraries
• forceEVMLA - falls back to EVM legacy assembly if there is an issue with the Yul IR compilation pipeline.
• optimizer - Compiler optimizations:
  • enabled: true (default) or false.
  • mode: 3 (default) recommended for most projects. Mode z reduces bytecode size for large projects that make heavy use of keccak and far calls.
  • fallback_to_optimizing_for_size (optional) indicates that the compiler will try to recompile with optimizer mode "z" if the bytecode is too large.
• suppressedWarnings - Suppress specified warnings. Supported values: "txorigin" (when contracts use tx.origin), and "sendtransfer" (when contracts use .transfer)
• suppressedErrors - Suppress specified errors. Supported values: "txorigin" (when contracts use tx.origin), and "sendtransfer" (when contracts use .transfer)
• metadata: Metadata settings. If the option is omitted, the metadata hash appends by default:
  • bytecodeHash: Can only be none. It removes metadata hash from the bytecode.
• dockerImage and tag are deprecated options used to identify the name of the compiler docker image.
• contractsToCompile (optional) field is utilized to compile only the specified contracts. The contract names do not necessarily need to be written in full qualified form. The plugin will perform an include operation, attempting to match the provided contract names.

Compiler integrations

The zksolc compilers are stored in the cache folder with the path {cache}/hardhat-nodejs/compilers-v2/zksolc. In this location, you can inspect the locally stored compiler versions.

{cache} is a placeholder for a path that is resolved by Hardhat

The compilerVersion.json file is used by the plugin to get the latest available version and the minimum required compiler version. This file undergoes invalidation every 24 hours (currently), subsequently being updated with fresh information. This approach is implemented to provide a caching mechanism, avoiding the risk of encountering GitHub throttling issues during fetching new releases.

ZKsync Era Solidity compiler

Due to several codegen limitations of the upstream Solidity compiler, our team had to fork it in order to effectively address and resolve these constraints.

For usage of EraVM compiler, eraVersion should be added inside solidity property in the hardhat.config.ts file:

solidity: {
    version: "0.8.28"
},

• eraVersion - (optional) field used to specify version of EraVM compiler

Network configuration

Configure the zksync parameter in the networks to enable the zksolc compiler:

defaultNetwork: "zkSyncTestnet",
networks: {
  sepolia: {
    url: "https://sepolia.infura.io/v3/<API_KEY>", // The Ethereum Web3 RPC URL (optional).
    zksync: false, // disables zksolc compiler
  },
  zkSyncTestnet: {
    url: "https://sepolia.era.zksync.dev", // The testnet RPC URL of ZKsync Era network.
    ethNetwork: "sepolia", // The Ethereum Web3 RPC URL, or the identifier of the network (e.g. `mainnet` or `sepolia`)
    zksync: true, // enables zksolc compiler
  }
},

• zksync network option indicates whether zksolc is enabled on a certain network. false by default. Useful for multichain projects in which you can enable zksync only for specific networks.

Commands

yarn hardhat compile

Compiles all the smart contracts in the contracts directory and creates the artifacts-zk folder with all the compilation artifacts, including factory dependencies for the contracts, which could be used for contract deployment.

To understand what the factory dependencies are, read more about them here documentation.

Troubleshooting

Error in plugin @matterlabs/hardhat-zksync-solc: Invalid zksolc compiler version

This error is returned when the version defined in the hardhat.config.ts file is lower than the minimal required (versions are defined in file compilerVersion.json). Update the version to solve the issue.

Why is there an unexpected end of JSON input compilation error?

This is an error that is usually thrown when compiling a large smart contract codebase.

If you encounter such an error, please do the following:

• Update the @matterlabs/hardhat-zksync-solc library and try to re-compile the smart contracts afterwards.
• If after the recompilation you get the Library not found error, then you should follow the instructions from compiling libraries.