gate-evm-tools 1.0.26 → 1.0.27

package/runtime/workflow/lib/gateToolSync.ts

@@ -0,0 +1,398 @@
+import crypto from "crypto";
+import fs from "fs";
+import path from "path";
+import hardhat from "../../projectHardhat";
+import { syncWithHre } from "gate-evm-tools/sync";
+import { writeJsonFile } from "./config";
+
+export interface GateToolSyncEvidence {
+  outputPath: string;
+  data: Record<string, unknown>;
+}
+
+export type GateToolSyncHre = Parameters<typeof syncWithHre>[1];
+
+export interface SyncGateToolUupsOptions {
+  root: string;
+  evidenceDir: string;
+  evidenceName: string;
+  scheme: "evm" | "zksync-eravm";
+  network: string;
+  target: string;
+  manifestDir: string;
+  proxy: string;
+  implementation: string;
+  contract: string;
+  constructorArgs: unknown[];
+  transactionHash: string;
+  hre?: GateToolSyncHre;
+}
+
+const SAFE_FILE_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,199}$/;
+const HASH = /^[a-f0-9]{64}$/;
+const TRANSACTION_HASH = /^0x[a-fA-F0-9]{64}$/;
+
+const confinedPath = (root: string, requested: string, label: string): string => {
+  const resolvedRoot = path.resolve(root);
+  const resolved = path.resolve(requested);
+  const relative = path.relative(resolvedRoot, resolved);
+  if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw new Error(`${label} must be inside the project root`);
+  }
+  let current = resolvedRoot;
+  for (const segment of relative.split(path.sep).filter(Boolean)) {
+    current = path.join(current, segment);
+    if (fs.existsSync(current) && fs.lstatSync(current).isSymbolicLink()) {
+      throw new Error(`${label} path cannot contain a symlink`);
+    }
+  }
+  return resolved;
+};
+
+const record = (value: unknown, label: string): Record<string, unknown> => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must be an object`);
+  }
+  return value as Record<string, unknown>;
+};
+
+const stringField = (value: Record<string, unknown>, key: string): string => {
+  const field = value[key];
+  if (typeof field !== "string" || !field) {
+    throw new Error(`GateTool sync result is missing ${key}`);
+  }
+  return field;
+};
+
+const sameAddress = (left: string, right: string): boolean => (
+  left.toLowerCase() === right.toLowerCase()
+);
+
+const readRegularBytes = (filePath: string, label: string): Buffer => {
+  const stat = fs.lstatSync(filePath);
+  if (!stat.isFile()) throw new Error(`${label} must be a regular file`);
+  return fs.readFileSync(filePath);
+};
+
+const jsonFromBytes = (contents: Buffer, label: string): Record<string, unknown> => {
+  return record(JSON.parse(contents.toString("utf8")) as unknown, label);
+};
+
+const canonicalJsonBytes = (value: unknown): Buffer => (
+  Buffer.from(`${JSON.stringify(value, null, 2)}\n`)
+);
+
+const writeImmutableFile = (
+  filePath: string,
+  contents: Buffer,
+  root: string,
+  label: string,
+): Buffer => {
+  const confined = confinedPath(root, filePath, label);
+  fs.mkdirSync(path.dirname(confined), { recursive: true });
+  confinedPath(root, path.dirname(confined), `${label} directory`);
+  if (fs.existsSync(confined)) {
+    const existing = readRegularBytes(confined, label);
+    if (!existing.equals(contents)) {
+      throw new Error(`${label} already exists with different bytes`);
+    }
+    return existing;
+  }
+
+  const temporary = confinedPath(
+    root,
+    `${confined}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`,
+    `${label} temporary file`,
+  );
+  let descriptor: number | undefined;
+  try {
+    descriptor = fs.openSync(temporary, "wx", 0o600);
+    fs.writeFileSync(descriptor, contents);
+    fs.fsyncSync(descriptor);
+    fs.closeSync(descriptor);
+    descriptor = undefined;
+    try {
+      fs.linkSync(temporary, confined);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+      const existing = readRegularBytes(confined, label);
+      if (!existing.equals(contents)) {
+        throw new Error(`${label} already exists with different bytes`);
+      }
+    }
+    const stored = readRegularBytes(confined, label);
+    if (!stored.equals(contents)) {
+      throw new Error(`${label} does not match the committed source report`);
+    }
+    return stored;
+  } finally {
+    if (descriptor !== undefined) fs.closeSync(descriptor);
+    if (fs.existsSync(temporary)) fs.unlinkSync(temporary);
+  }
+};
+
+const validateManifestTransaction = (
+  syncReport: Record<string, unknown>,
+  options: SyncGateToolUupsOptions,
+): void => {
+  if (
+    syncReport.version !== 1
+    || syncReport.status !== "committed"
+    || typeof syncReport.beforeHash !== "string"
+    || typeof syncReport.afterHash !== "string"
+    || !HASH.test(syncReport.beforeHash)
+    || !HASH.test(syncReport.afterHash)
+  ) {
+    throw new Error("GateTool manifest transaction report is not committed evidence");
+  }
+  const manifestFile = stringField(syncReport, "manifestFile");
+  const expectedManifestRoot = path.resolve(options.root, options.manifestDir);
+  const resolvedManifest = path.resolve(options.root, manifestFile);
+  if (!resolvedManifest.startsWith(`${expectedManifestRoot}${path.sep}`)) {
+    throw new Error("GateTool sync wrote outside the target manifest directory");
+  }
+};
+
+const validateEvidenceIdentity = (
+  raw: Record<string, unknown>,
+  options: SyncGateToolUupsOptions,
+): void => {
+  if (
+    raw.version !== 1
+    || raw.status !== "succeeded"
+    || raw.evidenceName !== options.evidenceName
+    || raw.scheme !== options.scheme
+    || raw.network !== options.network
+    || raw.target !== options.target
+    || raw.manifestDir !== options.manifestDir
+    || raw.contract !== options.contract
+    || JSON.stringify(raw.constructorArgs) !== JSON.stringify(options.constructorArgs)
+    || raw.transactionHash !== options.transactionHash.toLowerCase()
+    || typeof raw.proxy !== "string"
+    || typeof raw.implementation !== "string"
+    || !sameAddress(raw.proxy, options.proxy)
+    || !sameAddress(raw.implementation, options.implementation)
+  ) {
+    throw new Error(
+      "GateTool sync metadata identity does not match the immutable UUPS receipt",
+    );
+  }
+};
+
+const validateEvidenceBinding = (
+  raw: Record<string, unknown>,
+  options: SyncGateToolUupsOptions,
+  expectedSyncReportPath: string,
+): { syncReport: Record<string, unknown>; syncReportBytes: Buffer } => {
+  validateEvidenceIdentity(raw, options);
+  const syncReportPath = confinedPath(
+    options.root,
+    path.resolve(options.root, stringField(raw, "syncReportPath")),
+    "GateTool manifest transaction report",
+  );
+  if (syncReportPath !== expectedSyncReportPath) {
+    throw new Error("GateTool sync evidence does not reference its immutable report snapshot");
+  }
+  const syncReport = record(
+    raw.manifestTransaction,
+    "GateTool sync manifest transaction",
+  );
+  validateManifestTransaction(syncReport, options);
+  const syncReportBytes = canonicalJsonBytes(syncReport);
+  const syncReportHash = crypto
+    .createHash("sha256")
+    .update(syncReportBytes)
+    .digest("hex");
+  if (
+    raw.syncReportHash !== syncReportHash
+    || raw.completedAt !== syncReport.completedAt
+  ) {
+    throw new Error("GateTool sync evidence does not match its committed manifest transaction");
+  }
+  return { syncReport, syncReportBytes };
+};
+
+const validateExistingEvidence = (
+  raw: Record<string, unknown>,
+  options: SyncGateToolUupsOptions,
+  expectedSyncReportPath: string,
+): void => {
+  const binding = validateEvidenceBinding(raw, options, expectedSyncReportPath);
+  const storedBytes = readRegularBytes(
+    expectedSyncReportPath,
+    "GateTool manifest transaction snapshot",
+  );
+  if (!storedBytes.equals(binding.syncReportBytes)) {
+    throw new Error("GateTool sync evidence does not match its immutable report snapshot");
+  }
+};
+
+const buildSyncEvidence = (
+  options: SyncGateToolUupsOptions,
+  syncReportPath: string,
+  syncReportBytes: Buffer,
+  syncReport: Record<string, unknown>,
+): Record<string, unknown> => ({
+  version: 1,
+  status: "succeeded",
+  evidenceName: options.evidenceName,
+  scheme: options.scheme,
+  network: options.network,
+  target: options.target,
+  manifestDir: options.manifestDir,
+  proxy: options.proxy.toLowerCase(),
+  implementation: options.implementation.toLowerCase(),
+  contract: options.contract,
+  constructorArgs: options.constructorArgs,
+  transactionHash: options.transactionHash.toLowerCase(),
+  syncReportPath: path.relative(options.root, syncReportPath).split(path.sep).join("/"),
+  syncReportHash: crypto.createHash("sha256").update(syncReportBytes).digest("hex"),
+  manifestTransaction: syncReport,
+  completedAt: syncReport.completedAt,
+});
+
+export const syncGateToolUups = async (
+  options: SyncGateToolUupsOptions,
+): Promise<GateToolSyncEvidence> => {
+  if (!SAFE_FILE_ID.test(options.evidenceName)) {
+    throw new Error(`GateTool sync evidenceName must match ${SAFE_FILE_ID}`);
+  }
+  if (!TRANSACTION_HASH.test(options.transactionHash)) {
+    throw new Error("GateTool sync requires a confirmed transaction hash");
+  }
+  const evidenceDir = confinedPath(
+    options.root,
+    options.evidenceDir,
+    "GateTool sync evidence directory",
+  );
+  const outputPath = confinedPath(
+    options.root,
+    path.join(evidenceDir, `${options.evidenceName}-sync.json`),
+    "GateTool sync evidence",
+  );
+  const syncReportSnapshotPath = confinedPath(
+    options.root,
+    path.join(evidenceDir, `${options.evidenceName}-manifest-transaction.json`),
+    "GateTool manifest transaction snapshot",
+  );
+  const syncMetadataPath = confinedPath(
+    options.root,
+    path.join(evidenceDir, `${options.evidenceName}-manifest-transaction-metadata.json`),
+    "GateTool manifest transaction metadata",
+  );
+  const relativeOutputPath = path.relative(options.root, outputPath).split(path.sep).join("/");
+  if (fs.existsSync(outputPath)) {
+    const outputBytes = readRegularBytes(outputPath, "GateTool sync evidence");
+    const data = jsonFromBytes(outputBytes, "GateTool sync evidence");
+    if (!fs.existsSync(syncMetadataPath)) {
+      throw new Error("GateTool sync evidence is missing its immutable identity metadata");
+    }
+    const metadataBytes = readRegularBytes(
+      syncMetadataPath,
+      "GateTool manifest transaction metadata",
+    );
+    if (!outputBytes.equals(metadataBytes)) {
+      throw new Error("GateTool sync evidence does not match its immutable identity metadata");
+    }
+    validateExistingEvidence(data, options, syncReportSnapshotPath);
+    return { outputPath: relativeOutputPath, data };
+  }
+  if (fs.existsSync(syncMetadataPath)) {
+    const metadataBytes = readRegularBytes(
+      syncMetadataPath,
+      "GateTool manifest transaction metadata",
+    );
+    const data = jsonFromBytes(
+      metadataBytes,
+      "GateTool manifest transaction metadata",
+    );
+    if (!metadataBytes.equals(canonicalJsonBytes(data))) {
+      throw new Error("GateTool manifest transaction metadata must be canonical JSON");
+    }
+    const binding = validateEvidenceBinding(
+      data,
+      options,
+      syncReportSnapshotPath,
+    );
+    writeImmutableFile(
+      syncReportSnapshotPath,
+      binding.syncReportBytes,
+      options.root,
+      "GateTool manifest transaction snapshot",
+    );
+    validateExistingEvidence(data, options, syncReportSnapshotPath);
+    writeJsonFile(outputPath, data);
+    return { outputPath: relativeOutputPath, data };
+  }
+  if (fs.existsSync(syncReportSnapshotPath)) {
+    throw new Error(
+      "GateTool manifest transaction snapshot is missing immutable identity metadata",
+    );
+  }
+
+  const rawResult = record(await syncWithHre({
+    scheme: options.scheme,
+    network: options.network,
+    target: options.target,
+    proxy: options.proxy,
+    contract: options.contract,
+    constructorArgs: options.constructorArgs,
+    ...(options.scheme === "evm"
+      ? { skipTxHash: true }
+      : { transactionHash: options.transactionHash }),
+  }, options.hre ?? hardhat, options.root), "GateTool sync result");
+  const returnedProxy = typeof rawResult.proxyAddress === "string"
+    ? rawResult.proxyAddress
+    : stringField(rawResult, "proxy");
+  const returnedImplementation = typeof rawResult.implementationAddress === "string"
+    ? rawResult.implementationAddress
+    : stringField(rawResult, "implementation");
+  if (
+    !sameAddress(returnedProxy, options.proxy)
+    || !sameAddress(returnedImplementation, options.implementation)
+  ) {
+    throw new Error("GateTool sync result does not match the confirmed UUPS chain state");
+  }
+  const returnedSyncReport = record(
+    rawResult.manifestTransaction,
+    "GateTool returned manifest transaction",
+  );
+  validateManifestTransaction(returnedSyncReport, options);
+  const returnedSyncReportBytes = canonicalJsonBytes(returnedSyncReport);
+
+  const syncReportPath = confinedPath(
+    options.root,
+    stringField(rawResult, "syncReport"),
+    "GateTool manifest transaction report",
+  );
+  const sourceSyncReportBytes = readRegularBytes(
+    syncReportPath,
+    "GateTool manifest transaction report",
+  );
+  if (!sourceSyncReportBytes.equals(returnedSyncReportBytes)) {
+    throw new Error(
+      "GateTool source report does not match its returned manifest transaction",
+    );
+  }
+
+  const data = buildSyncEvidence(
+    options,
+    syncReportSnapshotPath,
+    returnedSyncReportBytes,
+    returnedSyncReport,
+  );
+  writeImmutableFile(
+    syncMetadataPath,
+    canonicalJsonBytes(data),
+    options.root,
+    "GateTool manifest transaction metadata",
+  );
+  writeImmutableFile(
+    syncReportSnapshotPath,
+    returnedSyncReportBytes,
+    options.root,
+    "GateTool manifest transaction snapshot",
+  );
+  writeJsonFile(outputPath, data);
+  return { outputPath: relativeOutputPath, data };
+};