Hardhat Tutorial

TIP

Hardhat for Visual Studio Code is the official Hardhat extension that adds advanced support for Solidity to VSCode. If you use Visual Studio Code, give it a try!

TIPS

If you are using Windows, we strongly recommend using WSL 2 to follow this guide. WSL 2 allows you to run a Linux distribution alongside Windows, providing a better development experience for Hardhat.

Install WSL

You can now install everything you need to run WSL with a single command. Open PowerShell or Windows Command Prompt in administrator mode by right-clicking and selecting "Run as administrator", enter the wsl --install command, then restart your machine.

wsl --install

This command will enable the features necessary to run WSL and install the Ubuntu distribution of Linux. (This default distribution can be changed).

Additional WSL Tips

To change the default Linux distribution installed, use the -d flag:

wsl --install -d <Distribution Name>

To see a list of available Linux distributions, run:

wsl --list --online

Set Up Your Linux User Info

Once you have installed WSL, you will need to create a user account and password for your newly installed Linux distribution. Follow the Best practices for setting up a WSL development environment guide to learn more.

Quick Start

To create the sample project, run the following command in your project folder:

npx hardhat init

This will set up a basic Hardhat project structure for you.

Hardhat CLI Commands

You can interact with Hardhat using the following commands:

npx hardhat
Hardhat version 2.9.9

Usage: hardhat [GLOBAL OPTIONS] <TASK> [TASK OPTIONS]

GLOBAL OPTIONS:
  --config              A Hardhat config file.
  --emoji               Use emoji in messages.
  --help                Shows this message, or a task's help if its name is provided
  --max-memory          The maximum amount of memory that Hardhat can use.
  --network             The network to connect to.
  --show-stack-traces   Show stack traces.
  --tsconfig            A TypeScript config file.
  --verbose             Enables Hardhat verbose logging
  --version             Shows hardhat's version.

AVAILABLE TASKS:
  check                 Check whatever you need
  clean                 Clears the cache and deletes all artifacts
  compile               Compiles the entire project, building all artifacts
  console               Opens a hardhat console
  coverage              Generates a code coverage report for tests
  flatten               Flattens and prints contracts and their dependencies
  help                  Prints this message
  node                  Starts a JSON-RPC server on top of Hardhat Network
  run                   Runs a user-defined script after compiling the project
  test                  Runs mocha tests
  typechain             Generate Typechain typings for compiled contracts
  verify                Verifies contract on Etherscan

To get help for a specific task, run:

npx hardhat help [task]

Compiling Your Contracts

To compile your contracts, run:

npx hardhat compile

This will compile your Solidity contracts and generate artifacts in the artifacts/ folder.

Testing Your Contracts

Your project comes with tests that use Mocha, Chai, Ethers.js, and Hardhat Ignition. Here is an example test file:

import {
  time,
  loadFixture,
} from "@nomicfoundation/hardhat-toolbox/network-helpers";
import { anyValue } from "@nomicfoundation/hardhat-chai-matchers/withArgs";
import { expect } from "chai";
import hre from "hardhat";

