Hardhat Deploy

https://github.com/wighawag/hardhat-deploy
Admin
A Hardhat plugin for replicable deployments and easy testing, enabling named accounts,...
Tokens:51,114
Snippets:542
Trust Score:10
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
### Multi-Environment Setup Example

Source: https://github.com/wighawag/hardhat-deploy/blob/main/documentation/how-to/configure-network-helpers.md

Illustrates setting up environment variables for development, staging, and production environments, showing different configurations for the same network.

```bash
# Development
ETH_NODE_URI_sepolia=https://sepolia.infura.io/v3/DEV-PROJECT-ID
MNEMONIC_sepolia=test test test test test test test test test test test junk

# Staging
ETH_NODE_URI_sepolia=https://sepolia.infura.io/v3/STAGING-PROJECT-ID
MNEMONIC_sepolia=your staging mnemonic

# Production
ETH_NODE_URI_ethereum=SECRET
MNEMONIC_ethereum=SECRET
```

--------------------------------

### Start Development Environment with Zellij

Source: https://github.com/wighawag/hardhat-deploy/blob/main/demoes/proxies/README.md

Launch an in-memory Ethereum node and tests using Zellij. Assumes Zellij is installed.

```bash
pnpm start
```

--------------------------------

### Manual Setup for hardhat-deploy

Source: https://context7.com/wighawag/hardhat-deploy/llms.txt

Install the required packages for manual setup of hardhat-deploy and its core dependencies.

```bash
pnpm add -D hardhat-deploy rocketh @rocketh/node @rocketh/deploy @rocketh/read-execute
# optional but recommended
pnpm add -D @rocketh/proxy @rocketh/export @rocketh/verifier @rocketh/viem
```

--------------------------------

### Install Proxy Extension

Source: https://github.com/wighawag/hardhat-deploy/blob/main/documentation/how-to/deploy-with-proxies.md

Install the proxy extension using npm or pnpm.

```bash
npm install -D @rocketh/proxy
```

```bash
pnpm add -D @rocketh/proxy
```

--------------------------------

### Install Local Dependencies

Source: https://github.com/wighawag/hardhat-deploy/blob/main/demoes/proxies/README.md

Install all project dependencies using PNPM.

```bash
pnpm i
```

--------------------------------

### Rocketh Deploy Script Setup

Source: https://github.com/wighawag/hardhat-deploy/blob/main/AGENTS.md

Sets up the deploy script by importing necessary types, artifacts, and the setup function from Rocketh.

```typescript
import {type Extensions, type Accounts, type Data, extensions} from './config.js';
import * as artifacts from '../generated/artifacts/index.js';
import {setupDeployScripts} from 'rocketh';

const {deployScript} = setupDeployScripts<Extensions, Accounts, Data>(extensions);
export {deployScript, artifacts};

```

--------------------------------

### GitHub Actions for Deployment

Source: https://github.com/wighawag/hardhat-deploy/blob/main/skills/hardhat-deploy-migration/SKILL.md

Example GitHub Actions workflow for deploying contracts. It checks out code, sets up Node.js and pnpm, installs dependencies, compiles contracts, and deploys/verifies on Sepolia network using environment secrets.

```yaml
name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: pnpm/action-setup@v2
      - uses: actions/setup-node@v3
        with:
          node-version: "22"
          cache: "pnpm"

      - run: pnpm install
      - run: pnpm compile --build-profile production

      - name: Deploy to Sepolia
        env:
          ETH_NODE_URI_SEPOLIA: ${{ secrets.SEPOLIA_RPC_URL }}
          MNEMONIC_SEPOLIA: ${{ secrets.SEPOLIA_MNEMONIC }}
        run: pnpm deploy sepolia

      - name: Verify Contracts
        env:
          ETH_NODE_URI_SEPOLIA: ${{ secrets.SEPOLIA_RPC_URL }}
          MNEMONIC_SEPOLIA: ${{ secrets.SEPOLIA_MNEMONIC }}
          ETHERSCAN_API_KEY: ${{ secrets.ETHERSCAN_API_KEY }}
        run: pnpm verify sepolia
```

--------------------------------

### v2 package.json Example

Source: https://github.com/wighawag/hardhat-deploy/blob/main/skills/hardhat-deploy-migration/SKILL.md

Example of dependencies in a project using hardhat-deploy v2 and Rocketh.

```json
{
  "type": "module",
  "devDependencies": {
    "hardhat": "^3.1.4",
    "hardhat-deploy": "^2.0.0",
    "rocketh": "^0.17.15",
    "@rocketh/deploy": "^0.17.9",
    "@rocketh/read-execute": "^0.17.9",
    "@rocketh/node": "^0.17.18",
    "@rocketh/proxy": "^0.17.13",
    "@rocketh/signer": "^0.17.9",
    "viem": "^2.45.0",
    "earl": "^2.0.0",
    "@nomicfoundation/hardhat-viem": "^3.0.1",
    "@nomicfoundation/hardhat-node-test-runner": "^3.0.8",
    "@nomicfoundation/hardhat-network-helpers": "^3.0.3",
    "@nomicfoundation/hardhat-keystore": "^3.0.3"
  }
}
```

--------------------------------

### Launch Zellij Without Installation

Source: https://github.com/wighawag/hardhat-deploy/blob/main/demoes/proxies/README.md

Try Zellij without installing it by downloading and running the launch script.

```bash
bash <(curl -L zellij.dev/launch) --layout zellij.kdl
```

--------------------------------

### Install Viem Extension

Source: https://github.com/wighawag/hardhat-deploy/blob/main/documentation/how-to/use-viem-integration.md

Install the `@rocketh/viem` package as a development dependency using npm or pnpm.

```bash
npm install -D @rocketh/viem
```

```bash
pnpm add -D @rocketh/viem
```

--------------------------------

### Install Dependencies with pnpm

Source: https://github.com/wighawag/hardhat-deploy/blob/main/AGENTS.md

Use this command to install all project dependencies. Ensure pnpm is installed globally.

```bash
pnpm install
```

--------------------------------

### Start Documentation Dev Server with pnpm

Source: https://github.com/wighawag/hardhat-deploy/blob/main/AGENTS.md

