gate-evm-tools 1.0.31 → 1.2.0

package/docs/plans/2026-10-28-openzeppelin-toolkit-consolidation.md

@@ -0,0 +1,396 @@
+# OpenZeppelin 扩展收口到 GateTool 与 full 模板去补丁计划
+
+日期：2026-10-28
+状态：P0 T1—T11 已完成。工作树：`feat/oz-toolkit-consolidation`。
+计划来源：根据当前代码、已有部署约束和本次需求直接整理。
+
+## 1. 目标与实施原则
+
+把项目模板维护的 OpenZeppelin 部署扩展统一交给 `gate-evm-tools`。新建 full 项目不再包含 `patches/`、`patch-package` 或应用补丁的安装脚本，部署能力通过 GateTool 的正式准备、执行和校验接口使用。
+
+本轮优先交付现行普通 CREATE2 与 UUPS 工作流的完整去补丁闭环。Transparent Proxy 是旧补丁提供、当前正式交付引擎尚未完整支持的能力，作为独立可选扩展列在第 9 节；没有完成该扩展时，新 full 文档必须明确代理工作流支持 UUPS，不能声称完全等价替代旧补丁。
+
+实施遵守以下约束：
+
+- 面向新模板，不编写旧项目自动迁移器，也不继续兼容 `upgrades.deployProxy(..., { create2Factory: ... })` 的私有参数。
+- 复用当前 GateTool 引擎、交易准备、签名边界、manifest 和部署记录实现，不再建立一套直接发送交易的部署引擎。
+- OpenZeppelin 官方依赖继续提供安全检查、storage layout 和代理合约；不修改其 `node_modules` 内容，不运行安装时自动打补丁。
+- 准备阶段只编译、读取和生成计划/calldata；真实执行由现有 dev/prod 执行入口负责，不能隐式选择第一个 signer。
+- prod 继续读取 dev 完成后生成并冻结的执行计划；管理员选择执行身份，有权限则执行，无权限则交付 calldata，不重新填写业务参数。
+- Hardhat 编译设置、网络配置、业务参数、`.openzeppelin*`、`contractInfo.json` 及部署证据仍由项目拥有；工具包统一维护实现。
+- full 继续保留已有 Foundry、zkSync 和可选示例能力；本轮清理集中在补丁及其耦合，不把 full 改成 core。
+
+## 2. 当前代码与工作范围
+
+| 仓库 | 已检查位置 | 当前基线 | 本轮职责 |
+| --- | --- | --- | --- |
+| EvmGateTools | `/Users/vector/gate/EvmGateTools` | `main` / `8be8b59` / `1.0.31` | 正式接口、OZ 校验、依赖版本、能力诊断、文档和验收 |
+| EvmHardhatCli | `/Users/vector/gate/.worktrees/evm-delivery/EvmHardhatCli` | `feat/evm-delivery` / `a3c39e8` / `2.1.24` | full 模板、安装/升级命令、配套版本和生成器验证 |
+| SmartFlowAI | 当前 App 与部署 Skill | 本轮不修改 | 后续单独更新随 App 携带的工具链包 |
+
+执行开始时重新 fetch 并检查这两个目标仓库的分支关系，使用同名功能分支和成对工作树。建议分支名 `feat/oz-toolkit-consolidation`，成对目录为 `/Users/vector/gate/.worktrees/oz-toolkit-consolidation/{EvmGateTools,EvmHardhatCli}`。GateTool 以最新 `main` 为基础；生成器以包含 `a3c39e8` 的最新交付代码为基础，不能直接从尚不包含这套模板的旧 `main` 开始。
+
+当前可以确认的事实：
+
+1. full 的补丁文件为 `templates/full/patches/@openzeppelin+hardhat-upgrades+3.9.1.patch`，共 685 行，同时修改 OZ 的源码、编译产物和类型。
+2. 补丁增加实现合约/代理 CREATE2 部署、指定实现地址、Multicall 初始化、部署后调用、owner 转移，以及 UUPS/Transparent 分支。
+3. `docs/workflow-reference.md` 明确：GateTool 工作流不调用被补丁修改的 `deployProxy` 路径。
+4. 现有准备协议只有 `create2-deploy`、`uups-placeholder-deploy`、`uups-upgrade`，正式 delivery 的代理记录与校验也主要围绕 UUPS。
+5. full 的 `postinstall` 和 `patch-package` 脚本会应用补丁，生成器 `installDependencies()` 还会在安装后显式执行项目本地的补丁命令。
+6. 生成器 `upgrade.ts` 将补丁列为升级文件，并维护补丁脚本、依赖固定值和 `upgrade-security-patch.pending.json` 状态，不能只删除模板里的 `.patch` 文件。
+7. GateTool 当前 `runtime/delivery/setup.ts` 仍将自身版本固定为 `1.0.29`；模板依赖为 `^1.0.28`。这与现有 `1.0.31` 工具包不一致，必须同步处理。
+8. `delivery-setup` 目前要求 core 的生成来源标记，不接受 full。此次 full 去补丁不能顺带把 full 当作 core，或直接改成另一套交付入口。
+
+## 3. 补丁能力去向
+
+| 补丁能力 | 本轮去向 | 验收要求 |
+| --- | --- | --- |
+| 实现合约 CREATE2 部署 | 复用 `src/core/preparation/evm.ts` | 使用真实构造参数编码；预测地址、salt、bytecode 绑定到计划 |
+| UUPS 代理部署 | 现有占位代理 + 原子首次升级/初始化 | 保持初始化与升级的原子边界，不暴露未初始化的正式业务代理 |
+| UUPS 后续升级 | 现有官方实现安全校验和 storage layout 校验 | 不兼容布局必须在准备阶段失败，不产生可执行计划 |
+| Multicall 与部署后调用 | 复用 controlled Multicall 和现有 call 步骤 | 调用顺序、目标、value、calldata 均进入计划；要求原子性的调用必须在同一交易中 |
+| owner 设置/转移 | 显式初始化参数或计划内业务调用 | 使用计划中的目标 owner；不自动取 signer 地址代替业务参数 |
+| 已存在实现/代理的复用 | 现有部署复用策略与注册记录 | 不能仅凭 `getCode != 0x` 接受；必须校验身份、实际实现、布局及必要证据 |
+| OZ manifest 与项目地址注册 | 现有显式 target manifest seam 和事务化登记 | dev/prod 隔离；失败不留下部分更新；未知 txHash 不伪造为全零值 |
+| 手写脚本调用 OZ 私有扩展参数 | 不继续提供该私有接口 | 文档提供 GateTool 正式 API/CLI 的替代示例；不做 monkey patch |
+| Transparent Proxy / ProxyAdmin | 第 9 节可选扩展 | 必须完成部署、升级、权限、登记和交付链路后才声明支持 |
+
+## 4. 拟交付的项目形态
+
+新 full 项目保留：
+
+```text
+project/
+├── contracts/                 # 项目业务合约
+├── test/                      # 项目测试与保留的基础设施测试
+├── scripts/tasks/             # 项目任务、业务参数和可选示例
+├── hardhat.config.ts          # 编译设置、项目网络、工具包接入
+├── foundry.toml               # full 已有的 Foundry 配置
+├── config.yaml                # 部署目标与业务配置
+├── rpc.env                    # 项目实际连接信息
+├── contractInfo.json          # 按运行流程生成/维护的项目注册记录
+├── .openzeppelin*/            # 按运行流程生成的项目 manifest
+└── package.json               # 直接调用 GateTool 的命令
+```
+
+不再生成 `patches/`，也不复制工具包部署实现到项目的 `scripts/workflow/` 或 `scripts/config/`。`postinstall` 不再承担部署扩展安装职责。模板里因 Solidity import 或 Hardhat 插件加载而需要的 OZ 依赖仍显式声明并锁定；“收口”不代表删除项目真实需要的官方依赖。
+
+## 5. 详细任务
+
+### T1：固定能力范围与验收基线
+
+**优先级：P0。依赖：无。**
+
+涉及文件：
+
+- 新增 GateTool：`docs/openzeppelin-integration.md`。
+- 参考：补丁文件、`src/core/preparation/{types,evm}.ts`、`runtime/workflow/steps/{deploy,upgrade,call}.ts`。
+
+任务：
+
+- [x] 逐项核对第 3 节映射；对照源码确认每项实际调用路径，避免把名称相同当成功能等价。
+- [x] 明确本轮代理范围为 UUPS；Transparent 列为独立选项，文档和错误信息一致。
+- [x] 固定三类请求样例：普通 CREATE2、UUPS 首次部署、UUPS 升级；增加初始化、部署后调用和最终 owner 的业务样例。
+- [x] 记录现有官方 OZ 安装文件摘要，作为后续“未被打补丁”的比较基线。
+
+完成标准：每项需要保留的能力都有实际入口、输入、输出和验收用例；不支持的代理类型有明确边界。
+
+### T2：修复 GateTool 自身版本与依赖安装闭环
+
+**优先级：P0。依赖：T1。**
+
+涉及文件：
+
+- 修改 GateTool：`runtime/delivery/setup.ts`、`package.json`、`package-lock.json`。
+- 修改测试：`test/delivery-setup.test.mjs`、`test/integration/delivery-core.test.mjs`。
+- 如需要拆分：新增 `runtime/delivery/toolchain.ts`，只负责读取当前包身份和配套依赖版本。
+
+任务：
+
+- [x] 先增加回归：用当前真实 `.tgz` 初始化 core、显式安装、再次 inspect，不能因旧的 `1.0.29` 固定值被拒绝。
+- [x] 将 GateTool 自身预期版本取自当前安装包身份；其他经过验收的依赖继续精确锁定。
+- [x] 保留显式绝对 `toolPackage` 本地 tarball 能力，检查其实际安装名称、版本及必要 exports。
+- [x] 错配包、缺失依赖、外部路径依赖继续失败；未安装依赖时保持 `dependencies_pending`，不提前导入未就绪文件。
+- [x] 覆盖 setup 重复执行无额外修改，业务注释、网络、参数和生成来源标记保持完整。
+
+完成标准：当前工具包通过真实安装闭环进入 ready；诊断读取与实际运行使用同一个项目中的工具包。
+
+### T3：确定正式 API 边界并补齐能力诊断
+
+**优先级：P0。依赖：T1、T2。**
+
+涉及文件：
+
+- 修改 GateTool：`src/workflow/index.ts`、`src/core/preparation/{types,normalize,index}.ts`、`package.json`。
+- 必要时新增：`runtime/deployment-evm/index.ts`、`runtime/deployment-evm/types.ts`，作为薄的公开适配层。
+- 新增测试：`test/evm-deployment-api.test.mjs`。
+
+任务：
+
+- [x] 继续以 `prepareWorkflow(hre, request)` 作为三类已有请求的准备实现，不复制 CREATE2/OZ 校验逻辑。
+- [x] 检查手写脚本需要的准备、Multicall 组合和结果类型是否已有稳定 export；只有缺少正式入口时才增加 `gate-evm-tools/deployment-evm` 适配层。
+- [x] 公开的组合接口只接收明确的目标、value、calldata 和显式顺序，返回交易描述；不读取私钥，不选择 signer，不发送交易。
+- [x] 对旧私有字段、Transparent 等本轮不支持的请求给出明确错误，不静默忽略、降级或跳过安全校验。
+- [x] 覆盖 CJS、ESM、TypeScript 调用；加入可直接运行的准备请求与返回交易样例。
+
+完成标准：项目脚本可以通过正式 API 完成准备和 calldata 生成；最终执行仍接入现有引擎。
+
+### T4：验证普通部署与 UUPS 对补丁的独立性
+
+**优先级：P0。依赖：T3。**
+
+涉及文件：
+
+- 修改 GateTool：`src/core/preparation/{evm,evmManifestSync,manifest}.ts` 中确认存在的缺口。
+- 关联：`runtime/workflow/steps/{deploy,upgrade}.ts`、`runtime/delivery/{existing-code,compiler,journal}.ts`。
+- 测试：`test/prepare-evm.test.mjs`、`test/evm-manifest-sync.test.mjs`、`test/delivery-existing-code.test.mjs`。
+
+任务：
+
+- [x] 从干净的官方 OZ 包开始验证；不得使用先前已被补丁修改的 `node_modules` 作为验收环境。
+- [x] 验证普通 CREATE2 的构造参数参与 initCodeHash 和预测地址，错误地址策略在发送前失败。
+- [x] 验证 UUPS 实现部署、占位代理、首次升级与初始化；保留当前原子交易结构。
+- [x] 验证后续升级的实现安全、普通 storage layout 和 namespace layout 检查。
+- [x] 验证复用路径：错误实现、错误代理类型、bytecode/布局不匹配不得仅凭地址有代码而通过。
+- [x] 核对 manifest、registry 与 receipt 的事实对应；不把未知创建交易哈希写成全零或使用升级交易冒充创建交易。
+
+完成标准：三个准备路径及其拒绝场景均在无补丁环境成立，真实执行路径能使用同一份准备结果。
+
+### T5：确认部署后调用、owner 与原子交易边界
+
+**优先级：P0。依赖：T4。**
+
+涉及文件：
+
+- 关联 GateTool：`runtime/workflow/lib/{create2,transactionPlanner}.ts`、`runtime/workflow/steps/{deploy,call}.ts`。
+- 关联 delivery：`runtime/delivery/{planning,preparation,journal,identities}.ts`。
+- 新增测试：`test/evm-deployment-batch.test.mjs`。
+
+任务：
+
+- [x] 把旧补丁的 `postDeployCalls` 与 owner 转移转换成明确的计划调用；只补现有组合能力的真实缺口。
+- [x] 分清两类业务调用：必须和部署原子的调用进入同一 Multicall；允许独立执行的调用作为显式后续步骤。
+- [x] 对需要原子性的流程，验证部署、初始化/首次升级、业务设置和 owner 转移的准确顺序。
+- [x] 目标 owner 来自业务参数，区分 sender、管理员、合约 owner 和 Multicall 执行上下文。
+- [x] 检查非零 value、总 value、`aggregate3`/`aggregate3Value` 与 `allowFailure: false`；不沿用旧补丁只支持零 value 的隐含限制。
+- [x] 若新增计划字段，确保规范化、哈希、模拟、锁定、导出、执行、恢复和校验均绑定该字段；不能只改 calldata 生成函数。
+- [x] 验证任一步失败时原子交易回滚，最终 owner/配置断言不通过时不进入可执行发布状态。
+
+完成标准：部署后操作与交付计划一致；导出和真实执行不会使用不同调用序列。
+
+### T6：清理 full 模板中的补丁与安装耦合
+
+**优先级：P0。依赖：T4、T5。**
+
+涉及文件：
+
+- 删除生成器：`templates/full/patches/@openzeppelin+hardhat-upgrades+3.9.1.patch` 及空补丁目录。
+- 修改：`templates/full/{package.json,README.md,AGENTS.md,.gate-template.json}`。
+- 检查：`templates/full/hardhat.config.ts`、`templates/full/test/`、`templates/full/scripts/tasks/`。
+
+任务：
+
+- [x] 删除模板的 `patch-package` 依赖及两个补丁脚本；不删除与本任务无关的项目命令。
+- [x] 将 GateTool 依赖与本次配套包对齐，保留必要 OZ 官方包的精确版本。
+- [x] 检查示例、测试和说明书中是否直接使用旧的 `create2Factory` 私有参数，替换为正式 API/工作流示例。
+- [x] 核对 Hardhat 插件加载顺序，仍在 OZ 加载前完成 manifest 环境选择；避免重复插件注册。
+- [x] full 的 Node 要求对齐 GateTool 的 `>=22.13.0`，修正文档当前的 Node 18 描述。
+- [x] 在 full 来源标记中增加明确的无补丁能力标识，例如 `openzeppelin.unpatched.v1`；保留 full 身份，不冒充 core。
+- [x] core 仍保持基础开发模板，不自动增加 OZ、zkSync、Foundry 或部署安装步骤。
+
+完成标准：带示例和不带示例的新 full 项目都不包含补丁文件、依赖或脚本，现有 core 默认行为不变。
+
+### T7：调整生成器安装流程
+
+**优先级：P0。依赖：T6。**
+
+涉及文件：
+
+- 修改生成器：`src/utils/package.ts`、`src/commands/create.ts`。
+- 修改/替换测试：`test/package-install-security.test.mjs`。
+- 新增测试：`test/package-install.test.mjs`。
+
+任务：
+
+- [x] 删除强制寻找与调用项目本地 `patch-package` 的逻辑及专用 resolver。
+- [x] npm 保留显式 `--ignore-scripts` 的现行安装策略；不以去补丁为由自动开放所有依赖的生命周期脚本。
+- [x] yarn/pnpm 保留其已支持的安装语义；统一检查命令退出结果，不新增兜底 `npx` 下载工具。
+- [x] 为 npm/yarn/pnpm 增加实际进程调用断言：安装成功后不再启动补丁程序。
+- [x] 安装失败不能被输出为“项目已可运行”；脚手架已经写出的情况下明确提示依赖未就绪。
+- [x] Foundry 安装仍为独立动作，保持现有 full 功能，不把它混入 OZ 初始化。
+
+完成标准：没有 `.bin/patch-package` 的新项目能正常安装；安装失败、无效包管理器和缺少可执行文件都有准确状态。
+
+### T8：清理生成器 upgrade 命令的补丁假设
+
+**优先级：P0。依赖：T6、T7。**
+
+涉及文件：
+
+- 修改生成器：`src/commands/upgrade.ts`、`src/utils/upgrade-selection.ts`。
+- 修改测试：`test/{upgrade-dependencies,upgrade-conflicts,packaged-network-upgrade,package-install-security}.test.mjs`。
+
+任务：
+
+- [x] 从升级文件清单移除 `patches/`；从必需依赖清单移除 `patch-package`。
+- [x] 删除强制补丁脚本调和与“补丁应用成功才可完成”的条件，不再要求模板必须提供 `postinstall`。
+- [x] 清理 security-patch pending/fingerprint 状态机；若仍需要安装待完成状态，只记录真实的依赖安装状态，使用与补丁无关的命名。
+- [x] 保留普通文件冲突、依赖冲突、路径/符号链接保护和自定义脚本保护；不把删除补丁机制扩大为删除这些校验。
+- [x] 新版 full 项目更新可执行，`--skip-install` 准确报告依赖待安装，不声称缺少“安全补丁”。
+- [x] 不编写旧补丁项目自动迁移器；检测到旧私有补丁项目时明确拒绝自动转成新能力配置，并提供新建项目指引。
+- [x] 不自动删除用户自定义 `postinstall`、第三方补丁或其他业务文件。
+
+完成标准：新 full 的创建和升级均不依赖补丁机制；遗留项目不会被误报已完成无补丁改造。
+
+### T9：统一版本、构建产物与说明文档
+
+**优先级：P0。依赖：T2—T8。**
+
+涉及文件：
+
+- GateTool：`package.json`、`package-lock.json`、`README.md`、`docs/{workflow-reference,workflow-runtime,delivery-setup,openzeppelin-integration}.md`。
+- 生成器：`package.json`、`package-lock.json`、`README.md`、`templates/full/{package.json,README.md}`。
+- 两仓库的已跟踪 `dist*` 与 runtime identity 由各自正式构建命令生成。
+
+任务：
+
+- [x] 固定配套依赖和包身份；源码删除旧自身版本固定值，测试预期从实际包元数据读取。
+- [x] 建议 GateTool `1.1.0`、生成器 `2.2.0` 作为此变更的待评审版本；不覆盖已公开的旧包版本。
+- [x] 文档列清支持的代理类型、API 输入输出、无签名准备方式、dev/prod 操作和 manifest 归属。
+- [x] 移除“安装会应用 OZ 补丁”“必须保留 postinstall”等过时指引。
+- [x] 增加手写脚本从旧私有参数转用正式准备 API 的新项目示例；不承诺旧脚本无修改运行。
+- [x] 用正式 build 更新编译产物和 runtime identity，不手改生成文件。
+
+完成标准：生成器新项目声明、实际安装包、运行时版本和文档一致，没有版本号互相矛盾。
+
+### T10：成对本地包与无补丁项目验收
+
+**优先级：P0。依赖：T9。**
+
+涉及文件：
+
+- 新增 GateTool：`test/integration/openzeppelin-unpatched.test.mjs`。
+- 新增生成器：`test/packaged-unpatched-full.test.mjs`。
+- 修改生成器：`test/{full-template,direct-package-template,optional-examples}.test.mjs`。
+- 配套夹具放在两个仓库各自的 `test/fixtures/`，不能使用临时机上的绝对工作树 import。
+
+任务：
+
+- [x] 分别构建和 `npm pack` 两个仓库；用实际生成器包创建 full 项目，再显式安装实际 GateTool tarball。
+- [x] 在独立临时目录安装，验收必须解析项目中的工具包与官方 OZ 包，不能靠源码工作树或已打补丁缓存通过。
+- [x] 覆盖 `--template full` 的带示例/无示例、跳过安装/后续安装路径；显式传 `--template full`，避免默认 core 造成假通过。
+- [x] 保存安装前后 OZ 关键文件摘要，确认官方内容没有被修改。
+- [x] 执行编译和项目测试；Foundry 已安装时验证保留的 full 测试；zkSync 做插件加载/相关既有回归，不把 EVM 成功当成 zkSync 已执行验收。
+- [x] 本地链完成：普通 CREATE2、UUPS 初始化、部署后设置与 owner、兼容升级、不兼容升级拒绝、重复部署复用。
+- [x] 分别验证正式 full 的现有 `gate-workflow` 路径和 core 的 `gate-delivery setup` 路径，不混用生成标记或审批协议。
+- [x] 通过现有 prod API，验证已冻结计划的 calldata 导出与本地执行、恢复、最终校验；全程不使用真实生产网络和密钥。
+- [x] 保存包版本、Git SHA、tarball SHA-256、实际执行命令/结果及明确未覆盖项。
+
+完成标准：成对包在新项目中完成无补丁闭环；产物可供后续 App 联调复现。
+
+### T11：独立检查与交付
+
+**优先级：P0。依赖：T10。**
+
+- [x] 对照第 3 节能力矩阵逐条复核结果，记录支持、明确不支持及验收证据。
+- [x] 检查项目产物没有补丁文件、私有参数调用、工具实现副本或安装时修改 OZ 的操作。
+- [x] 检查真实发送交易只发生在已有执行入口，准备/calldata 导出不会广播。
+- [x] 检查改动没有削弱 storage layout、manifest、签名身份、计划冻结和部署后断言。
+- [x] 两仓库分别提交，保留成对本地包与验收记录；是否合并、推送、发布 npm 或替换 App 内包，按后续明确指令执行。
+
+## 6. 阶段顺序与里程碑
+
+```text
+T1 能力边界
+  └─ T2 版本闭环 → T3 正式接口 → T4 无补丁部署/升级 → T5 原子调用与 owner
+                                                     └─ T6 模板清理
+                                                          └─ T7 安装 → T8 upgrade
+                                                                       └─ T9 配套版本/文档
+                                                                            └─ T10 成对包验收
+                                                                                 └─ T11 检查交付
+```
+
+| 里程碑 | 交付标准 |
+| --- | --- |
+| M1：GateTool 可独立承接 | T1—T5 完成，官方 OZ 未修改时准备、执行、升级与原子调用成立 |
+| M2：模板无补丁 | T6—T9 完成，创建/安装/升级不再应用或要求补丁 |
+| M3：可供 App 联调 | T10—T11 完成，两个本地包、哈希、项目夹具和验收记录齐备 |
+
+不能以“文件已删除”代替 M2，也不能以“单元测试通过”代替 M3。
+
+## 7. 验证安排与停止条件
+
+只运行与当前任务相关的验证；没有新改动、失败或未解决问题时，不反复执行相同的大套测试。
+
+建议的分组命令：
+
+```sh
+# 在 EvmGateTools 工作树中
+npm run build
+node --test test/evm-deployment-api.test.mjs test/evm-deployment-batch.test.mjs test/prepare-evm.test.mjs test/evm-manifest-sync.test.mjs
+node --test test/delivery-setup.test.mjs test/delivery-existing-code.test.mjs
+node --test test/integration/delivery-core.test.mjs test/integration/openzeppelin-unpatched.test.mjs
+
+# 在 EvmHardhatCli 工作树中
+npm run build
+node --test test/direct-package-template.test.mjs test/default-core.test.mjs test/core-project.test.mjs
+node --test test/package-install.test.mjs test/upgrade-dependencies.test.mjs test/upgrade-conflicts.test.mjs
+node --test test/packaged-unpatched-full.test.mjs
+```
+
+新增测试文件在所属任务落地后再运行。历史大型 full-template 测试先剔除已经失效的补丁契约断言，再运行受影响的分组；不要通过保留假补丁/空补丁脚本让旧测试表面通过。
+
+每组测试首次发现问题时定位并修复，随后只重跑受影响分组。最终以一次成对包验收验证整合结果；重复打包必须能解释输入变更。所有项目测试基于本地链或只读模拟，不以公开生产链部署作为完成条件。
+
+## 8. 本轮完成标准与交付物
+
+- [x] GateTool 正式接口和既有执行引擎承接第 3 节 P0 能力，官方 OZ 内容保持原样。
+- [x] 新 full 项目无 `patches/`、`patch-package` 依赖/脚本/强制调用；core 仍为干净默认模板。
+- [x] 新 full 文档准确声明 UUPS 支持范围，Transparent 没有被悄悄降级或宣称已支持。
+- [x] GateTool 自身版本来源、模板声明、安装版本和包身份一致，当前 `1.0.29` 固定值问题已解决。
+- [x] 产生两个本地 `.tgz`、各自 SHA-256、源码提交、机器可读配套清单及本地验收日志。
+- [x] 留下 API/CLI 示例与新项目操作说明，能从业务代码完成后开始生成实际部署计划。
+- [x] 不把此次模板/API 清理描述为 App 内 LLM、Keychain 或真实生产链已完成验收。
+
+## 9. 可选扩展：Transparent Proxy 完整支持
+
+这是范围确认项，默认不并入 P0。它会明显扩大代理协议、执行、登记和恢复的修改面。如果要求保留旧补丁的全部代理类型能力，应把下列任务作为删除补丁前的额外验收门槛，而不是只复制补丁中的 Transparent 分支。
+
+### P1-A：请求与交易准备
+
+- 在 `src/core/preparation/{types,normalize,evm}.ts` 增加明确的 Transparent 初次部署、升级协议和结果类型。
+- 按实际采用的 OZ 5.4.0 `TransparentUpgradeableProxy`/`ProxyAdmin` ABI 和 artifact 编码构造与升级交易。
+- 区分 initial owner、ProxyAdmin 合约地址、ProxyAdmin owner、代理业务 owner 和实际执行人。
+- 把编译/官方安全校验、构造参数、预测地址、升级调用及所有权证据写进准备结果。
+
+### P1-B：执行、权限与记录
+
+- 修改 UUPS 固定分支涉及的 workflow、delivery 校验、journal、compiler evidence、existing-code 和生产最终校验。
+- 为 Transparent 记录正确 proxy kind、实现与 admin 关系，完成 manifest、registry、CheckCode 和恢复语义。
+- 生成发往实际 ProxyAdmin 的交易；有权限的执行人与无权限的 calldata 导出使用同一个冻结计划。
+- 不复用 UUPS 的 `upgradeToAndCall` 交易或占位代理假设。
+
+### P1-C：成对包验收
+
+- 本地链完成首次部署、初始化、兼容升级、owner 交接、重复运行与恢复。
+- 错误 ProxyAdmin、错误 owner、不兼容布局、错误代理类型和复用不匹配均被拒绝。
+- 实测 calldata 导出的目标是正确的 ProxyAdmin，接收者可按已有计划执行，不重新提供业务参数。
+- 完成后才更新模板能力声明和文档中的代理支持矩阵。
+
+## 10. 评审时需确认的范围选择
+
+1. **建议本轮采用 P0：普通 CREATE2 + UUPS 完成去补丁收口。** Transparent 如有实际项目需求，再执行第 9 节；不能把它计入本轮已支持能力。
+2. **建议直接切换新项目 API，不兼容旧 OZ 私有参数。** 原有项目不自动重写、不自动删除个人补丁。
+3. **建议先交付成对本地包，再做 App 联调。** 包版本建议为 GateTool `1.1.0`、生成器 `2.2.0`；发布动作和 App 内工具链替换另行明确。
+
+用户已确认本轮 P0 范围，T1—T11 按顺序实施；实际状态以任务勾选与验收记录为准。此计划不触发 npm 发布或远程合并。
+
+## 11. 本轮验收记录
+
+T1—T11 按序实现，配套版本为 GateTool `1.1.0` / 生成器 `2.2.0`。
+详见 [无补丁验收记录](../openzeppelin-acceptance.md) 和产物目录的 `pair-manifest.json`。
+full 带/不带示例均通过独立安装与真实 workflow engine；core setup/dev/release/prod
+实际本地链闭环通过。prod 两笔交易在回执丢失和文件中断后恢复，未增加签名或广播。
+
+生成器历史大型源码复制测试未全量通过，具体数量、原因与受影响分组的验证结果已在验收记录单独披露；
+不将其描述为整套测试通过。Transparent、App 内 LLM/Keychain、公开生产链、npm 发布与远程推送/合并均未执行。

