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 zkEVM bytecode, this means that these libraries can not be inlined by the zkSync compiler.

Practically this means that libraries with public methods need to be deployed separately and their addresses passed as an argument 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:

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

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;
    }
}

Support for missing libraries in hardhat-zksync-solc ^0.4.2

Version 0.4.2 introduced a mode that detects non-inlinable libraries that are missing and that are required for the compilation of contracts.

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://era.zksync.io/docs/tools/hardhat/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.

Using hardhat-zksync-solc version < 0.4.2

Following error:

Error in plugin @matterlabs/hardhat-zksync-solc: LLVM("Library `contracts/MiniMath.sol:MiniMath` not found")

The error indicates that the compilation process is expecting the address of the MiniMath library, but it is not being provided.

To resolve the error, it's necessary to manually resolve the libraries. For detailed instructions, please refer to this section.

Non-inline libraries deployment

Automatic deployment

Note

This approach is effective only with specific plugin versions:

• hardhat-zksync-solc >= 0.4.2
• hardhat-zksync-deploy >= 0.6.5

Make sure that you are using the specified versions or a later versions to ensure compatibility with the described resolution method.

Note

Vyper does not support automatic deployment of missing libraries, and the process needs to be handled manually.

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 0xF9702469Dfb84A9aC171E284F71615bd3D3f1EdC. 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:

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

module.exports = {
  zksolc: {
    version: "latest", // Uses latest available in https://github.com/matter-labs/zksolc-bin/
    settings: {
      libraries: {
        "contracts/MiniMath.sol": {
          MiniMath: "0xF9702469Dfb84A9aC171E284F71615bd3D3f1EdC",
        },
      },
    },
  },
  defaultNetwork: "zkTestnet",
  networks: {
    zkTestnet: {
      url: "https://sepolia.era.zksync.dev", // URL of the zkSync network RPC
      ethNetwork: "sepolia", // Can also be the RPC URL of the Ethereum network (e.g. `https://sepolia.infura.io/v3/<API_KEY>`)
      zksync: true,
    },
  },
  solidity: {
    version: "0.8.13",
  },
};

The address of the library is passed in the following lines:

libraries: {
  'contracts/MiniMath.sol': {
    'MiniMath': '0xF9702469Dfb84A9aC171E284F71615bd3D3f1EdC'
  }
},

where 'contracts/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.