@nomicfoundation/hardhat-viem

hardhat-viem

Hardhat plugin for integration with Viem, a lightweight, composable, and type-safe Ethereum library.

What

This plugin integrates the Viem Ethereum library into your Hardhat development environment. Viem is an alternative to ethers.js that offers developers a different way to interact with the Ethereum blockchain.

By installing and configuring hardhat-viem, you gain access to the capabilities of the Viem library directly within your Hardhat projects. This integration enables you to perform various Ethereum-related tasks using Viem's features and functionalities.

Note: This plugin relies on the Viem library, so familiarity with Viem's documentation can enhance your experience when working with hardhat-viem.

Installation

npm install --save-dev @nomicfoundation/hardhat-viem viem

And add the following statement to your hardhat.config.js:

require("@nomicfoundation/hardhat-viem");

Or, if you are using TypeScript, add this to your hardhat.config.ts:

import "@nomicfoundation/hardhat-viem";

Note: you might want to pin Viem-related dependencies because Viem does not strictly follow semantic versioning for type changes. You can read more here.

Required plugins

No plugins dependencies.

Tasks

This plugin creates no additional tasks.

Environment extensions

This plugins adds a viem object to the Hardhat Runtime Environment which provides a minimal set of capabilities for interacting with the blockchain.

Clients

Viem supports three types of clients:

Public client

A Public Client is an interface to "public" JSON-RPC API methods such as retrieving block numbers, transactions, reading from smart contracts, etc through Public Actions.

import hre from "hardhat";

const publicClient = await hre.viem.getPublicClient();

const blockNumber = await publicClient.getBlockNumber();

const balance = await publicClient.getBalance({
  address: "0xA0Cf798816D4b9b9866b5330EEa46a18382f251e",
});

Wallet client

A Wallet Client is an interface to interact with Ethereum Accounts and provides the ability to retrieve accounts, execute transactions, sign messages, etc. through Wallet Actions.

import hre from "hardhat";

const [fromWalletClient, toWalletClient] = await hre.viem.getWalletClients();

const hash = await fromWalletClient.sendTransaction({
  to: toWalletClient.account.address,
  value: parseEther("0.0001"),
});

import hre from "hardhat";

const walletClient = await hre.viem.getWalletClient(
  "0xA0Cf798816D4b9b9866b5330EEa46a18382f251e"
);

const signature = await walletClient.signMessage({
  account,
  message: "hello world",
});

Test client

A Test Client is an interface to "test" JSON-RPC API methods such as mining blocks, impersonating accounts, setting fees, etc. through Test Actions.

import hre from "hardhat";

const testClient = await hre.viem.getTestClient();

await testClient.mine({
  blocks: 1000000,
});

Client options

You can pass options to the getPublicClient, getWalletClient, and getTestClient methods to customize the client's behavior.

import hre from "hardhat";

const publicClient = await hre.viem.getPublicClient({
  pollingInterval: 1000,
  cacheTime: 2000,
});

For a complete list of options, see:

• Public client parameters
• Wallet client parameters
• Test client parameters

Contracts

The viem object provides convenient methods for deploying and interacting with smart contracts on the blockchain.

Deploying a Contract

To deploy a contract to the blockchain, use the deployContract method:

import hre from "hardhat";

const contract = await hre.viem.deployContract("contractName", [
  "arg1",
  50,
  "arg3",
]);

By default, the first wallet client retrieved by hre.viem.getWalletClients() is used to deploy the contract. You can also specify a different wallet client by passing a third parameter, along with other properties, such as gas and value:

import hre from "hardhat";

const [_, secondWalletClient] = await hre.viem.getWalletClients();

const contractA = await hre.viem.deployContract(
  "contractName",
  ["arg1", 50, "arg3"],
  {
    client: { wallet: secondWalletClient }
    gas: 1000000,
    value: parseEther("0.0001"),
    confirmations: 5, // 1 by default
  }
);

Retrieving an Existing Contract

If the contract is already deployed, you can retrieve an instance of it using the getContractAt method:

import hre from "hardhat";

const contract = await hre.viem.getContractAt(
  "contractName",
  "0x1234567890123456789012345678901234567890"
);

By default, the first wallet client retrieved by hre.viem.getWalletClients() will be used for interacting with the contract. If you want to specify a different wallet client, you can do so by passing it as a third parameter, just like when deploying a contract:

import hre from "hardhat";

const [_, secondWalletClient] = await hre.viem.getWalletClients();

const contract = await hre.viem.getContractAt(
  "contractName",
  "0x1234567890123456789012345678901234567890",
  { client: { wallet: secondWalletClient } }
);

Interacting with Contracts

Once you have an instance of a contract, you can interact with it by calling its methods:

let response = await contract.read.method1();
await contract.write.method2([10, "arg2"]);

Send deployment transaction

By default, the deployContract method sends a deployment transaction to the blockchain and waits for the transaction to be mined. If you want to send the transaction without waiting for it to be mined, you can do so by using sendDeploymentTransaction:

import hre from "hardhat";

const { contract: contractName, deploymentTransaction } =
  await hre.viem.sendDeploymentTransaction(
    "contractName",
    ["arg1", 50, "arg3"],
    {
      client: { wallet: secondWalletClient },
      gas: 1000000,
      value: parseEther("0.0001"),
    }
  );

Then, if you want to wait for the transaction to be mined, you can do:

import hre from "hardhat";

const publicClient = await hre.viem.getPublicClient();
const { contractAddress } = await publicClient.waitForTransactionReceipt({
  hash: deploymentTransaction.hash,
});

Library linking

Some contracts need to be linked with libraries before they are deployed. You can pass the addresses of their libraries to the deployContract and sendDeploymentTransaction functions with an object like this:

const contractA = await hre.viem.deployContract(
  "contractName",
  ["arg1", 50, "arg3"],
  {
    libraries: {
      ExampleLib: "0x...",
    },
  }
);

This allows you to deploy a contract linked to the ExampleLib library at the address "0x...".

To deploy a contract, all libraries must be linked. An error will be thrown if any libraries are missing.

Using ContractTypesMap for easier contract type imports

To simplify importing contract types in hardhat-viem, you can use the ContractTypesMap. This map contains the contract types of all contracts in your project, indexed by their names.

import { ContractTypesMap } from "hardhat/types/artifacts";

const contract: ContractTypesMap["ContractName"];

This reduces the need for multiple imports and makes your code cleaner and easier to manage.

Usage

There are no additional steps you need to take for this plugin to work.

Install it and access Viem through the Hardhat Runtime Environment anywhere you need it (tasks, scripts, tests, etc).

Read the documentation on the Hardhat Runtime Environment to learn how to access the HRE in different ways to use Viem from anywhere the HRE is accessible.