package/docs/plans/2026-11-02-transparent-proxy-delivery.md

@@ -0,0 +1,78 @@
+# Transparent / ProxyAdmin delivery support
+
+## Scope
+
+New ordinary EVM projects using the locked OpenZeppelin Contracts 5 toolchain.
+Keep full free of patches and private OpenZeppelin options. Preserve the UUPS
+and zkSync paths. Business ownership and ProxyAdmin ownership are explicit,
+separate business inputs completed by the developer before prod release freeze.
+Production operators consume frozen inputs and supply only execution identity.
+
+## Ordered work
+
+- [x] T1. Add explicit transparent deployment/upgrade preparation requests and
+  canonical plans. Bind implementation/proxy constructor calldata, derived
+  ProxyAdmin address, admin owner, official safety/storage checks and reuse.
+- [x] T2. Connect native workflow steps and delivery semantic/journal/compiler
+  checks. Include same-fork deployment followed by upgrade and external routing.
+- [x] T3. Register and reconcile transparent implementations, proxies and admin
+  identities in manifests/metadata. Extend CheckCode, dev acceptance and prod
+  finalization/history checks without weakening UUPS evidence.
+- [x] T4. Document the capability in deployment skill and tool instructions;
+  keep template defaults and official OpenZeppelin packages unchanged.
+- [x] T5. Build and run targeted regressions plus isolated local-chain
+  deployment, initialization, upgrade, calldata and rejection verification.
+
+## Acceptance
+
+CREATE2 prediction includes the official OZ 5 transparent proxy constructor.
+Its internally created ProxyAdmin is verified at the deterministic CREATE
+address and its owner is verified independently of the business owner. Upgrades
+target ProxyAdmin, retain original proxy address, validate the current registered
+implementation/layout and bind the expected admin identity. Wrong admin/owner,
+unsafe implementation/layout, mismatched runtime and unsupported chain scheme
+fail before execution. No package lifecycle patches or public-chain broadcasts.
+
+## Evidence
+
+Task baseline and isolated verification artifacts:
+`/Users/vector/gate/.artifacts/transparent-proxy-support/`.
+Existing dirty worktree changes are preserved. Local package publication/App
+staging are separate from source implementation and validation.
+
+## Verified results
+
+- TypeScript ESM/CJS/runtime builds pass.
+- Installed official packages on a disposable chain: CREATE2 constructor binding,
+  separate business/admin ownership, compatible upgrade and state retention,
+  incompatible layout refusal, wrong admin/owner/runtime refusal, reuse, workflow
+  manifest sync and external upgrade routing all pass. Official OZ file hashes
+  remain unchanged; original UUPS acceptance also passes.
+- Full template two-target qualification passes.
+- Full Transparent development delivery passes with deploy → same-fork upgrade →
+  configure, 4 transactions, 3 business assertions, implementation/proxy/admin
+  CheckCode and file-only recovery without duplicate signatures.
+- Static production finalizer rejects admin slot/immutable/owner/runtime drift
+  at the finalized block. Deployment skill validation passes.
+- Final production preparation now consumes the released qualification's
+  derivationSeed while retaining the new executionId. This fixes same-fork
+  compiler-closure drift without removing any baseline or hash check.
+- Full production release/export/execution/recovery passes: 4 transactions,
+  exactly 4 signatures and 4 broadcasts, 3 business assertions; release marker
+  interruption, lost broadcast response and finalization file interruption all
+  recover, repeated verification does not resend. Calldata export runs without a
+  signer or a new block, includes all 4 transactions and matches the locked plan.
+- Targeted regression: 236 tests pass; sibling-fixture zkSync regression: 8 pass.
+  Skill validation and whitespace checks pass. No project template or official
+  OZ payload change was needed for this capability.
+
+Evidence summary: `acceptance-summary.json`; production evidence:
+`local-production-acceptance.json`, `local-production-export.json`,
+`local-production-raw.json` under the evidence directory above. The local node
+was stopped after acceptance. Source changes remain uncommitted; npm publication
+and replacement of the App-owned packages were not performed.
+
+The two older zkSync tests reference a sibling `contract-tools` checkout. For
+this worktree verification only, a temporary sibling symlink was created and
+removed after the tests. No production fixture or repository source was changed
+for that accommodation.

