gate-evm-tools 1.0.23 → 1.0.24

package/dist/core/preparation/evm.js

@@ -0,0 +1,290 @@
+import { concat, ContractFactory, getAddress, getCreate2Address, Interface, keccak256, } from 'ethers';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import { Manifest } from '@openzeppelin/upgrades-core';
+import { getDeployData } from '@openzeppelin/hardhat-upgrades/dist/utils/deploy-impl.js';
+import { artifactIdentity, assertArtifactScheme } from './artifacts.js';
+import { canonicalPreparationJson, hashPreparationRequest, normalizePreparationPlan, } from './normalize.js';
+const ERC1967_PROXY_ARTIFACT = '@openzeppelin/contracts/proxy/ERC1967/ERC1967Proxy.sol:ERC1967Proxy';
+const FACTORY_INTERFACE = new Interface([
+    'function deploy(bytes32 salt, bytes initCode, bytes data, uint256 create2ForwardValue, uint256 callForwardValue) payable returns (address)',
+]);
+const UPGRADE_INTERFACE = new Interface([
+    'function upgradeToAndCall(address newImplementation, bytes data) payable',
+]);
+const sha256Json = (value) => crypto
+    .createHash('sha256')
+    .update(canonicalPreparationJson(JSON.parse(JSON.stringify(value))))
+    .digest('hex');
+const loadDefaultUpgradeEvidence = async (hre, request, factory, validationOptions) => {
+    const getImplementationAddress = hre.upgrades?.erc1967?.getImplementationAddress;
+    if (!getImplementationAddress) {
+        throw new Error('OpenZeppelin ERC-1967 implementation lookup is required');
+    }
+    if (!hre.network.provider)
+        throw new Error('Hardhat network provider is required');
+    const currentImplementation = await getImplementationAddress(request.proxy);
+    const deployData = await getDeployData(hre, factory, validationOptions);
+    const manifest = await Manifest.forNetwork(hre.network.provider);
+    const oldDeployment = await manifest.getDeploymentFromAddress(currentImplementation);
+    const hasCanonical = fs.existsSync(manifest.file);
+    const hasFallback = manifest.fallbackFile !== manifest.file && fs.existsSync(manifest.fallbackFile);
+    if (hasCanonical && hasFallback) {
+        throw new Error('OpenZeppelin manifest canonical/fallback files are ambiguous');
+    }
+    const manifestFile = hasCanonical ? manifest.file : hasFallback ? manifest.fallbackFile : undefined;
+    if (!manifestFile)
+        throw new Error('OpenZeppelin manifest file is missing');
+    return {
+        currentImplementation,
+        oldLayoutHash: sha256Json(oldDeployment.layout),
+        newLayoutHash: sha256Json(deployData.layout),
+        manifestDigest: crypto.createHash('sha256').update(fs.readFileSync(manifestFile)).digest('hex'),
+    };
+};
+const assertAddressPolicy = (predictedAddress, policy, label) => {
+    if (!policy)
+        return;
+    const normalized = getAddress(predictedAddress);
+    if (policy.expectedAddress && normalized !== getAddress(policy.expectedAddress)) {
+        throw new Error(`${label} predicted ${normalized} but expected ${policy.expectedAddress}`);
+    }
+    if (policy.leadingZeroBytes !== undefined
+        && !normalized.slice(2).toLowerCase().startsWith('00'.repeat(policy.leadingZeroBytes))) {
+        throw new Error(`${label} does not satisfy leadingZeroBytes=${policy.leadingZeroBytes}`);
+    }
+};
+const buildDeployment = async (input) => {
+    assertArtifactScheme(input.artifact, 'evm');
+    const factory = new ContractFactory(input.artifact.abi, input.artifact.bytecode);
+    const constructorInput = factory.interface.encodeDeploy(input.constructorArgs);
+    const initCode = concat([input.artifact.bytecode, constructorInput]);
+    const initCodeHash = keccak256(initCode);
+    const predictedAddress = getCreate2Address(input.factory, input.salt, initCodeHash);
+    assertAddressPolicy(predictedAddress, input.policy, input.role);
+    const code = await input.hre.ethers.provider.getCode(predictedAddress);
+    const status = code && code !== '0x' ? 'reused' : 'required';
+    const deployment = {
+        role: input.role,
+        address: predictedAddress,
+        salt: input.salt,
+        status,
+        constructorInput,
+        initCodeHash,
+    };
+    if (status === 'reused')
+        return { deployment, initCode, factory };
+    const purpose = input.role === 'contract'
+        ? 'deploy-contract'
+        : input.role === 'implementation'
+            ? 'deploy-implementation'
+            : 'deploy-proxy';
+    return {
+        deployment,
+        initCode,
+        factory,
+        transaction: {
+            id: purpose,
+            purpose,
+            to: input.factory,
+            value: '0',
+            data: FACTORY_INTERFACE.encodeFunctionData('deploy', [
+                input.salt,
+                initCode,
+                '0x',
+                0,
+                0,
+            ]),
+            operation: 0,
+        },
+    };
+};
+const preparePlain = async (hre, request, artifact) => {
+    const prepared = await buildDeployment({
+        hre,
+        role: 'contract',
+        artifact,
+        constructorArgs: request.constructorArgs,
+        factory: request.factory,
+        salt: request.salt,
+        policy: request.addressPolicy,
+    });
+    const create2ForwardValue = BigInt(request.create2ForwardValue ?? '0');
+    const callForwardValue = BigInt(request.callForwardValue ?? '0');
+    const transactions = prepared.transaction
+        ? [{
+                ...prepared.transaction,
+                value: (create2ForwardValue + callForwardValue).toString(10),
+                data: FACTORY_INTERFACE.encodeFunctionData('deploy', [
+                    request.salt,
+                    prepared.initCode,
+                    '0x',
+                    create2ForwardValue,
+                    callForwardValue,
+                ]),
+            }]
+        : [];
+    const network = await hre.ethers.provider.getNetwork();
+    return normalizePreparationPlan({
+        version: 1,
+        requestHash: hashPreparationRequest(request),
+        kind: request.kind,
+        scheme: request.scheme,
+        network: request.network,
+        target: request.target,
+        chainId: network.chainId.toString(),
+        contract: request.contract,
+        artifact: artifactIdentity(artifact, 'evm'),
+        validation: {
+            kind: 'artifact',
+            engine: 'hardhat-artifact',
+            artifactFormat: 'hh-sol-artifact-1',
+        },
+        deployments: [prepared.deployment],
+        transactions,
+    });
+};
+const prepareUupsInitial = async (hre, request, artifact) => {
+    const implementationFactory = new ContractFactory(artifact.abi, artifact.bytecode);
+    const validateImplementation = hre.upgrades?.validateImplementation;
+    if (!validateImplementation) {
+        throw new Error('OpenZeppelin validateImplementation is required for UUPS preparation');
+    }
+    const validationOptions = {
+        kind: 'uups',
+        constructorArgs: request.constructorArgs,
+    };
+    if (request.unsafeAllow)
+        validationOptions.unsafeAllow = request.unsafeAllow;
+    await validateImplementation(implementationFactory, validationOptions);
+    const implementation = await buildDeployment({
+        hre,
+        role: 'implementation',
+        artifact,
+        constructorArgs: request.constructorArgs,
+        factory: request.factory,
+        salt: request.implementationSalt,
+    });
+    const proxyArtifact = await hre.artifacts.readArtifact(ERC1967_PROXY_ARTIFACT);
+    const proxy = await buildDeployment({
+        hre,
+        role: 'proxy',
+        artifact: proxyArtifact,
+        constructorArgs: [request.placeholderImplementation, '0x'],
+        factory: request.factory,
+        salt: request.proxySalt,
+        policy: request.proxyAddressPolicy,
+    });
+    const initData = request.call
+        ? implementation.factory.interface.encodeFunctionData(request.call.method, request.call.args)
+        : '0x';
+    const transactions = [implementation.transaction, proxy.transaction]
+        .filter((transaction) => transaction !== undefined);
+    transactions.push({
+        id: 'upgrade-proxy',
+        purpose: 'upgrade-proxy',
+        to: proxy.deployment.address,
+        value: '0',
+        data: UPGRADE_INTERFACE.encodeFunctionData('upgradeToAndCall', [
+            implementation.deployment.address,
+            initData,
+        ]),
+        operation: 0,
+    });
+    const network = await hre.ethers.provider.getNetwork();
+    return normalizePreparationPlan({
+        version: 1,
+        requestHash: hashPreparationRequest(request),
+        kind: request.kind,
+        scheme: request.scheme,
+        network: request.network,
+        target: request.target,
+        chainId: network.chainId.toString(),
+        contract: request.contract,
+        proxyKind: 'uups',
+        artifact: artifactIdentity(artifact, 'evm'),
+        validation: {
+            kind: 'uups-initial',
+            engine: 'openzeppelin',
+            artifactFormat: 'hh-sol-artifact-1',
+            implementationSafe: true,
+        },
+        deployments: [implementation.deployment, proxy.deployment],
+        transactions,
+    });
+};
+const prepareUupsUpgrade = async (hre, request, artifact, dependencies) => {
+    const implementationFactory = new ContractFactory(artifact.abi, artifact.bytecode);
+    const validateUpgrade = hre.upgrades?.validateUpgrade;
+    if (!validateUpgrade) {
+        throw new Error('OpenZeppelin validateUpgrade is required for UUPS preparation');
+    }
+    const validationOptions = {
+        kind: 'uups',
+        constructorArgs: request.constructorArgs,
+    };
+    if (request.unsafeAllow)
+        validationOptions.unsafeAllow = request.unsafeAllow;
+    await validateUpgrade(request.proxy, implementationFactory, validationOptions);
+    const evidence = await (dependencies.loadUpgradeEvidence ?? loadDefaultUpgradeEvidence)(hre, request, implementationFactory, validationOptions);
+    const implementation = await buildDeployment({
+        hre,
+        role: 'implementation',
+        artifact,
+        constructorArgs: request.constructorArgs,
+        factory: request.factory,
+        salt: request.implementationSalt,
+        policy: request.implementationAddressPolicy,
+    });
+    const initData = request.call
+        ? implementation.factory.interface.encodeFunctionData(request.call.method, request.call.args)
+        : '0x';
+    const transactions = implementation.transaction ? [implementation.transaction] : [];
+    transactions.push({
+        id: 'upgrade-proxy',
+        purpose: 'upgrade-proxy',
+        to: request.proxy,
+        value: '0',
+        data: UPGRADE_INTERFACE.encodeFunctionData('upgradeToAndCall', [
+            implementation.deployment.address,
+            initData,
+        ]),
+        operation: 0,
+    });
+    const network = await hre.ethers.provider.getNetwork();
+    return normalizePreparationPlan({
+        version: 1,
+        requestHash: hashPreparationRequest(request),
+        kind: request.kind,
+        scheme: request.scheme,
+        network: request.network,
+        target: request.target,
+        chainId: network.chainId.toString(),
+        contract: request.contract,
+        proxyKind: 'uups',
+        artifact: artifactIdentity(artifact, 'evm'),
+        validation: {
+            kind: 'uups-upgrade',
+            engine: 'openzeppelin',
+            artifactFormat: 'hh-sol-artifact-1',
+            implementationSafe: true,
+            storageLayoutCompatible: true,
+            ...evidence,
+        },
+        deployments: [implementation.deployment],
+        transactions,
+    });
+};
+export const prepareEvm = async (hre, request, dependencies = {}) => {
+    if (request.scheme !== 'evm')
+        throw new Error('EVM adapter received a non-EVM request');
+    const artifact = await hre.artifacts.readArtifact(request.contract);
+    assertArtifactScheme(artifact, 'evm');
+    if (request.kind === 'create2-deploy')
+        return preparePlain(hre, request, artifact);
+    if (request.kind === 'uups-placeholder-deploy') {
+        return prepareUupsInitial(hre, request, artifact);
+    }
+    return prepareUupsUpgrade(hre, request, artifact, dependencies);
+};
+//# sourceMappingURL=evm.js.map

