Hardhat2 + Foundry EVM 开发框架

这是一个将 Hardhat 与 Foundry 无缝整合的 Solidity 开发框架，既保留了 Hardhat 的插件生态（部署、验证、脚本执行、TypeScript 开发体验），也利用 Foundry 的高速 EVM、测试与脚本执行能力。适用于复杂合约开发、测试驱动开发 (TDD)、多环境部署与高级调试需求。

create2 factory

框架通过魔改 hardhdat-upgrade 包实现可以指定各条链的factory合约地址使用create2部署地址一样的合约。 注意：调用factory部署合约时需要确定你的地址拥有factory合约的admin权限，否则会失败。

可升级合约使用方式（想要使用factory部署，在调用upgrades.deployProxy时指定create2Factory配置即可。否则不指定create2Factory配置就是非create2 factory模式进行部署）：

const ContractFactory = await ethers.getContractFactory(CONTRACT_NAME);
const INIT_ARGS: any[] = [];

const create2Config = {
    address: FACTORY_ADDRESS,
    salt: proxySalt,          // 代理合约的 salt
    implSalt: implSalt,       // 实现合约的 salt
    deployImpl: true,         // 实现合约也用 CREATE2 部署
  };
  
  const contract = await upgrades.deployProxy(
    ContractFactory,
    INIT_ARGS,
    {
      initializer: 'initialize',
      kind: 'uups',
      ...( { create2Factory: create2Config } as any ),
    }
  );

不可升级合约使用方式（不想使用factory部署，直接调用Yourcontract.deploy即可）：

const ContractFactory = await ethers.getContractFactory('YourContract');
const bytecode = ContractFactory.bytecode;
const constructorArgs = ethers.AbiCoder.defaultAbiCoder().encode(
  ['uint256'], // 构造函数参数类型
  [123]        // 构造函数参数值
);

const initCode = ethers.concat([bytecode, constructorArgs]);

const factoryContract = await ethers.getContractAt(
  ['function deploy(bytes32 salt, bytes memory initCode, bytes memory data, uint256 create2ForwardValue, uint256 callForwardValue) external payable returns (address)'],
  FACTORY_ADDRESS
);

const tx = await factoryContract.deploy(
  salt,
  initCode,
  '0x',  // 部署后不需要额外调用
  0,     // create2ForwardValue
  0      // callForwardValue
);

同时本项目集成了 check / sync / validate / parse 四个核心命令，构建出一套完整的智能合约升级与安全验证流程。 额外带有修复hardhat-config.ts文件引用错误的功能 fix（使用evm-hardhat-foundry包部署的框架则不会用到此功能,以往项目可能会用到,例如错误引用：import { HardhatUserConfig } from "hardhat/config";）

功能特性

功能一： 字节码检查（check） 功能二： 合约状态同步（sync） 功能三： 升级验证（validate） 功能四： Calldata解析（parse） 功能五： hardhat-config.ts文件修复（fix）

功能一： 字节码检查（check）

• ✅ 检查链下合约代码和链上合约代码是否一致
• ✅ 支持检查单个合约、指定网络或所有合约
• ✅ 智能识别 Constructor 参数差异和 Immutable 变量差异
• ✅ 自动移除元数据进行比较
• ✅ 生成详细的 JSON 报告
• ✅ 支持增量更新报告

1. 修改配置文件

在项目根目录创建 contractInfo.json 文件：

{
  "eth": {
    "Vault": "0x80aaf2e4636c510e067a5d300d8bafd48027addf",
    "VaultCrossChainRelay": "0x060194eec4556096baaabd6bf553d2658d6a66ab"
  },
  "bsc": {
    "Vault": "0x2cb7d2603a5f43b9fe79e98f09fe3eec40b6765d",
    "VaultCrossChainRelay": "0x23ae3a565e0896866e7725fe6d49fd777359c162"
  }
}

格式说明：

• 第一层 key 是网络名称（必须与 hardhat.config.js 中的网络名称一致）
• 第二层 key 是合约名称（必须与编译的合约名称一致）
• value 是合约地址

2. 配置 Hardhat

确保 hardhat.config.js 中配置了相应的网络：

module.exports = {
  networks: {
    eth: {
      url: "https://eth-mainnet.g.alchemy.com/v2/YOUR-API-KEY",
    },
    bsc: {
      url: "https://bsc-dataseed.binance.org/",
    }
  }
};

3. 使用工具

📋 查看帮助

npx gate-tool --help

🔍 字节码检查

# 检查所有合约（推荐）
npx gate-tool check

# 检查指定合约
npx gate-tool check --contract Vault

# 检查指定网络
npx gate-tool check --network eth

# 指定配置文件路径
npx gate-tool check --config ./config/contracts.json

# 指定输出报告路径
npx gate-tool check --output ./reports/result.json

功能二： 合约状态同步（sync）

• ✅ 同步链上合约状态到本地 .openzeppelin 文件
• ✅ 自动读取链上实现合约地址
• ✅ 获取并更新存储布局信息

1. 同步链上合约状态

当合约通过 calldata 方式由其他人（如多签钱包）执行升级后，本地的 .openzeppelin 文件不会自动更新。使用此命令可以从链上读取最新状态并更新本地文件。

# 同步合约状态（推荐）
npx gate-tool sync \
  --proxy 0x1234... \
  --contract CounterUUPS \
  --network sepolia

功能三： 升级验证（validate）

