CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-nomiclabs--hardhat-ethers

Hardhat plugin that integrates ethers.js into the Hardhat development environment with helper functions for contract deployment, interaction, and signer management.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

index.mddocs/

Hardhat Ethers Plugin

The @nomiclabs/hardhat-ethers plugin integrates ethers.js into the Hardhat development environment, providing developers with a comprehensive set of utilities for interacting with Ethereum smart contracts. It extends the Hardhat Runtime Environment with an ethers object that includes the full ethers.js API plus additional Hardhat-specific functionality.

Package Information

  • Package Name: @nomiclabs/hardhat-ethers
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install --save-dev @nomiclabs/hardhat-ethers 'ethers@^5.0.0'

Core Imports

Add the plugin to your hardhat.config.ts:

import "@nomiclabs/hardhat-ethers";

Or in hardhat.config.js:

require("@nomiclabs/hardhat-ethers");

Access ethers through the Hardhat Runtime Environment:

import { ethers } from "hardhat";
// or access via HRE parameter in tasks, tests, scripts

Basic Usage

import { ethers } from "hardhat";

// Deploy a contract
const contractFactory = await ethers.getContractFactory("MyContract");
const contract = await contractFactory.deploy(arg1, arg2);
await contract.deployed();

// Get signers
const [deployer, user] = await ethers.getSigners();

// Interact with existing contract
const existingContract = await ethers.getContractAt("MyContract", contractAddress);
const result = await existingContract.someMethod();

Architecture

The hardhat-ethers plugin is built around several key components:

  • Environment Extension: Extends Hardhat Runtime Environment with ethers object containing full ethers.js API plus Hardhat helpers
  • Helper Functions: Streamlined functions for contract deployment, factory creation, and contract interaction
  • Signer Management: Enhanced signer functionality with SignerWithAddress class that includes address property
  • Provider Integration: Automatic provider setup connected to the selected Hardhat network
  • Library Linking: Support for Solidity library linking in complex contract deployments

Capabilities

Contract Factories

Functions for creating contract factories from artifacts, names, or ABI/bytecode combinations. Supports library linking for complex contracts.

function getContractFactory(
  name: string,
  signerOrOptions?: ethers.Signer | FactoryOptions
): Promise<ethers.ContractFactory>;

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

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

interface FactoryOptions {
  signer?: ethers.Signer;
  libraries?: Libraries;
}

interface Libraries {
  [libraryName: string]: string;
}

Contract Factories

Contract Interaction

Functions for interacting with deployed contracts at specific addresses using contract names, artifacts, or ABI definitions.

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

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

Contract Interaction

Contract Deployment

Simplified contract deployment functionality that combines factory creation and deployment in a single function call.

function deployContract(
  name: string,
  args?: any[],
  signerOrOptions?: ethers.Signer | FactoryOptions
): Promise<ethers.Contract>;

function deployContract(
  name: string,
  signerOrOptions?: ethers.Signer | FactoryOptions
): Promise<ethers.Contract>;

Contract Deployment

Signer Management

Enhanced signer functionality with SignerWithAddress class and helper functions for managing test accounts and impersonation.

function getSigners(): Promise<SignerWithAddress[]>;

function getSigner(address: string): Promise<SignerWithAddress>;

function getImpersonatedSigner(address: string): Promise<SignerWithAddress>;

class SignerWithAddress extends ethers.Signer {
  readonly address: string;
  static create(signer: ethers.providers.JsonRpcSigner): Promise<SignerWithAddress>;
  getAddress(): Promise<string>;
  signMessage(message: string | ethers.utils.Bytes): Promise<string>;
  signTransaction(transaction: ethers.utils.Deferrable<ethers.providers.TransactionRequest>): Promise<string>;
  sendTransaction(transaction: ethers.utils.Deferrable<ethers.providers.TransactionRequest>): Promise<ethers.providers.TransactionResponse>;
  connect(provider: ethers.providers.Provider): SignerWithAddress;
  _signTypedData(...params: Parameters<ethers.providers.JsonRpcSigner["_signTypedData"]>): Promise<string>;
  toJSON(): string;
}

Signer Management

Provider Access

Direct access to the ethers provider automatically configured for the selected Hardhat network.

const provider: ethers.providers.JsonRpcProvider;

The provider is available at ethers.provider and is automatically connected to the network specified in your Hardhat configuration.

Types

import { Artifact } from "hardhat/types";

interface Libraries {
  [libraryName: string]: string;
}

interface FactoryOptions {
  signer?: ethers.Signer;
  libraries?: Libraries;
}

interface HardhatEthersHelpers {
  provider: ethers.providers.JsonRpcProvider;
  getContractFactory: typeof getContractFactory;
  getContractFactoryFromArtifact: (
    artifact: Artifact,
    signerOrOptions?: ethers.Signer | FactoryOptions
  ) => Promise<ethers.ContractFactory>;
  getContractAt: (
    nameOrAbi: string | any[],
    address: string,
    signer?: ethers.Signer
  ) => Promise<ethers.Contract>;
  getContractAtFromArtifact: (
    artifact: Artifact,
    address: string,
    signer?: ethers.Signer
  ) => Promise<ethers.Contract>;
  getSigner: (address: string) => Promise<SignerWithAddress>;
  getSigners: () => Promise<SignerWithAddress[]>;
  getImpersonatedSigner: (address: string) => Promise<SignerWithAddress>;
  deployContract: typeof deployContract;
}

Ethers.js Integration

The plugin provides the complete ethers.js v5 API through the ethers object, including:

  • Contracts: ethers.Contract, ethers.ContractFactory
  • Providers: ethers.providers.*
  • Signers: ethers.Signer, ethers.Wallet
  • Utilities: ethers.utils.*
  • Constants: ethers.constants.*
  • BigNumber: ethers.BigNumber

All ethers.js functionality is available alongside the Hardhat-specific helpers.

Install with Tessl CLI

npx tessl i tessl/npm-nomiclabs--hardhat-ethers

docs

contract-deployment.md

contract-factories.md

contract-interaction.md

index.md

signer-management.md

tile.json