package/dist/core/preparation/evm.js.map

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

package/dist/core/preparation/index.d.ts

@@ -0,0 +1,9 @@
+import type { GateToolPreparationPlanV1 } from './types.js';
+export interface GateToolPreparationHre {
+    network: {
+        name: string;
+    };
+    run(task: string, options?: Record<string, unknown>): Promise<unknown>;
+}
+export declare const prepareWorkflow: (hre: GateToolPreparationHre, rawRequest: unknown) => Promise<GateToolPreparationPlanV1>;
+//# sourceMappingURL=index.d.ts.map

package/dist/core/preparation/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/preparation/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,yBAAyB,EAE1B,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1B,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACxE;AAED,eAAO,MAAM,eAAe,GAC1B,KAAK,sBAAsB,EAC3B,YAAY,OAAO,KAClB,OAAO,CAAC,yBAAyB,CAYnC,CAAC"}

package/dist/core/preparation/index.js

@@ -0,0 +1,15 @@
+import { prepareEvm } from './evm.js';
+import { prepareZkSync } from './zksync.js';
+import { normalizePreparationRequest } from './normalize.js';
+export const prepareWorkflow = async (hre, rawRequest) => {
+    const request = normalizePreparationRequest(rawRequest);
+    if (hre.network.name !== request.network) {
+        throw new Error(`preparation request network ${request.network} does not match Hardhat network ${hre.network.name}`);
+    }
+    await hre.run('compile', { quiet: true });
+    if (request.scheme === 'evm') {
+        return prepareEvm(hre, request);
+    }
+    return prepareZkSync(hre, request);
+};
+//# sourceMappingURL=index.js.map

