Hardhat migrate
Hardhat plugin to simplify the deployment and verification of contracts.
What
This plugin helps you deploy and automatically verify the source code for your Solidity contracts on Etherscan.
This is a fairly simple and rather straightforward Hardhat plugin:
-
For deployment, it uses @truffle/deployer and @truffle/reporters to report on the deployment process.
-
For verification, it uses @nomiclabs/hardhat-etherscan
Installation
npm install --save-dev @dlsl/hardhat-migrate
And add the following statement to your hardhat.config.js
:
require("@nomiclabs/hardhat-web3");
require("@nomiclabs/hardhat-truffle5");
require("@dlsl/hardhat-migrate");
Or, if you are using TypeScript, add this to your hardhat.config.ts
:
import "@nomiclabs/hardhat-web3";
import "@nomiclabs/hardhat-truffle5";
import "@dlsl/hardhat-migrate";
Important.
The @nomiclabs/hardhat-web3
and @nomiclabs/hardhat-truffle5
are necessary,
as these plugins are used to work with migration files.
See How it works for further information.
Naming convention
It is also mandatory to specify the naming convention for migrations such as this one:
X_migration_name.migration.js
- Where X is an ordinal number of the migration in which it will be applied.
- migration_name is simply the name of the migration.
Tasks
migrate
task, which allows you to deploy and automatically verify contracts.migrate:verify
task, which helps you verify already deployed contracts.
Under the hood, for verification process, it uses @nomiclabs/hardhat-etherscan plugin.
⚠️ Hardhat Config: Make sure they are follow the docs from@nomiclabs/hardhat-etherscan
.
Do not import @dlsl/hardhat-migrate
and @nomiclabs/hardhat-etherscan
together, the etherscan plugin is already included in the migrate plugin.
To view the available options, run the command (help command):
npx hardhat help migrate
Environment extensions
This plugin does not extend the environment.
Usage
You may add the following migrate
config to your hardhat config file:
module.exports = {
migrate: {
from: 1,
to: 5,
only: 2,
skip: 1,
verify: true,
attempts: 2,
confirmations: 5,
pathToMigrations: "./deploy/",
skipVerificationErrors: ["already verified"],
},
};
Parameter explanation
from
: 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.confirmations
: The number defining after how many blocks the verification should start.attempts
: The number of attempts to verify the contract.pathToMigrations
: The path to the folder with the specified migrations.skipVerificationErrors
: The user can specify custom verification errors that will be omitted and just be printed to the log instead of stopping the program completely. By default, if this parameter is not specified, thealready verified
error is omitted.
verify
: The flag indicating whether the verification of the contract is needed.force
: The flag indicating whether the contracts compilation is forced.
Deploying
You can set your own migrations and deploy the contracts to the network you want.
With only parameter
$ npx hardhat migrate --network goerli --verify --only 2
In this case, only the migration that begins with digit 2 will be applied. The plugin will also try to automatically verify the deployed contracts.
Or with from/to parameters
$ npx hardhat migrate --network sepolia --from 1 --to 2
In this case, migrations 1 through 2 (both) will be applied without the automatic verification.
Verifying
This plugin has a
migrate:verify
task, to learn how to use it, see the example project.
You can manually verify contracts:
$ npx hardhat verify --network goerli DEPLOYED_CONTRACT_ADDRESS "Constructor argument 1"
Other examples of manual contract verification can be found here @nomiclabs/hardhat-etherscan
How it works
The plugin includes the following packages to perform the deployment and verification process:
- For deployment
- For verification:
The core of this plugin is migration files, you can specify the migration route that suits you best.
You can find an example of migration files in the sample project.
Migration Lifecycle
The migration files are sorted by the first digit in the file name and run one after the other in ascending order.
Parameters: from
, to
, only
and skip
affect the selection of the migration files.
Deployer
Deployer contains two functions that are used to deploy contracts:
- Deployment function
Under the hood, it uses TruffleDeployer
from @truffle/deployer
and TruffleReporter
from @truffle/reporters to deploy the contracts and log their statuses during the deployment process.
After that, if the user had set the verify
flag, the contract would be automatically verified. However,
the execution will wait confirmations
number of blocks before sending a request to etherscan.
- Link function
The link function of the TruffleContract
class from the @nomiclabs/hardhat-truffle5
package is used to link external libraries to a contract.
Verifier
If the verify
flag is set, automatic verification will start immediately after the contract is deployed.
For a list of parameters that affect the verification process, see Parameter Explanation.
If verification fails, the attempts
parameter indicates how many additional requests will be made before the migration process is terminated.
The user can also define which verification errors are irrelevant and have to be ignored using the skipVerificationErrors
parameter. By default, the already verified
error is omitted.
Logger
Logger provides two functions:
logTransaction
- logs data about the transaction after its confirmation.logContracts
- logs contract addresses in an assembled table.
Known limitations
- This plugin, as well as the Hardhat Toolbox plugin, use the @nomiclabs/hardhat-etherscan plugin internally, so both of these plugins cannot be imported at the same time. A quick fix is to manually import the needed plugins that ToolBox imports.
- Adding, removing, moving or renaming new contracts to the hardhat project or reorganizing the directory structure of contracts after deployment may alter the resulting bytecode in some solc versions. See this Solidity issue for further information.