package/docs/superpowers/plans/2026-08-17-custody-hardhat-signers.md

@@ -135,7 +135,7 @@ Run the focused test. Expected: FAIL because `installCustodyHardhatRuntime` does
 
 - [ ] **Step 3: Implement runtime installation and plugin registration**
 
-Expose a pure testable installer and register it through `extendEnvironment`. Read `WALLET_CREDENTIAL` or legacy `PRIVATE_KEY` only when signer helpers execute, cache by credential, require `CUSTODY_API_BASE_URL`, and never change impersonated signers.
+Expose a pure testable installer and register it through `extendEnvironment`. Read `PRIVATE_KEY` only when signer helpers execute, cache by credential, require `CUSTODY_API_BASE_URL`, and never change impersonated signers.
 
 - [ ] **Step 4: Verify GREEN**
 

package/docs/workflow-reference.md

@@ -1,3 +1,5 @@
+> 历史文档：其中的 gate-workflow 命令已移除。新项目使用 gate-tool delivery 与 delivery API，见 [部署接入](delivery-setup.md)。
+
 # Full EVM workflow reference
 
 Reference for the full EVM template and GateTool task-based deployment workflow.
@@ -90,8 +92,7 @@ CUSTODY_API_BASE_URL=https://custody.example.com
 `CUSTODY_API_BASE_URL` must be an HTTP(S) base URL without embedded
 credentials, query parameters, or fragments.
 
