ERC-7730 描述符安全审计指南：流程详解与核心工具实操

你的角色是审计 ERC-7730 描述符。这些 JSON 文件决定了以太坊钱包在用户签署交易时展示何种信息。你的最终任务，是发布一份加密证明，以佐证你的审查结论。

你必须承诺的事项

• 定期审查描述符。例如，你可以将 clearsig 仓库 添加至你的 Watch 列表，并配置好通知。
• 为每一个你审查过的描述符，发布一份签名的证明（或创建一个 issue 来反馈问题）。
• 随着描述符的迭代演化，持续维护你的证明。新版本必须附上新的证明。

准备工具

下述大多数步骤依赖于 clearsig，这是一个实现了 ERC-7730 翻译、ERC-8176 描述符哈希以及 ERC-8213 字节级摘要的 CLI 工具。

uv tool install clearsig    # 或：pipx install clearsig / pip install clearsig

本指南涉及的子命令如下：

• clearsig translate — 利用描述符解码原始 calldata（见步骤 3 和 5）。
• clearsig generate — 从 Sourcify 引导生成全新的基准描述符，用于交叉验证提交内容（见步骤 3）。
• clearsig descriptor-hash（别名 dh）— 计算用于证明的 ERC-8176 哈希。

默认情况下，clearsig 会使用上游注册表 ~/.clearsig/registry。在审查 PR 时，你应在本地检出 PR 分支，并将 clearsig 指向该检出路径，以确保翻译时使用的是你正在审查的描述符，而非已合并的版本：

git fetch origin pull/<PR-number>/head:pr-<PR-number>
git checkout pr-<PR-number>
export ERC7730_REGISTRY_PATH=$(pwd)

五步审查流程

1. 项目背景检查
在描述符 JSON 中找到项目 URL。确认协议的真实目的，并判断 PR 提交者与该项目是否具备合理的关联性。

2. 合约验证
确认合约已在 repo.sourcify.dev 上完成验证。仔细交叉比对合约地址与 ABI，确保它们与描述符中的声明完全一致。如果合约未经验证——切勿签名。对于 Sourcify 不支持的链，PR 描述中必须包含指向该链区块浏览器上已验证源代码的链接。

3. 描述符准确性核验

• 参数名称、类型和顺序须与 ABI 匹配。
• 函数选择器必须正确无误。
• Intent 字段应反映真实的用户影响，杜绝误导性的简化。
• 批准、转账和特权操作必须被准确标记。
• payable 与 non-payable 的区分需要精确。
• 确保跨链部署时描述符的一致性。

运行 clearsig generate --chain-id <N> --to <address> --owner <name> 可从已验证的 Sourcify ABI 生成基准描述符（它能自动遍历代理以定位实现合约）。将提交者提供的描述符与此基准进行差异对比，便能发现遗漏的函数、错误类型的参数以及选择器不匹配等问题。

4. Intent 可变性分析

函数的显示意图可能随时间与其执行行为产生分歧，分歧点包括：代理升级、由管理员控制的状态变更，或是基于可变存储的分支逻辑。为此，ERC-7730 技术规范 的 v2 版本提供了两种链上前提机制，用以声明限定描述符意图声明的状态：

• context.contract.proxy — 适用于标准化可升级代理（EIP-1967、EIP-1822、EIP-2535）。用于声明已审计的实现地址；对于钻石代理，则声明选择器到 facet 的路由。
• context.contract.stateRefs — 一个存储槽前提条件数组。用于声明 slot、expectedValue 和可选的 mask。覆盖管理员控制的参数、状态依赖的分支、自定义代理实现槽等类似的可变链上状态。

审计员的自问：显示的意图是否依赖于这些可变向量？
对于 display.formats 中的每个函数，核心问题不是“这个合约是否使用了预言机、时间戳或外部调用？”，而是“渲染出的 intent 字符串或任何格式化的 fields，其值是否依赖于受那些向量影响的状态？”。一个完全由用户输入（如数量、接收方、最小输出额、截止时间）来参数化其显示意图的函数，即便合约内部查询了预言机，其描述符也无需表达 intent 的可变性。反之，如果一个函数将预言机提供的值作为其意图的一部分进行渲染，那就必须明确表达出来。

验证所声明前提条件的准确性
对于每个 proxy 声明：

• 从标准化存储槽（EIP-1967/EIP-1822）读取实时实现地址，或通过钻石的 facets() 调用（EIP-2535）来枚举 facet。
• 确认每个实时实现都已被列在 expectedImplementations 中。
• 对于钻石代理，确认实时的 selector → facet 映射与声明的 (address, selectors) 对匹配，既要确保每个 facet 都列出，也要确保每个选择器都路由到了声明的 facet。

对于每个 stateRef：

