Understanding Hardhat Compilation Artifacts

Introduction

When you compile smart contracts using Hardhat, the process generates two distinct types of files for each contract—not for each .sol source file. These are known as an artifact and a debug file.

The artifact is a JSON file containing all the essential information required to deploy the contract and interact with it. This format is compatible with most development tools, including those that work with Truffle's artifact structure. Each artifact includes the following key properties:

• contractName: A string representing the name of the contract.
• abi: A JSON description of the contract's Application Binary Interface (ABI).
• bytecode: A "0x"-prefixed hexadecimal string of the unlinked deployment bytecode. If the contract is not deployable, this value is set to "0x".
• deployedBytecode: A "0x"-prefixed hexadecimal string of the unlinked runtime or deployed bytecode. This is also set to "0x" for non-deployable contracts.
• linkReferences: The link references object for the bytecode, as returned by the Solidity compiler (solc). This is an empty object if the contract does not require linking.
• deployedLinkReferences: The link references object for the deployed bytecode, also as provided by solc. It is empty if no linking is necessary.

The debug file contains all the information needed to reproduce the compilation process and debug the contract. This includes the original solc input and output, as well as the version of the compiler used.

Build Information Files

Hardhat optimizes the compilation process by compiling the smallest possible set of files together. Files that are compiled simultaneously share the same solc input and output. To avoid redundancy, this information is stored in deduplicated build information files located in the artifacts/build-info directory. Each debug file references its corresponding build information file, which contains the solc input, output, and compiler version.

Developers typically do not need to interact with these build information files directly.

Reading Artifacts

The Hardhat Runtime Environment (HRE) provides an artifacts object with several helper methods. For instance, you can retrieve a list of all artifact paths by calling hre.artifacts.getArtifactPaths().

To read the content of a specific artifact, use hre.artifacts.readArtifact("ContractName"), where "ContractName" is the name of your contract. This method works only if there is exactly one contract with that name in the project. If multiple contracts share the same name, you must use the fully qualified name to avoid ambiguity: hre.artifacts.readArtifact("path/to/Contract.sol:ContractName").

👉 Explore advanced development tools

Directory Structure

The artifacts/ directory mirrors the original structure of your contracts directory. For example, if your source directory is organized as follows:

contracts
├── Foo.sol
├── Bar.sol
└── Qux.sol

The artifacts directory will have a corresponding structure:

artifacts
└── contracts
 ├── Foo.sol
 │   ├── Foo.json
 │   ├── Foo.dbg.json
 │   ├── Foo2.json
 │   └── Foo2.dbg.json
 ├── Bar.sol
 │   ├── Bar.json
 │   └── Bar.dbg.json
 └── Qux.sol
     ├── Foo.json
     └── Foo.dbg.json

Each Solidity file in the source directory gets its own subdirectory within the artifacts structure. These subdirectories contain one artifact file (.json) and one debug file (.dbg.json) for each contract defined within the source file. Note that multiple Solidity files can contain contracts with the same name, and this structure supports that scenario without conflict.

Frequently Asked Questions

What is the purpose of Hardhat artifacts?

Artifacts contain the essential data needed to deploy and interact with smart contracts, including the ABI and bytecode. They ensure compatibility with various development tools and simplify the deployment process.

How do I resolve errors when multiple contracts have the same name?

You must use the fully qualified name of the contract, which includes the path to the source file and the contract name separated by a colon (e.g., contracts/Foo.sol:Foo).

Can I modify artifact files manually?

It is not recommended to manually modify artifact files. They are automatically generated by Hardhat during compilation, and changes may lead to inconsistencies or errors during deployment.

What is the difference between bytecode and deployedBytecode?

Bytecode refers to the initial deployment code, while deployedBytecode is the runtime code that remains on the blockchain after deployment. The latter is used for contract interactions.

How does Hardhat optimize the compilation process?

Hardhat compiles only the necessary files together, reducing redundant work. It uses build information files to store shared compilation data, improving efficiency.

Where can I learn more about smart contract development?

Numerous resources are available for developers looking to enhance their skills. 👉 Discover comprehensive development strategies