gate-evm-tools 1.0.21 → 1.0.23

package/README.md

@@ -163,6 +163,53 @@ module.exports = {
 };
 ```
 
+#### 托管钱包 Signer（ethers v5 / v6）
+
+`gate-evm-tools` 支持把真实私钥和托管钱包统一放在同一个配置项中：
+
+```text
+# 真实私钥
+PRIVATE_KEY=0x...
+
+# 或托管钱包凭证
+PRIVATE_KEY=custody:<ProjectSecret>:<WalletAddress>
+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` 代替 `PRIVATE_KEY`。如果两个变量同时存在，值必须一致，否则会拒绝启动，避免误用账户。
+
+Hardhat 配置需要在 ethers 和 OpenZeppelin 插件之后加载托管插件，并用 `resolveHardhatAccounts` 处理网络账户：
+
+```typescript
+import "@nomicfoundation/hardhat-ethers";
+import "@openzeppelin/hardhat-upgrades";
+import "gate-evm-tools/hardhat";
+import { resolveHardhatAccounts } from "gate-evm-tools/hardhat";
+
+const walletCredential =
+  process.env.WALLET_CREDENTIAL ?? process.env.PRIVATE_KEY ?? "";
+
+export default {
+  networks: {
+    sepolia: {
+      url: process.env.SEPOLIA_RPC_URL,
+      accounts: resolveHardhatAccounts(walletCredential),
+    },
+  },
+};
+```
+
+- 真实私钥返回给原生 `networks.accounts`，部署行为保持不变。
+- 托管凭证让原生 accounts 保持为空，并自动替换 `ethers.getSigners()`、匹配地址的 `ethers.getSigner()` 和 `ethers.provider.getSigner(0)`。
+- 实际 ethers 主版本取自 `hre.ethers.version`；v5 使用运行时 `Signer`，v6 使用运行时 `AbstractSigner`，包内不会固定加载某个 ethers 版本。
+- 业务部署脚本无需传入额外 signer；`ethers.getContractFactory()`、`deployContract()` 和 `upgrades.deployProxy()` 会取得托管 signer。
+- 完整托管凭证通过 Bearer 发送，服务端拆解 Project Secret 与绑定钱包地址；凭证不会写入日志，每次签名请求都会生成独立的 `Idempotency-Key`。
+
+托管服务只返回签名或 raw transaction，不负责广播。交易最终仍由当前 Hardhat ethers Provider 广播。现有 OpenZeppelin CREATE2/Multicall 补丁与 signer 注入是两套独立能力，升级项目应继续保留原补丁。
+
 ### 4. 编译合约
 
 ```bash