• ✅ 验证合约升级的安全性
• ✅ 检查存储布局兼容性
• ✅ 自动部署新实现合约
• ✅ 生成 upgradeToAndCall 的 calldata
• ✅ 支持同一合约和不同合约的升级模式

1. 验证升级安全性并生成 calldata

验证合约升级的安全性，并生成 upgradeToAndCall 的 calldata。

# 不同合约升级（从 CounterUUPS 升级到 CounterUUPSV2）
npx gate-tool validate \
  --proxy 0x1234... \
  --old CounterUUPS \
  --new CounterUUPSV2 \
  --network sepolia

# 同一合约升级（修改现有合约后升级）（推荐）
npx gate-tool validate \
  --proxy 0x1234... \
  --old CounterUUPS \
  --new CounterUUPS \
  --network sepolia

# 指定输出文件路径
npx gate-tool validate \
  --proxy 0x1234... \
  --old CounterUUPS \
  --new CounterUUPSV2 \
  --network sepolia \
  --output ./upgrade-info.json

注意： validate 命令会在链上部署新的实现合约（仅用于验证），但不会升级代理合约。请使用生成的 calldata 通过多签钱包执行升级。

功能四： Calldata 解析（parse）

• ✅ 解析 EVM calldata，显示函数名称和参数
• ✅ 支持从 Hardhat artifacts 自动查找 ABI
• ✅ 支持指定自定义 ABI 文件路径
• ✅ 支持直接提供 ABI 数组
• ✅ 支持批量解析多个 calldata
• ✅ 友好的彩色输出和 JSON 导出

1. 解析 Calldata

解析 EVM calldata，将其转换为人类可读的函数调用信息。

# 从 JSON 文件单个或批量读取（推荐）
npx gate-tool parse --input parseCalldata.example.json --output results.json

# 直接从命令行参数（使用合约名称从 artifacts 查找 ABI）
npx gate-tool parse \
  --to 0x5FbDB2315678afecb367f032d93F642f64180aa3 \
  --contract Counter \
  --calldata 0x3fb5c1cb0000000000000000000000000000000000000000000000000000000000000064

# 使用自定义 ABI 文件
npx gate-tool parse \
  --to 0x1234... \
  --abi-path ./custom-abi/MyContract.json \
  --calldata 0x...

**输入文件格式示例：**

```json
{
  "to": "0x5FbDB2315678afecb367f032d93F642f64180aa3",
  "contractName": "Counter",
  "calldata": "0x3fb5c1cb0000000000000000000000000000000000000000000000000000000000000064"
}

批量解析格式（数组 包含三种形式）：

[
  {
    "to": "0x...",
    "contractName": "Counter",
    "calldata": "0x..."
  },
  {
    "to": "0x...",
    "abiPath": "./abi.json",
    "calldata": "0x..."
  },
  {
    "": "0x...",
    "abi": [
      {
        "inputs": [
          {"name": "spender", "type": "address"},
          {"name": "amount", "type": "uint256"}
        ],
        "name": "approve",
        "outputs": [{"name": "", "type": "bool"}],
        "stateMutability": "nonpayable",
        "type": "function"
      }
    ],
    "calldata": "0x..."
  }
]

支持三种 ABI 来源方式：

1. contractName - 从 Hardhat artifacts 自动查找（需要先编译合约）
2. abiPath - 指定 ABI 文件路径
3. abi - 直接在 JSON 中提供 ABI 数组

功能五： 配置修复（fix）

• ✅ 自动检测 Hardhat 配置文件的兼容性问题
• ✅ 智能修复 ESM 模块导入错误
• ✅ 交互式确认修复操作
• ✅ 自动备份原配置文件
• ✅ 支持仅检查模式

1. 配置修复（推荐首次使用）

如果在使用过程中遇到 Hardhat 配置导入错误，可以使用 fix 命令自动修复：

# 自动检测并修复配置问题（推荐 交互式）
npx gate-tool fix

# 仅检查问题，不执行修复
npx gate-tool fix --check

# 跳过确认，直接修复
npx gate-tool fix --yes

常见问题：

• Cannot find module 'hardhat/config' - 导入语句需要使用 type 关键字
• Did you mean to import "hardhat/config.js"? - ESM 模块兼容性问题

fix 命令会自动将：

import { HardhatUserConfig } from "hardhat/config";

修复为：

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

命令选项

check 命令

选项	简写	说明	默认值
--contract <name>	-c	指定要检查的合约名称	-
--network <name>	-n	指定要检查的网络名称	-
--config <path>	-	指定配置文件路径	./contractInfo.json
--output <path>	-o	指定输出报告文件路径	./bytecode-check-report.json

sync 命令

选项	简写	说明	必需
--proxy <address>	-	代理合约地址	✅
--contract <name>	-	合约名称	✅
--network <name>	-n	网络名称	-

validate 命令

选项	简写	说明	必需
--proxy <address>	-	代理合约地址	✅
--old <name>	-	旧合约名称	✅
--new <name>	-	新合约名称	✅
--network <name>	-n	网络名称	-
--output <path>	-o	输出文件路径	./upgradeCalldata.json

parse 命令

选项	简写	说明	默认值
--input <path>	-i	输入 JSON 文件路径	-
--to <address>	-	目标合约地址（命令行模式）	-
--calldata <data>	-	Calldata 十六进制数据（命令行模式）	-
--contract <name>	-c	合约名称（从 artifacts 查找 ABI）	-
--abi-path <path>	-	自定义 ABI 文件路径	-
--output <path>	-o	输出 JSON 文件路径	-
ABI 来源优先级：直接提供的 abi > abiPath > contractName