{"id":25420207,"url":"https://github.com/dl-solarity/hardhat-migrate","last_synced_at":"2026-01-12T05:44:37.492Z","repository":{"id":63082689,"uuid":"561819074","full_name":"dl-solarity/hardhat-migrate","owner":"dl-solarity","description":"The simplest way to deploy smart contracts","archived":false,"fork":false,"pushed_at":"2025-11-15T07:12:39.000Z","size":2152,"stargazers_count":35,"open_issues_count":4,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-11-15T09:09:45.147Z","etag":null,"topics":["deploy","hardhat-plugin","smart-contracts","solarity","typechain","verify"],"latest_commit_sha":null,"homepage":"https://npmjs.com/package/@solarity/hardhat-migrate","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dl-solarity.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-11-04T15:03:25.000Z","updated_at":"2025-08-29T13:28:05.000Z","dependencies_parsed_at":"2023-10-17T05:29:38.364Z","dependency_job_id":"1fac7caf-011f-402c-9ec5-0a5d8e4fde4e","html_url":"https://github.com/dl-solarity/hardhat-migrate","commit_stats":{"total_commits":123,"total_committers":3,"mean_commits":41.0,"dds":"0.16260162601626016","last_synced_commit":"aa1fa88a5cf3ee36eec7b50189703ce0cd650191"},"previous_names":["dl-solarity/hardhat-migrate","dl-solidity-library/hardhat-migrate"],"tags_count":27,"template":false,"template_full_name":null,"purl":"pkg:github/dl-solarity/hardhat-migrate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dl-solarity%2Fhardhat-migrate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dl-solarity%2Fhardhat-migrate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dl-solarity%2Fhardhat-migrate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dl-solarity%2Fhardhat-migrate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dl-solarity","download_url":"https://codeload.github.com/dl-solarity/hardhat-migrate/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dl-solarity%2Fhardhat-migrate/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28335226,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T00:36:25.062Z","status":"online","status_checked_at":"2026-01-12T02:00:08.677Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["deploy","hardhat-plugin","smart-contracts","solarity","typechain","verify"],"created_at":"2025-02-16T19:36:26.296Z","updated_at":"2026-01-12T05:44:37.485Z","avatar_url":"https://github.com/dl-solarity.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![npm](https://img.shields.io/npm/v/@solarity/hardhat-migrate.svg)](https://www.npmjs.com/package/@solarity/hardhat-migrate) [![hardhat](https://hardhat.org/buidler-plugin-badge.svg?1)](https://hardhat.org)\n\n# Hardhat Migrate\n\nThe simplest way to deploy smart contracts.\n\n## What\n\nThis plugin helps you deploy and verify the source code for your Solidity contracts via migrations. \n\nWith sleek UX that doesn't require writing \"deployment wrappers\", users can:\n\n- Specify custom smart contract deployment rules and configuration via [@ethers](https://www.npmjs.com/package/ethers).\n- Verify smart contracts source code through seamless integration with [@nomicfoundation/hardhat-verify](https://www.npmjs.com/package/@nomicfoundation/hardhat-verify).\n- Leverage \"migration recovery mode\" that syncs up deployment from the last failed transaction.\n- Observe real-time status and logging of executing transactions.\n- Check out the generation of deployment reports in Markdown (.md) or JSON (.json) format.\n- Simplify Solidity `libraries` usage via auto-linking mechanics.\n- Support multiple wallet types, including [Cast Wallet](https://book.getfoundry.sh/cast/) and [Trezor](https://trezor.io/) hardware wallet.\n- And much more.\n\n## Installation\n\n### 1. Install the dependencies\n\n```bash\nnpm install --save-dev @solarity/hardhat-migrate @nomicfoundation/hardhat-ethers @nomicfoundation/hardhat-verify\n```\n\n### 2. Register the plugin in `hardhat.config.ts`\n\n```ts\nimport { HardhatUserConfig } from \"hardhat/config\";\nimport hardhatEthers from \"@nomicfoundation/hardhat-ethers\";\nimport hardhatVerify from \"@nomicfoundation/hardhat-verify\";\nimport hardhatMigrate from \"@solarity/hardhat-migrate\";\n\nconst config: HardhatUserConfig = {\n  plugins: [hardhatEthers, hardhatVerify, hardhatMigrate],\n  // networks, solidity, ...\n};\n\nexport default config;\n```\n\n\u003e [!NOTE]\n\u003e `@nomicfoundation/hardhat-ethers` must be available so the deployer can resolve the active signer.\n\n### Environment extensions\n\n## Tasks\n\n- `migrate` — compiles, runs numbered migration files, reports progress, and (optionally) verifies contracts.\n- `migrate:verify` — reuses `.migrate.storage` data to verify previously deployed contracts in batch mode.\n\nRun `npx hardhat help migrate` (or `migrate:verify`) to inspect every flag.\n\n## Configuration\n\nAdd a `migrate` section to `HardhatUserConfig`. The snippet below shows all defaults:\n\n```ts\nconst config: HardhatUserConfig = {\n  plugins: [hardhatEthers, hardhatVerify, hardhatMigrate],\n  migrate: {\n    filter: { from: -1, to: -1, only: -1, skip: -1 },\n    verification: { verify: false, verificationDelay: 5000, verifyParallel: 1, verifyAttempts: 3 },\n    paths: { pathToMigrations: \"./deploy\", namespace: \"\", reportPath: \"cache\", reportFormat: \"md\" },\n    execution: {\n      force: false,\n      continue: false,\n      wait: 1,\n      transactionStatusCheckInterval: 2000,\n      withoutCLIReporting: false,\n    },\n    castWallet: {\n      passwordFile: \"/path/to/password\",\n      keystore: \"/path/to/keystore\",\n      account: \"account-name\",\n    },\n    trezorWallet: {\n      enabled: false,\n      mnemonicIndex: 0,\n    },\n  },\n};\n```\n\n- **filter** — choose which migration numbers run (`only` overrides `from`/`to`; `skip` overrides `only`).\n- **verification** — toggle automatic verification and control retries, delays, and parallelism.\n- **paths** — point to the folder that stores migrations (`pathToMigrations` + optional `namespace`), and configure where/how reports are written (`cache`/`md` by default).\n- **execution** — manage compilation forcing, `--continue` mode, confirmation depth (`wait`), spinner refresh rate, and opt-out of CLI reporting.\n- **castWallet / trezorWallet** — opt into external signers via config or CLI flags (see [External Wallets](./docs/ExternalWallets.md)).\n\n\u003e [!NOTE]\n\u003e Cast-based signing is only enabled once you provide `account`, `keystore`, or the matching CLI flags/environment variables.\n\nEvery CLI flag maps 1:1 to these settings (kebab-cased). For example, `npx hardhat migrate --verify --verify-parallel 3 --namespace l2` \noverrides the corresponding config fields for that run.\n\n## Usage\n\nEach migration file must match `X_name.migration.ts` (where `X` is the execution order). Hardhat Migrate injects an instance \nof `Deployer` into the default-exported async function so you can focus on contract logic and recovery.\n\n```ts\n// ./deploy/1_token.migration.ts\nimport { ethers } from \"ethers\";\nimport type { Deployer } from \"@solarity/hardhat-migrate\";\nimport { Reporter } from \"@solarity/hardhat-migrate\";\n\nimport { ERC20Mock__factory } from \"../generated-types/ethers\";\n\nexport default async function (deployer: Deployer) {\n  const token = await deployer.deploy(ERC20Mock__factory, [\"Example Token\", \"ET\", 18]);\n\n  await (await token.mint(\"0x1E3953B6ee74461169A3E346060AE27bD0B5bF2B\", ethers.parseEther(\"1000\"), {\n    customData: { txName: \"Mint allocation\" },\n  })).wait();\n\n  await Reporter.reportContractsMD([\"Example Token\", await token.getAddress()]);\n}\n```\n\n`npx hardhat migrate --network sepolia` compiles contracts (forced when `execution.force` is true), runs each script in order, \nshows live transaction status, and produces Markdown/JSON reports under `cache/`.\n\n## Verification\n\nIf `migrate.verification.verify` is `true`, verification kicks in right after the last migration finishes. You can re-run verification later via `npx hardhat migrate:verify --input-file ./cache/.migrate.storage.json --parallel 4 --attempts 5`.\n\n## Migration naming \u0026 namespaces\n\nPlace migrations under `pathToMigrations` (default `./deploy`) and prefix them with an ordinal: `1_token.migration.ts`, `2_setup.migration.ts`, etc. To isolate environments, create subfolders and set `migrate.paths.namespace` or pass `--namespace \u003cfolder\u003e`:\n\n```\ndeploy\n├── l1\n│   ├── 1_core.migration.ts\n│   └── 2_setup.migration.ts\n└── l2-testnet\n    ├── 1_prepare.migration.ts\n    └── 2_bridge.migration.ts\n```\n\n`npx hardhat migrate --namespace l2-testnet` executes only the files inside that scope.\n\n## Recovery \u0026 transaction naming\n\nEnable `execution.continue` (or pass `--continue`) to resume from the first failed transaction. To avoid collisions when \nrerunning the same contract method, set `txName` via `overrides.customData`:\n\n```ts\nawait contract.someMethod(value, { customData: { txName: \"configure:v1\" } });\n```\n\nRecovered transactions/contracts are logged so you can confirm what was reused versus redeployed. \nIf collisions are detected, the CLI warns that recovery might be unreliable and suggests supplying explicit names.\n\n## External wallets\n\nHardhat Migrate can sign via Foundry Cast or Trezor Connect in addition to the default Hardhat signer.\n\n```ts\nconst config: HardhatUserConfig = {\n  // ...\n  migrate: {\n    castWallet: { account: \"test-0\", passwordFile: \"./passwords/.env\" },\n    trezorWallet: { enabled: false, mnemonicIndex: 0 },\n  },\n};\n```\n\nCLI overrides are available as `--account`, `--password-file`, `--keystore`, `--trezor-enabled`, and `--trezor-mnemonic-index`. \nSee [External Wallets](./docs/ExternalWallets.md) for best practices around secrets.\n\n## Example\n\nThe snippet below shows the structure of a simple migration alongside the corresponding CLI output and stored report.\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003cth\u003eMigration Script\u003c/th\u003e\n\u003cth\u003eDeployment Output\u003c/th\u003e\n\u003cth\u003eMigration Report\u003c/th\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\n\n```ts\n// file location: ./deploy/1_token.migration.ts\n\nimport { ethers } from \"ethers\";\nimport type { Deployer } from \"@solarity/hardhat-migrate\";\nimport { Reporter } from \"@solarity/hardhat-migrate\";\n\nimport { ERC20Mock__factory } from \"../generated-types/ethers\";\n\nexport default async (deployer: Deployer) =\u003e {\n  const token = await deployer.deploy(ERC20Mock__factory, [\"Example Token\", \"ET\", 18]);\n\n  const recipient = \"0x1E3953B6ee74461169A3E346060AE27bD0B5bF2B\";\n  const amount = ethers.parseEther(\"1000\");\n\n  await token.mint(recipient, amount, { customData: { txName: \"Airdrop\" } });\n\n  await Reporter.reportContractsMD([\"Example Token\", await token.getAddress()]);\n};\n```\n\u003c/td\u003e\n\u003ctd\u003e\n\n```\nMigration files:\n\u003e 1_token.migration.ts\n\n\u003e Network:             sepolia\n\u003e Network id:          11155111\n\nStarting migration...\n\nRunning 1_token.migration.ts...\n\nDeploying ERC20Mock\n\u003e explorer: 0xc35dd9e9600f102cf3b414f1341560870021b3824ace4bedbd59e2216bd89a49\n\u003e contractAddress: 0xc596A6e2f1558c7e030272d2A2E37E53050E2D63\n\u003e blockNumber: 7844739\n\u003e blockTimestamp: 1741263816\n\u003e account: 0xf41ceE234219D6cc3d90A6996dC3276aD378cfCF\n\u003e value: 0.0 ETH\n\u003e balance: 0.117945868841929599 ETH\n\u003e gasUsed: 571635\n\u003e gasPrice: 96.422889727 GWei\n\u003e fee: 0.055118698569093645 ETH\n\nTransaction: ERC20Mock.mint(address,uint256)(2 arguments)\n\u003e explorer: 0x508a289795cb8e3e1265dfd8f528efc206146a62deba4f9a80a2fa19d6a6ec8e\n\u003e blockNumber: 7844740\n\u003e blockTimestamp: 1741263828\n\u003e account: 0xf41ceE234219D6cc3d90A6996dC3276aD378cfCF\n\u003e value: 0.0 ETH\n\u003e balance: 0.111637670105208768 ETH\n\u003e gasUsed: 68433\n\u003e gasPrice: 92.180654607 GWei\n\u003e fee: 0.006308198736720831 ETH\n\n| Contract      | Address                                    |\n| ------------- | ------------------------------------------ |\n| Example Token | 0xc596A6e2f1558c7e030272d2A2E37E53050E2D63 |\n\n\u003e Total transactions:  2\n\u003e Final cost:          0.061426897305814476 ETH\n```\n\u003c/td\u003e\n\u003ctd\u003e\n\n# Migration Report 2025-03-14T16:01:26.567Z.md\n\n## General Information\n\n### Migration Files\n\n- 1_token.migration.ts\n\n### Networks\n\n- sepolia - Chain ID: 11155111. Explorer: https://sepolia.etherscan.io\n\n## Detailed Migration Files\n\n### 1_token.migration.ts\n\n- https://sepolia.etherscan.io/tx/0xc35dd9e9600f102cf3b414f1341560870021b3824ace4bedbd59e2216bd89a49\n- https://sepolia.etherscan.io/tx/0x508a289795cb8e3e1265dfd8f528efc206146a62deba4f9a80a2fa19d6a6ec8e\n\n## Stats\n\n| Total Contracts | Total Transactions | Gas Used | Average Gas Price | Fee Payed                | Native Currency Sent |\n| --------------- | ------------------ | -------- | ----------------- | ------------------------ | -------------------- |\n| 1               | 1                  | 640068   | 94.301772167 GWei | 0.061426897305814476 ETH | 0.0 ETH              |\n\nTotal Cost:\n\n0.061426897305814476 ETH\n\n## All Data\n\n| Name                                          | Address                                                            |\n| --------------------------------------------- | ------------------------------------------------------------------ |\n| contracts/mock/tokens/ERC20Mock.sol:ERC20Mock | 0xc596A6e2f1558c7e030272d2A2E37E53050E2D63                         |\n| ERC20Mock.mint(address,uint256)(2 arguments)  | 0x508a289795cb8e3e1265dfd8f528efc206146a62deba4f9a80a2fa19d6a6ec8e |\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\nReports are saved under `cache/` as `.md` or `.json` depending on `paths.reportFormat`.\n\n## Documentation\n\n- [Deployer API](./docs/Deployer.md) — deployment helpers, proxies, signer management.\n- [Reporter API](./docs/Reporter.md) — logging utilities used from migration scripts.\n- [Migration Process](./docs/MigrationProcess.md) — lifecycle, namespaces, recovery, verification.\n- [External Wallets](./docs/ExternalWallets.md) — Cast and Trezor configuration/CLI overrides.\n- [Detailed Example](./docs/DetailedExample.md) — end-to-end walkthrough.\n\n## Known limitations\n\n- Changing Solidity compiler inputs (file layout, artifacts, etc.) between runs can alter bytecode and break verification. \nSee [Solidity#9573](https://github.com/ethereum/solidity/issues/9573) for details.\n- `factory.attach()` and similar native Ethers helpers bypass the storage that recovery relies on. Always use `deployer.deployed()` \nor persist addresses manually via `deployer.save()`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdl-solarity%2Fhardhat-migrate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdl-solarity%2Fhardhat-migrate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdl-solarity%2Fhardhat-migrate/lists"}