Launches a local development server for the project's documentation. This allows for live previewing of documentation changes.

```bash
pnpm docs:dev
```

--------------------------------

### Install and Scaffold Project with hardhat-deploy

Source: https://context7.com/wighawag/hardhat-deploy/llms.txt

Use the CLI scaffolding tool to initialize a new project, compile contracts, and deploy to the in-memory node.

```bash
pnpm dlx hardhat-deploy init --install my-project
cd my-project

pnpm hardhat compile

pnpm hardhat deploy
```

--------------------------------

### Complete Hardhat Configuration Example

Source: https://github.com/wighawag/hardhat-deploy/blob/main/documentation/how-to/configure-network-helpers.md

Demonstrates how to use all three network helpers (addNetworksFromEnv, addNetworksFromKnownList, addForkConfiguration) together in a Hardhat configuration file.

```typescript
import {
  HardhatUserConfig
} from 'hardhat/config';
import HardhatDeploy from 'hardhat-deploy';
import {
  addForkConfiguration,
  addNetworksFromEnv,
  addNetworksFromKnownList,
} from 'hardhat-deploy/helpers';

const config: HardhatUserConfig = {
  plugins: [HardhatDeploy],
  solidity: {
    version: '0.8.28',
    settings: {
      optimizer: {
        enabled: true,
        runs: 999999,
      },
    },
  },
  networks:
    // Step 3: Add fork configuration for chosen network
    addForkConfiguration(
      // Step 2: Add network config for all known chains using kebab-case names
      // Uses MNEMONIC_<network> (or MNEMONIC if not set) for accounts
      // Uses ETH_NODE_URI_<network> for RPC URLs
      addNetworksFromKnownList(
        // Step 1: Add networks for each ETH_NODE_URI_<network> env var found
        // Also reads MNEMONIC_<network> to populate accounts
        addNetworksFromEnv(
          // Base configuration - your custom networks
          {
            default: {
              type: 'edr-simulated',
              chainType: 'l1',
            },
          }
        )
      )
    ),
  paths: {
    sources: ['src'],
  },
};

export default config;
```

--------------------------------

### Install Verification Extension (npm)

Source: https://github.com/wighawag/hardhat-deploy/blob/main/documentation/how-to/verify-contracts.md

Install the verification extension using npm. This is a prerequisite for contract verification.

```bash
npm install -D @rocketh/verifier
```

--------------------------------

### Install Export Extension

Source: https://github.com/wighawag/hardhat-deploy/blob/main/documentation/how-to/export-deployments.md

Install the export extension using npm or pnpm. This is a prerequisite for exporting deployment data.

```bash
npm install -D @rocketh/export
```

```bash
pnpm add -D @rocketh/export
```

--------------------------------

### Install Diamond Extension

Source: https://github.com/wighawag/hardhat-deploy/blob/main/documentation/how-to/deploy-diamond-contracts.md

Install the diamond extension for hardhat-deploy using npm or pnpm.

```bash
npm install -D @rocketh/diamond
```

```bash
pnpm add -D @rocketh/diamond
```

--------------------------------

### Rocketh Deploy Script Example

Source: https://github.com/wighawag/hardhat-deploy/blob/main/AGENTS.md

Demonstrates how to use the `deployScript` wrapper to define a contract deployment with account, artifact, and arguments.

```typescript
import {deployScript, artifacts} from '../rocketh/deploy.js';

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

    await deploy('MyContract', {
      account: deployer,           // Who deploys (was 'from:' in v1)
      artifact: artifacts.MyContract,  // Contract artifact
      args: ['arg1', 'arg2'],
    });
  },
  {tags: ['MyContract'], id: 'deploy_my_contract'},
);

```

--------------------------------

### v1 Test Fixture and Example

Source: https://github.com/wighawag/hardhat-deploy/blob/main/documentation/how-to/migration-from-v1.md

Illustrates the v1 pattern for setting up test fixtures using `deployments.createFixture` and interacting with contracts.

```typescript
import {
  expect
} from "chai";
import {
  ethers,
  deployments,
  getUnnamedAccounts,
  getNamedAccounts,
} from "hardhat";
import { IERC20 } from "../typechain-types";
import { setupUser, setupUsers } from "./utils";

const setup = deployments.createFixture(async () => {
  await deployments.fixture("SimpleERC20");
  const { simpleERC20Beneficiary } = await getNamedAccounts();
  const contracts = {
    SimpleERC20: await ethers.getContract<IERC20>("SimpleERC20"),
  };
  const users = await setupUsers(await getUnnamedAccounts(), contracts);
  return {
    ...contracts,
    users,
    simpleERC20Beneficiary: await setupUser(simpleERC20Beneficiary, contracts),
  };
});

describe("SimpleERC20", function () {
  it("transfer fails", async function () {
    const { users } = await setup();
    await expect(
      users[0].SimpleERC20.transfer(users[1].address, 1),
    ).to.be.revertedWith("NOT_ENOUGH_TOKENS");
  });

  it("transfer succeed", async function () {
    const { users, simpleERC20Beneficiary, SimpleERC20 } = await setup();
    await simpleERC20Beneficiary.SimpleERC20.transfer(users[1].address, 1);

    await expect(
      simpleERC20Beneficiary.SimpleERC20.transfer(users[1].address, 1),
    )
      .to.emit(SimpleERC20, "Transfer")
      .withArgs(simpleERC20Beneficiary.address, users[1].address, 1);
  });
});
```

--------------------------------

### Install Verification Extension (pnpm)

Source: https://github.com/wighawag/hardhat-deploy/blob/main/documentation/how-to/verify-contracts.md

Install the verification extension using pnpm. This is a prerequisite for contract verification.

```bash
pnpm add -D @rocketh/verifier
```

--------------------------------

### Install PNPM Globally

Source: https://github.com/wighawag/hardhat-deploy/blob/main/demoes/proxies/README.md

Install the PNPM package manager globally using npm.

```bash
npm i -g pnpm
```

--------------------------------

### Deployment Commands for DeFi Protocol

Source: https://github.com/wighawag/hardhat-deploy/blob/main/documentation/how-to/use-tags-and-dependencies.md

