https://github.com/dl-solarity/hardhat-migrate
The simplest way to deploy smart contracts
https://github.com/dl-solarity/hardhat-migrate
deploy hardhat-plugin smart-contracts solarity typechain verify
Last synced: about 1 month ago
JSON representation
The simplest way to deploy smart contracts
- Host: GitHub
- URL: https://github.com/dl-solarity/hardhat-migrate
- Owner: dl-solarity
- License: mit
- Created: 2022-11-04T15:03:25.000Z (over 2 years ago)
- Default Branch: master
- Last Pushed: 2025-03-23T12:16:28.000Z (about 2 months ago)
- Last Synced: 2025-04-10T00:17:24.536Z (about 1 month ago)
- Topics: deploy, hardhat-plugin, smart-contracts, solarity, typechain, verify
- Language: TypeScript
- Homepage: https://npmjs.com/package/@solarity/hardhat-migrate
- Size: 1.58 MB
- Stars: 34
- Watchers: 4
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://www.npmjs.com/package/@solarity/hardhat-migrate) [](https://hardhat.org)
# 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](https://www.npmjs.com/package/ethers).
- Verify smart contracts source code through seamless integration with [@nomicfoundation/hardhat-verify](https://www.npmjs.com/package/@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 markdown (.md) deployment reports.
- Simplify Solidity `libraries` usage via auto-linking mechanics.
- Support multiple wallet types, including [Cast Wallet](https://book.getfoundry.sh/cast/) and [Trezor](https://trezor.io/) hardware wallet.
- And much more.
## Installation
```bash
npm install --save-dev @solarity/hardhat-migrate
```
Add the following statement to your `hardhat.config.js`:
```js
require("@solarity/hardhat-migrate");
require("@nomicfoundation/hardhat-ethers");
require("@nomicfoundation/hardhat-verify"); // If you want to verify contracts
```
Or, if you are using TypeScript, add this to your `hardhat.config.ts`:
```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-ethers` import is obligatory as it is used to determine the deployment account.
## Usage
You may add the following `migrate` config to your `hardhat.config` file:
```js
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:
- `filter`
- `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.**
- `verification`
- `verify` - 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.
- `paths`
- `pathToMigrations` - 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 (`./cache` by default).
- `execution`
- `force` - 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.
- `castWallet`
- `passwordFile` - File path to the keystore password.
- `keystore` - Use a keystore file or directory. Cannot be used with `account`.
- `account` - The name of the cast wallet account. Cannot be used with `keystore`.
- `trezorWallet`
- `enabled` - The flag indicating whether to use the Trezor hardware wallet for signing transactions.
- `mnemonicIndex` - The mnemonic index for Trezor wallet.
## Tasks
- `migrate` task, which allows you to deploy and automatically verify contracts.
- `migrate:verify` task, which helps you verify already deployed contracts.
To view the available options, run the help command:
```bash
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-verify` plugin.
## 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:
```bash
npx hardhat migrate --network
```
This command will run the migration script and execute all the specified actions, producing the following *live* deployment log:
Migration Script
Deployment Output
Markdown Report
```ts
// file location: ./deploy/1_token.migration.ts
import { ethers } from "ethers";
import { Deployer, Reporter } from "@solarity/hardhat-migrate";
import { ERC20Mock__factory } from "../generated-types/ethers";
export = async (deployer: Deployer) => {
// deploy the token via `Deployer` object
const token = await deployer.deploy(
ERC20Mock__factory, // contract to deploy
["Example Token", "ET", 18] // constructor params
);
const recipient = "0x1E3953B6ee74461169A3E346060AE27bD0B5bF2B";
const amount = ethers.parseEther("1000");
// call `mint` function on the token
await token.mint(recipient, amount);
// log the token address via `Reporter` object
await Reporter.reportContractsMD(
["Example Token", await token.getAddress()]
);
};
```
```
Migration files:
> 1_token.migration.ts
> Network: sepolia
> Network id: 11155111
Starting migration...
Running 1_token.migration.ts...
Deploying ERC20Mock
> explorer: 0xc35dd9e9600f102cf3b414f1341560870021b3824ace4bedbd59e2216bd89a49
> contractAddress: 0xc596A6e2f1558c7e030272d2A2E37E53050E2D63
> blockNumber: 7844739
> blockTimestamp: 1741263816
> account: 0xf41ceE234219D6cc3d90A6996dC3276aD378cfCF
> value: 0.0 ETH
> balance: 0.117945868841929599 ETH
> gasUsed: 571635
> gasPrice: 96.422889727 GWei
> fee: 0.055118698569093645 ETH
Transaction: ERC20Mock.mint(address,uint256)(2 arguments)
> explorer: 0x508a289795cb8e3e1265dfd8f528efc206146a62deba4f9a80a2fa19d6a6ec8e
> blockNumber: 7844740
> blockTimestamp: 1741263828
> account: 0xf41ceE234219D6cc3d90A6996dC3276aD378cfCF
> value: 0.0 ETH
> balance: 0.111637670105208768 ETH
> gasUsed: 68433
> gasPrice: 92.180654607 GWei
> fee: 0.006308198736720831 ETH
| Contract | Address |
| ------------- | ------------------------------------------ |
| Example Token | 0xc596A6e2f1558c7e030272d2A2E37E53050E2D63 |
> Total transactions: 2
> Final cost: 0.061426897305814476 ETH
```
# Migration Report 2025-03-14T16:01:26.567Z.md
## General Information
### Migration Files
- 1_token.migration.ts
### Networks
- sepolia - Chain ID: 11155111. Explorer: https://sepolia.etherscan.io
## Detailed Migration Files
### 1_token.migration.ts
- https://sepolia.etherscan.io/tx/0xc35dd9e9600f102cf3b414f1341560870021b3824ace4bedbd59e2216bd89a49
- https://sepolia.etherscan.io/tx/0x508a289795cb8e3e1265dfd8f528efc206146a62deba4f9a80a2fa19d6a6ec8e
## Stats
| Total Contracts | Total Transactions | Gas Used | Average Gas Price | Fee Payed | Native Currency Sent |
| --------------- | ------------------ | -------- | ----------------- | ------------------------ | -------------------- |
| 1 | 1 | 640068 | 94.301772167 GWei | 0.061426897305814476 ETH | 0.0 ETH |
Total Cost:
0.061426897305814476 ETH
## All Data
| Name | Address |
| --------------------------------------------- | ------------------------------------------------------------------ |
| contracts/mock/tokens/ERC20Mock.sol:ERC20Mock | 0xc596A6e2f1558c7e030272d2A2E37E53050E2D63 |
| ERC20Mock.mint(address,uint256)(2 arguments) | 0x508a289795cb8e3e1265dfd8f528efc206146a62deba4f9a80a2fa19d6a6ec8e |
The detailed migration report with all information about transactions is automatically saved in the `./cache` folder.
## Documentation
For more detailed information, please refer to the following documentation:
- [Deployer API](./docs/Deployer.md) - Core functionality for contract deployment
- [Reporter API](./docs/Reporter.md) - Logging and reporting utilities
- [Migration Process](./docs/MigrationProcess.md) - Lifecycle and transaction handling
- [External Wallets](./docs/ExternalWallets.md) - Cast Wallet and Trezor integration
- [Detailed Example](./docs/DetailedExample.md) - 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](https://github.com/ethereum/solidity/issues/9573) for further information.
- This plugin does not function properly with native Ethers factory methods, such as `factory.attach()`. Instead, use `deployer.deployed()`.