describe("Lock", function () {
  // We define a fixture to reuse the same setup in every test.
  // We use loadFixture to run this setup once, snapshot that state,
  // and reset Hardhat Network to that snapshot in every test.
  async function deployOneYearLockFixture() {
    const ONE_YEAR_IN_SECS = 365 * 24 * 60 * 60;
    const ONE_GWEI = 1_000_000_000;

    const lockedAmount = ONE_GWEI;
    const unlockTime = (await time.latest()) + ONE_YEAR_IN_SECS;

    // Contracts are deployed using the first signer/account by default
    const [owner, otherAccount] = await hre.ethers.getSigners();

    const Lock = await hre.ethers.getContractFactory("Lock");
    const lock = await Lock.deploy(unlockTime, { value: lockedAmount });

    return { lock, unlockTime, lockedAmount, owner, otherAccount };
  }

  describe("Deployment", function () {
    it("Should set the right unlockTime", async function () {
      const { lock, unlockTime } = await loadFixture(deployOneYearLockFixture);

      expect(await lock.unlockTime()).to.equal(unlockTime);
    });

    it("Should set the right owner", async function () {
      const { lock, owner } = await loadFixture(deployOneYearLockFixture);

      expect(await lock.owner()).to.equal(owner.address);
    });

    it("Should receive and store the funds to lock", async function () {
      const { lock, lockedAmount } = await loadFixture(
        deployOneYearLockFixture
      );

      expect(await hre.ethers.provider.getBalance(lock.target)).to.equal(
        lockedAmount
      );
    });

    it("Should fail if the unlockTime is not in the future", async function () {
      // We don't use the fixture here because we want a different deployment
      const latestTime = await time.latest();
      const Lock = await hre.ethers.getContractFactory("Lock");
      await expect(Lock.deploy(latestTime, { value: 1 })).to.be.revertedWith(
        "Unlock time should be in the future"
      );
    });
  });

  describe("Withdrawals", function () {
    describe("Validations", function () {
      it("Should revert with the right error if called too soon", async function () {
        const { lock } = await loadFixture(deployOneYearLockFixture);

        await expect(lock.withdraw()).to.be.revertedWith(
          "You can't withdraw yet"
        );
      });

      it("Should revert with the right error if called from another account", async function () {
        const { lock, unlockTime, otherAccount } = await loadFixture(
          deployOneYearLockFixture
        );

        // We can increase the time in Hardhat Network
        await time.increaseTo(unlockTime);

        // We use lock.connect() to send a transaction from another account
        await expect(lock.connect(otherAccount).withdraw()).to.be.revertedWith(
          "You aren't the owner"
        );
      });

      it("Shouldn't fail if the unlockTime has arrived and the owner calls it", async function () {
        const { lock, unlockTime } = await loadFixture(
          deployOneYearLockFixture
        );

        // Transactions are sent using the first signer by default
        await time.increaseTo(unlockTime);

        await expect(lock.withdraw()).not.to.be.reverted;
      });
    });

    describe("Events", function () {
      it("Should emit an event on withdrawals", async function () {
        const { lock, unlockTime, lockedAmount } = await loadFixture(
          deployOneYearLockFixture
        );

        await time.increaseTo(unlockTime);

        await expect(lock.withdraw())
          .to.emit(lock, "Withdrawal")
          .withArgs(lockedAmount, anyValue); // We accept any value as when arg
      });
    });

    describe("Transfers", function () {
      it("Should transfer the funds to the owner", async function () {
        const { lock, unlockTime, lockedAmount, owner } = await loadFixture(
          deployOneYearLockFixture
        );

        await time.increaseTo(unlockTime);

        await expect(lock.withdraw()).to.changeEtherBalances(
          [owner, lock],
          [lockedAmount, -lockedAmount]
        );
      });
    });
  });
});

You can run your tests with:

npx hardhat test

Deploying Your Contracts

To deploy your contracts, you can use Hardhat Ignition. Here is an example deployment script:

import { buildModule } from "@nomicfoundation/hardhat-ignition/modules";

const JAN_1ST_2030 = 1893456000;
const ONE_GWEI: bigint = 1_000_000_000n;

const LockModule = buildModule("LockModule", (m) => {
  const unlockTime = m.getParameter("unlockTime", JAN_1ST_2030);
  const lockedAmount = m.getParameter("lockedAmount", ONE_GWEI);

  const lock = m.contract("Lock", [unlockTime], {
    value: lockedAmount,
  });

  return { lock };
});

export default LockModule;

You can deploy it using:

npx hardhat ignition deploy ./ignition/modules/Lock.ts

Connecting to Hardhat Network

To run Hardhat Network in standalone mode, use:

npx hardhat node

This will expose a JSON-RPC interface at http://127.0.0.1:8545.

Project Setup

To create a new Hardhat project, run the following commands:

mkdir hardhat-deploy && cd hardhat-deploy
npx hardhat init -y

This will set up a basic Hardhat project with TypeScript support.

Install Dependencies

Install OpenZeppelin contracts for ERC20 token implementation:

npm install @openzeppelin/contracts

Clean and Reorganize Project

Remove default folders and create new ones for contracts and scripts:

rm -rf test ignition contracts
mkdir -p contracts scripts

Create ERC20 Token Contract

Create a new ERC20 token contract in the contracts folder:

cat << EOF > contracts/MyToken.sol
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import "@openzeppelin/contracts/token/ERC20/ERC20.sol";

contract MyToken is ERC20 {
    constructor(uint256 initialSupply) ERC20("MyToken", "MTK") {
        _mint(msg.sender, initialSupply);
    }
}
EOF

Compile Contracts

Compile the contracts using Hardhat:

npx hardhat compile

Update Hardhat Config

Update the hardhat.config.ts file to include the necessary configurations:

import { HardhatUserConfig } from "hardhat/config";
import "@nomicfoundation/hardhat-toolbox-viem";

const config: HardhatUserConfig = {
  solidity: "0.8.20",
  networks: {
    hardhat: {},
  },
};

export default config;

Start Hardhat Network

Start a local Hardhat network:

npx hardhat node

This will start a local Hardhat network and display a list of accounts with their private keys.

Deploy Contract

Create a deployment script in the scripts folder:

cat << EOF > scripts/deploy.ts
import { hardhat } from "viem/chains";
import { createWalletClient, http, parseUnits, createPublicClient } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import MyTokenJson from "../artifacts/contracts/MyToken.sol/MyToken.json";

async function main() {
    console.log("Deploying contract...");

    const account = privateKeyToAccount("0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80");

    const publicClient = createPublicClient({
        chain: hardhat,
        transport: http(),
    });

    const walletClient = createWalletClient({
        chain: hardhat,
        transport: http(),
        account,
    });

    const { abi, bytecode } = MyTokenJson;

    const hash = await walletClient.deployContract({
        abi,
        bytecode: bytecode as `0x${string}`,
        args: [parseUnits("1000000", 18)],
    });

    console.log("Deployment transaction hash:", hash);

    const receipt = await publicClient.waitForTransactionReceipt({ hash });

    console.log("Token deployed to:", receipt.contractAddress);
}

