gate-evm-tools 1.0.25 → 1.0.27

package/runtime/workflow/lib/checkCodeRunner.ts

@@ -0,0 +1,1225 @@
+import crypto from "crypto";
+import fs from "fs";
+import path from "path";
+import {
+  CheckCodeEvidenceEntry,
+  updateCheckCodeEvidenceIndex,
+} from "./checkCodeReport";
+import type { DeploymentInfo } from "./deploymentInfo";
+
+export type ManifestSyncStatus =
+  | "not_required"
+  | "already_current"
+  | "synced"
+  | "proxy_kind_unknown"
+  | "failed";
+
+export type CheckCodeStatus =
+  | "compile_failed"
+  | "check_failed"
+  | "sync_partial"
+  | "succeeded";
+
+export type DeploymentScheme = "evm" | "zksync-eravm";
+
+export type EffectiveContractInfo = Record<string, Record<string, string>>;
+
+export interface CheckCodeOptions {
+  root: string;
+  runId: string;
+  artifactHash: string;
+  networks?: string[];
+  contracts?: string[];
+  deploymentAudit?: {
+    deploymentId: string;
+    registryCommitId: string;
+  };
+}
+
+export interface CheckCodeDeploymentAuditEvidence {
+  deploymentId: string;
+  registryCommitId: string;
+  registryCommitPath: string;
+  registryCommitHash: string;
+  selections: Array<{ network: string; executionId: string }>;
+}
+
+export interface CommandResult {
+  status: number;
+  error?: string;
+}
+
+export interface CommandEvidence {
+  command: string;
+  args: string[];
+  status: number;
+  network: string;
+  scheme: DeploymentScheme;
+  manifestDir?: string;
+  manifestFile?: string;
+  error?: string;
+}
+
+export interface CheckCodeEntry {
+  network: string;
+  scheme: DeploymentScheme;
+  instanceId: string;
+  contractInfoKey: string;
+  actualContract: string;
+  address: string;
+  proxyKind?: string;
+  implementationAddress?: string;
+  manifestDir: string;
+  manifestFile: string;
+  syncStatus: ManifestSyncStatus;
+  beforeHash: string;
+  afterHash: string;
+}
+
+export interface CheckCodeRunReport {
+  version: 1;
+  runId: string;
+  status: CheckCodeStatus;
+  artifactHash: string;
+  sourceContractInfoPath: "contractInfo.json";
+  deploymentAudit?: CheckCodeDeploymentAuditEvidence;
+  effectiveContractInfoPath?: string;
+  rawCheckReportPath?: string;
+  entries: CheckCodeEntry[];
+  commands: CommandEvidence[];
+  startedAt: string;
+  completedAt: string;
+  error?: string;
+  reportPath: string;
+}
+
+export interface CheckCodeDependencies {
+  runCommand: (
+    command: string,
+    args: string[],
+    options?: { cwd: string; env?: NodeJS.ProcessEnv },
+  ) => Promise<CommandResult> | CommandResult;
+  loadContractInfo: () => EffectiveContractInfo;
+  loadDeploymentInfo: () => DeploymentInfo;
+  resolveScheme: (network: string) => DeploymentScheme;
+  resolveManifestDir: (network: string) => string;
+  resolveManifestFile: (
+    network: string,
+    manifestDir: string,
+  ) => Promise<string> | string;
+  getImplementation: (
+    network: string,
+    address: string,
+  ) => Promise<string | undefined>;
+  getStorageLayoutHash: (
+    contractName: string,
+  ) => Promise<string>;
+  now?: () => string;
+}
+
+const SAFE_MANIFEST_DIR = /^\.openzeppelin(?:\.[a-z0-9][a-z0-9-]*)?$/;
+const SAFE_MANIFEST_FILE = /^\.openzeppelin(?:\.[a-z0-9][a-z0-9-]*)?\/[A-Za-z0-9][A-Za-z0-9._-]*\.json$/;
+const HASH = /^[0-9a-f]{64}$/;
+
+const isRecord = (value: unknown): value is Record<string, unknown> => (
+  Boolean(value) && typeof value === "object" && !Array.isArray(value)
+);
+
+const exactKeys = (
+  value: Record<string, unknown>,
+  required: string[],
+  optional: string[],
+  label: string,
+): void => {
+  const keys = Object.keys(value);
+  if (
+    required.some((key) => !keys.includes(key))
+    || keys.some((key) => !required.includes(key) && !optional.includes(key))
+  ) {
+    throw new Error(`${label} is not canonical: unsupported or missing fields`);
+  }
+};
+
+const isoTimestamp = (value: unknown, label: string): string => {
+  if (typeof value !== "string" || !Number.isFinite(Date.parse(value))) {
+    throw new Error(`${label} must be an ISO timestamp`);
+  }
+  return value;
+};
+
+const manifestDir = (value: unknown, label: string): string => {
+  if (typeof value !== "string" || !SAFE_MANIFEST_DIR.test(value)) {
+    throw new Error(`${label} is not a canonical manifest directory`);
+  }
+  return value;
+};
+
+const manifestFile = (value: unknown, directory: string, label: string): string => {
+  if (
+    typeof value !== "string"
+    || !SAFE_MANIFEST_FILE.test(value)
+    || !value.startsWith(`${directory}/`)
+  ) {
+    throw new Error(`${label} must belong to its canonical manifest directory`);
+  }
+  return value;
+};
+
+export const validateCheckCodeRunReport = (value: unknown): CheckCodeRunReport => {
+  if (!isRecord(value)) throw new Error("CheckCode report must be an object");
+  exactKeys(value, [
+    "version",
+    "runId",
+    "status",
+    "artifactHash",
+    "sourceContractInfoPath",
+    "entries",
+    "commands",
+    "startedAt",
+    "completedAt",
+    "reportPath",
+  ], ["deploymentAudit", "effectiveContractInfoPath", "rawCheckReportPath", "error"], "CheckCode report");
+  if (value.version !== 1) throw new Error("CheckCode report version must be 1");
+  if (value.sourceContractInfoPath !== "contractInfo.json") {
+    throw new Error("CheckCode report sourceContractInfoPath must be contractInfo.json");
+  }
+  if (value.deploymentAudit !== undefined) {
+    if (!isRecord(value.deploymentAudit)) {
+      throw new Error("CheckCode report deploymentAudit must be an object");
+    }
+    exactKeys(value.deploymentAudit, [
+      "deploymentId",
+      "registryCommitId",
+      "registryCommitPath",
+      "registryCommitHash",
+      "selections",
+    ], [], "CheckCode report deploymentAudit");
+    if (
+      typeof value.deploymentAudit.deploymentId !== "string"
+      || typeof value.deploymentAudit.registryCommitId !== "string"
+      || typeof value.deploymentAudit.registryCommitPath !== "string"
+      || !HASH.test(String(value.deploymentAudit.registryCommitHash))
+      || !Array.isArray(value.deploymentAudit.selections)
+      || value.deploymentAudit.selections.length === 0
+    ) {
+      throw new Error("CheckCode report deploymentAudit is invalid");
+    }
+    const expectedPath = `scripts/tasks/${value.deploymentAudit.deploymentId}/results/registry/${value.deploymentAudit.registryCommitId}.json`;
+    if (value.deploymentAudit.registryCommitPath !== expectedPath) {
+      throw new Error("CheckCode report deploymentAudit registry path is invalid");
+    }
+    const selectionKeys = value.deploymentAudit.selections.map((raw, index) => {
+      if (!isRecord(raw)) throw new Error(`CheckCode deploymentAudit selection ${index} is invalid`);
+      exactKeys(raw, ["network", "executionId"], [], `CheckCode deploymentAudit selection ${index}`);
+      if (typeof raw.network !== "string" || typeof raw.executionId !== "string") {
+        throw new Error(`CheckCode deploymentAudit selection ${index} is invalid`);
+      }
+      return `${raw.network}\0${raw.executionId}`;
+    });
+    if (
+      new Set(value.deploymentAudit.selections.map((item) => String((item as Record<string, unknown>).network))).size
+        !== value.deploymentAudit.selections.length
+      || JSON.stringify(selectionKeys) !== JSON.stringify([...selectionKeys].sort())
+    ) {
+      throw new Error("CheckCode deploymentAudit selections must be unique and sorted");
+    }
+  }
+  if (
+    value.status !== "compile_failed"
+    && value.status !== "check_failed"
+    && value.status !== "sync_partial"
+    && value.status !== "succeeded"
+  ) {
+    throw new Error("CheckCode report status is invalid");
+  }
+  if (!Array.isArray(value.entries) || !Array.isArray(value.commands)) {
+    throw new Error("CheckCode report entries and commands must be arrays");
+  }
+  const entries = value.entries.map((raw, index): CheckCodeEntry => {
+    if (!isRecord(raw)) throw new Error(`CheckCode entry ${index} must be an object`);
+    exactKeys(raw, [
+      "network",
+      "scheme",
+      "instanceId",
+      "contractInfoKey",
+      "actualContract",
+      "address",
+      "manifestDir",
+      "manifestFile",
+      "syncStatus",
+      "beforeHash",
+      "afterHash",
+    ], ["proxyKind", "implementationAddress"], `CheckCode entry ${index}`);
+    if (
+      (raw.scheme !== "evm" && raw.scheme !== "zksync-eravm")
+      || raw.syncStatus !== "not_required"
+      && raw.syncStatus !== "already_current"
+      && raw.syncStatus !== "synced"
+      && raw.syncStatus !== "proxy_kind_unknown"
+      && raw.syncStatus !== "failed"
+    ) {
+      throw new Error(`CheckCode entry ${index} syncStatus is invalid`);
+    }
+    const entryManifestDir = manifestDir(raw.manifestDir, `CheckCode entry ${index}.manifestDir`);
+    manifestFile(raw.manifestFile, entryManifestDir, `CheckCode entry ${index}.manifestFile`);
+    for (const key of [
+      "network",
+      "instanceId",
+      "contractInfoKey",
+      "actualContract",
+      "address",
+      "manifestFile",
+    ]) {
+      if (typeof raw[key] !== "string" || !String(raw[key]).trim()) {
+        throw new Error(`CheckCode entry ${index}.${key} is required`);
+      }
+    }
+    if (!HASH.test(String(raw.beforeHash)) || !HASH.test(String(raw.afterHash))) {
+      throw new Error(`CheckCode entry ${index} manifest hash is invalid`);
+    }
+    return raw as unknown as CheckCodeEntry;
+  });
+  const commands = value.commands.map((raw, index): CommandEvidence => {
+    if (!isRecord(raw)) throw new Error(`CheckCode command ${index} must be an object`);
+    exactKeys(raw, ["command", "args", "status", "network", "scheme"], ["manifestDir", "manifestFile", "error"], `CheckCode command ${index}`);
+    if (
+      typeof raw.command !== "string"
+      || !Array.isArray(raw.args)
+      || !Number.isInteger(raw.status)
+      || typeof raw.network !== "string"
+      || !raw.network.trim()
+      || (raw.scheme !== "evm" && raw.scheme !== "zksync-eravm")
+    ) {
+      throw new Error(`CheckCode command ${index} is invalid`);
+    }
+    if ((raw.manifestDir === undefined) !== (raw.manifestFile === undefined)) {
+      throw new Error(`CheckCode command ${index} manifestDir and manifestFile must appear together`);
+    }
+    if (raw.manifestDir !== undefined) {
+      const commandManifestDir = manifestDir(raw.manifestDir, `CheckCode command ${index}.manifestDir`);
+      if (raw.manifestFile !== undefined) {
+        manifestFile(raw.manifestFile, commandManifestDir, `CheckCode command ${index}.manifestFile`);
+      }
+    }
+    return raw as unknown as CommandEvidence;
+  });
+  if (value.status === "succeeded") {
+    if (
+      entries.some((entry) => ![
+        "not_required",
+        "already_current",
+        "synced",
+      ].includes(entry.syncStatus))
+      || commands.some((command) => command.status !== 0)
+      || value.error !== undefined
+    ) {
+      throw new Error("Succeeded CheckCode report contains unsuccessful evidence");
+    }
+  }
+  if (value.status !== "succeeded" && (typeof value.error !== "string" || !value.error)) {
+    throw new Error("Unsuccessful CheckCode report requires an error");
+  }
+  return {
+    ...(value as unknown as CheckCodeRunReport),
+    entries,
+    commands,
+    startedAt: isoTimestamp(value.startedAt, "CheckCode startedAt"),
+    completedAt: isoTimestamp(value.completedAt, "CheckCode completedAt"),
+  };
+};
+
+const safeRunId = (runId: string): string => {
+  if (!/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(runId)) {
+    throw new Error("CheckCode runId contains unsupported characters");
+  }
+  return runId;
+};
+
+const safeBindingId = (value: string, label: string): string => {
+  if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,199}$/.test(value)) {
+    throw new Error(`${label} contains unsupported characters`);
+  }
+  return value;
+};
+
+const normalizeForJson = (value: unknown): unknown => {
+  if (Array.isArray(value)) return value.map(normalizeForJson);
+  if (isRecord(value)) {
+    return Object.fromEntries(
+      Object.keys(value).sort().map((key) => [key, normalizeForJson(value[key])]),
+    );
+  }
+  return value;
+};
+
+const hashValue = (value: unknown): string => crypto
+  .createHash("sha256")
+  .update(JSON.stringify(normalizeForJson(value)))
+  .digest("hex");
+
+const writeJsonAtomic = (filePath: string, value: unknown): void => {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const temporary = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    fs.writeFileSync(temporary, JSON.stringify(value, null, 2) + "\n");
+    fs.renameSync(temporary, filePath);
+  } catch (error) {
+    if (fs.existsSync(temporary)) fs.unlinkSync(temporary);
+    throw error;
+  }
+};
+
+const readJson = (filePath: string, label: string): Record<string, unknown> => {
+  let value: unknown;
+  try {
+    value = JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch (error) {
+    throw new Error(`${label} is invalid: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (!isRecord(value)) throw new Error(`${label} must be an object`);
+  return value;
+};
+
+const prepareDeploymentAudit = (
+  options: CheckCodeOptions,
+): CheckCodeDeploymentAuditEvidence | undefined => {
+  if (!options.deploymentAudit) return undefined;
+  if (options.contracts?.length) {
+    throw new Error("Deployment CheckCode audit cannot filter contracts");
+  }
+  const deploymentId = safeBindingId(
+    options.deploymentAudit.deploymentId,
+    "deploymentAudit deploymentId",
+  );
+  const registryCommitId = safeBindingId(
+    options.deploymentAudit.registryCommitId,
+    "deploymentAudit registryCommitId",
+  );
+  const registryCommitPath = [
+    "scripts",
+    "tasks",
+    deploymentId,
+    "results",
+    "registry",
+    `${registryCommitId}.json`,
+  ].join("/");
+  const registryFile = path.join(options.root, ...registryCommitPath.split("/"));
+  const registry = readJson(registryFile, "Registry commit report");
+  if (
+    registry.version !== 1
+    || registry.status !== "committed"
+    || registry.taskId !== deploymentId
+    || registry.commitId !== registryCommitId
+    || !Array.isArray(registry.selections)
+    || registry.selections.length === 0
+  ) {
+    throw new Error("Registry commit report does not match the deployment audit");
+  }
+  const selections = registry.selections.map((raw, index) => {
+    if (!isRecord(raw)) throw new Error(`Registry commit selection ${index} is invalid`);
+    return {
+      network: safeBindingId(String(raw.network || ""), `Registry selection ${index} network`),
+      executionId: safeBindingId(
+        String(raw.executionId || ""),
+        `Registry selection ${index} executionId`,
+      ),
+    };
+  });
+  const sortedSelections = [...selections].sort((left, right) => left.network.localeCompare(right.network));
+  if (
+    new Set(selections.map((selection) => selection.network)).size !== selections.length
+    || JSON.stringify(selections) !== JSON.stringify(sortedSelections)
+  ) {
+    throw new Error("Registry commit selections must be unique and sorted");
+  }
+  if (options.networks?.length) {
+    const requested = [...new Set(options.networks)].sort();
+    const committed = selections.map((selection) => selection.network).sort();
+    if (JSON.stringify(requested) !== JSON.stringify(committed)) {
+      throw new Error("Deployment CheckCode networks must exactly match the registry commit");
+    }
+  }
+  const contractInfo = readJson(path.join(options.root, "contractInfo.json"), "contractInfo.json");
+  if (registry.afterHash !== hashValue(contractInfo)) {
+    throw new Error("Formal contractInfo does not match the registry commit");
+  }
+  const taskDir = path.join(options.root, "scripts", "tasks", deploymentId);
+  const lock = readJson(path.join(taskDir, "parameters.lock.json"), "parameters.lock.json");
+  if (lock.version !== 2 || lock.deploymentId !== deploymentId || !Array.isArray(lock.executions)) {
+    throw new Error("Deployment CheckCode requires canonical parameters.lock.json");
+  }
+  const status = readJson(path.join(taskDir, "status.json"), "deployment status.json");
+  if (status.status !== "deployed_pending_code_audit" || !isRecord(status.networks)) {
+    throw new Error("Deployment is not pending code audit");
+  }
+  const sourceRecordPaths = Array.isArray(registry.sourceRecordPaths)
+    ? new Set(registry.sourceRecordPaths.map(String))
+    : new Set<string>();
+  for (const selection of selections) {
+    const executions = lock.executions.filter((raw) => (
+      isRecord(raw) && raw.executionId === selection.executionId
+    ));
+    if (executions.length !== 1) {
+      throw new Error(`Deployment lock is missing execution ${selection.executionId}`);
+    }
+    const execution = executions[0];
+    if (
+      !isRecord(execution.releaseFingerprint)
+      || execution.releaseFingerprint.artifactHash !== options.artifactHash
+    ) {
+      throw new Error(`CheckCode artifactHash does not match ${selection.network} execution lock`);
+    }
+    const networkStatus = status.networks[selection.network];
+    if (
+      !isRecord(networkStatus)
+      || networkStatus.deployStatus !== "deployed_pending_code_audit"
+      || networkStatus.registryExecutionId !== selection.executionId
+    ) {
+      throw new Error(`${selection.network} is not pending audit for the committed execution`);
+    }
+    const recordPath = `scripts/tasks/${deploymentId}/results/${selection.network}.${selection.executionId}.deployment.json`;
+    if (!sourceRecordPaths.has(recordPath)) {
+      throw new Error(`Registry commit does not bind deployment record ${recordPath}`);
+    }
+    const record = readJson(path.join(options.root, ...recordPath.split("/")), "Deployment record");
+    if (
+      record.taskId !== deploymentId
+      || record.network !== selection.network
+      || record.executionId !== selection.executionId
+      || record.status !== "applied"
+    ) {
+      throw new Error(`Deployment record is not applied for ${selection.network}`);
+    }
+  }
+  return {
+    deploymentId,
+    registryCommitId,
+    registryCommitPath,
+    registryCommitHash: crypto.createHash("sha256").update(fs.readFileSync(registryFile)).digest("hex"),
+    selections,
+  };
+};
+
+const completeDeploymentAudit = (
+  root: string,
+  report: CheckCodeRunReport,
+  audit: CheckCodeDeploymentAuditEvidence,
+): void => {
+  const taskDir = path.join(root, "scripts", "tasks", audit.deploymentId);
+  const statusFile = path.join(taskDir, "status.json");
+  const reportFile = path.join(root, ...report.reportPath.split("/"));
+  const reportHash = crypto.createHash("sha256").update(fs.readFileSync(reportFile)).digest("hex");
+  const status = readJson(statusFile, "deployment status.json");
+  const currentNetworks = isRecord(status.networks) ? status.networks : {};
+  const networks = { ...currentNetworks };
+  for (const selection of audit.selections) {
+    const current = currentNetworks[selection.network];
+    if (!isRecord(current) || current.registryExecutionId !== selection.executionId) {
+      throw new Error(`${selection.network} deployment status changed during CheckCode`);
+    }
+    networks[selection.network] = {
+      ...current,
+      deployStatus: "completed",
+      checkCodeStatus: "succeeded",
+      checkCodeRunId: report.runId,
+      checkCodeReportPath: report.reportPath,
+      updatedAt: report.completedAt,
+    };
+  }
+  writeJsonAtomic(statusFile, {
+    ...status,
+    status: "completed",
+    networks,
+    codeAudit: {
+      status: "succeeded",
+      runId: report.runId,
+      reportPath: report.reportPath,
+      reportHash,
+      artifactHash: report.artifactHash,
+      registryCommitId: audit.registryCommitId,
+      registryCommitPath: audit.registryCommitPath,
+      registryCommitHash: audit.registryCommitHash,
+      selections: audit.selections,
+      completedAt: report.completedAt,
+    },
+    updatedAt: report.completedAt,
+  });
+};
+
+const directoryHash = (directory: string): string => {
+  if (!fs.existsSync(directory)) return hashValue([]);
+  if (fs.lstatSync(directory).isSymbolicLink()) {
+    throw new Error(`Manifest directory cannot be a symlink: ${directory}`);
+  }
+  const files: string[] = [];
+  const visit = (current: string): void => {
+    for (const name of fs.readdirSync(current).sort()) {
+      const filePath = path.join(current, name);
+      const stat = fs.lstatSync(filePath);
+      if (stat.isSymbolicLink()) throw new Error(`Manifest path cannot contain symlinks: ${filePath}`);
+      if (stat.isDirectory()) visit(filePath);
+      else if (stat.isFile()) files.push(filePath);
+    }
+  };
+  visit(directory);
+  const hash = crypto.createHash("sha256");
+  for (const filePath of files) {
+    hash.update(path.relative(directory, filePath).split(path.sep).join("/"));
+    hash.update("\0");
+    hash.update(fs.readFileSync(filePath));
+    hash.update("\0");
+  }
+  return hash.digest("hex");
+};
+
+const confinedManifestFile = (input: {
+  root: string;
+  directory: string;
+  requestedFile: string;
+}): { absolute: string; relative: string } => {
+  const expectedDirectory = path.resolve(input.root, input.directory);
+  const absolute = path.isAbsolute(input.requestedFile)
+    ? path.resolve(input.requestedFile)
+    : path.resolve(input.root, input.requestedFile);
+  if (path.dirname(absolute) !== expectedDirectory) {
+    throw new Error(`Manifest file escapes ${input.directory}: ${input.requestedFile}`);
+  }
+  const name = path.basename(absolute);
+  if (!/^[a-z0-9][a-z0-9-]*\.json$/.test(name)) {
+    throw new Error(`Manifest filename is not canonical: ${name}`);
+  }
+  if (fs.existsSync(absolute)) {
+    const stat = fs.lstatSync(absolute);
+    if (stat.isSymbolicLink()) throw new Error(`Manifest file cannot be a symlink: ${absolute}`);
+    if (!stat.isFile()) throw new Error(`Manifest path is not a regular file: ${absolute}`);
+  }
+  return {
+    absolute,
+    relative: path.relative(input.root, absolute).split(path.sep).join("/"),
+  };
+};
+
+const filterContractInfo = (
+  contractInfo: EffectiveContractInfo,
+  networks: string[] | undefined,
+  contracts: string[] | undefined,
+): EffectiveContractInfo => {
+  const networkFilter = networks ? new Set(networks) : undefined;
+  const contractFilter = contracts ? new Set(contracts) : undefined;
+  return Object.fromEntries(Object.entries(contractInfo)
+    .filter(([network]) => !networkFilter || networkFilter.has(network))
+    .map(([network, entries]) => [
+      network,
+      Object.fromEntries(Object.entries(entries).filter(([key]) => {
+        if (!contractFilter) return true;
+        const parts = key.split(":");
+        return contractFilter.has(key)
+          || contractFilter.has(parts[0])
+          || contractFilter.has(parts.at(-1) || key);
+      })),
+    ])
+    .filter(([, entries]) => Object.keys(entries).length > 0));
+};
+
+const registryEntries = (contractInfo: EffectiveContractInfo): Array<{
+  network: string;
+  instanceId: string;
+  contractInfoKey: string;
+  actualContract: string;
+  address: string;
+}> => Object.entries(contractInfo).flatMap(([network, entries]) => (
+  Object.entries(entries).map(([contractInfoKey, address]) => {
+    const parts = contractInfoKey.split(":");
+    return {
+      network,
+      instanceId: parts[0],
+      contractInfoKey,
+      actualContract: parts.at(-1) || contractInfoKey,
+      address,
+    };
+  })
+)).sort((left, right) => (
+  `${left.network}.${left.contractInfoKey}`.localeCompare(`${right.network}.${right.contractInfoKey}`)
+));
+
+const manifestDocument = (filePath: string): Record<string, unknown> => {
+  if (!fs.existsSync(filePath)) return {};
+  try {
+    const parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
+    return isRecord(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+};
+
+const manifestIsCurrent = (input: {
+  filePath: string;
+  proxyAddress: string;
+  implementationAddress: string;
+  storageLayoutHash: string;
+}): boolean => {
+  const proxy = input.proxyAddress.toLowerCase();
+  const implementation = input.implementationAddress.toLowerCase();
+  let hasProxy = false;
+  let hasImplementation = false;
+  let hasLayout = false;
+  const document = manifestDocument(input.filePath);
+  if (Array.isArray(document.proxies)) {
+    hasProxy = document.proxies.some((item) => (
+      isRecord(item)
+      && typeof item.address === "string"
+      && item.address.toLowerCase() === proxy
+    ));
+  }
+  if (isRecord(document.impls)) {
+    for (const rawImplementation of Object.values(document.impls)) {
+      if (!isRecord(rawImplementation)) continue;
+      const addresses = [rawImplementation.address]
+        .concat(Array.isArray(rawImplementation.allAddresses) ? rawImplementation.allAddresses : [])
+        .filter((address): address is string => typeof address === "string")
+        .map((address) => address.toLowerCase());
+      if (!addresses.includes(implementation)) continue;
+      hasImplementation = true;
+      if (rawImplementation.layout !== undefined) {
+        hasLayout = hashValue(rawImplementation.layout) === input.storageLayoutHash;
+      }
+    }
+  }
+  return hasProxy && hasImplementation && hasLayout;
+};
+
+const ADDRESS = /^0x[0-9a-fA-F]{40}$/;
+const TRANSACTION_HASH = /^0x[0-9a-fA-F]{64}$/;
+
+const sameAddress = (left: unknown, right: unknown): boolean => (
+  typeof left === "string"
+  && typeof right === "string"
+  && ADDRESS.test(left)
+  && ADDRESS.test(right)
+  && left.toLowerCase() === right.toLowerCase()
+);
+
+const sameJson = (left: unknown, right: unknown): boolean => (
+  JSON.stringify(normalizeForJson(left)) === JSON.stringify(normalizeForJson(right))
+);
+
+const confinedRegularFile = (
+  root: string,
+  requested: unknown,
+  label: string,
+): string => {
+  if (typeof requested !== "string" || !requested || path.isAbsolute(requested)) {
+    throw new Error(`${label} must be a project-relative path`);
+  }
+  const projectRoot = path.resolve(root);
+  const absolute = path.resolve(projectRoot, requested);
+  const relative = path.relative(projectRoot, absolute);
+  if (!relative || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw new Error(`${label} escapes the project root`);
+  }
+  let current = projectRoot;
+  for (const segment of relative.split(path.sep)) {
+    current = path.join(current, segment);
+    const stat = fs.lstatSync(current);
+    if (stat.isSymbolicLink()) throw new Error(`${label} cannot contain a symlink`);
+  }
+  const stat = fs.lstatSync(absolute);
+  if (!stat.isFile()) throw new Error(`${label} must be a regular file`);
+  return absolute;
+};
+
+const readConfinedJson = (
+  root: string,
+  requested: unknown,
+  label: string,
+): { absolute: string; bytes: Buffer; data: Record<string, unknown> } => {
+  const absolute = confinedRegularFile(root, requested, label);
+  const bytes = fs.readFileSync(absolute);
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(bytes.toString("utf8"));
+  } catch (error) {
+    throw new Error(`${label} is invalid: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (!isRecord(parsed)) throw new Error(`${label} must be an object`);
+  return { absolute, bytes, data: parsed };
+};
+
+const readRequiredString = (
+  input: Record<string, unknown>,
+  key: string,
+  label: string,
+): string => {
+  const value = input[key];
+  if (typeof value !== "string" || !value.trim()) throw new Error(`${label}.${key} is required`);
+  return value;
+};
+
+const assertZkUupsSyncEvidence = (input: {
+  root: string;
+  network: string;
+  manifestDir: string;
+  manifest: { absolute: string; relative: string };
+  metadata: NonNullable<DeploymentInfo["networks"][string][string]>;
+  selected: ReturnType<typeof registryEntries>[number];
+  implementation: string;
+}): void => {
+  if (input.metadata.source.kind !== "deployment") {
+    throw new Error("zkSync UUPS CheckCode requires a deployment record source");
+  }
+  const source = input.metadata.source;
+  const expectedRecordPath = [
+    "scripts",
+    "tasks",
+    source.deploymentId,
+    "results",
+    `${input.network}.${source.executionId}.deployment.json`,
+  ].join("/");
+  if (
+    source.recordPath !== expectedRecordPath
+    || input.metadata.contractInfoKey !== input.selected.contractInfoKey
+    || input.metadata.actualContract !== input.selected.actualContract
+    || !sameAddress(input.metadata.address, input.selected.address)
+    || !sameAddress(input.metadata.implementationAddress, input.implementation)
+  ) {
+    throw new Error("zkSync deployment metadata does not match the applied target");
+  }
+  const record = readConfinedJson(input.root, source.recordPath, "zkSync deployment record").data;
+  if (
+    record.taskId !== source.deploymentId
+    || record.executionId !== source.executionId
+    || record.network !== input.network
+    || record.status !== "applied"
+    || !Array.isArray(record.changes)
+  ) {
+    throw new Error("zkSync deployment record does not match the applied target");
+  }
+  const matchingChanges = record.changes.filter((raw) => (
+    isRecord(raw)
+    && raw.status === "applied"
+    && raw.instanceId === input.selected.instanceId
+    && raw.actualContract === input.metadata.actualContract
+    && raw.contractInfoKey === input.selected.contractInfoKey
+    && sameAddress(raw.proxyAddress ?? raw.address ?? raw.candidateAddress, input.selected.address)
+    && sameAddress(raw.implementationAddress, input.implementation)
+  )) as Record<string, unknown>[];
+  if (matchingChanges.length !== 1) {
+    throw new Error("zkSync deployment record must contain exactly one matching applied UUPS change");
+  }
+  const change = matchingChanges[0];
+  if (!isRecord(change.gateToolSync)) {
+    throw new Error("zkSync UUPS deployment change is missing immutable GateTool sync evidence");
+  }
+  const gateToolSync = change.gateToolSync;
+  const outputPath = readRequiredString(gateToolSync, "outputPath", "zkSync GateTool sync evidence");
+  if (!isRecord(gateToolSync.data)) {
+    throw new Error("zkSync GateTool sync evidence data is required");
+  }
+  const evidence = readConfinedJson(input.root, outputPath, "zkSync GateTool sync evidence");
+  if (!sameJson(evidence.data, gateToolSync.data)) {
+    throw new Error("zkSync GateTool sync evidence file does not match the applied deployment record");
+  }
+  const expectedEvidenceBytes = Buffer.from(`${JSON.stringify(evidence.data, null, 2)}\n`);
+  if (!evidence.bytes.equals(expectedEvidenceBytes)) {
+    throw new Error("zkSync GateTool sync evidence must use canonical immutable JSON");
+  }
+
+  const data = evidence.data;
+  if (
+    data.version !== 1
+    || data.status !== "succeeded"
+    || data.scheme !== "zksync-eravm"
+    || data.network !== input.network
+    || data.target !== input.network
+    || data.manifestDir !== input.manifestDir
+    || data.contract !== input.metadata.actualContract
+    || !sameAddress(data.proxy, input.selected.address)
+    || !sameAddress(data.implementation, input.implementation)
+    || !sameJson(data.constructorArgs, change.constructorArgs ?? [])
+    || typeof data.transactionHash !== "string"
+    || !TRANSACTION_HASH.test(data.transactionHash)
+    || typeof change.txHash !== "string"
+    || data.transactionHash.toLowerCase() !== change.txHash.toLowerCase()
+  ) {
+    throw new Error("zkSync GateTool sync evidence does not match the applied UUPS deployment");
+  }
+  if (!isRecord(data.manifestTransaction)) {
+    throw new Error("zkSync GateTool sync evidence is missing the manifest transaction");
+  }
+  const transaction = data.manifestTransaction;
+  if (
+    transaction.version !== 1
+    || transaction.status !== "committed"
+    || transaction.manifestFile !== input.manifest.relative
+    || typeof transaction.afterHash !== "string"
+    || !HASH.test(transaction.afterHash)
+  ) {
+    throw new Error("zkSync GateTool manifest transaction is not canonical committed evidence");
+  }
+  const syncReportPath = readRequiredString(data, "syncReportPath", "zkSync GateTool sync evidence");
+  const syncReport = confinedRegularFile(input.root, syncReportPath, "zkSync manifest transaction snapshot");
+  const expectedSnapshot = Buffer.from(`${JSON.stringify(transaction, null, 2)}\n`);
+  const snapshot = fs.readFileSync(syncReport);
+  if (
+    !snapshot.equals(expectedSnapshot)
+    || data.syncReportHash !== crypto.createHash("sha256").update(snapshot).digest("hex")
+  ) {
+    throw new Error("zkSync manifest transaction snapshot does not match immutable sync evidence");
+  }
+  if (
+    crypto.createHash("sha256").update(fs.readFileSync(input.manifest.absolute)).digest("hex")
+      !== transaction.afterHash
+  ) {
+    throw new Error("zkSync manifest bytes no longer match the applied GateTool sync evidence");
+  }
+};
+
+export const runCheckCode = async (
+  options: CheckCodeOptions,
+  dependencies: CheckCodeDependencies,
+): Promise<CheckCodeRunReport> => {
+  const runId = safeRunId(options.runId);
+  const now = dependencies.now || (() => new Date().toISOString());
+  const startedAt = now();
+  const deploymentAudit = prepareDeploymentAudit(options);
+  const runDir = path.join(options.root, "scripts", "checkcode", "runs", runId);
+  const reportFile = path.join(runDir, "report.json");
+  const effectiveContractInfoFile = path.join(runDir, "effective-contract-info.json");
+  const rawCheckReportFile = path.join(runDir, "gate-tool-check.json");
+  const commands: CommandEvidence[] = [];
+  const entries: CheckCodeEntry[] = [];
+  const formalContractInfoPath = path.join(options.root, "contractInfo.json");
+  const formalContractInfoBefore = fs.existsSync(formalContractInfoPath)
+    ? fs.readFileSync(formalContractInfoPath)
+    : undefined;
+
+  const assertFormalContractInfoUnchanged = (): void => {
+    const exists = fs.existsSync(formalContractInfoPath);
+    if (
+      (formalContractInfoBefore === undefined && exists)
+      || (formalContractInfoBefore !== undefined && !exists)
+      || (
+        formalContractInfoBefore !== undefined
+        && exists
+        && !formalContractInfoBefore.equals(fs.readFileSync(formalContractInfoPath))
+      )
+    ) {
+      throw new Error("Formal contractInfo.json changed during CheckCode");
+    }
+  };
+
+  const report = (status: CheckCodeStatus, error?: string): CheckCodeRunReport => {
+    assertFormalContractInfoUnchanged();
+    const value = validateCheckCodeRunReport({
+      version: 1,
+      runId,
+      status,
+      artifactHash: options.artifactHash,
+      sourceContractInfoPath: "contractInfo.json",
+      ...(deploymentAudit ? { deploymentAudit } : {}),
+      ...(fs.existsSync(effectiveContractInfoFile)
+        ? { effectiveContractInfoPath: path.relative(options.root, effectiveContractInfoFile).split(path.sep).join("/") }
+        : {}),
+      ...(fs.existsSync(rawCheckReportFile)
+        ? { rawCheckReportPath: path.relative(options.root, rawCheckReportFile).split(path.sep).join("/") }
+        : {}),
+      entries,
+      commands,
+      startedAt,
+      completedAt: now(),
+      ...(error ? { error } : {}),
+      reportPath: path.relative(options.root, reportFile).split(path.sep).join("/"),
+    });
+    writeJsonAtomic(reportFile, value);
+    return value;
+  };
+
+  const runCommand = async (
+    command: string,
+    args: string[],
+    evidence: {
+      network: string;
+      scheme: DeploymentScheme;
+      manifestDir?: string;
+      manifestFile?: string;
+      env?: NodeJS.ProcessEnv;
+      evidenceArgs?: string[];
+    },
+  ): Promise<CommandResult> => {
+    let result: CommandResult;
+    try {
+      result = await dependencies.runCommand(command, args, {
+        cwd: options.root,
+        env: evidence.env,
+      });
+    } catch (error) {
+      result = { status: 1, error: error instanceof Error ? error.message : String(error) };
+    }
+    commands.push({
+      command,
+      args: evidence.evidenceArgs || args,
+      status: result.status,
+      network: evidence.network,
+      scheme: evidence.scheme,
+      ...(evidence.manifestDir ? { manifestDir: evidence.manifestDir } : {}),
+      ...(evidence.manifestFile ? { manifestFile: evidence.manifestFile } : {}),
+      ...(result.error ? { error: result.error } : {}),
+    });
+    return result;
+  };
+
+  let contractInfo: EffectiveContractInfo;
+  let deploymentInfo: DeploymentInfo;
+  try {
+    contractInfo = filterContractInfo(
+      dependencies.loadContractInfo(),
+      deploymentAudit
+        ? deploymentAudit.selections.map((selection) => selection.network)
+        : options.networks,
+      options.contracts,
+    );
+    deploymentInfo = dependencies.loadDeploymentInfo();
+    writeJsonAtomic(effectiveContractInfoFile, contractInfo);
+  } catch (error) {
+    return report("check_failed", error instanceof Error ? error.message : String(error));
+  }
+  const selectedEntries = registryEntries(contractInfo);
+  if (
+    selectedEntries.length === 0
+    && (Boolean(options.networks?.length) || Boolean(options.contracts?.length))
+  ) {
+    return report("check_failed", "CheckCode scope contains no contracts");
+  }
+
+  const selectedNetworks = [...new Set(selectedEntries.map((entry) => entry.network))].sort();
+  const schemes = new Map<string, DeploymentScheme>();
+  try {
+    for (const network of selectedNetworks) {
+      const scheme = dependencies.resolveScheme(network);
+      if (scheme !== "evm" && scheme !== "zksync-eravm") {
+        throw new Error(`CheckCode scheme for ${network} must be evm or zksync-eravm`);
+      }
+      schemes.set(network, scheme);
+    }
+  } catch (error) {
+    return report("check_failed", error instanceof Error ? error.message : String(error));
+  }
+
+  let checkedNetwork: string | undefined;
+  for (const selected of selectedEntries) {
+    const scheme = schemes.get(selected.network)!;
+    if (checkedNetwork !== selected.network) {
+      const env = {
+        ...process.env,
+        HARDHAT_NETWORK: selected.network,
+        GATE_WORKFLOW_TARGET: selected.network,
+      };
+      const compile = await runCommand("npm", [
+        "run",
+        "compile",
+        "--",
+        "--network",
+        selected.network,
+      ], { network: selected.network, scheme, env });
+      if (compile.status !== 0) {
+        return report("compile_failed", compile.error || `Compilation failed for ${selected.network}`);
+      }
+
+      const check = await runCommand("npx", [
+        "--no-install",
+        "gate-tool",
+        "check",
+        "--scheme",
+        scheme,
+        "--network",
+        selected.network,
+        "--config",
+        effectiveContractInfoFile,
+        "--output",
+        rawCheckReportFile,
+      ], {
+        network: selected.network,
+        scheme,
+        env,
+        evidenceArgs: [
+          "--no-install",
+          "gate-tool",
+          "check",
+          "--scheme",
+          scheme,
+          "--network",
+          selected.network,
+          "--config",
+          path.relative(options.root, effectiveContractInfoFile).split(path.sep).join("/"),
+          "--output",
+          path.relative(options.root, rawCheckReportFile).split(path.sep).join("/"),
+        ],
+      });
+      if (check.status !== 0) {
+        return report("check_failed", check.error || `gate-tool check failed for ${selected.network}`);
+      }
+      checkedNetwork = selected.network;
+    }
+    let resolvedManifestDir: string;
+    try {
+      resolvedManifestDir = manifestDir(
+        dependencies.resolveManifestDir(selected.network),
+        `Manifest directory for ${selected.network}`,
+      );
+    } catch (error) {
+      return report("sync_partial", error instanceof Error ? error.message : String(error));
+    }
+    const directory = path.join(options.root, resolvedManifestDir);
+    const beforeHash = directoryHash(directory);
+    let exactManifest: { absolute: string; relative: string };
+    try {
+      exactManifest = confinedManifestFile({
+        root: options.root,
+        directory: resolvedManifestDir,
+        requestedFile: await dependencies.resolveManifestFile(
+          selected.network,
+          resolvedManifestDir,
+        ),
+      });
+    } catch (error) {
+      return report("sync_partial", error instanceof Error ? error.message : String(error));
+    }
+    const metadata = deploymentInfo.networks[selected.network]?.[selected.instanceId];
+    let implementationAddress: string | undefined;
+    try {
+      implementationAddress = await dependencies.getImplementation(
+        selected.network,
+        selected.address,
+      );
+    } catch (error) {
+      entries.push({
+        ...selected,
+        scheme,
+        manifestDir: resolvedManifestDir,
+        manifestFile: exactManifest.relative,
+        syncStatus: "failed",
+        beforeHash,
+        afterHash: directoryHash(directory),
+      });
+      continue;
+    }
+
+    const base = {
+      ...selected,
+      scheme,
+      actualContract: metadata?.actualContract || selected.actualContract,
+      ...(metadata?.proxyKind ? { proxyKind: metadata.proxyKind } : {}),
+      ...(implementationAddress ? { implementationAddress } : {}),
+      manifestDir: resolvedManifestDir,
+      manifestFile: exactManifest.relative,
+      beforeHash,
+    };
+    if (metadata?.proxyKind === "uups" && !implementationAddress) {
+      entries.push({ ...base, syncStatus: "failed", afterHash: directoryHash(directory) });
+      continue;
+    }
+    if (scheme === "zksync-eravm" && metadata?.proxyKind === "uups") {
+      try {
+        assertZkUupsSyncEvidence({
+          root: options.root,
+          network: selected.network,
+          manifestDir: resolvedManifestDir,
+          manifest: exactManifest,
+          metadata,
+          selected,
+          implementation: implementationAddress!,
+        });
+        entries.push({ ...base, syncStatus: "already_current", afterHash: beforeHash });
+      } catch {
+        entries.push({ ...base, syncStatus: "failed", afterHash: directoryHash(directory) });
+      }
+      continue;
+    }
+    if (!implementationAddress || metadata?.proxyKind && metadata.proxyKind !== "uups") {
+      entries.push({ ...base, syncStatus: "not_required", afterHash: directoryHash(directory) });
+      continue;
+    }
+    if (!metadata || metadata.proxyKind !== "uups") {
+      entries.push({ ...base, syncStatus: "proxy_kind_unknown", afterHash: directoryHash(directory) });
+      continue;
+    }
+    if (scheme !== "evm") {
+      entries.push({ ...base, syncStatus: "failed", afterHash: directoryHash(directory) });
+      continue;
+    }
+    let storageLayoutHash: string;
+    try {
+      storageLayoutHash = await dependencies.getStorageLayoutHash(metadata.actualContract);
+    } catch (error) {
+      entries.push({ ...base, syncStatus: "failed", afterHash: directoryHash(directory) });
+      continue;
+    }
+    if (manifestIsCurrent({
+      filePath: exactManifest.absolute,
+      proxyAddress: selected.address,
+      implementationAddress,
+      storageLayoutHash,
+    })) {
+      entries.push({ ...base, syncStatus: "already_current", afterHash: beforeHash });
+      continue;
+    }
+    const sync = await runCommand("npx", [
+      "--no-install",
+      "gate-tool",
+      "sync",
+      "--proxy",
+      selected.address,
+      "--contract",
+      metadata.actualContract,
+      "--network",
+      selected.network,
+      "--scheme",
+      "evm",
+      "--target",
+      selected.network,
+      "--skip-tx-hash",
+    ], {
+      network: selected.network,
+      scheme,
+      manifestDir: resolvedManifestDir,
+      manifestFile: exactManifest.relative,
+      env: {
+        ...process.env,
+        HARDHAT_NETWORK: selected.network,
+        GATE_WORKFLOW_TARGET: selected.network,
+        MANIFEST_DEFAULT_DIR: resolvedManifestDir,
+      },
+    });
+    const afterHash = directoryHash(directory);
+    entries.push({
+      ...base,
+      syncStatus: sync.status === 0 && afterHash !== beforeHash ? "synced" : "failed",
+      afterHash,
+    });
+  }
+
+  if (entries.some((entry) => (
+    entry.syncStatus === "failed" || entry.syncStatus === "proxy_kind_unknown"
+  ))) {
+    return report("sync_partial", "One or more manifest outcomes require review");
+  }
+
+  const checkedAt = now();
+  updateCheckCodeEvidenceIndex(
+    options.root,
+    entries.map((entry): CheckCodeEvidenceEntry => ({
+      status: "passed",
+      network: entry.network,
+      scheme: entry.scheme,
+      instanceId: entry.instanceId,
+      contractInfoKey: entry.contractInfoKey,
+      address: entry.address,
+      artifactHash: options.artifactHash,
+      runId,
+      checkedAt,
+    })),
+  );
+  const succeeded = report("succeeded");
+  if (deploymentAudit) completeDeploymentAudit(options.root, succeeded, deploymentAudit);
+  return succeeded;
+};