-`WALLET_CREDENTIAL` is an optional alias for `PRIVATE_KEY`. If both variables
-are configured, they must contain the same value. `hardhat.config.ts` loads the
+`PRIVATE_KEY` is the only wallet credential environment variable. `hardhat.config.ts` loads the
 custody plugin after the ethers and OpenZeppelin plugins. A real private key is
 passed through native `networks.accounts`; a custody credential leaves native
 accounts empty and supplies the remote signer through Hardhat and the workflow
@@ -285,7 +286,7 @@ npm run workflow -- \
 `--network` to Hardhat and passes workflow arguments such as `--task`, `--mode`,
 `--target`, `--step`, `--from`, `--simulationSigner`, and `--operator` to the runtime.
 For `--mode execute` on real configured networks, the runtime fails early when
-neither `WALLET_CREDENTIAL` nor `PRIVATE_KEY` is present in the project `.env`
+`PRIVATE_KEY` is absent or empty in the project `.env`
 or process environment.
 Every target whose `environment` is `production` additionally requires
 `--useLock`; a production execute without the immutable final-simulation plan
@@ -710,7 +711,7 @@ acceptance requirement.
 signer setup. The tracked `rpc.env` file provides the shared `BASE_RPC_URI` for
 the project; SmartFlow may populate its initially empty value once when it
 creates a new internal project. `.env` remains untracked and only provides
