gate-evm-tools 1.0.20 → 1.0.22

package/README.md

@@ -228,6 +228,31 @@ npx gate-tool check --output ./reports/result.json
 
 当合约通过 calldata 方式由其他人（如多签钱包）执行升级后，本地的 `.openzeppelin` 文件不会自动更新。使用此命令可以从链上读取最新状态并更新本地文件。
 
+`sync` 和 `validate` 会在加载 OpenZeppelin upgrades 之前确定 manifest 目录。约定路由如下：
+
+| 网络名 | Manifest 目录 | 含义 |
+|------|------|------|
+| `bscDev` 等以 `Dev` 结尾的网络 | `.openzeppelin.dev` | development 发布阶段 |
+| `bscProd` 等以 `Prod` 结尾的网络 | `.openzeppelin` | production 发布阶段 |
+| 其他远程网络 | 显式 `MANIFEST_DEFAULT_DIR` | 项目根目录下单层 `.openzeppelin.<name>` |
+
+Dev/Prod 可以使用同一个 chainId 和 RPC，但代表两套独立合约状态。其他自定义网络必须显式设置安全的项目内目录，例如：
+
+```bash
+MANIFEST_DEFAULT_DIR=.openzeppelin.sepolia \
+npx gate-tool sync --proxy 0x1234... --contract CounterUUPS --network sepolia
+```
+
+`--network` 和 `-n` 都会在加载 command tree 前参与路由；自动化和迁移脚本建议始终使用完整的 `--network`。本地 `hardhat`、`localhost`、`local`、`anvil` 的 manifest 写入不支持：OpenZeppelin 会把 ephemeral development manifest 固定放到系统临时目录，所以 `sync`/`validate` 会明确拒绝，而不是声称写入某个项目内目录。
+
+如果约定目录与 `MANIFEST_DEFAULT_DIR` 冲突、目录不明确、路径越界或经过符号链接，写 manifest 的命令会 fail closed，不会继续执行。
+
+`sync` 和 `validate` 对同一 canonical manifest 使用同一把 gate-tool 锁。事务同时快照 canonical 文件与 OpenZeppelin fallback（如 `unknown-{chainId}.json`）；若两者同时存在会在写入前拒绝，若 OpenZeppelin 把 fallback 移到 canonical 后流程失败，则按原始文件名和原始字节完整回滚。
+
+`sync` 自己的补充写入使用原子替换。结果、精确 before/after 文件名和 hash 写入项目根目录的 per-manifest 报告，例如 development BSC 为 `gate-tool-sync-report.openzeppelin.dev.bsc.json`，production BSC 为 `gate-tool-sync-report.openzeppelin.bsc.json`。返回值中的 `syncReport` 是本次报告的权威路径；不要假设一个由 Dev/Prod 共享的固定报告名。
+
+最新 full 模版项目优先使用 `workflow:checkcode` 做只读验收，由模版负责选择精确的 manifest 文件并调用 gate-tool。
+
 ```bash
 # 同步合约状态
 npx gate-tool sync \

package/bin/cli.js

@@ -1,9 +1,13 @@
 #!/usr/bin/env node
 
-import('../dist/index.js').then(module => {
-  module.run();
+import { prepareManifestEnvironment } from './manifest-bootstrap.js';
+
+Promise.resolve().then(() => {
+  prepareManifestEnvironment();
+  return import('../dist/index.js');
+}).then(module => {
+  return module.run();
 }).catch(err => {
   console.error('Failed to start CLI:', err);
   process.exit(1);
 });
-

package/bin/manifest-bootstrap.js

@@ -0,0 +1,88 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const MANIFEST_MUTATING_COMMANDS = new Set(['sync', 'validate']);
+const SAFE_MANIFEST_DIR = /^\.openzeppelin(?:\.[a-z0-9][a-z0-9-]*)?$/;
+
+const argumentValue = (argv, name) => {
+  for (let index = 2; index < argv.length; index += 1) {
+    const value = argv[index];
+    if (value === name) return argv[index + 1];
+    if (value.startsWith(`${name}=`)) return value.slice(name.length + 1);
+  }
+  return undefined;
+};
+
+const commandName = (argv) => argv.slice(2).find((value) => !value.startsWith('-'));
+
+const conventionalManifestDir = (network) => {
+  if (!network) return undefined;
+  if (/prod$/i.test(network)) return '.openzeppelin';
+  if (/dev$/i.test(network)) return '.openzeppelin.dev';
+  return undefined;
+};
+
+const isLocalDevelopmentNetwork = (network) => (
+  /^(hardhat|localhost|local|anvil)$/i.test(network || '')
+);
+
+const assertConfinedManifestDirectory = (cwd, manifestDir) => {
+  if (!SAFE_MANIFEST_DIR.test(manifestDir)) {
+    throw new Error(`Unsafe MANIFEST_DEFAULT_DIR: ${manifestDir}`);
+  }
+  const projectRoot = path.resolve(cwd);
+  const candidate = path.resolve(projectRoot, manifestDir);
+  if (path.dirname(candidate) !== projectRoot) {
+    throw new Error(`Manifest directory escapes the project: ${manifestDir}`);
+  }
+  if (fs.existsSync(candidate)) {
+    const stat = fs.lstatSync(candidate);
+    if (stat.isSymbolicLink()) {
+      throw new Error(`Manifest directory cannot be a symlink: ${manifestDir}`);
+    }
+    if (!stat.isDirectory()) {
+      throw new Error(`Manifest path must be a directory: ${manifestDir}`);
+    }
+  }
+};
+
+export const resolveManifestBootstrap = ({
+  argv = process.argv,
+  env = process.env,
+  cwd = process.cwd(),
+} = {}) => {
+  const command = commandName(argv);
+  const network = (
+    argumentValue(argv, '--network') ?? argumentValue(argv, '-n')
+  )?.trim();
+  const mutatesManifest = MANIFEST_MUTATING_COMMANDS.has(command);
+  if (mutatesManifest && isLocalDevelopmentNetwork(network)) {
+    throw new Error(
+      `Local development manifest mutation is unsupported for ${network}: `
+      + 'OpenZeppelin stores ephemeral development manifests outside the project',
+    );
+  }
+  const conventional = conventionalManifestDir(network);
+  const configured = env.MANIFEST_DEFAULT_DIR?.trim();
+  if (configured && conventional && configured !== conventional) {
+    throw new Error(
+      `MANIFEST_DEFAULT_DIR conflict for ${network}: expected ${conventional}, received ${configured}`,
+    );
+  }
+  const manifestDir = configured || conventional;
+  if (mutatesManifest && !manifestDir) {
+    throw new Error(
+      `Cannot resolve OpenZeppelin manifest directory for network ${network || '<missing>'}; `
+      + 'set MANIFEST_DEFAULT_DIR explicitly',
+    );
+  }
+  if (manifestDir) assertConfinedManifestDirectory(cwd, manifestDir);
+  return { command, network, manifestDir, mutatesManifest };
+};
+
+export const prepareManifestEnvironment = (options = {}) => {
+  const env = options.env ?? process.env;
+  const resolved = resolveManifestBootstrap({ ...options, env });
+  if (resolved.manifestDir) env.MANIFEST_DEFAULT_DIR = resolved.manifestDir;
+  return resolved;
+};

package/dist/commands/check.js

@@ -3,7 +3,7 @@ import ora from 'ora';
 import prompts from 'prompts';
 import { findConfigFile, readConfigFile, saveReport, mergeReports } from '../utils/files.js';
 import { printSummary, printProgress, printConfig } from '../utils/output.js';
-import { BytecodeChecker } from '../core/bytecodeChecker.js';
+import { BytecodeChecker } from '../core/BytecodeChecker.js';
 import { isHardhatConfigImportError, detectAndFixWithPrompt, showManualFixGuide } from '../utils/configFixer.js';
 import fs from 'fs-extra';
 import path from 'path';

package/dist/core/{bytecodeChecker.d.ts → BytecodeChecker.d.ts}

@@ -3,16 +3,13 @@ type HardhatRuntimeEnvironment = any;
 interface LocalBytecodeData {
     bytecode: string;
     abi: any[];
+    immutableReferences: ImmutableReferences;
 }
-interface ConstructorInput {
-    type: string;
-    name: string;
-    inputs?: ConstructorInput[];
-}
-interface Constructor {
-    type: string;
-    inputs: ConstructorInput[];
+interface ImmutableReference {
+    start: number;
+    length: number;
 }
+type ImmutableReferences = Record<string, ImmutableReference[]>;
 interface LibraryLinkInfo {
     placeholder: string;
     position: number;
@@ -21,15 +18,8 @@ interface LibraryLinkInfo {
 interface ComparisonResult {
     matches: boolean;
     reason: string;
-    constructorDetails?: any[];
     libraryLinks?: LibraryLinkInfo[];
 }
-interface ConstructorCheckResult {
-    isConstructorDiff: boolean;
-    reason: string;
-    differences?: any[];
-    diffCount?: number;
-}
 export declare class BytecodeChecker {
     private hre;
     private addressData;
@@ -61,37 +51,11 @@ export declare class BytecodeChecker {
      */
     private getProxyLocalBytecode;
     /**
-     * 检查是否是constructor参数差异（主要是immutable变量）
-     */
-    checkConstructorParamsDifference(onchainCode: string, localCode: string, abi?: any[] | null): ConstructorCheckResult;
-    /**
-     * 基于ABI的智能分析
+     * 使用 artifact 的 fully-qualified identity 读取编译器生成的 immutableReferences。
+     * build-info 缺失时保留空引用，使完全一致的 bytecode 仍可通过；一旦存在差异，
+     * compareBytecode 会按 fail-closed 规则拒绝缺少编译器证据的匹配。
      */
-    smartAnalyzeWithABI(onchainCode: string, localCode: string, abi: any[]): ConstructorCheckResult;
-    /**
-     * 检测immutable变量
-     */
-    detectImmutableVariables(onchainCode: string, localCode: string): ConstructorCheckResult;
-    /**
-     * 检测constructor参数
-     */
-    detectConstructorParams(onchainCode: string, localCode: string, constructor: Constructor): ConstructorCheckResult;
-    /**
-     * 去重参数：按顺序匹配参数
-     */
-    deduplicateParams(allMatches: any[], params: ConstructorInput[]): any[];
-    /**
-     * 查找地址参数
-     */
-    findAddressParams(onchainCode: string, localCode: string, param: ConstructorInput): any[];
-    /**
-     * 查找数值参数
-     */
-    findUintParams(onchainCode: string, localCode: string, param: ConstructorInput): any[];
-    /**
-     * 回退分析方法
-     */
-    fallbackAnalyze(onchainCode: string, localCode: string): ConstructorCheckResult;
+    private getArtifactLocalBytecode;
     /**
      * 标准化bytecode（移除metadata）
      */
@@ -129,10 +93,14 @@ export declare class BytecodeChecker {
         local: string;
         selfAddress: string;
     } | null;
+    /**
+     * 只屏蔽编译器声明的 immutable 区间，并比较其余 runtime bytecode。
+     */
+    private compareWithImmutableReferences;
     /**
      * 比较两个bytecode
      */
-    compareBytecode(onchainBytecode: string, localBytecode: string, abi?: any[] | null): ComparisonResult;
+    compareBytecode(onchainBytecode: string, localBytecode: string, _abi?: any[] | null, immutableReferences?: ImmutableReferences): ComparisonResult;
     /**
      * 检查单个合约
      *
@@ -162,4 +130,4 @@ export declare class BytecodeChecker {
     generateNetworkContractResults(results: CheckResult[]): Record<string, Record<string, any>>;
 }
 export {};
-//# sourceMappingURL=bytecodeChecker.d.ts.map
+//# sourceMappingURL=BytecodeChecker.d.ts.map

package/dist/core/BytecodeChecker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BytecodeChecker.d.ts","sourceRoot":"","sources":["../../src/core/BytecodeChecker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1D,KAAK,yBAAyB,GAAG,GAAG,CAAC;AAErC,UAAU,iBAAiB;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,GAAG,EAAE,CAAC;IACX,mBAAmB,EAAE,mBAAmB,CAAC;CAC1C;AAED,UAAU,kBAAkB;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,KAAK,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,kBAAkB,EAAE,CAAC,CAAC;AAEhE,UAAU,eAAe;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,UAAU,gBAAgB;IACxB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,eAAe,EAAE,CAAC;CAClC;AAED,qBAAa,eAAe;IAC1B,OAAO,CAAC,GAAG,CAA4B;IACvC,OAAO,CAAC,WAAW,CAAiB;gBAExB,GAAG,EAAE,yBAAyB,EAAE,WAAW,EAAE,cAAc;IAKvE;;;;;;;;;OASG;IACH,OAAO,CAAC,iBAAiB;IAuBzB;;OAEG;IACG,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAgB3E;;;;OAIG;IACG,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAaxE;;;OAGG;YACW,qBAAqB;IAWnC;;;;OAIG;YACW,wBAAwB;IAsCtC;;OAEG;IACH,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAiB3C;;;;;;;;OAQG;IACH,4BAA4B,CAC1B,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,GAChB;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,eAAe,EAAE,CAAA;KAAE;IAqCtE;;;;;;;;;;;;;OAaG;IACH,2BAA2B,CACzB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,GAChB;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAmBjE;;OAEG;IACH,OAAO,CAAC,8BAA8B;IAoHtC;;OAEG;IACH,eAAe,CACb,eAAe,EAAE,MAAM,EACvB,aAAa,EAAE,MAAM,EACrB,IAAI,GAAE,GAAG,EAAE,GAAG,IAAW,EACzB,mBAAmB,GAAE,mBAAwB,GAC5C,gBAAgB;IA6DnB;;;;;OAKG;IACG,aAAa,CAAC,YAAY,EAAE;QAChC,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;KACjB,GAAG,OAAO,CAAC,WAAW,CAAC;IAuDxB;;OAEG;IACG,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAsBxE;;OAEG;IACG,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAuBzE;;OAEG;IACG,iBAAiB,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAejD;;OAEG;IACH,8BAA8B,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CA4B5F"}