gate-evm-tools 1.0.25 → 1.0.27

package/runtime/workflow/lib/checkCode/finalize.ts

@@ -0,0 +1,198 @@
+import fs from "fs";
+import path from "path";
+import { validateCheckCodeRunReport } from "../checkCodeRunner";
+
+export interface DevelopmentCheckCodeFinalizeInput {
+  root: string;
+  deploymentId: string;
+  sourceSuperTaskId: string;
+  developmentNetwork: string;
+  executionId: string;
+  runId: string;
+  now?: () => string;
+}
+
+export interface DevelopmentCheckCodeFinalizeResult {
+  reportPath: string;
+  handoffPath: string;
+  statusPath: string;
+  documentPath: string;
+}
+
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,199}$/;
+
+const safeId = (value: string, label: string): string => {
+  if (!SAFE_ID.test(value)) throw new Error(`${label} is invalid`);
+  return value;
+};
+
+const readObject = (filePath: string, label: string): Record<string, unknown> => {
+  const value = JSON.parse(fs.readFileSync(filePath, "utf8")) as unknown;
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must be an object`);
+  }
+  return value as Record<string, unknown>;
+};
+
+const object = (value: unknown): Record<string, unknown> => (
+  value && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : {}
+);
+
+const writeAtomic = (filePath: string, contents: string): void => {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const temporary = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    fs.writeFileSync(temporary, contents);
+    fs.renameSync(temporary, filePath);
+  } catch (error) {
+    if (fs.existsSync(temporary)) fs.unlinkSync(temporary);
+    throw error;
+  }
+};
+
+const writeJsonAtomic = (filePath: string, value: unknown): void => {
+  writeAtomic(filePath, JSON.stringify(value, null, 2) + "\n");
+};
+
+export const finalizeDevelopmentCheckCode = (
+  input: DevelopmentCheckCodeFinalizeInput,
+): DevelopmentCheckCodeFinalizeResult => {
+  const deploymentId = safeId(input.deploymentId, "deploymentId");
+  const sourceSuperTaskId = safeId(input.sourceSuperTaskId, "sourceSuperTaskId");
+  const developmentNetwork = safeId(input.developmentNetwork, "developmentNetwork");
+  const executionId = safeId(input.executionId, "executionId");
+  const runId = safeId(input.runId, "CheckCode runId");
+  const updatedAt = (input.now || (() => new Date().toISOString()))();
+  if (!Number.isFinite(Date.parse(updatedAt))) throw new Error("Finalize timestamp is invalid");
+
+  const taskBase = `scripts/tasks/${deploymentId}`;
+  const reportPath = `scripts/checkcode/runs/${runId}/report.json`;
+  const statusPath = `${taskBase}/status.json`;
+  const handoffPath = `${taskBase}/handoff.json`;
+  const documentPath = `${taskBase}/docs/checkcode-report.md`;
+  const absolute = (relative: string): string => path.join(input.root, ...relative.split("/"));
+  const report = validateCheckCodeRunReport(readObject(absolute(reportPath), "CheckCode report"));
+  if (
+    report.status !== "succeeded"
+    || report.runId !== runId
+    || report.reportPath !== reportPath
+  ) {
+    throw new Error("Development CheckCode requires the selected canonical succeeded report");
+  }
+
+  const status = readObject(absolute(statusPath), "status.json");
+  const phases = object(status.phases);
+  const networks = object(status.networks);
+  const network = object(networks[developmentNetwork]);
+  if (
+    status.sourceSuperTaskId !== sourceSuperTaskId
+    || status.developmentNetwork !== developmentNetwork
+    || network.registryExecutionId !== executionId
+    || network.deployStatus !== "deployed_pending_code_audit"
+  ) {
+    throw new Error("Development CheckCode status identity is invalid");
+  }
+  const nextStatus = {
+    ...status,
+    status: "code_checked",
+    phases: {
+      ...phases,
+      checkCode: {
+        networks: [developmentNetwork],
+        status: "succeeded",
+        report: reportPath,
+      },
+    },
+    networks: {
+      ...networks,
+      [developmentNetwork]: {
+        ...network,
+        deployStatus: "deployed_pending_code_audit",
+        checkCodeStatus: "succeeded",
+        checkCodeRunId: runId,
+        checkCodeReportPath: reportPath,
+        updatedAt,
+      },
+    },
+    updatedAt,
+  };
+
+  const existingHandoff = readObject(absolute(handoffPath), "handoff.json");
+  const { checkCodeReport: _legacyCheckCodeReport, ...handoff } = existingHandoff;
+  const nextHandoff = {
+    ...handoff,
+    stageKind: "check_code",
+    status: "code_checked",
+    sourceSuperTaskId,
+    deploymentId,
+    developmentNetwork,
+    executionId,
+    networks: [developmentNetwork],
+    development_deployed: true,
+    checkCode: {
+      runId,
+      reportPath,
+      artifactHash: report.artifactHash,
+    },
+    updatedAt,
+  };
+
+  const lines = [
+    "# CheckCode Report",
+    "",
+    `sourceSuperTaskId: ${sourceSuperTaskId}`,
+    `deploymentId: ${deploymentId}`,
+    `developmentNetwork: ${developmentNetwork}`,
+    `executionId: ${executionId}`,
+    `runId: ${runId}`,
+    `artifactHash: ${report.artifactHash}`,
+    `reportPath: ${reportPath}`,
+    `status: ${report.status}`,
+    `startedAt: ${report.startedAt}`,
+    `completedAt: ${report.completedAt}`,
+    "",
+    "## Commands",
+    ...report.commands.map((command) => (
+      `- ${command.command} ${command.args.join(" ")} — exit ${command.status}`
+    )),
+    "",
+  ];
+  writeJsonAtomic(absolute(statusPath), nextStatus);
+  writeJsonAtomic(absolute(handoffPath), nextHandoff);
+  writeAtomic(absolute(documentPath), lines.join("\n"));
+  return { reportPath, handoffPath, statusPath, documentPath };
+};
+
+export const runDevelopmentCheckCodeFinalizeCli = (
+  argv: string[],
+  defaultRoot: string = process.cwd(),
+): DevelopmentCheckCodeFinalizeResult => {
+  const values = new Map<string, string>();
+  for (let index = 0; index < argv.length; index += 1) {
+    const item = argv[index];
+    if (!item.startsWith("--")) continue;
+    const equalAt = item.indexOf("=");
+    const key = item.slice(2, equalAt > 2 ? equalAt : undefined);
+    const next = argv[index + 1];
+    const value = equalAt > 2 ? item.slice(equalAt + 1) : next;
+    if (!value || value.startsWith("--")) throw new Error(`--${key} requires a value`);
+    if (values.has(key)) throw new Error(`--${key} may be provided only once`);
+    values.set(key, value.trim());
+    if (equalAt < 0) index += 1;
+  }
+  const required = (key: string): string => {
+    const value = values.get(key);
+    if (!value) throw new Error(`--${key} is required`);
+    return value;
+  };
+  return finalizeDevelopmentCheckCode({
+    root: path.resolve(values.get("root") || defaultRoot),
+    deploymentId: required("deploymentId"),
+    sourceSuperTaskId: required("sourceSuperTaskId"),
+    developmentNetwork: required("developmentNetwork"),
+    executionId: required("executionId"),
+    runId: required("runId"),
+  });
+};

package/runtime/workflow/lib/checkCode/index.ts

@@ -0,0 +1,18 @@
+import { runCheckCode, type CheckCodeRunReport } from "../checkCodeRunner";
+import { parseCheckCodeOptions } from "./args";
+import { createCheckCodeDependencies } from "./dependencies";
+
+export { parseCheckCodeOptions } from "./args";
+
+export const runCheckCodeWorkflow = async (
+  argv: string[] = process.argv.slice(2),
+  defaultRoot: string = process.cwd(),
+): Promise<CheckCodeRunReport> => {
+  const options = parseCheckCodeOptions(argv, defaultRoot);
+  const runtime = createCheckCodeDependencies(options.root);
+  try {
+    return await runCheckCode(options, runtime.dependencies);
+  } finally {
+    runtime.dispose();
+  }
+};

package/runtime/workflow/lib/checkCode/plan.ts

@@ -0,0 +1,163 @@
+import fs from "fs";
+import path from "path";
+
+export interface CheckCodePlanTarget {
+  network: string;
+  manifestDir: string;
+  contracts: string[];
+}
+
+export interface CheckCodePlanInput {
+  root: string;
+  runId: string;
+  artifactHash: string;
+  deploymentId?: string;
+  sourceSuperTaskId?: string;
+  developmentNetwork?: string;
+  executionId?: string;
+  targets: CheckCodePlanTarget[];
+}
+
+export interface CheckCodePlanResult {
+  planPath: string;
+  runId: string;
+  artifactHash: string;
+}
+
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,199}$/;
+const HASH = /^[0-9a-f]{64}$/;
+const MANIFEST_DIR = /^\.openzeppelin(?:\.[a-z0-9][a-z0-9-]*)?$/;
+
+const safeId = (value: string, label: string): string => {
+  if (!SAFE_ID.test(value)) throw new Error(`${label} is invalid`);
+  return value;
+};
+
+const superTaskIdentity = (input: CheckCodePlanInput): boolean => {
+  const values = [
+    input.deploymentId,
+    input.sourceSuperTaskId,
+    input.developmentNetwork,
+    input.executionId,
+  ];
+  if (values.every(Boolean)) return true;
+  if (values.some(Boolean)) {
+    throw new Error(
+      "SuperTask CheckCode plan requires deploymentId, sourceSuperTaskId, developmentNetwork, and executionId together",
+    );
+  }
+  return false;
+};
+
+const writeTextAtomic = (filePath: string, contents: string): void => {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const temporary = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    fs.writeFileSync(temporary, contents);
+    fs.renameSync(temporary, filePath);
+  } catch (error) {
+    if (fs.existsSync(temporary)) fs.unlinkSync(temporary);
+    throw error;
+  }
+};
+
+export const prepareCheckCodePlan = (
+  input: CheckCodePlanInput,
+): CheckCodePlanResult => {
+  const runId = safeId(input.runId, "CheckCode runId");
+  if (!HASH.test(input.artifactHash)) throw new Error("CheckCode artifactHash is invalid");
+  const isSuperTask = superTaskIdentity(input);
+  const targets = [...input.targets]
+    .map((target) => ({
+      network: safeId(target.network, "CheckCode target network"),
+      manifestDir: target.manifestDir,
+      contracts: [...new Set(target.contracts.map((item) => item.trim()).filter(Boolean))].sort(),
+    }))
+    .sort((left, right) => left.network.localeCompare(right.network));
+  if (targets.length === 0) throw new Error("CheckCode plan requires at least one target");
+  if (new Set(targets.map((target) => target.network)).size !== targets.length) {
+    throw new Error("CheckCode plan target networks must be unique");
+  }
+  for (const target of targets) {
+    if (!MANIFEST_DIR.test(target.manifestDir)) {
+      throw new Error(`CheckCode manifestDir is invalid for ${target.network}`);
+    }
+  }
+  if (isSuperTask && (
+    targets.length !== 1 || targets[0].network !== input.developmentNetwork
+  )) {
+    throw new Error("SuperTask CheckCode plan must target only developmentNetwork");
+  }
+
+  const relativePath = isSuperTask
+    ? `scripts/tasks/${safeId(input.deploymentId!, "deploymentId")}/docs/checkcode-plan.md`
+    : "docs/checkcode-plan.md";
+  const lines = [
+    "# CheckCode Plan",
+    "",
+    `runId: ${runId}`,
+    `artifactHash: ${input.artifactHash}`,
+    ...(isSuperTask ? [
+      `deploymentId: ${safeId(input.deploymentId!, "deploymentId")}`,
+      `sourceSuperTaskId: ${safeId(input.sourceSuperTaskId!, "sourceSuperTaskId")}`,
+      `developmentNetwork: ${safeId(input.developmentNetwork!, "developmentNetwork")}`,
+      `executionId: ${safeId(input.executionId!, "executionId")}`,
+    ] : []),
+    "",
+    "## Targets",
+    ...targets.flatMap((target) => [
+      `- network: ${target.network}`,
+      `  manifestDir: ${target.manifestDir}`,
+      `  contracts: ${target.contracts.join(", ") || "<all>"}`,
+    ]),
+    "",
+  ];
+  writeTextAtomic(path.join(input.root, ...relativePath.split("/")), lines.join("\n"));
+  return { planPath: relativePath, runId, artifactHash: input.artifactHash };
+};
+
+export const runCheckCodePlanCli = (
+  argv: string[],
+  defaultRoot: string = process.cwd(),
+): CheckCodePlanResult => {
+  const values = new Map<string, string[]>();
+  for (let index = 0; index < argv.length; index += 1) {
+    const item = argv[index];
+    if (!item.startsWith("--")) continue;
+    const equalAt = item.indexOf("=");
+    const key = item.slice(2, equalAt > 2 ? equalAt : undefined);
+    const next = argv[index + 1];
+    const value = equalAt > 2 ? item.slice(equalAt + 1) : next;
+    if (!value || value.startsWith("--")) throw new Error(`--${key} requires a value`);
+    if (equalAt < 0) index += 1;
+    const current = values.get(key) || [];
+    current.push(value);
+    values.set(key, current);
+  }
+  const one = (key: string, required = false): string | undefined => {
+    const items = values.get(key) || [];
+    if (items.length > 1) throw new Error(`--${key} may be provided only once`);
+    if (required && !items[0]?.trim()) throw new Error(`--${key} is required`);
+    return items[0]?.trim() || undefined;
+  };
+  const developmentNetwork = one("developmentNetwork");
+  const network = one("network") || developmentNetwork;
+  if (!network) throw new Error("--network or --developmentNetwork is required");
+  return prepareCheckCodePlan({
+    root: path.resolve(one("root") || defaultRoot),
+    runId: one("runId", true)!,
+    artifactHash: one("artifactHash", true)!,
+    deploymentId: one("deploymentId"),
+    sourceSuperTaskId: one("sourceSuperTaskId"),
+    developmentNetwork,
+    executionId: one("executionId"),
+    targets: [{
+      network,
+      manifestDir: one("manifestDir", true)!,
+      contracts: (values.get("contract") || [])
+        .flatMap((item) => item.split(","))
+        .map((item) => item.trim())
+        .filter(Boolean),
+    }],
+  });
+};

package/runtime/workflow/lib/checkCodeReport.ts

@@ -0,0 +1,133 @@
+import fs from "fs";
+import path from "path";
+
+export interface CheckCodeEvidenceEntry {
+  status: "passed";
+  network: string;
+  scheme: "evm" | "zksync-eravm";
+  instanceId: string;
+  contractInfoKey: string;
+  address: string;
+  artifactHash: string;
+  runId: string;
+  checkedAt: string;
+}
+
+export interface CheckCodeEvidenceIndex {
+  version: 1;
+  entries: Record<string, CheckCodeEvidenceEntry>;
+}
+
+export interface ReusableDeploymentExpectation {
+  network: string;
+  scheme: "evm" | "zksync-eravm";
+  instanceId: string;
+  address: string;
+  artifactHash: string;
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> => {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+};
+
+const evidenceIndexPath = (root: string): string => {
+  return path.join(root, "scripts", "checkcode", "index.json");
+};
+
+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;
+  }
+};
+
+export const loadCheckCodeEvidenceIndex = (root: string): CheckCodeEvidenceIndex => {
+  const filePath = evidenceIndexPath(root);
+  if (!fs.existsSync(filePath)) {
+    throw new Error("Existing deployment has no passed CheckCode evidence index");
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch (error) {
+    throw new Error(
+      "CheckCode evidence index must contain valid JSON: "
+      + (error instanceof Error ? error.message : String(error)),
+    );
+  }
+  if (!isRecord(parsed) || parsed.version !== 1 || !isRecord(parsed.entries)) {
+    throw new Error("CheckCode evidence index must contain version 1 entries");
+  }
+
+  const entries: Record<string, CheckCodeEvidenceEntry> = {};
+  for (const [key, entryValue] of Object.entries(parsed.entries)) {
+    if (!isRecord(entryValue) || entryValue.status !== "passed") {
+      throw new Error("CheckCode evidence entry " + key + " must have passed status");
+    }
+    for (const field of [
+      "network",
+      "scheme",
+      "instanceId",
+      "contractInfoKey",
+      "address",
+      "artifactHash",
+      "runId",
+      "checkedAt",
+    ] as const) {
+      if (typeof entryValue[field] !== "string" || !String(entryValue[field]).trim()) {
+        throw new Error("CheckCode evidence entry " + key + "." + field + " is required");
+      }
+    }
+    entries[key] = entryValue as unknown as CheckCodeEvidenceEntry;
+  }
+  return { version: 1, entries };
+};
+
+export const assertReusableDeployment = (
+  root: string,
+  expected: ReusableDeploymentExpectation,
+): CheckCodeEvidenceEntry => {
+  const index = loadCheckCodeEvidenceIndex(root);
+  const evidence = Object.values(index.entries).find((entry) => (
+    entry.network === expected.network && entry.instanceId === expected.instanceId
+  ));
+  if (!evidence) {
+    throw new Error(
+      "Existing deployment " + expected.network + "." + expected.instanceId
+      + " has no passed CheckCode evidence",
+    );
+  }
+  if (evidence.address.toLowerCase() !== expected.address.toLowerCase()) {
+    throw new Error("CheckCode address does not match the existing deployment");
+  }
+  if (evidence.scheme !== expected.scheme) {
+    throw new Error("CheckCode scheme does not match the existing deployment");
+  }
+  if (evidence.artifactHash !== expected.artifactHash) {
+    throw new Error("CheckCode artifactHash does not match the execution artifactHash");
+  }
+  return evidence;
+};
+
+export const updateCheckCodeEvidenceIndex = (
+  root: string,
+  evidenceEntries: CheckCodeEvidenceEntry[],
+): CheckCodeEvidenceIndex => {
+  const filePath = evidenceIndexPath(root);
+  let current: CheckCodeEvidenceIndex = { version: 1, entries: {} };
+  if (fs.existsSync(filePath)) {
+    current = loadCheckCodeEvidenceIndex(root);
+  }
+  const entries = { ...current.entries };
+  for (const evidence of evidenceEntries) {
+    entries[evidence.network + "." + evidence.instanceId] = evidence;
+  }
+  const next = { version: 1 as const, entries };
+  writeJsonAtomic(filePath, next);
+  return next;
+};