Command-line examples for deploying specific parts of the DeFi protocol using tags. This allows for phased deployments and managing dependencies.

```bash
# Deploy core infrastructure only
npx hardhat deploy --tags core

# Deploy DeFi components (requires core)
npx hardhat deploy --tags defi

# Deploy governance (requires tokens)
npx hardhat deploy --tags dao

# Deploy everything
npx hardhat deploy
```

--------------------------------

### Fork Testing Workflow Examples

Source: https://github.com/wighawag/hardhat-deploy/blob/main/documentation/how-to/configure-network-helpers.md

Provides examples of how to use the HARDHAT_FORK environment variable to test against different network forks, including specifying a block number.

```bash
# Test against mainnet fork
HARDHAT_FORK=ethereum npm run test

# Test against polygon fork at specific block
HARDHAT_FORK=polygon HARDHAT_FORK_NUMBER=50000000 npm run test

# Deploy to fork for testing
HARDHAT_FORK=ethereum npm run deploy
```

--------------------------------

### v1 Proxy Deploy Script Example

Source: https://github.com/wighawag/hardhat-deploy/blob/main/skills/hardhat-deploy-migration/SKILL.md

Example of a v1 proxy deployment script using Hardhat Runtime Environment. It configures proxy usage based on network type and logs deployment details.

```typescript
import { HardhatRuntimeEnvironment } from "hardhat/types";
import { DeployFunction } from "hardhat-deploy/types";

const func: DeployFunction = async function (hre: HardhatRuntimeEnvironment) {
  const { deployer } = await hre.getNamedAccounts();
  const { deploy } = hre.deployments;
  const useProxy = !hre.network.live;

  // proxy only in non-live network (localhost and hardhat network) enabling HCR (Hot Contract Replacement)
  // in live network, proxy is disabled and constructor is invoked
  await deploy("GreetingsRegistry", {
    from: deployer,
    proxy: useProxy && "postUpgrade",
    args: [2],
    log: true,
    autoMine: true, // speed up deployment on local network (ganache, hardhat), no effect on live networks
  });

  return !useProxy; // when live network, record the script as executed to prevent rexecution
};
export default func;
func.id = "deploy_greetings_registry"; // id required to prevent reexecution
func.tags = ["GreetingsRegistry"];

```

--------------------------------

### v2 Deployment Script Example

Source: https://github.com/wighawag/hardhat-deploy/blob/main/documentation/installation.md

This is an example of a deployment script for v2 of hardhat-deploy, utilizing the `deployScript` function from `rocketh/deploy.js`.

```typescript
import { deployScript, artifacts } from "../rocketh/deploy.js";

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

    await deploy("MyContract", {
      account: deployer,
      artifact: artifacts.MyContract,
      args: ["Hello"],
    });
  },
  // finally you can pass tags and dependencies
  { tags: ["MyContract"] },
);

```

--------------------------------

### v1 Deployment Script Example

Source: https://github.com/wighawag/hardhat-deploy/blob/main/documentation/installation.md

This is an example of a deployment script from v1 of hardhat-deploy. It exports a function that receives the Hardhat runtime environment.

```typescript
// deploy/00_deploy_my_contract.js
// export a function that get passed the Hardhat runtime environment
module.exports = async ({ getNamedAccounts, deployments }) => {
  const { deploy } = deployments;
  const { deployer } = await getNamedAccounts();
  await deploy("MyContract", {
    from: deployer,
    args: ["Hello"],
    log: true,
  });
};
// add tags and dependencies
module.exports.tags = ["MyContract"];
```

--------------------------------

### v2 Test Example with Hardhat Deploy Migration

Source: https://github.com/wighawag/hardhat-deploy/blob/main/skills/hardhat-deploy-migration/SKILL.md

This example shows how to migrate tests to the newer version of hardhat-deploy, utilizing node:test, earl, and custom fixtures with `loadAndExecuteDeploymentsFromFiles`.

```typescript
import { expect } from "earl";
import { describe, it } from "node:test";
import { network } from "hardhat";
import { EthereumProvider } from "hardhat/types/providers";
import { loadAndExecuteDeploymentsFromFiles } from "../rocketh/environment.js";
import { Abi_SimpleERC20 } from "../generated/abis/SimpleERC20.js";

function setupFixtures(provider: EthereumProvider) {
  return {
    async deployAll() {
      const env = await loadAndExecuteDeploymentsFromFiles({
        provider: provider,
      });

      // Deployment are inherently untyped since they can vary from
      //  network or even be different from current artifacts so here
      //  we type them manually assuming the artifact is still matching
      const SimpleERC20 = env.get<Abi_SimpleERC20>("SimpleERC20");

      return {
        env,
        SimpleERC20,
        namedAccounts: env.namedAccounts,
        unnamedAccounts: env.unnamedAccounts,
      };
    },
  };
}

const { provider, networkHelpers } = await network.connect();
const { deployAll } = setupFixtures(provider);

describe("SimpleERC20", function () {
  it("transfer fails", async function () {
    const { env, SimpleERC20, unnamedAccounts } =
      await networkHelpers.loadFixture(deployAll);

    await expect(
      env.execute(SimpleERC20, {
        account: unnamedAccounts[0],
        functionName: "transfer",
        args: [unnamedAccounts[1], 1n],
      }),
    ).toBeRejectedWith("NOT_ENOUGH_TOKENS");
  });

  it("transfer succeed", async function () {
    const { env, SimpleERC20, unnamedAccounts, namedAccounts } =
      await networkHelpers.loadFixture(deployAll);

    await env.execute(SimpleERC20, {
      account: namedAccounts.simpleERC20Beneficiary,
      functionName: "transfer",
      args: [unnamedAccounts[1], 1n],
    });

    env.execute(SimpleERC20, {
      account: namedAccounts.simpleERC20Beneficiary,
      functionName: "transfer",
      args: [unnamedAccounts[1], 1n],
    });
    // TODO
    // expect(...).toEmit(SimpleERC20, 'Transfer')
    // .withArgs(simpleERC20Beneficiary.address, users[1].address, 1));
  });
});
```

--------------------------------