package/dist/core/preparation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/preparation/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,2BAA2B,EAAE,MAAM,gBAAgB,CAAC;AAW7D,MAAM,CAAC,MAAM,eAAe,GAAG,KAAK,EAClC,GAA2B,EAC3B,UAAmB,EACiB,EAAE;IACtC,MAAM,OAAO,GAAiC,2BAA2B,CAAC,UAAU,CAAC,CAAC;IACtF,IAAI,GAAG,CAAC,OAAO,CAAC,IAAI,KAAK,OAAO,CAAC,OAAO,EAAE,CAAC;QACzC,MAAM,IAAI,KAAK,CACb,+BAA+B,OAAO,CAAC,OAAO,mCAAmC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,CACpG,CAAC;IACJ,CAAC;IACD,MAAM,GAAG,CAAC,GAAG,CAAC,SAAS,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1C,IAAI,OAAO,CAAC,MAAM,KAAK,KAAK,EAAE,CAAC;QAC7B,OAAO,UAAU,CAAC,GAAkD,EAAE,OAAO,CAAC,CAAC;IACjF,CAAC;IACD,OAAO,aAAa,CAAC,GAAqD,EAAE,OAAO,CAAC,CAAC;AACvF,CAAC,CAAC"}

package/dist/core/preparation/manifest.d.ts