• 读取实时存储槽值（使用 cast storage <address> <slot> 或 eth_getStorageAt）。
• 确认它在比较规则下与 expectedValue 匹配（若有 mask 则进行掩码比较，否则需要精确匹配）。

验证前提条件的完备性
对于 display.formats 中的每个函数，枚举其（传递性地）读取、且可由非用户角色（如 owner、admin、governance、代理升级权限、delegatecall 目标）写入的所有存储槽。Slither 的 read-state-variables 和权限检测器是开展此项工作的良好起点。任何可被非用户角色写入并读取的存储槽，只要其值限定了显示的意图，却又未在 proxy 或 stateRefs 中声明，那就是一个遗漏的可变向量。此时，你应该为此提交一个补充性的 PR，或者拒绝签名。

v2 无法表达的向量 —— 这些情况必须省略函数
如果函数的显示意图依赖于下述任何一项，描述符就必须从 display.formats 中省略该函数。为这类函数编写格式化描述符是错误的，你绝对不得为其发布证明：

• 基于时间的分支：依赖 block.timestamp 或 block.number 阈值，而描述符又需要渲染或见证它们。
• 区块环境依赖：如 block.basefee、block.coinbase、tx.origin 等。
• 基于参数的隐藏分支：触发未显示逻辑的魔法输入值或哨兵地址。
• 动态外部调用解析：在运行时解析目标合约的情况，如注册表查找、工厂部署、CREATE2 预测、链下预言机端点等。
• 链下依赖：预言机端点、签名服务、由链下决定的库链接。
• 组合行为：通过 multicall、账户抽象批量处理、hook 或类似包装器修改了函数行为。

若发现某函数的描述符存在此类向量，勿签名。应要求提交者从 display.formats 中省略该函数（钱包会对被省略的选择器回退到不透明签名），然后重新提交。

EIP-7702 委托账户
如果描述符绑定到一个可能被 EIP-7702 委托 EOA 调用的合约，那么 EOA 的委托不在执行路径上，审查可按常规流程进行。如果描述符绑定到本身即是 7702 委托（智能钱包风格用例）的合约，那么像审查其他任何合约一样审查它即可。描述符描述了委托的行为，而钱包在签名时，会通过读取 EOA 的委托指示器来解析描述符。

5. 测试者验证 （专用的测试者工具尚在开发中）
专用的测试者工具尚未上线，目前请使用 clearsig translate 命令，通过描述符运行示例交易，并确认渲染出的输出是否清晰无误。记得先将 ERC7730_REGISTRY_PATH 指向 PR 的检出路径。

clearsig translate <calldata> --to <contract_address> --chain-id <N>

请混合使用常规路径交易（即最常见的用户操作）和边缘情况（最大值、零值、特殊地址）进行测试。确认以下三点：

• intent 文本与函数的实际功能相符。
• 每个字段的值都已正确渲染（数量有正确的小数位数，代币有正确的代码，地址解析为预期的名称）。
• 没有字段被静默省略。

提交你的证明

完整审查通过后，你需要创建一个 EAS 链下证明（遵循 ERC-8176 模式）：

1. 计算描述符哈希
   descriptorHash = keccak256(RFC 8785 JCS 规范化的描述符 JSON) —— 请勿直接对原始文件字节进行哈希。
   安装 clearsig 后，执行：

   clearsig descriptor-hash registry/<project>/<descriptorname>.json
   ## 0x...

2. 前往 Ethereum Attestation Service，选择“使用模式证明”，并选用“链下”方式。

3. 签署证明。

4. 将原始证明数据从 EAS 复制并保存为 JSON 文件，然后通过 PR 提交到注册表，路径如下：

   registry/<project>/sigs/<descriptorname>.eip155-1-0xYourAddress.json

   如果 sigs 文件夹不存在，请手动创建。

关键规则

• 仅在完成完整审查后，方可签名。
• 请为你所审查的确切文件版本签名。
• 严禁修改任何既有证明——你需要发布一个新的证明。
• 如果发现问题：不要签名。应转而创建一个 GitHub issue。
• 若你的密钥发生泄露，或你打算撤回证明，请通过 EAS 在链上提交撤销。
• 如果你已明确将密钥共享给任何钱包，须即刻通知它们该泄露事件。

获取列表

若要加入审计员列表，请创建一个 auditors/eip155-1-0xYourAddress/profile.json 文件并提交 PR：

{
  "id": "eip155:1:0xYourAddress",
  "name": "Your Name",
  "ens": "yourname.eth",
  "organization": "Your Org"
}

其中，ens 和 organization 字段为可选项。文件夹名称即是你的标识符。钱包将通过 ENS 解析你的身份，而证明的撤销则通过 EAS 处理，不依赖于此索引。

注册表地址： github.com/ethereum/clear-signing-erc7730-registry

• 原文链接：github.com/ethereum/clea...