TypeChain Documentation

TypeChain generates <contract-name>.ts files that provide type-safe interfaces for Ethers 5.x.x Contract instances. These typings allow you to interact with contracts with full TypeScript support for:

• Methods: Accessible via contract.someMethod(...) or contract.functions.someMethod(...).
• Events & Filters: Typed events available at contract.interface.events.AnEvent and filters at contract.filters.AnEvent.
• Gas Estimation: Typed method gas estimates via contract.estimateGas.someMethod.
• Event Listeners: Typed overrides for listener methods like on and once that return the same contract type.

Note: These are type declarations only and are not available at runtime; all generated contracts remain instances of the standard Ethers Contract class.

Use the ethers-v6 target to generate wrappers for the Ethers.js v6 library. For optimal integration with Hardhat, use the official Hardhat plugin.

If your project uses nodenext (also known as node16modules), use the --node16-modules flag to ensure the generated typings are compatible.

After installation, you must register the plugin in your Hardhat configuration file.

For JavaScript (hardhat.config.js):

require('@typechain/hardhat')
require('@nomicfoundation/hardhat-ethers')
require('@nomicfoundation/hardhat-chai-matchers')

For TypeScript (hardhat.config.ts):

import '@typechain/hardhat'
import '@nomicfoundation/hardhat-ethers'
import '@nomicfoundation/hardhat-chai-matchers'

Important: Before running for the first time, execute npx hardhat clean. This ensures TypeChain performs a full generation rather than an incremental one. You should also run hardhat clean if you modify any TypeChain configuration options.

To use TypeChain, install the core package as a development dependency. You must also install a specific target package corresponding to the library you are using (e.g., @typechain/ethers-v6).

Note: Generated code requires TypeScript version 4.3 or newer.

npm install --save-dev typechain

After the initial setup, you can run the example's tests using pnpm test. Note that pnpm install automatically triggers TypeChain type generation. If you need to manually regenerate the types, use the pnpm generate-types command.

pnpm install # it will automatically run TypeChain types generation

pnpm test

# To manually regenerate types:
pnpm generate-types

To run the TypeChain x Hardhat example, you must first build the monorepo. Follow these steps from the root of the monorepo:

1. Install dependencies: pnpm install
2. Build the monorepo: pnpm build

Once built, you can enter the example directory and run pnpm install. This will automatically trigger the TypeChain types generation.

# in the root of monorepo
pnpm install
pnpm build

To run migrations, use the pnpm migrate command.

Important Limitation: Migrations must be transpiled from TypeScript to JavaScript before they can be executed by Truffle. This requirement does not apply to running tests.