@@ -0,0 +1,43 @@
+import { type StorageLayout } from '@openzeppelin/upgrades-core';
+export interface TargetManifestPaths {
+    root: string;
+    target: string;
+    manifestDir: string;
+    file: string;
+    fallbackFile: string;
+}
+export interface TargetManifestData {
+    manifestVersion: string;
+    impls: Record<string, {
+        address: string;
+        txHash?: string;
+        allAddresses?: string[];
+        layout: StorageLayout;
+    } | undefined>;
+    proxies: Array<{
+        address: string;
+        txHash?: string;
+        kind: 'uups' | 'transparent' | 'beacon';
+    }>;
+    admin?: unknown;
+}
+export interface RegisteredZkUpgradeState {
+    manifest: TargetManifestData;
+    paths: TargetManifestPaths;
+    bytes: Buffer;
+    digest: string;
+    oldLayout: StorageLayout;
+}
+export declare const resolveTargetManifestDirectory: (root: string, target: string, env?: NodeJS.ProcessEnv) => string;
+export declare const resolveTargetManifestPaths: (root: string, target: string, chainId: number, env?: NodeJS.ProcessEnv) => TargetManifestPaths;
+export declare const parseTargetManifest: (bytes: Buffer) => TargetManifestData;
+export declare const readRegisteredZkUpgradeState: (input: {
+    root: string;
+    target: string;
+    chainId: number;
+    proxy: string;
+    currentImplementation: string;
+    env?: NodeJS.ProcessEnv;
+}) => RegisteredZkUpgradeState;
+export declare const hashStorageLayout: (layout: StorageLayout) => string;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/core/preparation/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/core/preparation/manifest.ts"],"names":[],"mappings":"AAIA,OAAO,EAAgB,KAAK,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAa/E,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,kBAAkB;IACjC,eAAe,EAAE,MAAM,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE;QACpB,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;QACxB,MAAM,EAAE,aAAa,CAAC;KACvB,GAAG,SAAS,CAAC,CAAC;IACf,OAAO,EAAE,KAAK,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,QAAQ,CAAC;KACzC,CAAC,CAAC;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,KAAK,EAAE,mBAAmB,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,aAAa,CAAC;CAC1B;AA8BD,eAAO,MAAM,8BAA8B,GACzC,MAAM,MAAM,EACZ,QAAQ,MAAM,EACd,MAAK,MAAM,CAAC,UAAwB,KACnC,MA2CF,CAAC;AAEF,eAAO,MAAM,0BAA0B,GACrC,MAAM,MAAM,EACZ,QAAQ,MAAM,EACd,SAAS,MAAM,EACf,MAAK,MAAM,CAAC,UAAwB,KACnC,mBAgBF,CAAC;AAeF,eAAO,MAAM,mBAAmB,GAAI,OAAO,MAAM,KAAG,kBAsBnD,CAAC;AAeF,eAAO,MAAM,4BAA4B,GAAI,OAAO;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,qBAAqB,EAAE,MAAM,CAAC;IAC9B,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB,KAAG,wBA2BH,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAAI,QAAQ,aAAa,KAAG,MAG1C,CAAC"}