main().catch((error) => {
    console.error(error);
    process.exitCode = 1;
});
EOF

Run the deployment script:

npx hardhat run scripts/deploy.ts --network hardhat

Write Advanced Tests

Create a test file in the test folder:

cat << 'EOF' > test/myToken.test.ts
import { expect } from "chai";
import { createPublicClient, createWalletClient, http, parseUnits } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { hardhat } from "viem/chains";
import MyTokenJson from "../artifacts/contracts/MyToken.sol/MyToken.json";

describe("MyToken", function () {
    const privateKey = "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80";
    const account = privateKeyToAccount(privateKey);

    const publicClient = createPublicClient({
        chain: hardhat,
        transport: http(),
    });

    const walletClient = createWalletClient({
        chain: hardhat,
        transport: http(),
        account,
    });

    let tokenAddress: `0x${string}`;

    before(async function () {
        const { abi, bytecode } = MyTokenJson;

        // Deploy contract
        const hash = await walletClient.deployContract({
            abi,
            bytecode: bytecode as `0x${string}`,
            args: [parseUnits("1000000", 18)], // Total supply 1M tokens
        });

        // Wait for contract deployment
        const receipt = await publicClient.waitForTransactionReceipt({ hash });
        tokenAddress = receipt.contractAddress!;

        console.log("Token deployed at:", tokenAddress);
    });

    it("Check token name and symbol", async function () {
        const { abi } = MyTokenJson;

        const name = await publicClient.readContract({
            address: tokenAddress,
            abi,
            functionName: "name",
        });

        const symbol = await publicClient.readContract({
            address: tokenAddress,
            abi,
            functionName: "symbol",
        });

        expect(name).to.equal("MyToken");
        expect(symbol).to.equal("MTK");
    });

    it("Check total supply", async function () {
        const { abi } = MyTokenJson;

        const totalSupply = await publicClient.readContract({
            address: tokenAddress,
            abi,
            functionName: "totalSupply",
        });

        expect(BigInt(totalSupply)).to.equal(parseUnits("1000000", 18));
    });

    it("Check deployer's balance", async function () {
        const { abi } = MyTokenJson;

        const balance = await publicClient.readContract({
            address: tokenAddress,
            abi,
            functionName: "balanceOf",
            args: [account.address],
        });

        expect(BigInt(balance)).to.equal(parseUnits("1000000", 18));
    });

    it("Transfers tokens", async function () {
        const { abi } = MyTokenJson;
        const recipient = "0x000000000000000000000000000000000000dead";
        const amount = parseUnits("1000", 18);

        const hash = await walletClient.writeContract({
            address: tokenAddress,
            abi,
            functionName: "transfer",
            args: [recipient, amount],
        });

        await publicClient.waitForTransactionReceipt({ hash });

        const balance = await publicClient.readContract({
            address: tokenAddress,
            abi,
            functionName: "balanceOf",
            args: [recipient],
        });

        expect(BigInt(balance)).to.equal(amount);
    });

    it("Fails transfer when balance is insufficient", async function () {
        const { abi } = MyTokenJson;
        const recipient = "0x000000000000000000000000000000000000beef";
        const amount = parseUnits("1000001", 18); 

        let errorOccurred = false;

        try {
            await walletClient.writeContract({
                address: tokenAddress,
                abi,
                functionName: "transfer",
                args: [recipient, amount],
            });
        } catch (error: any) {
            errorOccurred = true;
            console.log("Transfer failed as expected:", error);

            if (error.data?.errorName) {
                expect(error.data.errorName).to.equal("ERC20InsufficientBalance");
            } else {
                expect(error.metaMessages.join(" ")).to.include("ERC20InsufficientBalance");
            }
        }

        expect(errorOccurred).to.be.true;
    });

    it("Total supply remains constant after transfers", async function () {
        const { abi } = MyTokenJson;

        const totalSupplyAfter = await publicClient.readContract({
            address: tokenAddress,
            abi,
            functionName: "totalSupply",
        });

        expect(BigInt(totalSupplyAfter)).to.equal(parseUnits("1000000", 18));
    });
});

EOF

Run the tests:

npx hardhat test test/myToken.test.ts

Reference Documentation

For detailed documentation on Hardhat, including guides, API references, and tutorials, visit the official Hardhat documentation:

Official Website

To learn more about Hardhat, explore its features, and stay updated with the latest news, visit the official Hardhat website:

Additional Notes

Hardhat is a powerful development environment for Ethereum smart contracts. It provides tools for compiling, testing, debugging, and deploying your contracts. Make sure to explore the documentation and website to get the most out of Hardhat.