solidity-hardhat-development

用途

本技能面向 Hardhat 3.x 的 Solidity 智能合约开发工作流，适用于以下场景：启动新的 Hardhat 3 项目、从 v2 迁移到 v3、使用 Foundry 兼容测试测试 Solidity 合约、使用 Hardhat Ignition 部署，以及构建多链应用。

环境要求

Node.js：v22.10 或更新版本
模块系统：ESM，需在 package.json 中设置 "type": "module"
初始化命令：npx hardhat --init
配置入口：来自 hardhat/config 的 defineConfig

配置

使用 solidity、networks 和 plugins 键组织配置。使用 configVariable("KEY") 处理密钥，避免将其写入代码。插件必须显式列出——v2 中的副作用导入方式不再有效。

网络类型：

edr-simulated：用于本地进程内测试
http：用于远程 RPC 连接

chainType 接受 "l1"、"op" 或 "generic"。构建配置文件（build profiles）允许按环境设置，例如为生产环境启用优化器。

示例配置：

import { defineConfig, configVariable } from "hardhat/config";
import { hardhatIgnition } from "@nomicfoundation/hardhat-ignition";

export default defineConfig({
  solidity: "0.8.28",
  plugins: [hardhatIgnition],
  networks: {
    hardhat: { type: "edr-simulated" },
    mainnet: { type: "http", url: configVariable("MAINNET_RPC_URL") },
  },
});

测试

测试类型与运行器：

Solidity（.t.sol）：由 Rust 驱动，继承 forge-std/Test.sol，支持完整的 vm cheatcodes，内置模糊测试（fuzzing）
TypeScript：Node 测试运行器 + Viem，或 Mocha + Ethers；通过 networkHelpers 属性访问网络辅助工具

命令：

npx hardhat test：运行所有测试
npx hardhat test solidity：仅运行 Solidity 测试
--coverage：覆盖率数据
--gas-stats：Gas 使用数据

部署（Ignition）

Hardhat Ignition 是主要的部署框架：通过 buildModule 声明式定义模块、自动并行化交易、自动恢复失败的部署。

部署：npx hardhat ignition deploy ignition/modules/MyModule.ts --network <network>
验证：使用 @nomicfoundation/hardhat-verify 插件

多链支持

Hardhat 3 可同时模拟多条链。使用 const mainnet = await network.connect("mainnet") 按网络连接。可并发分叉多条链，用于复杂的跨链测试。

调试

console.log（hardhat/console.sol）：在合约内进行打印调试
测试命令的 verbosity 标志：提高跟踪详细程度
EDR 堆栈跟踪：详细的失败跟踪

从 v2 迁移

v2 与 v3 对照：

CommonJS → ESM（"type": "module"）
Node.js < 22 → Node.js v22.10+
module.exports → defineConfig
副作用插件导入 → 显式 plugins 数组
Ethers v5 → Ethers v6 或 Viem
单一网络对象 → 多链 NetworkManager
v2 插件 → v3 专用插件版本

必备插件：hardhat-verify、hardhat-ignition、hardhat-keystore。

通过 MCP 增强

当 solidity-agent-toolkit 可用时，可提供以下能力：

compile_contract：构建合约并获取产物
run_tests：执行测试套件
gas_snapshot：获取 Gas 报告
dry_run_deploy：模拟部署
run_slither、run_aderyn：执行安全分析

参考

可参阅 Hardhat 3 Cheatsheet 获取示例。