package/dist/core/preparation/manifest.js

@@ -0,0 +1,169 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import YAML from 'yaml';
+import { networkNames } from '@openzeppelin/upgrades-core';
+import { canonicalPreparationJson } from './normalize.js';
+const SAFE_TARGET = /^[A-Za-z0-9][A-Za-z0-9_-]{0,199}$/;
+const SAFE_MANIFEST_DIR = /^\.openzeppelin(?:\.[a-z0-9][a-z0-9-]*)?$/;
+const ENVIRONMENTS = new Set(['local', 'development', 'production']);
+const regularFile = (filePath, label) => {
+    if (!fs.existsSync(filePath))
+        throw new Error(`${label} is missing: ${filePath}`);
+    const stat = fs.lstatSync(filePath);
+    if (stat.isSymbolicLink())
+        throw new Error(`${label} cannot be a symlink`);
+    if (!stat.isFile())
+        throw new Error(`${label} must be a regular file`);
+};
+const assertManifestDirectory = (root, manifestDir) => {
+    if (!SAFE_MANIFEST_DIR.test(manifestDir) || manifestDir === '.upgradable') {
+        throw new Error(`unsafe OpenZeppelin manifest directory: ${manifestDir}`);
+    }
+    const resolvedRoot = path.resolve(root);
+    const candidate = path.resolve(resolvedRoot, manifestDir);
+    if (path.dirname(candidate) !== resolvedRoot) {
+        throw new Error(`OpenZeppelin manifest directory escapes the project: ${manifestDir}`);
+    }
+    if (fs.existsSync(candidate)) {
+        const stat = fs.lstatSync(candidate);
+        if (stat.isSymbolicLink()) {
+            throw new Error(`OpenZeppelin manifest directory cannot be a symlink: ${manifestDir}`);
+        }
+        if (!stat.isDirectory()) {
+            throw new Error(`OpenZeppelin manifest path must be a directory: ${manifestDir}`);
+        }
+    }
+    return candidate;
+};
+export const resolveTargetManifestDirectory = (root, target, env = process.env) => {
+    if (!SAFE_TARGET.test(target) || target.startsWith('_')) {
+        throw new Error(`invalid manifest target: ${target}`);
+    }
+    const resolvedRoot = path.resolve(root);
+    const configFile = path.join(resolvedRoot, 'config.yaml');
+    regularFile(configFile, 'config.yaml');
+    const parsed = YAML.parse(fs.readFileSync(configFile, 'utf8'), { merge: true });
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('config.yaml must define target keys at the top level');
+    }
+    const selected = parsed[target];
+    if (!selected || typeof selected !== 'object' || Array.isArray(selected)) {
+        throw new Error(`config.yaml has no target ${target}`);
+    }
+    const config = selected;
+    if (!ENVIRONMENTS.has(String(config.environment))) {
+        throw new Error(`config.yaml target ${target} has an invalid environment`);
+    }
+    const manifestDir = config.openzeppelin?.manifestDir;
+    if (typeof manifestDir !== 'string') {
+        throw new Error(`config.yaml target ${target} must define openzeppelin.manifestDir`);
+    }
+    if (config.environment === 'production' && manifestDir !== '.openzeppelin') {
+        throw new Error(`production target ${target} must use .openzeppelin`);
+    }
+    if (config.environment !== 'production' && manifestDir === '.openzeppelin') {
+        throw new Error(`non-production target ${target} must not use .openzeppelin`);
+    }
+    assertManifestDirectory(resolvedRoot, manifestDir);
+    const configuredEnvironment = env.MANIFEST_DEFAULT_DIR?.trim();
+    if (configuredEnvironment && configuredEnvironment !== manifestDir) {
+        throw new Error(`MANIFEST_DEFAULT_DIR conflict for ${target}: expected ${manifestDir}, received ${configuredEnvironment}`);
+    }
+    const configuredTarget = env.GATE_WORKFLOW_TARGET?.trim();
+    if (configuredTarget && configuredTarget !== target) {
+        throw new Error(`GATE_WORKFLOW_TARGET conflict: expected ${target}, received ${configuredTarget}`);
+    }
+    return manifestDir;
+};
+export const resolveTargetManifestPaths = (root, target, chainId, env = process.env) => {
+    if (!Number.isSafeInteger(chainId) || chainId <= 0) {
+        throw new Error(`invalid manifest chainId: ${chainId}`);
+    }
+    const resolvedRoot = path.resolve(root);
+    const manifestDir = resolveTargetManifestDirectory(resolvedRoot, target, env);
+    const directory = path.join(resolvedRoot, manifestDir);
+    const fallbackName = `unknown-${chainId}.json`;
+    const canonicalName = `${networkNames[chainId] ?? `unknown-${chainId}`}.json`;
+    return {
+        root: resolvedRoot,
+        target,
+        manifestDir,
+        file: path.join(directory, canonicalName),
+        fallbackFile: path.join(directory, fallbackName),
+    };
+};
+const readManifestBytes = (paths) => {
+    const canonicalExists = fs.existsSync(paths.file);
+    const distinctFallback = paths.file !== paths.fallbackFile;
+    const fallbackExists = distinctFallback && fs.existsSync(paths.fallbackFile);
+    if (canonicalExists && fallbackExists) {
+        throw new Error('OpenZeppelin canonical and fallback manifests are ambiguous');
+    }
+    const selected = canonicalExists ? paths.file : fallbackExists ? paths.fallbackFile : undefined;
+    if (!selected)
+        throw new Error(`OpenZeppelin manifest is missing for target ${paths.target}`);
+    regularFile(selected, 'OpenZeppelin manifest');
+    return fs.readFileSync(selected);
+};
+export const parseTargetManifest = (bytes) => {
+    let raw;
+    try {
+        raw = JSON.parse(bytes.toString('utf8'));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`OpenZeppelin manifest is invalid JSON: ${message}`);
+    }
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new Error('OpenZeppelin manifest must be an object');
+    }
+    const value = raw;
+    if (value.manifestVersion !== '3.2') {
+        throw new Error('OpenZeppelin manifest version must be 3.2');
+    }
+    if (!value.impls || typeof value.impls !== 'object' || Array.isArray(value.impls)) {
+        throw new Error('OpenZeppelin manifest impls must be an object');
+    }
+    if (!Array.isArray(value.proxies)) {
+        throw new Error('OpenZeppelin manifest proxies must be an array');
+    }
+    return value;
+};
+const matchingImplementation = (manifest, implementation) => {
+    const expected = implementation.toLowerCase();
+    for (const entry of Object.values(manifest.impls)) {
+        if (!entry)
+            continue;
+        const addresses = [entry.address, ...(entry.allAddresses ?? [])];
+        if (addresses.some((address) => address.toLowerCase() === expected))
+            return entry.layout;
+    }
+    return undefined;
+};
+export const readRegisteredZkUpgradeState = (input) => {
+    const paths = resolveTargetManifestPaths(input.root, input.target, input.chainId, input.env);
+    const bytes = readManifestBytes(paths);
+    const manifest = parseTargetManifest(bytes);
+    const proxyEntry = manifest.proxies.find((entry) => entry.address.toLowerCase() === input.proxy.toLowerCase());
+    if (!proxyEntry)
+        throw new Error(`proxy ${input.proxy} is not registered in the target manifest`);
+    if (proxyEntry.kind !== 'uups')
+        throw new Error(`proxy ${input.proxy} is not registered as UUPS`);
+    const oldLayout = matchingImplementation(manifest, input.currentImplementation);
+    if (!oldLayout) {
+        throw new Error(`current implementation ${input.currentImplementation} is not registered in the target manifest`);
+    }
+    return {
+        manifest,
+        paths,
+        bytes,
+        digest: crypto.createHash('sha256').update(bytes).digest('hex'),
+        oldLayout,
+    };
+};
+export const hashStorageLayout = (layout) => crypto
+    .createHash('sha256')
+    .update(canonicalPreparationJson(layout))
+    .digest('hex');
+//# sourceMappingURL=manifest.js.map