-`WALLET_CREDENTIAL`/`PRIVATE_KEY`, `CUSTODY_API_BASE_URL`, and the optional full
+`PRIVATE_KEY`, `CUSTODY_API_BASE_URL`, and the optional full
 `ZKSYNC_RPC_URL`.
 
 Each remote network declares `route`, `publicFallback`, and `useBaseRpc`
@@ -1179,3 +1180,10 @@ Workflow implementations are provided by `gate-evm-tools`; npm scripts invoke th
 `npx --no-install gate-workflow --help` exposes compiled workflow commands without a manual ts-node preload. Existing npm commands remain supported. Before upgrading an existing task, finish it with the original runtime or reconcile it and prepare a new execution ID; execution bindings reject a different package build. `gate-workflow migrate` previews removal of recognized baseline files and shims; `--apply` backs up originals, updates known commands/imports and removes known runtime scripts; customized files or unresolved references require manual review. It does not change business data or install dependencies.
 
 Network declarations live directly in `hardhat.config.ts` under its single `networks` block. Edit names, chain IDs, RPC routes/fallbacks and zkSync flags there; do not create a second network list. `createNetworkHelpers` from `gate-evm-tools/runtime-config/networks` supplies only account/RPC/fork mechanics. Add `rpcUrl: process.env.BSC_DEV_RPC_URL` to one `remoteNetwork({ ... })` entry to override its RPC, or spread that entry into `{ ...remoteNetwork({ ... }), timeout: 60000 }` for other Hardhat fields. Load rpc.env/.env before creating the helpers. Dev/Prod represent business environments, not testnet/mainnet. Compiler versions/settings remain project-owned; overlay migration merges the network block and keeps the original toolchain. The deprecated `createTemplateNetworks` export remains for older generated projects only and is not called by the current template.