package/dist/core/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;
     /**
      * 检查单个合约
      *

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

@@ -1 +1 @@
-{"version":3,"file":"BytecodeChecker.d.ts","sourceRoot":"","sources":["../../src/core/BytecodeChecker.ts"],"names":[],"mappings":"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"}
+{"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"}

package/dist/core/BytecodeChecker.js

@@ -62,11 +62,7 @@ export class BytecodeChecker {
             if (contractName.endsWith('::Proxy')) {
                 return await this.getProxyLocalBytecode();
             }
-            const artifact = await this.hre.artifacts.readArtifact(contractName);
-            return {
-                bytecode: artifact.deployedBytecode,
-                abi: artifact.abi
-            };
+            return await this.getArtifactLocalBytecode(contractName);
         }
         catch (error) {
             throw new Error(`Failed to get local bytecode: ${error.message}`);
@@ -78,11 +74,7 @@ export class BytecodeChecker {
      */
     async getProxyLocalBytecode() {
         try {
-            const artifact = await this.hre.artifacts.readArtifact('ERC1967Proxy');
-            return {
-                bytecode: artifact.deployedBytecode,
-                abi: artifact.abi
-            };
+            return await this.getArtifactLocalBytecode('ERC1967Proxy');
         }
         catch (error) {
             throw new Error(`无法找到 ERC1967Proxy 的本地 artifact。\n` +
@@ -90,225 +82,38 @@ export class BytecodeChecker {
         }
     }
     /**
-     * 检查是否是constructor参数差异（主要是immutable变量）
-     */
-    checkConstructorParamsDifference(onchainCode, localCode, abi = null) {
-        if (onchainCode.length !== localCode.length) {
-            return { isConstructorDiff: false, reason: "长度不同" };
-        }
-        if (onchainCode === localCode) {
-            return { isConstructorDiff: false, reason: "完全相同" };
-        }
-        if (abi) {
-            const smartAnalysis = this.smartAnalyzeWithABI(onchainCode, localCode, abi);
-            if (smartAnalysis.isConstructorDiff) {
-                return smartAnalysis;
-            }
-        }
-        return this.fallbackAnalyze(onchainCode, localCode);
-    }
-    /**
-     * 基于ABI的智能分析
-     */
-    smartAnalyzeWithABI(onchainCode, localCode, abi) {
-        const constructor = abi.find(item => item.type === 'constructor');
-        if (!constructor || !constructor.inputs || constructor.inputs.length === 0) {
-            return this.detectImmutableVariables(onchainCode, localCode);
-        }
-        return this.detectConstructorParams(onchainCode, localCode, constructor);
-    }
-    /**
-     * 检测immutable变量
+     * 使用 artifact 的 fully-qualified identity 读取编译器生成的 immutableReferences。
+     * build-info 缺失时保留空引用，使完全一致的 bytecode 仍可通过；一旦存在差异，
+     * compareBytecode 会按 fail-closed 规则拒绝缺少编译器证据的匹配。
      */
-    detectImmutableVariables(onchainCode, localCode) {
-        const matches = [];
-        const zeroPattern64 = /0{64}/g;
-        let match;
-        while ((match = zeroPattern64.exec(localCode)) !== null) {
-            const position = match.index;
-            const onchainSegment = onchainCode.substr(position, 64);
-            const localSegment = match[0];
-            if (onchainSegment !== localSegment && /^[0-9a-f]{64}$/i.test(onchainSegment)) {
-                if (onchainSegment.startsWith('000000000000000000000000') &&
-                    onchainSegment.substr(24, 40) !== '0000000000000000000000000000000000000000') {
-                    const address = onchainSegment.substr(24, 40);
-                    matches.push({
-                        position: position,
-                        length: 64,
-                        onchainValue: onchainSegment,
-                        localValue: localSegment,
-                        type: "address",
-                        description: `Immutable地址变量: 0x${address}`
-                    });
-                }
-                else {
-                    try {
-                        const value = BigInt('0x' + onchainSegment);
-                        matches.push({
-                            position: position,
-                            length: 64,
-                            onchainValue: onchainSegment,
-                            localValue: localSegment,
-                            type: "uint256",
-                            description: `Immutable uint256变量: ${value.toString()}`
-                        });
-                    }
-                    catch (e) {
-                        // 忽略无法解析的值
-                    }
-                }
-            }
-        }
-        if (matches.length > 0) {
-            const descriptions = matches.map(m => m.description).join(", ");
-            return {
-                isConstructorDiff: true,
-                reason: `Immutable变量差异: ${descriptions}`,
-                differences: matches,
-                diffCount: matches.reduce((sum, m) => sum + m.length, 0)
-            };
-        }
-        return { isConstructorDiff: false, reason: "未检测到immutable变量模式" };
-    }
-    /**
-     * 检测constructor参数
-     */
-    detectConstructorParams(onchainCode, localCode, constructor) {
-        const params = constructor.inputs;
-        const allMatches = [];
-        for (const param of params) {
-            if (param.type === 'address') {
-                const addressMatches = this.findAddressParams(onchainCode, localCode, param);
-                allMatches.push(...addressMatches);
-            }
-            else if (param.type.startsWith('uint')) {
-                const uintMatches = this.findUintParams(onchainCode, localCode, param);
-                allMatches.push(...uintMatches);
-            }
-        }
-        if (allMatches.length > 0) {
-            const uniqueParams = this.deduplicateParams(allMatches, params);
-            const descriptions = uniqueParams.map(p => p.description).join(", ");
-            return {
-                isConstructorDiff: true,
-                reason: `Constructor参数差异(${params.map(p => `${p.type} ${p.name}`).join(', ')}): ${descriptions}`,
-                differences: uniqueParams,
-                diffCount: allMatches.reduce((sum, m) => sum + m.length, 0)
-            };
-        }
-        return { isConstructorDiff: false, reason: "未检测到constructor参数模式" };
-    }
-    /**
-     * 去重参数：按顺序匹配参数
-     */
-    deduplicateParams(allMatches, params) {
-        const uniqueAddresses = [];
-        const seenAddresses = new Set();
-        for (const match of allMatches) {
-            const address = match.address || match.onchainValue;
-            if (!seenAddresses.has(address)) {
-                seenAddresses.add(address);
-                uniqueAddresses.push({
-                    address: address,
-                    match: match
-                });
-            }
-        }
-        const uniqueParams = [];
-        const addressParams = params.filter(p => p.type === 'address');
-        const reversedAddresses = [...uniqueAddresses].reverse();
-        for (let i = 0; i < addressParams.length && i < reversedAddresses.length; i++) {
-            const param = addressParams[i];
-            const addressInfo = reversedAddresses[i];
-            uniqueParams.push({
-                ...addressInfo.match,
-                description: `${param.name}(${param.type}): 0x${addressInfo.address}`
-            });
-        }
-        return uniqueParams;
-    }
-    /**
-     * 查找地址参数
-     */
-    findAddressParams(onchainCode, localCode, param) {
-        const matches = [];
-        const zeroPattern64 = /0{64}/g;
-        let match;
-        while ((match = zeroPattern64.exec(localCode)) !== null) {
-            const position = match.index;
-            const onchainSegment = onchainCode.substr(position, 64);
-            const localSegment = match[0];
-            if (onchainSegment !== localSegment && /^[0-9a-f]{64}$/i.test(onchainSegment)) {
-                if (onchainSegment.startsWith('000000000000000000000000')) {
-                    const address = onchainSegment.substr(24, 40);
-                    if (address !== '0000000000000000000000000000000000000000') {
-                        const alreadyExists = matches.some(m => m.address === address && m.position === position);
-                        if (!alreadyExists) {
-                            matches.push({
-                                position: position,
-                                length: 64,
-                                onchainValue: onchainSegment,
-                                localValue: localSegment,
-                                type: "address",
-                                address: address,
-                                description: `${param.name}(${param.type}): 0x${address}`
-                            });
-                        }
-                    }
+    async getArtifactLocalBytecode(contractName) {
+        const artifact = await this.hre.artifacts.readArtifact(contractName);
+        let immutableReferences = {};
+        const sourceName = artifact.sourceName;
+        const artifactContractName = artifact.contractName;
+        const getBuildInfo = this.hre.artifacts.getBuildInfo;
+        if (typeof sourceName === 'string' &&
+            typeof artifactContractName === 'string' &&
+            typeof getBuildInfo === 'function') {
+            try {
+                const fullyQualifiedName = `${sourceName}:${artifactContractName}`;
+                const buildInfo = await getBuildInfo.call(this.hre.artifacts, fullyQualifiedName);
+                const compilerReferences = buildInfo?.output?.contracts?.[sourceName]?.[artifactContractName]
+                    ?.evm?.deployedBytecode?.immutableReferences;
+                if (compilerReferences &&
+                    typeof compilerReferences === 'object' &&
+                    !Array.isArray(compilerReferences)) {
+                    immutableReferences = compilerReferences;
                 }
             }
-        }
-        return matches;
-    }
-    /**
-     * 查找数值参数
-     */
-    findUintParams(onchainCode, localCode, param) {
-        const matches = [];
-        const bitSize = param.type === 'uint' ? 256 : parseInt(param.type.replace('uint', ''));
-        const hexLength = bitSize / 4;
-        const zeroPattern = new RegExp(`0{${hexLength}}`, 'g');
-        let match;
-        while ((match = zeroPattern.exec(localCode)) !== null) {
-            const position = match.index;
-            const onchainSegment = onchainCode.substr(position, hexLength);
-            if (onchainSegment !== match[0] && new RegExp(`^[0-9a-f]{${hexLength}}$`, 'i').test(onchainSegment)) {
-                try {
-                    const value = BigInt('0x' + onchainSegment);
-                    matches.push({
-                        position: position,
-                        length: hexLength,
-                        onchainValue: onchainSegment,
-                        localValue: match[0],
-                        type: param.type,
-                        description: `${param.name}(${param.type}): ${value.toString()}`
-                    });
-                }
-                catch (e) {
-                    // 忽略无法解析的值
-                }
+            catch {
+                immutableReferences = {};
             }
         }
-        return matches;
-    }
-    /**
-     * 回退分析方法
-     */
-    fallbackAnalyze(onchainCode, localCode) {
-        const wethAddress = 'c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2';
-        const zeroAddress = '0000000000000000000000000000000000000000';
-        const onchainNormalized = onchainCode.replace(new RegExp(wethAddress, 'g'), zeroAddress);
-        if (onchainNormalized === localCode) {
-            return {
-                isConstructorDiff: true,
-                reason: "Constructor参数差异: WETH地址",
-                differences: [{ description: `WETH地址: 0x${wethAddress}` }],
-                diffCount: 40
-            };
-        }
         return {
-            isConstructorDiff: false,
-            reason: "未知代码差异"
+            bytecode: artifact.deployedBytecode,
+            abi: artifact.abi,
+            immutableReferences
         };
     }
     /**
@@ -395,10 +200,101 @@ export class BytecodeChecker {
         const normalizedOnchain = '73' + zeroFill + onchainCode.substring(42);
         return { onchain: normalizedOnchain, local: localCode, selfAddress: `0x${selfAddress}` };
     }
+    /**
+     * 只屏蔽编译器声明的 immutable 区间，并比较其余 runtime bytecode。
+     */
+    compareWithImmutableReferences(onchainCode, localCode, immutableReferences) {
+        if (!immutableReferences ||
+            typeof immutableReferences !== 'object' ||
+            Array.isArray(immutableReferences) ||
+            Object.keys(immutableReferences).length === 0) {
+            return {
+                matches: false,
+                reason: '字节码不匹配，compiler immutableReferences 缺失'
+            };
+        }
+        const ranges = [];
+        for (const [id, references] of Object.entries(immutableReferences)) {
+            if (!Array.isArray(references) || references.length === 0) {
+                return {
+                    matches: false,
+                    reason: `compiler immutable ${id} 引用列表无效`
+                };
+            }
+            const onchainValuesByLength = new Map();
+            for (let index = 0; index < references.length; index++) {
+                const reference = references[index];
+                if (!reference ||
+                    !Number.isInteger(reference.start) ||
+                    !Number.isInteger(reference.length) ||
+                    reference.start < 0 ||
+                    reference.length <= 0) {
+                    return {
+                        matches: false,
+                        reason: `compiler immutable ${id}[${index}] 元数据无效：start 必须是非负整数，length 必须是正整数`
+                    };
+                }
+                const startHex = reference.start * 2;
+                const lengthHex = reference.length * 2;
+                const endHex = startHex + lengthHex;
+                if (endHex > onchainCode.length || endHex > localCode.length) {
+                    return {
+                        matches: false,
+                        reason: `compiler immutable ${id}[${index}] 引用越界`
+                    };
+                }
+                const onchainValue = onchainCode.slice(startHex, endHex);
+                const priorValue = onchainValuesByLength.get(reference.length);
+                if (priorValue !== undefined && priorValue !== onchainValue) {
+                    return {
+                        matches: false,
+                        reason: `compiler immutable ${id} 的重复引用值不一致`
+                    };
+                }
+                onchainValuesByLength.set(reference.length, onchainValue);
+                ranges.push({ id, index, startHex, endHex, lengthHex });
+            }
+        }
+        if (ranges.length === 0) {
+            return {
+                matches: false,
+                reason: '字节码不匹配，compiler immutableReferences 缺失'
+            };
+        }
+        ranges.sort((left, right) => left.startHex - right.startHex || left.endHex - right.endHex);
+        for (let index = 1; index < ranges.length; index++) {
+            const previous = ranges[index - 1];
+            const current = ranges[index];
+            if (current.startHex < previous.endHex) {
+                return {
+                    matches: false,
+                    reason: `compiler immutable 引用区间重叠：${previous.id}[${previous.index}] 与 ${current.id}[${current.index}]`
+                };
+            }
+        }
+        let maskedOnchain = onchainCode;
+        let maskedLocal = localCode;
+        for (let index = ranges.length - 1; index >= 0; index--) {
+            const range = ranges[index];
+            const mask = '0'.repeat(range.lengthHex);
+            maskedOnchain = maskedOnchain.slice(0, range.startHex) + mask + maskedOnchain.slice(range.endHex);
+            maskedLocal = maskedLocal.slice(0, range.startHex) + mask + maskedLocal.slice(range.endHex);
+        }
+        if (maskedOnchain !== maskedLocal) {
+            return {
+                matches: false,
+                reason: 'compiler immutableReferences 区间外仍存在代码差异'
+            };
+        }
+        return {
+            matches: true,
+            reason: `编译器 immutableReferences 精确匹配（${ranges.length} 处）`
+        };
+    }
     /**
      * 比较两个bytecode
      */
-    compareBytecode(onchainBytecode, localBytecode, abi = null) {
+    compareBytecode(onchainBytecode, localBytecode, _abi = null, immutableReferences = {}) {
         const onchainNormalized = this.normalizeBytecode(onchainBytecode);
         let localNormalized = this.normalizeBytecode(localBytecode);
         let libraryLinks = [];
@@ -436,23 +332,16 @@ export class BytecodeChecker {
                 libraryLinks: libraryLinks.length > 0 ? libraryLinks : undefined
             };
         }
-        const constructorCheck = this.checkConstructorParamsDifference(onchainForCompare, localForCompare, abi);
-        if (constructorCheck.isConstructorDiff) {
-            return {
-                matches: true,
-                reason: `${constructorCheck.reason}${extraSuffix}`,
-                constructorDetails: constructorCheck.differences,
-                libraryLinks: libraryLinks.length > 0 ? libraryLinks : undefined
-            };
-        }
-        if (onchainForCompare.startsWith(localForCompare)) {
-            return {
-                matches: true,
-                reason: `前缀匹配（可能包含constructor参数）${extraSuffix}`,
-                libraryLinks: libraryLinks.length > 0 ? libraryLinks : undefined
-            };
-        }
-        return { matches: false, reason: "代码存在显著差异" };
+        const immutableComparison = this.compareWithImmutableReferences(onchainForCompare, localForCompare, immutableReferences);
+        return {
+            ...immutableComparison,
+            reason: immutableComparison.matches
+                ? `${immutableComparison.reason}${extraSuffix}`
+                : immutableComparison.reason,
+            libraryLinks: immutableComparison.matches && libraryLinks.length > 0
+                ? libraryLinks
+                : undefined
+        };
     }
     /**
      * 检查单个合约
@@ -490,7 +379,7 @@ export class BytecodeChecker {
             // 使用实际合约名获取本地 bytecode
             const localData = await this.getLocalBytecode(contractName);
             result.localBytecodeLength = localData.bytecode.length;
-            const comparison = this.compareBytecode(onchainBytecode, localData.bytecode, localData.abi);
+            const comparison = this.compareBytecode(onchainBytecode, localData.bytecode, localData.abi, localData.immutableReferences);
             result.matches = comparison.matches;
             result.reason = comparison.reason;
         }