package/dist/core/preparation/manifest.js.map

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

package/dist/core/preparation/normalize.d.ts

@@ -0,0 +1,7 @@
+import type { GateToolPreparationPlanV1, GateToolPreparationRequestV1 } from './types.js';
+export declare const normalizePreparationRequest: (raw: unknown) => GateToolPreparationRequestV1;
+export declare const canonicalPreparationJson: (raw: unknown) => string;
+export declare const hashPreparationRequest: (raw: unknown) => string;
+export declare const normalizePreparationPlan: (raw: unknown) => GateToolPreparationPlanV1;
+export declare const writePreparationPlanAtomic: (filePath: string, raw: unknown, root?: string) => GateToolPreparationPlanV1;
+//# sourceMappingURL=normalize.d.ts.map

package/dist/core/preparation/normalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../../../src/core/preparation/normalize.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAOV,yBAAyB,EACzB,4BAA4B,EAK7B,MAAM,YAAY,CAAC;AAmLpB,eAAO,MAAM,2BAA2B,GACtC,KAAK,OAAO,KACX,4BA+EF,CAAC;AAaF,eAAO,MAAM,wBAAwB,GAAI,KAAK,OAAO,KAAG,MAEvD,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAAI,KAAK,OAAO,KAAG,MAGrD,CAAC;AA2MF,eAAO,MAAM,wBAAwB,GAAI,KAAK,OAAO,KAAG,yBA2CvD,CAAC;AAkBF,eAAO,MAAM,0BAA0B,GACrC,UAAU,MAAM,EAChB,KAAK,OAAO,EACZ,aAAoB,KACnB,yBAaF,CAAC"}