dl-solarity
Hardhat migrate
The simplest way to deploy smart contracts.
What
This plugin helps you deploy and verify the source code for your Solidity contracts via migrations.
With sleek UX that doesn't require writing "deployment wrappers", users can:
- Specify custom smart contract deployment rules and configuration via @ethers.
- Verify smart contracts source code through seamless integration with @nomicfoundation/hardhat-verify.
- Leverage "migration recovery mode" that syncs up deployment from the last failed transaction.
- Observe real-time status and logging of executing transactions.
- Check out the generation of deployment reports in Markdown (.md) or JSON (.json) format.
- Simplify Solidity
librariesusage via auto-linking mechanics. - Support multiple wallet types, including Cast Wallet and Trezor hardware wallet.
- And much more.
Installation
npm install --save-dev @solarity/hardhat-migrateAdd the following statement to your hardhat.config.js:
require("@solarity/hardhat-migrate");
require("@nomicfoundation/hardhat-ethers");
require("@nomicfoundation/hardhat-verify"); // If you want to verify contractsOr, if you are using TypeScript, add this to your hardhat.config.ts:
import "@solarity/hardhat-migrate";
import "@nomicfoundation/hardhat-ethers";
import "@typechain/hardhat"; // For typization of Ethers
import "@nomicfoundation/hardhat-verify"; // If you want to verify contracts[!NOTE] The
@nomicfoundation/hardhat-ethersimport is obligatory as it is used to determine the deployment account.
Usage
You may add the following migrate config to your hardhat.config file:
module.exports = {
migrate: {
filter: {
from: -1,
to: -1,
only: -1,
skip: -1,
},
verification: {
verify: false,
verificationDelay: 5000,
verifyParallel: 1,
verifyAttempts: 3,
},
paths: {
pathToMigrations: "./deploy",
namespace: "",
},
execution: {
force: false,
continue: false,
wait: 1,
transactionStatusCheckInterval: 2000,
withoutCLIReporting: false,
},
castWallet: {
passwordFile: "/path/to/password",
keystore: "/path/to/keystore",
account: "account-name",
},
trezorWallet: {
enabled: false,
mnemonicIndex: 0,
},
},
};Where:
filterfrom- The migration number from which the migration will be applied.to- The migration number up to which the migration will be applied.only- The number of the migration that will be applied. Overrides from and to parameters.skip- The number of migration to skip. Overrides only parameter.
verificationverify- The flag indicating whether the contracts have to be verified after all migrations.verificationDelay- The delay in milliseconds between the deployment and verification of the contract.verifyParallel- The size of the batch for verification.verifyAttempts- The number of attempts to verify the contract.
pathspathToMigrations- The path to the folder with the specified migrations.namespace- The path to the subfolder where the migration should be run.reportPath- The path to directory where the migration report should be saved (./cacheby default).reportFormat- The format of the migration report (mdorjson). Defaults tomdfor Markdown format.
executionforce- The flag indicating whether the contracts compilation is forced.continue- The flag indicating whether the deployment should restore the state from the previous deployment.wait- The number of block confirmations to wait for after the transaction is mined.transactionStatusCheckInterval- The interval in milliseconds between transaction status checks.withoutCLIReporting- The flag indicating whether the CLI reporting should be disabled.
castWalletpasswordFile- File path to the keystore password.keystore- Use a keystore file or directory. Cannot be used withaccount.account- The name of the cast wallet account. Cannot be used withkeystore.
trezorWalletenabled- The flag indicating whether to use the Trezor hardware wallet for signing transactions.mnemonicIndex- The mnemonic index for Trezor wallet.
Tasks
migratetask, which allows you to deploy and automatically verify contracts.migrate:verifytask, which helps you verify already deployed contracts.
To view the available options, run the help command:
npx hardhat help migrate[!WARNING] If you are willing to verify smart contracts source code, make sure to specify the correct config for the
@nomicfoundation/hardhat-verifyplugin.
Migration naming
It is mandatory to follow this naming convention for migration files:
X_migration_name.migration.[js|ts]
- Where X is an ordinal number indicating the order in which the migration will be applied.
- migration_name is simply the name of the migration.
Example
After importing the necessary dependencies to the hardhat.config, create the file 1_token.migration.ts in the deploy directory.
Then run:
npx hardhat migrate --network <the network of choice>This command will run the migration script and execute all the specified actions, producing the following live deployment log:
| Migration Script | Deployment Output | Migration Report | ||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
Migration Report 2025-03-14T16:01:26.567Z.mdGeneral InformationMigration Files
Networks
Detailed Migration Files1_token.migration.ts
Stats
Total Cost: 0.061426897305814476 ETH All Data
|
The detailed migration report with all information about transactions is automatically saved in the ./cache folder in either Markdown (.md) or JSON (.json) format based on the reportFormat configuration.
Documentation
For more detailed information, please refer to the following documentation:
- Deployer API - Core functionality for contract deployment
- Reporter API - Logging and reporting utilities
- Migration Process - Lifecycle and transaction handling
- External Wallets - Cast Wallet and Trezor integration
- Detailed Example - Comprehensive migration example
Known limitations
- Adding, removing, moving, or renaming contracts in your Hardhat project or reorganizing the directory structure after deployment may alter the resulting bytecode in some Solidity compiler versions. See this Solidity issue for further information.
- This plugin does not function properly with native Ethers factory methods, such as
factory.attach(). Instead, usedeployer.deployed().