Migration to Hardhat v3

[DimaKush]

RFC: Add Hardhat 3 Support to Scaffold-ETH

Summary

This RFC proposes adding Hardhat 3 support to scaffold-eth-2, modernizing the development stack with improved security, better developer experience, and future-proof architecture.

Background

Scaffold-ETH currently uses Hardhat 2.x, which is stable but lacks modern features. Hardhat 3 (currently in beta) offers significant improvements that would benefit the scaffold-eth ecosystem.

Motivation

Current Pain Points

• Security: .env files with plaintext secrets in repositories
• Developer Experience: Complex plugin configuration and setup
• Maintenance: Hardhat 2.x is in maintenance mode
• Modern Standards: Missing ESM support and modern TypeScript features

Hardhat 3 Benefits

• 🔐 Encrypted Keystore: Secure secret management without .env files
• 🏗️ Declarative Config: Cleaner, more maintainable configuration
• 📦 ESM-First: Modern JavaScript/TypeScript standards
• 🚀 Better Deployment: Improved Hardhat Ignition integration
• 🔍 Enhanced Verification: Better contract verification workflow

Implementation Strategy

Option A: Gradual Migration (Recommended)

• Maintain Hardhat 2.x support alongside Hardhat 3
• Add Hardhat 3 as an optional feature flag
• Provide migration tools for existing projects
• Gradual deprecation of Hardhat 2.x

Option B: Complete Migration

• Direct upgrade to Hardhat 3
• Breaking change for all users
• Requires major version bump (v3.0.0)
• More disruptive but cleaner long-term

Technical Implementation

Core Changes Required

1. Dependencies Update

   {
     "hardhat": "^3.0.7",
     "@nomicfoundation/hardhat-ignition": "^3.0.3",
     "@nomicfoundation/hardhat-verify": "^3.0.3",
     "@nomicfoundation/hardhat-keystore": "^3.0.1",
     "@nomicfoundation/hardhat-toolbox-mocha-ethers": "^3.0.0"
   }

2. ESM Configuration

   {
     "type": "module"
   }

3. Updated Hardhat Config

   • Explicit plugin declarations
   • configVariable() for secrets
   • Updated network configurations

Impact Analysis

Breaking Changes

1. ESM Requirement: Projects must use ES modules
2. Secret Management: Migration from .env to keystore
3. Plugin Configuration: Explicit plugin declarations required
4. CLI Changes: Some commands have changed syntax

Migration Complexity

• Low: New projects (straightforward setup)
• Medium: Existing projects (requires migration script)
• High: CI/CD pipelines (need keystore integration)

Risk Assessment

• Technical Risk: Medium (Hardhat 3 is still in beta)
• User Impact: High (breaking changes for existing users)
• Maintenance: Low (reduces long-term maintenance burden)

Example Config

import type { HardhatUserConfig } from "hardhat/config";
import { configVariable } from "hardhat/config";
import hardhatIgnition from "@nomicfoundation/hardhat-ignition";
import hardhatKeystore from "@nomicfoundation/hardhat-keystore";
import hardhatVerify from "@nomicfoundation/hardhat-verify";
import hardhatToolboxMochaEthers from "@nomicfoundation/hardhat-toolbox-mocha-ethers";

const config: HardhatUserConfig = {
  plugins: [
    hardhatIgnition,
    hardhatKeystore,
    hardhatVerify,
    hardhatToolboxMochaEthers,
  ],
  solidity: {
    compilers: [
      {
        version: "0.8.20",
        settings: {
          optimizer: {
            enabled: true,
            runs: 200,
          },
        },
      },
    ],
  },
  networks: {
    hardhat: {
      type: "edr-simulated",
    },
    localhost: {
      type: "http",
      url: "http://127.0.0.1:8545",
    },
    sepolia: {
      type: "http",
      url: configVariable("SEPOLIA_RPC_URL"),
      accounts: [configVariable("DEPLOYER_PRIVATE_KEY")],
      chainId: 11155111, // Sepolia testnet
    },
  },
  verify: {
    etherscan: {
      apiKey: configVariable("ETHERSCAN_API_KEY"),
    },
  },
};

export default config;

Keystore Usage Example

# Set up secrets (interactive prompts)
npx hardhat keystore set SEPOLIA_RPC_URL
npx hardhat keystore set DEPLOYER_PRIVATE_KEY
npx hardhat keystore set ETHERSCAN_API_KEY

# For development (no password)
npx hardhat keystore set --dev LOCAL_PRIVATE_KEY

# List all secrets
npx hardhat keystore list

# Get a specific secret
npx hardhat keystore get <KEY>

Benefits

1. Security: No more .env files with plaintext secrets
2. Modern: Uses latest Hardhat features
3. Type Safety: Better TypeScript integration
4. Flexibility: Multiple concurrent network connections
5. Future-proof: Ready for upcoming Hardhat features

Open Questions

1. Timing: Should we wait for Hardhat 3 stable release or proceed with beta?
2. Migration Strategy: Gradual migration vs. complete migration?
3. Backward Compatibility: How long to maintain Hardhat 2.x support?
4. Scaffolding: How to handle new project generation with Hardhat 3?

Reference Implementation

I've successfully migrated a scaffold-eth project to Hardhat 3 in my RPS Arena project. Key implementation details:

• Working Hardhat 3 config with all plugins
• Keystore integration for secure secret management
• Updated deployment scripts using Hardhat Ignition
• Comprehensive documentation for migration process

Community Feedback Requested

• Do you support this migration?
• Which migration strategy do you prefer?
• What concerns do you have about breaking changes?
• Would you be willing to help with implementation/testing?

Next Steps

1. Community Discussion: Gather feedback on this RFC
2. Technical Review: Validate implementation approach
3. Timeline Planning: Determine migration schedule
4. Implementation: Begin development if approved

I'm committed to contributing this feature and helping with the migration process.

[technophile-04]

Hey, thanks for the discussion! We are already thinking of it, and since hardhat is one of the core components of SE-2, we would like a core contributor to take it up. Also

• Security: .env files with plaintext secrets in repositories

We already encrypt deployer's private key and don't store it in plaintext checkout #1008