Compiling non-inlinable libraries

Solidity libraries can be divided into two categories:

• Inlinable. The ones that contain only private or internal methods. Since they can never be called from outside, the Solidity compiler inlines them, i.e. does not use external calls to access the library methods and uses the code of these libraries as part of the code that uses them.
• Non-inlinable. The ones that have at least one public or external method. While they may be inlined by the Solidity compiler, they are not inlined when compiled to Yul representation. Since Yul is an intermediate step when compiling to ZKsync VM bytecode, this means that these libraries can not be inlined by the ZKsync compiler.

Libraries with public methods must be deployed separately, and their addresses should be passed as arguments when compiling the main contract. Usage of the methods of this library will be replaced with calls to its address.

OpenZeppelin utility libraries

Please note, that the total majority of the OpenZeppelin utility libraries are inlinable. That means that there is no need to do any further actions to make them compile.

This section describes the compilation of non-inlinable libraries only.

Example

Let's say that we have a small library that calculates the square of a number:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

library MiniMath {
    function square(uint256 x) public pure returns (uint256) {
         return x*x;
    }
}

And there is a smart contract that uses this library:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

import "./MiniMath.sol";

contract Main {
    uint256 public lastNumber;

    function storeSquare(uint256 x) public {
        uint256 square = MiniMath.square(x);
        lastNumber = square;
    }
}

If you try to create a project with these two files following the guidelines from the getting started guide, the yarn hardhat compile command will fail.

Using hardhat-zksync-solc version >= 0.4.2

Following error:

zksolc compiler detected missing libraries! For more details, visit: https://era.zksync.io/docs/tools/hardhat/compiling-libraries.html.
To compile and deploy libraries, please run: `yarn hardhat deploy-zksync:libraries`
For more details on how to use deploy-zksync:libraries task from hardhat-zksync-deploy plugin, visit: https://docs.zksync.io/tooling/hardhat/plugins/hardhat-zksync-deploy.html.

To address the error, you can follow the instructions provided in the output, which is the recommended approach. For more details, please refer to this section. Alternatively, if you prefer a manual resolution for the libraries, you can find detailed instructions in this section.

Choose the method that best suits your preferences or requirements.

Non-inline libraries deployment

Automatic deployment

hardhat-zksync-deploy plugin has the capability to automatically deploy all missing libraries generated by compiler. For additional information, you may refer to the documentation. This documentation provides details on how the tool handles the compilation and deployment of libraries that are currently missing.

Manual deployment

To resolve the issue, you need to create a separate project, where only the library file will be located. After deploying only the library to ZKsync Era, you should get the address of the deployed library and pass it to the compiler settings. The process of deploying the library is the same as deploying a smart contract. You can learn how to deploy smart contracts on ZKsync Era in the getting started guide.

Let's say that the address of the deployed library is 0x111C3E89Ce80e62EE88318C2804920D4c96f92bb. To pass this address to the compiler parameters, open the hardhat.config.ts file of the project where the Main contract is located and add the libraries section in the zksolc plugin properties:

  zksolc: {
    version: 'latest',
    settings: {
      libraries: {
        'contracts/MiniMath/MiniMath.sol': {
          MiniMath: '0x111C3E89Ce80e62EE88318C2804920D4c96f92bb',
        },
      },
    },
  },

where 'contracts/MiniMath/MiniMath.sol' is the location of the library's Solidity file and MiniMath is the name of the library.

Now, running yarn hardhat compile should successfully compile the Main contract.