+
+### Official unpatched OpenZeppelin
+
+CREATE2 / UUPS use GateTool preparation and explicit planned calls, not private
+OpenZeppelin deployProxy options. Transparent/ProxyAdmin is unsupported here.
+See [OpenZeppelin integration](openzeppelin-integration.md) for script API,
+atomic initialization, explicit ownership and prod calldata boundaries.

package/docs/workflow-runtime.md

@@ -1,3 +1,5 @@
+> 历史文档：其中的 gate-workflow 命令已移除。新项目使用 gate-tool delivery 与 delivery API，见 [部署接入](delivery-setup.md)。
+
 # Packaged workflow runtime (local preview)
 
 GateTool owns the full-template workflow implementation. New templates have no `scripts/workflow` or `scripts/config` forwarding directory: npm scripts call `gate-workflow`, and Hardhat/tests import package exports directly. Existing npm command names remain supported. Contracts, config.yaml/config.json, rpc.env, task YAML, salts, business scripts and result files remain project-owned. Compiler settings and deployment/vanity behavior are unchanged.
@@ -54,3 +56,7 @@ Register `registerZkSyncSolcAdapter(subtask, TASK_COMPILE_SOLIDITY_RUN_SOLC)` wi
 The RPC resolver and zkSync solc PATH adapter are also exported under `runtime-config/rpc` and `runtime-config/zksyncSolcPath`; new templates import these exports directly. Migration now recognizes 72 baseline helper/workflow files. Migration rewrites recognized Hardhat imports but preserves compiler/settings/overrides. Merge new helper calls into older inline configs separately while retaining the old toolchain for overlay projects. Network infrastructure/config.yaml profiles and business data stay project-owned.
 
 After this one-time migration, compatible runtime upgrades require updating the exact GateTool dependency and existing lockfile, without copying workflow scripts. Breaking configuration/API changes still require their documented migration. Finish active execution bindings on their original build before upgrading.
