A Hardhat Plugin For Replicable Deployments And Easy Testing

Note: This is the documentation for hardhat-deploy v2 that works with hardhat v3

Documentation for hardhat-deploy v1 can be found on the v1 branch

What it is

hardhat-deploy runs rocketh inside Hardhat 3. You write deploy scripts in your project's deploy folder, hardhat deploy --network <name> runs them and records what they deployed, and your tests run the same scripts as a fixture, so they test the contracts as deployed. Accounts are named (deployer, admin) per network instead of indexed, proxies and diamonds are declared and upgraded by re-running the script, and a proxy owned by a Safe is upgraded through the Safe, rehearsed on a fork first.

Getting started

pnpm dlx hardhat-deploy init --install my-project
cd my-project
pnpm hardhat compile
pnpm hardhat deploy

or add it to a Hardhat 3 project: Get started with hardhat-deploy. For a complete project (a monorepo with watchers, verification, export and a slot for a frontend), start from template-ethereum-contracts.

A deploy script

// deploy/001_deploy_greetings_registry.ts
import {deployScript, artifacts} from '../rocketh/deploy.js';

export default deployScript(
	async ({deployViaProxy, namedAccounts}) => {
		const {deployer, admin} = namedAccounts;

		await deployViaProxy(
			'GreetingsRegistry',
			{account: deployer, artifact: artifacts.GreetingsRegistry, args: ['hello: ']},
			{owner: admin, execute: {init: {methodName: 'init', args: ['hello: ']}}},
		);
	},
	{tags: ['GreetingsRegistry']},
);

Run it again after changing GreetingsRegistry and the proxy is upgraded in place; run it unchanged and nothing is sent.

What it gives you

• Deploy scripts with tags and dependencies, re-runnable by design (Deploy scripts)
• Named accounts per network, and signers from the environment (Named accounts)
• Proxies, diamonds, routers and deterministic addresses, declared (Proxies)
• Your deploy scripts as test fixtures (Tests)
• Fork rehearsals with HARDHAT_FORK, and Safe-owned upgrades end to end (A Safe-owned project)
• Typed artifacts from every compilation, and networks from environment variables (Typed artifacts, Networks)
• Export for a frontend, verification, documentation (Export, verify and document)
• Hot Contract Replacement while you develop (Development workflow)

Documentation

The documentation is at rocketh.dev/hardhat-deploy, with a numbered path from setup to production.

Coming from v1? What changed says what v2 does differently or does not do, and the step-by-step migration walks a project through the port. To have an AI assistant do the port, give it the migration skill.

License

MIT

Sponsor

If you find this project useful, please consider sponsoring it! Your support helps me continue developing and maintaining this tool.