### v2 Proxy Deploy Script Example

Source: https://github.com/wighawag/hardhat-deploy/blob/main/skills/hardhat-deploy-migration/SKILL.md

Example of a v2 proxy deployment script using the new deployScript function. It utilizes env.deployViaProxy for more structured proxy configuration.

```typescript
import { deployScript, artifacts } from "../rocketh/deploy.js";
import { parseEther } from "viem";

export default deployScript(
  async (env) => {
    const { deployer } = env.namedAccounts;
    const useProxy = !env.tags.live;

    // proxy only in non-live network (localhost and hardhat network) enabling HCR (Hot Contract Replacement)
    // in live network, proxy is disabled and constructor is invoked
    await env.deployViaProxy(
      "GreetingsRegistry",
      {
        account: deployer,
        artifact: artifacts.GreetingsRegistry,
        args: ["2"],
      },
      {
        proxyDisabled: !useProxy,
        execute: "postUpgrade",
      },
    );

    return !useProxy; // when live network, record the script as executed to prevent rexecution
  },
  {
    tags: ["GreetingsRegistry"],
    id: "deploy_greetings_registry", // id required to prevent reexecution
  },
);

```

--------------------------------

### v1 Hardhat Config Example

Source: https://github.com/wighawag/hardhat-deploy/blob/main/documentation/installation.md

Example of named accounts configuration in hardhat.config.ts for v1 of hardhat-deploy.

```typescript
 namedAccounts: {
    deployer: 0,
    ...
  },
```

--------------------------------

### Setup Test Utilities for Fixtures

Source: https://github.com/wighawag/hardhat-deploy/blob/main/documentation/how-to/deployment-fixtures-in-tests.md

Create a test utilities file to set up fixtures by loading and executing deployment scripts. This function returns an object with deployment-related utilities.

```typescript
// test/utils/index.ts
import { EthereumProvider } from "hardhat/types/providers";
import { loadAndExecuteDeploymentsFromFiles } from "../../rocketh/environment.js";
import * as artifacts from "../../generated/artifacts/index.js";

export function setupFixtures(provider: EthereumProvider) {
  return {
    async deployAll() {
      const env = await loadAndExecuteDeploymentsFromFiles({
        provider: provider,
      });

      // Type the deployments for better IDE support
      const Greeter = env.get<typeof artifacts.Greeter.abi>("Greeter");

      return {
        env,
        Greeter,
        namedAccounts: env.namedAccounts,
        unnamedAccounts: env.unnamedAccounts,
      };
    },
  };
}
```

--------------------------------

### v2 hardhat.config.ts Example

Source: https://github.com/wighawag/hardhat-deploy/blob/main/documentation/how-to/migration-from-v1.md

This is an example of a hardhat.config.ts file using ESM syntax and v2 of hardhat-deploy. It demonstrates the updated structure for plugins, network configuration, and Solidity profiles.

```typescript
import type { HardhatUserConfig } from "hardhat/config";

import HardhatNodeTestRunner from "@nomicfoundation/hardhat-node-test-runner";
import HardhatViem from "@nomicfoundation/hardhat-viem";
import HardhatNetworkHelpers from "@nomicfoundation/hardhat-network-helpers";
import HardhatKeystore from "@nomicfoundation/hardhat-keystore";

import HardhatDeploy from "hardhat-deploy";
import {
  addForkConfiguration,
  addNetworksFromEnv,
  addNetworksFromKnownList,
} from "hardhat-deploy/helpers";

const config: HardhatUserConfig = {
  plugins: [
    HardhatNodeTestRunner,
    HardhatViem,
    HardhatNetworkHelpers,
    HardhatKeystore,
    HardhatDeploy,
  ],
  solidity: {
    profiles: {
      default: {
        version: "0.8.17",
      },
      production: {
        version: "0.8.17",
        settings: {
          optimizer: {
            enabled: true,
            runs: 999999,
          },
        },
      },
    },
  },
  networks: addForkConfiguration(
    addNetworksFromKnownList(
      addNetworksFromEnv({
        default: {
          type: "edr-simulated",
          chainType: "l1",
          accounts: {
            mnemonic: process.env.MNEMONIC || undefined,
          },
        },
      }),
    ),
  ),
  paths: {
    sources: ["src"],
  },
  generateTypedArtifacts: {
    destinations: [
      {
        folder: "./generated",
        mode: "typescript",
      },
    ],
  },
};

export default config;
```

--------------------------------

### v1 hardhat.config.ts Example

Source: https://github.com/wighawag/hardhat-deploy/blob/main/documentation/how-to/migration-from-v1.md

This is an example of a hardhat.config.ts file using CommonJS syntax and v1 of hardhat-deploy. It includes standard configurations for Solidity, networks, and paths.

```typescript
import "dotenv/config";
import { HardhatUserConfig } from "hardhat/types";

import "@nomicfoundation/hardhat-chai-matchers";
import "@nomicfoundation/hardhat-ethers";
import "@typechain/hardhat";

import "hardhat-deploy";
import "hardhat-deploy-ethers";
import "hardhat-deploy-tenderly";

import { node_url, accounts, addForkConfiguration } from "./utils/network";

const config: HardhatUserConfig = {
  solidity: {
    compilers: [
      {
        version: "0.8.17",
        settings: {
          optimizer: {
            enabled: true,
            runs: 2000,
          },
        },
      },
    ],
  },
  namedAccounts: {
    deployer: 0,
    simpleERC20Beneficiary: 1,
  },
  networks: addForkConfiguration({
    hardhat: {
      initialBaseFeePerGas: 0,
    },
    localhost: {
      url: node_url("localhost"),
      accounts: accounts(),
    },
    mainnet: {
      url: node_url("mainnet"),
      accounts: accounts("mainnet"),
    },
    sepolia: {
      url: node_url("sepolia"),
      accounts: accounts("sepolia"),
    },
  }),
  paths: {
    sources: "src",
  },
  mocha: {
    timeout: 0,
  },
  external: process.env.HARDHAT_FORK
    ? {
        deployments: {
          hardhat: ["deployments/" + process.env.HARDHAT_FORK],
          localhost: ["deployments/" + process.env.HARDHAT_FORK],
        },
      }
    : undefined,
};

export default config;
```

