Learn a clean deployment workflow
in ~45 minutes.

Before touching config, you need to understand what a “network” really means in dev. Think of deployment as a ladder:

• Localhost — instant feedback, zero money, fake ETH.
• Testnet — real chain rules, fake ETH, public explorer.
• Mainnet — real money, real users, no undo button.

The workflow we’ll follow:

1) Local deploy (fast sanity check)
2) Testnet deploy (real chain rules)
3) Verify + record addresses
4) Dry-run mainnet deployment
5) Mainnet deploy (with checklist)

In Hardhat 3, networks are typed by purpose:

• edr-simulated — local simulated networks
• http — real RPC networks

Here’s a minimal but correct config skeleton:

// hardhat.config.ts
import { defineConfig, configVariable } from "hardhat/config";
import "@nomicfoundation/hardhat-toolbox-ethers";

export default defineConfig({
  solidity: {
    version: "0.8.28",
    settings: { optimizer: { enabled: true, runs: 200 } },
  },

  networks: {
    // local simulated chain
    hardhatMainnet: {
      type: "edr-simulated",
      chainType: "l1",
    },

    // real testnet via RPC
    sepolia: {
      type: "http",
      chainType: "l1",
      url: configVariable("SEPOLIA_RPC_URL"),
      accounts: [configVariable("SEPOLIA_PRIVATE_KEY")],
    },

    // mainnet via RPC
    mainnet: {
      type: "http",
      chainType: "l1",
      url: configVariable("MAINNET_RPC_URL"),
      accounts: [configVariable("MAINNET_PRIVATE_KEY")],
    },
  },
});

Whether you use Hardhat config variables or dotenv, the rule is the same: keys and RPC URLs must live outside Git.

Classic beginner-friendly approach:

// .env (never commit)
SEPOLIA_RPC_URL=https://sepolia.infura.io/v3/xxxx
SEPOLIA_PRIVATE_KEY=0xYOUR_TESTNET_KEY

MAINNET_RPC_URL=https://mainnet.infura.io/v3/xxxx
MAINNET_PRIVATE_KEY=0xYOUR_MAINNET_KEY

ETHERSCAN_API_KEY=XXXX

Add this to .gitignore:

.env
deployments/*.json

Your deploy script should work on local and public networks without edits. Example deploy script:

// scripts/deploy.ts
import { network } from "hardhat";
import fs from "fs";

async function main() {
  const { ethers, networkName } = await network.connect();

  console.log("Deploying to:", networkName);

  // Example: deploy any existing contract
  const Contract = await ethers.getContractFactory("MyContract");
  const contract = await Contract.deploy();
  await contract.waitForDeployment();

  const address = await contract.getAddress();
  console.log("Deployed at:", address);

  // Save deployment
  const out = {
    address,
    deployedAt: new Date().toISOString(),
    network: networkName,
  };

  fs.mkdirSync("deployments", { recursive: true });
  fs.writeFileSync(`deployments/${networkName}.json`, JSON.stringify(out, null, 2));
  console.log("Saved deployments/" + networkName + ".json");
}

main().catch((e) => {
  console.error(e);
  process.exit(1);
});

Run on local simulated chain:

npx hardhat run scripts/deploy.ts --network hardhatMainnet

Once local deploy succeeds, move to testnet. Same script, different network:

npx hardhat run scripts/deploy.ts --network sepolia

If your deploy fails here, it’s usually one of these:

• RPC URL is wrong / rate limited
• Private key has no Sepolia ETH
• Constructor args mismatch

Verification is optional but recommended. It makes your source code public and readable.

If you use toolbox-ethers, verify plugin is included. Add Etherscan API key in env, then:

npx hardhat verify --network sepolia <address> <constructorArgs...>

You can automate this in scripts/verify.ts:

// scripts/verify.ts
import { network, run } from "hardhat";
import fs from "fs";

async function main() {
  const { networkName } = await network.connect();
  const p = `deployments/${networkName}.json`;

  if (!fs.existsSync(p)) {
    throw new Error("No deployments file: " + p);
  }

  const { address } = JSON.parse(fs.readFileSync(p, "utf8"));

  console.log("Verifying:", address);

  await run("verify:verify", {
    address,
    constructorArguments: [],
  });

  console.log("Verified!");
}

main().catch((e) => {
  console.error(e);
  process.exit(1);
});

Run it:

npx hardhat run scripts/verify.ts --network sepolia

A dry-run is a final rehearsal: you deploy with mainnet config but to a forked state locally.

Add forking to your simulated net:

// hardhat.config.ts (snippet)
hardhatMainnet: {
  type: "edr-simulated",
  chainType: "l1",
  forking: {
    url: configVariable("MAINNET_RPC_URL"),
    blockNumber: 20000000,
  },
},

Now run deploy on fork:

npx hardhat run scripts/deploy.ts --network hardhatMainnet

Some real projects use upgradeable proxies (UUPS / Transparent). You don’t need them for learning — but you should know the flow exists.

Install upgrades plugin:

npm install --save-dev @openzeppelin/hardhat-upgrades

Enable it:

// hardhat.config.ts
import "@openzeppelin/hardhat-upgrades";

Deploy as a proxy:

// scripts/deploy.ts (snippet)
const Box = await ethers.getContractFactory("Box");
const proxy = await upgrades.deployProxy(Box, [42], { kind: "uups" });
await proxy.waitForDeployment();

console.log("Proxy address:", await proxy.getAddress());