+
+`gate-evm-tools/deployment-evm` exposes signer-free preparation/composition over
+the same workflow engine. Official OZ packages remain unchanged; the proxy
+workflow supports UUPS. See [OpenZeppelin integration](openzeppelin-integration.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gate-evm-tools",
-  "version": "1.0.31",
+  "version": "1.2.0",
   "description": "Gate 智能合约工具集 - 字节码检查、合约升级验证、合约状态同步",
   "type": "module",
   "exports": {
@@ -62,6 +62,14 @@
       "types": "./dist-runtime/delivery/inputs.d.ts",
       "default": "./dist-runtime/delivery/inputs.js"
     },
+    "./delivery-task": {
+      "types": "./dist-runtime/delivery/task-identity.d.ts",
+      "default": "./dist-runtime/delivery/task-identity.js"
+    },
+    "./delivery-calldata": {
+      "types": "./dist-runtime/delivery/public-calldata.d.ts",
+      "default": "./dist-runtime/delivery/public-calldata.js"
+    },
     "./delivery-configuration": {
       "types": "./dist-runtime/delivery/configuration.d.ts",
       "default": "./dist-runtime/delivery/configuration.js"
@@ -101,6 +109,11 @@
     "./create2-miner": {
       "types": "./dist-runtime/miner/index.d.ts",
       "default": "./dist-runtime/miner/index.js"
+    },
+    "./deployment-evm": {
+      "types": "./dist/deployment-evm/index.d.ts",
+      "import": "./dist/deployment-evm/index.js",
+      "require": "./dist-cjs/deployment-evm/index.js"
     }
   },
   "typesVersions": {
@@ -173,13 +186,14 @@
       ],
       "create2-miner": [
         "dist-runtime/miner/index.d.ts"
+      ],
+      "deployment-evm": [
+        "dist/deployment-evm/index.d.ts"
       ]
     }
   },
   "bin": {
-    "gate-tool": "./bin/cli.js",
-    "gate-workflow": "./bin/workflow.cjs",
-    "gate-delivery": "./bin/delivery.cjs"
+    "gate-tool": "./bin/cli.js"
   },
   "files": [
     "bin/",
@@ -199,7 +213,7 @@
     "pretest": "npm run build",
     "test": "node --test test/*.test.mjs",
     "test:custody:hardhat-v6": "npm run build && node scripts/test-custody-hardhat-v6.mjs",
-    "test:delivery:core": "npm run build && node --test test/integration/delivery-core.test.mjs"
+    "test:delivery:evm": "npm run build && node --test test/integration/delivery-evm.test.mjs"
   },
   "keywords": [
     "bytecode",

package/runtime/config/hardhatAdapters.ts

@@ -53,6 +53,7 @@ export function withTemplateArtifactPaths(config: HardhatUserConfig, argv: strin
 export function registerWorkflowDependencyCompiler(subtask: typeof import("hardhat/config").subtask, taskName: string): void {
   subtask(taskName).setAction(async (args, _hre, runSuper) => {
     const sourceNames: string[] = await runSuper(args);
-    return [...new Set([...sourceNames, "@openzeppelin/contracts/proxy/ERC1967/ERC1967Proxy.sol"])];
+    return [...new Set([...sourceNames, "@openzeppelin/contracts/proxy/ERC1967/ERC1967Proxy.sol",
+      ...((_hre.network.config as {zksync?:boolean}).zksync === true ? [] : ["@openzeppelin/contracts/proxy/transparent/TransparentUpgradeableProxy.sol"])])];
   });
 }

package/runtime/delivery/aggregate-bootstrap.ts

@@ -16,7 +16,9 @@ export function registerOwnedFork(extendConfig:typeof import('hardhat/config').e
   extendConfig(config=>{
     if(config.networks[fork!.network]?.chainId!==fork!.chainId)throw new Error('Owned fork target chain mismatch');
     policies.set(config,config.networks.hardhat);
-    config.networks.hardhat={...config.networks.hardhat,chainId:fork!.chainId,
+    // Only the explicitly selected simulation operator is impersonated later. Avoid
+    // hydrating Hardhat's unrelated default wallets from the historical source RPC.
+    config.networks.hardhat={...config.networks.hardhat,chainId:fork!.chainId,accounts:[],
       forking:{enabled:true,url:fork!.url,blockNumber:fork!.blockNumber,httpHeaders:{}}};
   });
 }