--------------------------------

### Install hardhat-deploy and Rocketh Packages

Source: https://github.com/wighawag/hardhat-deploy/blob/main/documentation/how-to/setup-first-project.md

Install the core hardhat-deploy package and essential Rocketh packages for contract deployment and node interaction.

```bash
pnpm add -D hardhat-deploy rocketh @rocketh/node @rocketh/deploy @rocketh/read-execute
```

--------------------------------

### v1 Test Example with Hardhat Deploy

Source: https://github.com/wighawag/hardhat-deploy/blob/main/skills/hardhat-deploy-migration/SKILL.md

This example demonstrates testing smart contract interactions using the older version of hardhat-deploy, including setting up fixtures and using chai assertions.

```typescript
import { expect } from "chai";
import {
  ethers,
  deployments,
  getUnnamedAccounts,
  getNamedAccounts,
} from "hardhat";
import { IERC20 } from "../typechain-types";
import { setupUser, setupUsers } from "./utils";

const setup = deployments.createFixture(async () => {
  await deployments.fixture("SimpleERC20");
  const { simpleERC20Beneficiary } = await getNamedAccounts();
  const contracts = {
    SimpleERC20: await ethers.getContract<IERC20>("SimpleERC20"),
  };
  const users = await setupUsers(await getUnnamedAccounts(), contracts);
  return {
    ...contracts,
    users,
    simpleERC20Beneficiary: await setupUser(simpleERC20Beneficiary, contracts),
  };
});

describe("SimpleERC20", function () {
  it("transfer fails", async function () {
    const { users } = await setup();
    await expect(
      users[0].SimpleERC20.transfer(users[1].address, 1),
    ).to.be.revertedWith("NOT_ENOUGH_TOKENS");
  });

  it("transfer succeed", async function () {
    const { users, simpleERC20Beneficiary, SimpleERC20 } = await setup();
    await simpleERC20Beneficiary.SimpleERC20.transfer(users[1].address, 1);

    await expect(
      simpleERC20Beneficiary.SimpleERC20.transfer(users[1].address, 1),
    )
      .to.emit(SimpleERC20, "Transfer")
      .withArgs(simpleERC20Beneficiary.address, users[1].address, 1);
  });
});
```

--------------------------------

### v2 Test Utilities Setup Fixtures

Source: https://github.com/wighawag/hardhat-deploy/blob/main/skills/hardhat-deploy-migration/SKILL.md

Introduced in v2, this function sets up deployment fixtures, utilizing `loadAndExecuteDeploymentsFromFiles` for deployment and returning typed contract instances.

```typescript
import { Abi_GreetingsRegistry } from "../../generated/abis/GreetingsRegistry.js";
import { loadAndExecuteDeploymentsFromFiles } from "../../rocketh/environment.js";
import { EthereumProvider } from "hardhat/types/providers";

export function setupFixtures(provider: EthereumProvider) {
  return {
    async deployAll() {
      const env = await loadAndExecuteDeploymentsFromFiles({
        provider: provider,
      });

      // Deployment are inherently untyped since they can vary from
      //  network or even be different from current artifacts so here
      //  we type them manually assuming the artifact is still matching
      const GreetingsRegistry = env.get<Abi_GreetingsRegistry>("GreetingsRegistry");

      return {
        env,
        GreetingsRegistry,
        namedAccounts: env.namedAccounts,
        unnamedAccounts: env.unnamedAccounts,
      };
    },
  };
}
```

--------------------------------

### v1 Test Utilities Setup Functions

Source: https://github.com/wighawag/hardhat-deploy/blob/main/skills/hardhat-deploy-migration/SKILL.md

These functions were used in v1 for setting up users with contract instances connected to specific signers. They are not needed in v2.

```typescript
import { BaseContract } from "ethers";
import hre from "hardhat";

const { ethers } = hre;

export async function setupUsers<T extends { [contractName: string]: BaseContract }>(addresses: string[], contracts: T): Promise<({ address: string } & T)[]> {
  const users: ({ address: string } & T)[] = [];
  for (const address of addresses) {
    users.push(await setupUser(address, contracts));
  }
  return users;
}

export async function setupUser<T extends { [contractName: string]: BaseContract }>(address: string, contracts: T): Promise<{ address: string } & T> {
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  const user: any = { address };
  for (const key of Object.keys(contracts)) {
    user[key] = contracts[key].connect(await ethers.getSigner(address));
  }
  return user as { address: string } & T;
}
```

--------------------------------

### v1 package.json Scripts

Source: https://github.com/wighawag/hardhat-deploy/blob/main/documentation/how-to/migration-from-v1.md

Example of package.json scripts used in v1 of hardhat-deploy.

```json
{
  "scripts": {
    "prepare": "hardhat typechain",
    "compile": "hardhat compile",
    "void:deploy": "hardhat deploy --report-gas",
    "test": "cross-env HARDHAT_DEPLOY_FIXTURE=true HARDHAT_COMPILE=true mocha --bail --recursive test",
    "gas": "cross-env REPORT_GAS=true hardhat test",
    "coverage": "cross-env HARDHAT_DEPLOY_FIXTURE=true hardhat coverage",
    "dev:node": "cross-env MINING_INTERVAL=\"3000,5000\" hardhat node --hostname 0.0.0.0",
    "dev": "cross-env MINING_INTERVAL=\"3000,5000\" hardhat node --hostname 0.0.0.0 --watch",
    "local:dev": "hardhat --network localhost deploy --watch",
    "execute": "node ./_scripts.js run",
    "deploy": "node ./_scripts.js deploy",
    "verify": "node ./_scripts.js verify",
    "export": "node ./_scripts.js export"
  }
}
```

--------------------------------

### Setup Deployment Fixtures for Tests

Source: https://context7.com/wighawag/hardhat-deploy/llms.txt

Use `loadAndExecuteDeploymentsFromFiles` to run deploy scripts and `networkHelpers.loadFixture` to reset state before each test. This ensures isolated test environments.

