TypeChain

Common errors

• Cannot find module '@typechain/hardhat' or its corresponding type declarations.

  cause The Hardhat TypeChain plugin has not been installed or correctly imported/required in your `hardhat.config.ts`.
  fix Run `npm install --save-dev @typechain/hardhat` to install the plugin. Then, ensure it's imported in `hardhat.config.ts` using `import '@typechain/hardhat';` (for ESM) or `require('@typechain/hardhat');` (for CommonJS).

• Property 'connect' does not exist on type 'BaseContract' (or similar type mismatch errors when interacting with Ethers.js contracts).

  cause This error typically indicates a mismatch between the Ethers.js version installed in your project and the TypeChain target configured. For instance, using `ethers@^6.0.0` with types generated by `@typechain/ethers-v5`.
  fix Verify your `ethers` dependency version (e.g., `ethers@^6.0.0`) and set the TypeChain target accordingly in your `hardhat.config.ts` (e.g., `target: 'ethers-v6'`). Regenerate types after making changes.

• TypeError: Cannot read properties of undefined (reading 'getContractFactory') or Property 'ethers' does not exist on type 'HardhatRuntimeEnvironment'.

  cause This often occurs if `@nomicfoundation/hardhat-toolbox` or relevant Hardhat plugins (like `@nomiclabs/hardhat-ethers`) are not installed or correctly imported, preventing Hardhat from exposing the `ethers` object on its runtime environment.
  fix Ensure `@nomicfoundation/hardhat-toolbox` is installed (`npm install --save-dev @nomicfoundation/hardhat-toolbox`) and imported in `hardhat.config.ts`: `import '@nomicfoundation/hardhat-toolbox';`.

Warnings

• breaking TypeChain requires TypeScript version 4.3 or newer. Using older versions will result in compilation errors or incorrect type generation, as TypeChain leverages modern TypeScript features.
  Fix: Ensure `typescript` is installed at version `>=4.3.0` in your project's `devDependencies` to meet TypeChain's requirements.
• gotcha When using the `@typechain/ethers-v6` target with ESM module resolution (e.g., in a Node.js project configured with `type: 'module'`), you must explicitly enable the `--node16-modules` flag or `node16Modules: true` in your configuration for correct output. This ensures proper ESM resolution for the generated types.
  Fix: If using Hardhat, add `node16Modules: true` to your TypeChain configuration in `hardhat.config.ts`. If running TypeChain directly, pass the `--node16-modules` CLI flag.
• breaking Breaking changes exist between `ethers-v5` and `ethers-v6` TypeChain targets due to significant API differences in Ethers.js. Always ensure that the TypeChain target (`@typechain/ethers-v5` or `@typechain/ethers-v6`) matches the Ethers.js version used in your project to avoid type mismatches and runtime errors.
  Fix: Install the correct TypeChain Ethers target (e.g., `npm install --save-dev @typechain/ethers-v6`) and configure your `typechain` settings (`target: 'ethers-v6'`) to align with your project's Ethers.js dependency.
• gotcha The core `typechain` package provides the generator logic, but framework-specific bindings and integration (e.g., for Hardhat, Truffle, Ethers.js) require installing additional 'target' packages. Failing to install the correct target will prevent TypeChain from generating usable types for your chosen environment.
  Fix: Install all necessary TypeChain target packages as dev dependencies. For example: `npm install --save-dev typechain @typechain/hardhat @typechain/ethers-v6`.

Install

• npm install typechain npm
• yarn add typechain yarn
• pnpm add typechain pnpm

Imports

• GeneratedContract

  import { MyContract } from '../typechain-types/contracts/MyContract'

  TypeChain itself is primarily a CLI tool and a build-time generator. The most common 'imports' for users are for the *generated* TypeScript types, which reside in the output directory (e.g., 'typechain-types'). The exact path varies based on your project structure and contract name.
• Hardhat plugin enablement
  wrong:

  require('@typechain/hardhat')

  correct:

  import '@typechain/hardhat'

  When using TypeChain with Hardhat, you typically enable the plugin in `hardhat.config.ts`. If your Hardhat config is an ESM file, use `import`. For CommonJS (the default for older Hardhat setups), `require` is correct. This refers to the plugin registration, not importing specific symbols from the plugin.
• runTypeChain

  import { runTypeChain } from 'typechain'

  This symbol is used for advanced programmatic integration of TypeChain, not typically imported by end-users. Most users rely on the TypeChain CLI or framework-specific plugins (like `@typechain/hardhat`) to invoke TypeChain's generation process.

Quickstart

Demonstrates `typechain` integration with Hardhat by configuring the plugin, specifying an Ethers.js v6 target, and then using the generated TypeScript bindings for deploying and interacting with a sample smart contract.

import { HardhatUserConfig, task } from 'hardhat/config';
import '@nomicfoundation/hardhat-toolbox';
import '@typechain/hardhat'; // Import the Hardhat TypeChain plugin

const config: HardhatUserConfig = {
  solidity: "0.8.20",
  networks: {
    hardhat: {
      chainId: 1337, // Example local network ID
    },
  },
  typechain: {
    outDir: 'typechain-types', // Output directory for generated types
    target: 'ethers-v6', // Specify the target library (e.g., ethers.js v6)
    alwaysConsiderOverloadedFunctions: true,
  },
};

// Example Hardhat task demonstrating usage of TypeChain generated types
task("deploy", "Deploys a sample contract").setAction(async (taskArgs, hre) => {
  const [deployer] = await hre.ethers.getSigners();
  console.log(
    "Deploying contracts with the account:",
    deployer.address
  );

  // Accessing a generated contract factory type (e.g., Greeter__factory)
  // Ensure your contract is named 'Greeter.sol' in the 'contracts' directory
  const GreeterFactory = await hre.ethers.getContractFactory("Greeter");
  const greeter = await GreeterFactory.deploy("Hello, Hardhat!");

  await greeter.waitForDeployment();

  console.log(`Greeter deployed to ${greeter.target}`);

  // Using type-safe method calls on the deployed contract instance
  const message = await greeter.greet();
  console.log("Contract message:", message);
});

export default config;

/*
// Example Solidity contract: contracts/Greeter.sol
// SPDX-License-Identifier: MIT
// pragma solidity ^0.8.20;
// 
// contract Greeter {
//     string private _greeting;
// 
//     constructor(string memory greeting_) {
//         _greeting = greeting_;
//     }
// 
//     function greet() public view returns (string memory) {
//         return _greeting;
//     }
// 
//     function setGreeting(string memory greeting_) public {
//         _greeting = greeting_;
//     }
// }
*/