assetxContracts/README.md

# 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模式进行部署）：
```bash
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即可）：
```bash
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` 文件：

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

格式说明：
- 第一层 key 是网络名称（必须与 `hardhat.config.js` 中的网络名称一致）
- 第二层 key 是合约名称（必须与编译的合约名称一致）
- value 是合约地址

#### 2. 配置 Hardhat

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

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

#### 3. 使用工具

##### 📋 查看帮助

```bash
npx gate-tool --help
```

##### 🔍 字节码检查

```bash
# 检查所有合约（推荐）
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` 文件不会自动更新。使用此命令可以从链上读取最新状态并更新本地文件。

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

### 功能三： 升级验证（validate）
- ✅ 验证合约升级的安全性
- ✅ 检查存储布局兼容性
- ✅ 自动部署新实现合约
- ✅ 生成 upgradeToAndCall 的 calldata
- ✅ 支持同一合约和不同合约的升级模式

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

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

```bash
# 不同合约升级（从 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，将其转换为人类可读的函数调用信息。

```bash
# 从 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"
}
```

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

```json
[
  {
    "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` 命令自动修复：

```bash
# 自动检测并修复配置问题（推荐 交互式）
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` 命令会自动将：
```typescript
import { HardhatUserConfig } from "hardhat/config";
```
修复为：
```typescript
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