```typescript
// test/utils/index.ts
import { EthereumProvider } from "hardhat/types/providers";
import { artifacts, loadAndExecuteDeploymentsFromFiles } from "../../rocketh/environment.js";

export function setupFixtures(provider: EthereumProvider) {
  return {
    async deployAll() {
      const env = await loadAndExecuteDeploymentsFromFiles({ provider });
      const GreetingsRegistry = 
        env.get<typeof artifacts.GreetingsRegistry.abi>("GreetingsRegistry");
      return { env, GreetingsRegistry, namedAccounts: env.namedAccounts, unnamedAccounts: env.unnamedAccounts };
    },
  };
}

// test/GreetingsRegistry.test.ts
import { expect }      from "earl";
import { describe, it } from "node:test";
import { network }      from "hardhat";
import { setupFixtures } from "./utils/index.js";

const { provider, networkHelpers } = await network.connect();
const { deployAll } = setupFixtures(provider);

describe("GreetingsRegistry", function () {
  it("stores a message", async function () {
    const { env, GreetingsRegistry, unnamedAccounts } =
      await networkHelpers.loadFixture(deployAll);

    const greeter = unnamedAccounts[0];

    await expect(
      await env.read(GreetingsRegistry, { functionName: "messages", args: [greeter] }),
    ).toEqual("");

    await env.execute(GreetingsRegistry, {
      functionName: "setMessage",
      args:         ["hello world"],
      account:      greeter,
    });

    await expect(
      await env.read(GreetingsRegistry, { functionName: "messages", args: [greeter] }),
    ).toEqual("hello world");
  });
});
```

--------------------------------

### Network-Specific Configuration Example

Source: https://github.com/wighawag/hardhat-deploy/blob/main/documentation/how-to/configure-network-helpers.md

Shows how network helpers automatically manage network-specific settings like RPC URLs and chain IDs based on environment variables.

```typescript
// The helpers automatically handle network-specific settings
// Based on environment variables:

// ETH_NODE_URI_arbitrum=https://arb1.arbitrum.io/rpc
// MNEMONIC_arbitrum=your arbitrum mnemonic

// Results in:
// networks: {
//   arbitrum: {
//     type: 'http',
//     url: 'https://arb1.arbitrum.io/rpc',
//     accounts: { mnemonic: 'your arbitrum mnemonic' },
//     chainId: 42161,
//     chainType: 'op', // Automatically detected for OP-stack chains
//   }
// }
```

--------------------------------

### v1 package.json Dependencies

Source: https://github.com/wighawag/hardhat-deploy/blob/main/documentation/how-to/migration-from-v1.md

Example of dependencies in package.json for hardhat-deploy v1.

```json
{
  "devDependencies": {
    "hardhat": "^2.22.18",
    "hardhat-deploy": "^0.14.0",
    "hardhat-deploy-ethers": "^0.4.2",
    "hardhat-deploy-tenderly": "^1.0.0",
    "ethers": "^6.13.5"
  }
}
```

--------------------------------

### v1 Proxy Deployment Script for GreetingsRegistry

Source: https://github.com/wighawag/hardhat-deploy/blob/main/documentation/how-to/migration-from-v1.md

Example of a v1 deploy script for GreetingsRegistry using proxy deployment. It includes logic to determine proxy usage based on network live status.

```typescript
const func: DeployFunction = async function (hre: HardhatRuntimeEnvironment) {
  const { deployer } = await hre.getNamedAccounts();
  const { deploy } = hre.deployments;
  const useProxy = !hre.network.live;

  await deploy("GreetingsRegistry", {
    from: deployer,
    proxy: useProxy && "postUpgrade",
    args: [2],
    log: true,
    autoMine: true,
  });

  return !useProxy;
};
export default func;
func.id = "deploy_greetings_registry";
func.tags = ["GreetingsRegistry"];
```

--------------------------------

### v2 package.json Scripts

Source: https://github.com/wighawag/hardhat-deploy/blob/main/documentation/how-to/migration-from-v1.md

Example of package.json scripts for v2, incorporating new tools and patterns like ldenv and rocketh.

```json
{
  "scripts": {
    "prepare": "set-defaults .vscode && pnpm compile",
    "local_node": "ldenv -d localhost hardhat node",
    "compile": "hardhat compile",
    "compile:watch": "as-soon -w src pnpm compile",
    "fork:execute": "ldenv tsx @=HARDHAT_FORK=@@MODE @@",
    "fork:deploy": "pnpm compile --build-profile production && ldenv hardhat @=HARDHAT_FORK=@@MODE deploy @@",
    "deploy:dev": "ldenv -d localhost pnpm :deploy+export @@",
    "deploy:watch": "wait-on ./generated && ldenv -m localhost pnpm as-soon -w generated -w deploy pnpm run deploy:dev @@MODE @@",
    "test": "hardhat test",
    "test:watch": "wait-on ./generated && as-soon -w generated -w test hardhat test --no-compile",
    "typescript:watch": "as-soon -w js pnpm typescript",
    "format:check": "prettier --check .",
    "format": "prettier --write .",
    "lint": "slippy src/**/*.sol",
    "docgen": "ldenv -m default pnpm run deploy @@MODE --save-deployments true --skip-prompts ~~ pnpm rocketh-doc -e @@MODE --except-suffix _Implementation,_Proxy,_Router,_Route ~~ @@",
    "execute": "ldenv -n HARDHAT_NETWORK tsx @@",
    "deploy": "pnpm compile --build-profile production && ldenv hardhat --network @@MODE deploy @@",
    "verify": "ldenv rocketh-verify -e @@MODE @@",
    "export": "ldenv rocketh-export -e @@MODE @@",
    "typescript": "tsc"
  }
}
```

--------------------------------

### Getting Deployments by Tag v1 vs v2

Source: https://github.com/wighawag/hardhat-deploy/blob/main/skills/hardhat-deploy-migration/SKILL.md

Update how you get deployments by tag. v1 uses `deployments.getAll`, while v2 uses `loadAndExecuteDeploymentsFromFiles` with tags.

```typescript
const deploymentsList = await deployments.getAll();
const myDeployments = Object.values(deploymentsList);
```

```typescript
const env = await loadAndExecuteDeploymentsFromFiles({
  provider: provider,
  tags: ["MyTag"],
});
```

