hardhat-ethers

This plugin integrates ethers.js into Hardhat, adding an ethers object to each network connection.

Installation

This plugin is part of the Ethers+Mocha Hardhat Toolbox. If you are using that toolbox, there's nothing else you need to do.

To install this plugin, run the following command:

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

In your hardhat.config.ts file, import the plugin and add it to the plugins array:

import { defineConfig } from "hardhat/config";
import hardhatEthers from "@nomicfoundation/hardhat-ethers";

export default defineConfig({
  plugins: [hardhatEthers],
});

Usage

This plugin adds an ethers property to each network connection:

import { network } from "hardhat";

const { ethers } = await network.connect();

const counter = await ethers.deployContract("Counter");
await counter.inc();
console.log(await counter.x());

This object has the same API as ethers.js, with some extra Hardhat-specific functionality. The rest of this section describes the most important extra features. Check the API reference below for the complete list of extensions.

Provider

The plugin adds a provider property to the ethers object: an ethers.js provider connected to the network selected by network.connect().

const blockNumber = await ethers.provider.getBlockNumber();

const balance = await ethers.provider.getBalance(someAddress);

Use ethers.provider to access read-only blockchain data, such as accounts state, block data, or transactions objects.

Deploying contracts

The hardhat-ethers plugin also adds a deployContract method to the ethers object, which allows you to easily deploy contracts from your project:

const counter = await ethers.deployContract("Counter");

await counter.inc();
console.log(await counter.x());

Library linking

Some contracts need to be linked with libraries before they are deployed. You can pass the addresses of their libraries to methods like deployContract with an object mapping library names to their addresses:

const counter = await ethers.deployContract("Counter", {
  libraries: {
    SafeMath: "0x...",
  },
});

This allows you to deploy an instance of the Counter contract, linking its SafeMath library to the address "0x...". The plugin will throw an error if you try to deploy a contract or create a factory without linking the necessary libraries.

API

provider

An ethers.js provider connected to the network you selected when calling network.connect:

// the network selected with --network option if specified, or the default network otherwise
const { ethers } = await network.connect();

// a specific network from the config
const { ethers } = await network.connect("mainnet");

deployContract

Deploys a contract from your project.

function deployContract(
  name: string,
  constructorArgs?: any[],
  signer?: ethers.Signer,
): Promise<ethers.Contract>;

Receives the name of the contract to deploy. Most of the time this will be the name of the contract:

const counter = await ethers.deployContract("Counter");

If you have two contracts with the same name in different files, you'll need to use the fully qualified name of the contract, which includes its source name:

const counter = await ethers.deployContract("contracts/Counter.sol:Counter");

If your contract has constructor parameters, you can pass them as the second argument:

const counter = await ethers.deployContract("Counter", [42]);

By default, the contract will be deployed with the first available signer. If you want to use a different one, you can pass it as the third argument:

const [defaultSigner, deployer] = await ethers.getSigners();
const counter = await ethers.deployContract("Counter", [], deployer);

getContractFactory

Returns an ethers.js contract factory.

function getContractFactory(
  name: string,
  signer?: ethers.Signer,
): Promise<ethers.ContractFactory>;
function getContractFactory(
  name: string,
  factoryOptions: FactoryOptions,
): Promise<ethers.ContractFactory>;
function getContractFactory(
  abi: any[],
  bytecode: ethers.utils.BytesLike,
  signer?: ethers.Signer,
): Promise<ethers.ContractFactory>;

It can receive a contract name:

const Counter = await ethers.getContractFactory("Counter");
const counter = await Counter.deploy();

Or an ABI and a deployment bytecode:

const Counter = await ethers.getContractFactory(counterAbi, counterBytecode);
const counter = await Counter.deploy();

By default, the contracts deployed with the factory will use the first signer in the config. If you want to use a different signer, you can pass it as the second argument:

const [defaultSigner, deployer] = await ethers.getSigners();
const Counter = await ethers.getContractFactory("Counter", deployer);
const counter = await Counter.deploy();

getContractAt

Returns an ethers.js contract instance connected to a specific address.

function getContractAt(
  name: string,
  address: string,
  signer?: ethers.Signer,
): Promise<ethers.Contract>;
function getContractAt(
  abi: any[],
  address: string,
  signer?: ethers.Signer,
): Promise<ethers.Contract>;

It can receive a contract name and an address:

const counter = await ethers.getContractAt("Counter", "0x1234...abcd");

Or an ABI and an address:

const counter = await ethers.getContractAt(counterAbi, "0x1234...abcd");

By default, the contract will be connected to the first signer in the config. If you want to use a different signer, you can pass it as the third argument:

const [defaultSigner, caller] = await ethers.getSigners();
const counter = await ethers.getContractAt("Counter", "0x1234...abcd", caller);

getSigners

Returns an array of ethers.js signers that correspond to the accounts configured in your Hardhat project.

function getSigners(): Promise<ethers.Signer[]>;

For example:

const signers = await ethers.getSigners();

getSigner

Returns a specific ethers.js signer by its address.

function getSigner(address: string): Promise<ethers.Signer>;

For example:

const signer = await ethers.getSigner("0x1234...abcd");

getImpersonatedSigner

Like getSigner, but it impersonates the given address, allowing you to use it even if you don't have its private key.

function getImpersonatedSigner(address: string): Promise<ethers.Signer>;

For example:

const impersonatedSigner = await ethers.getImpersonatedSigner("0x1234...abcd");

getContractFactoryFromArtifact

Like getContractFactory, but receives a Hardhat artifact.

function getContractFactoryFromArtifact(
  artifact: Artifact,
  signer?: ethers.Signer,
): Promise<ethers.ContractFactory>;
function getContractFactoryFromArtifact(
  artifact: Artifact,
  factoryOptions: FactoryOptions,
): Promise<ethers.ContractFactory>;

getContractAtFromArtifact

Like getContractAt, but receives a Hardhat artifact.

function getContractAtFromArtifact(
  artifact: Artifact,
  address: string,
  signer?: ethers.Signer,
): Promise<ethers.Contract>;