--------------------------------

### Hardhat Deploy CLI Commands

Source: https://context7.com/wighawag/hardhat-deploy/llms.txt

Examples of using the Hardhat Deploy CLI to run scripts based on tags and dependencies.

```bash
# run only core contracts
npx hardhat deploy --tags core

# run DeFi layer (auto-deploys ProtocolToken first via dependency)
npx hardhat deploy --tags defi

# full deploy on Sepolia
npx hardhat --network sepolia deploy

```

--------------------------------

### v2 package.json Dependencies

Source: https://github.com/wighawag/hardhat-deploy/blob/main/documentation/how-to/migration-from-v1.md

Example of dependencies in package.json for hardhat-deploy v2, including Rocketh and Viem.

```json
{
  "type": "module",
  "devDependencies": {
    "hardhat": "^3.1.4",
    "hardhat-deploy": "^2.0.0",
    "rocketh": "^0.17.15",
    "@rocketh/deploy": "^0.17.9",
    "@rocketh/read-execute": "^0.17.9",
    "@rocketh/node": "^0.17.18",
    "@rocketh/proxy": "^0.17.13",
    "viem": "^2.45.0",
    "@nomicfoundation/hardhat-viem": "^3.0.1",
    "@nomicfoundation/hardhat-node-test-runner": "^3.0.8",
    "@nomicfoundation/hardhat-network-helpers": "^3.0.3",
    "@nomicfoundation/hardhat-keystore": "^3.0.3"
  }
}
```

--------------------------------

### Basic Test Structure with Fixtures

Source: https://github.com/wighawag/hardhat-deploy/blob/main/documentation/how-to/deployment-fixtures-in-tests.md

Implement a basic test structure using fixtures. This example demonstrates how to load fixtures, interact with a deployed contract (Greeter), and assert its state.

```typescript
// test/Greeter.test.ts
import { expect } from "earl";
import { describe, it } from "node:test"; // using node:test as hardhat v3 do not support vitest
import { network } from "hardhat";
import { setupFixtures } from "./utils/index.js";

const { provider, networkHelpers } = await network.connect();
const { deployAll } = setupFixtures(provider);

describe("Greeter", function () {
  it("basic test", async function () {
    const { env, Greeter, unnamedAccounts } = await networkHelpers.loadFixture(
      deployAll
    );
    const greetingToSet = "hello world";
    const greeter = unnamedAccounts[0];
    await expect(
      await env.read(Greeter, {
        functionName: "greet",
        args: [],
      })
    ).toEqual("");

    await env.execute(Greeter, {
      functionName: "setGreeting",
      args: [greetingToSet],
      account: greeter,
    });

    await expect(
      await env.read(Greeter, {
        functionName: "greet",
        args: [],
      })
    ).toEqual(greetingToSet);
  });
});
```

--------------------------------

### Hardhat Task Execution Examples

Source: https://github.com/wighawag/hardhat-deploy/blob/main/skills/hardhat-deploy-migration/SKILL.md

Execute common Hardhat tasks using the command line, including compiling with specific profiles, deploying to networks, and running tests.

```bash
# Compile with production profile
npx hardhat compile --build-profile production

# Deploy to specific network
npx hardhat --network sepolia deploy

# Run tests
npx hardhat test
```

--------------------------------

### Custom Fixture Setup with loadAndExecuteDeploymentsFromFiles in hardhat-deploy v2

Source: https://github.com/wighawag/hardhat-deploy/blob/main/skills/hardhat-deploy-migration/SKILL.md

Create custom test fixtures in hardhat-deploy v2 using loadAndExecuteDeploymentsFromFiles to manage deployment environments and contracts.

```typescript
import {loadAndExecuteDeploymentsFromFiles} from '../rocketh/environment.js';
import {network} from 'hardhat';

const {provider, networkHelpers} = await network.connect();

function setupFixtures(provider) {
  return {
    async deployAll() {
      const env = await loadAndExecuteDeploymentsFromFiles({
        provider: provider,
      });
      const MyContract = env.get<Abi_MyContract>("MyContract");
      return {env, MyContract, ...};
    },
  };
}

const {deployAll} = setupFixtures(provider);

// In test
const {env, MyContract} = await networkHelpers.loadFixture(deployAll);
```

--------------------------------

### Initialize npm Project

Source: https://github.com/wighawag/hardhat-deploy/blob/main/documentation/how-to/setup-first-project.md

Sets up a new npm project and navigates into the project directory.

```bash
mkdir my-project
cd my-project
```

--------------------------------

### Example Deploy Script (deploy_Counter.ts)

Source: https://github.com/wighawag/hardhat-deploy/blob/main/documentation/how-to/setup-first-project.md

Define a deployment script for a 'Counter' contract using the exported deployScript function. This script specifies the contract artifact and deployment account.

```typescript
import { deployScript, artifacts } from "../rocketh/deploy.js";

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

    await deploy("Counter", {
      account: deployer,
      artifact: artifacts.Counter,
    });
  },
  { tags: ["Counter", "Counter_deploy"] },
);

```

--------------------------------

### Initialize Project with npm

Source: https://github.com/wighawag/hardhat-deploy/blob/main/documentation/installation.md

Use this command to initialize a new project with hardhat-deploy using npm.

```bash
npx hardhat-deploy init --install my-project
```

--------------------------------

### Initialize Project with pnpm

Source: https://github.com/wighawag/hardhat-deploy/blob/main/documentation/installation.md

Use this command to initialize a new project with hardhat-deploy using pnpm.

```bash
pnpm dlx hardhat-deploy init --install my-project
```

--------------------------------

### Deploy a Library Contract

Source: https://github.com/wighawag/hardhat-deploy/blob/main/documentation/how-to-deploy-contracts.md

Deploy the library contract using the `deploy` function. The `exampleLibrary` variable will hold the deployment details, including the ABI and deployed address.

```javascript
const exampleLibrary = await deploy("ExampleLibrary", {
  artifact: artifacts.ExampleLibrary,
  account: deployer,
});
```

--------------------------------

### Navigate to Project Directory

Source: https://github.com/wighawag/hardhat-deploy/blob/main/documentation/installation.md

After initializing your project, change the current directory to the newly created project folder.

```bash
cd my-project
```

--------------------------------

### Install Hardhat Dependencies

Source: https://github.com/wighawag/hardhat-deploy/blob/main/documentation/how-to/setup-first-project.md

Installs essential packages for a working Hardhat project, including TypeScript support and Forge-std.

```bash
pnpm add -D hardhat @types/node typescript forge-std@github:foundry-rs/forge-std#v1.9.4
```

--------------------------------

### Create Deploy Folder

Source: https://github.com/wighawag/hardhat-deploy/blob/main/documentation/how-to/setup-first-project.md

Create the 'deploy' directory to store your smart contract deployment scripts.

```bash
mkdir deploy
```

--------------------------------

### Custom Network Configuration with Helpers

Source: https://github.com/wighawag/hardhat-deploy/blob/main/documentation/how-to/configure-network-helpers.md

Illustrates how to configure custom local and testnet networks using a combination of network helpers.

```typescript
const config: HardhatUserConfig = {
  networks: addForkConfiguration(
    addNetworksFromKnownList(
      addNetworksFromEnv({
        // Custom local network
        localhost: {
          type: 'edr-simulated',
          chainType: 'l1',
        },
        // Custom testnet
        'custom-testnet': {
          type: 'http',
          url: 'https://rpc.custom-testnet.com',
          chainId: 12345,
          accounts: { mnemonic: 'your custom testnet mnemonic' },
        },
      })
    )
  ),
};
```

--------------------------------

### Install Recommended Rocketh Extensions

Source: https://github.com/wighawag/hardhat-deploy/blob/main/documentation/how-to/setup-first-project.md

Install additional Rocketh extensions to enhance your deployment workflow with features like proxy management, export, verification, and documentation.

```bash
pnpm add -D @rocketh/proxy @rocketh/export @rocketh/verifier @rocketh/doc
```

--------------------------------

### Install hardhat-deploy v1

Source: https://github.com/wighawag/hardhat-deploy/blob/main/documentation/how-to/migration-from-v1.md

If you have a production project using hardhat-deploy v1 with Hardhat 2.x, it is recommended to stay on v1. This command uninstalls the current version and installs v1.

```bash
npm uninstall hardhat-deploy
npm install hardhat-deploy@1
```

--------------------------------

### Execute Script within Zellij

Source: https://github.com/wighawag/hardhat-deploy/blob/main/demoes/proxies/README.md

Example of executing a script within the Zellij environment after launching.

```bash
pnpm execute localhost scripts/setMessage.ts "Hello everyone"
```

--------------------------------

### Create Rocketh Configuration Directory

Source: https://github.com/wighawag/hardhat-deploy/blob/main/documentation/how-to/setup-first-project.md

Create the 'rocketh' directory to house your project's Rocketh configuration files.

```bash
mkdir rocketh
```

--------------------------------

### Update tsconfig.json for v1

Source: https://github.com/wighawag/hardhat-deploy/blob/main/documentation/how-to/migration-from-v1.md

This is an example of the tsconfig.json file used in v1. It specifies compiler options and included files.

```json
{
  "compilerOptions": {
    "target": "es5",
    "module": "commonjs",
    "strict": true,
    "esModuleInterop": true,
    "moduleResolution": "node",
    "forceConsistentCasingInFileNames": true,
    "outDir": "dist"
  },
  "include": [
    "hardhat.config.ts",
    "./scripts",
    "./deploy",
    "./test",
    "typechain/**/*"
  ]
}
```

--------------------------------

### Rocketh Test/Script Environment Setup

Source: https://github.com/wighawag/hardhat-deploy/blob/main/AGENTS.md

Configures the environment for tests and scripts by loading deployments and setting up the Hardhat environment.

```typescript
import {type Extensions, type Accounts, type Data, extensions} from './config.js';
import {setupEnvironmentFromFiles} from '@rocketh/node';
import {setupHardhatDeploy} from 'hardhat-deploy/helpers';

const {loadAndExecuteDeploymentsFromFiles} = setupEnvironmentFromFiles<Extensions, Accounts, Data>(extensions);
const {loadEnvironmentFromHardhat} = setupHardhatDeploy<Extensions, Accounts, Data>(extensions);

export {loadEnvironmentFromHardhat, loadAndExecuteDeploymentsFromFiles};

```

--------------------------------

### Import and set up Rocketh extensions

Source: https://github.com/wighawag/hardhat-deploy/blob/main/documentation/how-to/migration-from-v1.md

Ensure you have imported and set up the Rocketh extensions, particularly for the `execute` function.

```typescript
// rocketh/config.ts
import * as readExecuteExtension from "@rocketh/read-execute";

const extensions =
  {
    ...deployExtension,
    ...readExecuteExtension, // This provides execute function
  };
export { extensions };

```

--------------------------------

### Deploy Contracts to a Network

Source: https://github.com/wighawag/hardhat-deploy/blob/main/demoes/proxies/README.md

Deploy contracts to a specified network. Requires .env.local setup or Hardhat secret store configuration.

```bash
pnpm run deploy <network>
```

--------------------------------

### v1 SimpleERC20 Deployment Script

Source: https://github.com/wighawag/hardhat-deploy/blob/main/documentation/how-to/migration-from-v1.md

This is an example of a v1 deploy script for the SimpleERC20 contract. It uses HardhatRuntimeEnvironment and DeployFunction for script execution.

```typescript
import { HardhatRuntimeEnvironment } from "hardhat/types";
import { DeployFunction } from "hardhat-deploy/types";
import { parseEther } from "ethers";

const func: DeployFunction = async function (hre: HardhatRuntimeEnvironment) {
  const { deployments, getNamedAccounts } = hre;
  const { deploy } = deployments;

  const { deployer, simpleERC20Beneficiary } = await getNamedAccounts();

  await deploy("SimpleERC20", {
    from: deployer,
    args: [simpleERC20Beneficiary, parseEther("1000000000")],
    log: true,
    autoMine: true,
  });
};
export default func;
func.tags = ["SimpleERC20"];
```
Tokens:
Raw