gate-evm-tools 1.0.25 → 1.0.27

package/runtime/workflow/cli.ts

@@ -0,0 +1,356 @@
+import { createRequire } from "module";
+import { spawn, spawnSync, type ChildProcess } from "child_process";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "fs";
+import { tmpdir } from "os";
+import path from "path";
+import { openZeppelinProcessEnvironment } from "../config/openzeppelin";
+import { resolveCliTool } from "./lib/cliTool";
+import { validateExecutionId } from "./lib/executionId";
+import {
+  buildForkSnapshot,
+  isCapturedZkSyncChainSnapshot,
+  parseCapturedChainSnapshot,
+  type CapturedChainSnapshotV1,
+} from "./lib/forkSnapshot";
+import {
+  resolveZkSyncForkRunner,
+  startZkSyncForkRunner,
+  type RunningZkSyncFork,
+} from "./lib/zksyncForkRunner";
+
+type ArgValue = string | boolean;
+
+const WORKFLOW_ARG_KEYS = new Set([
+  "mode",
+  "target",
+  "step",
+  "from",
+  "executionId",
+  "useLock",
+  "sourceSuperTaskId",
+  "mergeCommit",
+  "parameterOverrides",
+  "existingDeploymentPolicies",
+  "simulationSigner",
+  "operator",
+  "releaseKind",
+]);
+
+const parseArgs = (argv: string[]): Record<string, ArgValue> => {
+  const args: Record<string, ArgValue> = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const item = argv[index];
+    if (!item.startsWith("--")) continue;
+
+    const equalIndex = item.indexOf("=");
+    if (equalIndex > 2) {
+      args[item.slice(2, equalIndex)] = item.slice(equalIndex + 1);
+      continue;
+    }
+
+    const key = item.slice(2);
+    const next = argv[index + 1];
+    if (!next || next.startsWith("--")) {
+      args[key] = true;
+    } else {
+      args[key] = next;
+      index += 1;
+    }
+  }
+  return args;
+};
+
+const stringArg = (
+  args: Record<string, ArgValue>,
+  key: string,
+): string | undefined => {
+  const value = args[key];
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+};
+
+interface SourceProxyHandshake {
+  proxyUrl: string;
+  snapshot: CapturedChainSnapshotV1;
+  zksync: boolean;
+}
+
+const delay = (milliseconds: number): Promise<void> => new Promise(
+  (resolve) => setTimeout(resolve, milliseconds),
+);
+
+const loopbackProxyUrl = (value: unknown): string => {
+  if (typeof value !== "string") throw new Error("Source-chain proxy handshake URL is missing");
+  let parsed: URL;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw new Error("Source-chain proxy handshake URL is invalid");
+  }
+  if (
+    parsed.protocol !== "http:"
+    || parsed.hostname !== "127.0.0.1"
+    || !parsed.port
+    || parsed.pathname === "/"
+    || parsed.username
+    || parsed.password
+    || parsed.search
+    || parsed.hash
+  ) {
+    throw new Error("Source-chain proxy handshake URL must be tokenized and loopback-only");
+  }
+  return parsed.toString();
+};
+
+const parseSourceProxyHandshake = (
+  value: unknown,
+  target: string,
+): SourceProxyHandshake => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("Source-chain proxy handshake must be an object");
+  }
+  const record = value as Record<string, unknown>;
+  const keys = Object.keys(record).sort();
+  if (JSON.stringify(keys) !== JSON.stringify(["proxyUrl", "snapshot", "version", "zksync"])) {
+    throw new Error("Source-chain proxy handshake fields are invalid");
+  }
+  if (record.version !== 1 || typeof record.zksync !== "boolean") {
+    throw new Error("Source-chain proxy handshake metadata is invalid");
+  }
+  return {
+    proxyUrl: loopbackProxyUrl(record.proxyUrl),
+    snapshot: parseCapturedChainSnapshot(record.snapshot, target, record.zksync),
+    zksync: record.zksync,
+  };
+};
+
+const waitForSourceProxy = async (
+  child: ChildProcess,
+  handshakePath: string,
+  target: string,
+): Promise<SourceProxyHandshake> => {
+  let launchError: Error | undefined;
+  child.once("error", (error) => {
+    launchError = error;
+  });
+  const deadline = Date.now() + 30_000;
+  while (Date.now() < deadline) {
+    if (launchError) throw new Error(`Source-chain proxy failed to start: ${launchError.message}`);
+    if (existsSync(handshakePath)) {
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(readFileSync(handshakePath, "utf8"));
+      } catch {
+        throw new Error("Source-chain proxy handshake is not valid JSON");
+      }
+      return parseSourceProxyHandshake(parsed, target);
+    }
+    if (child.exitCode !== null) {
+      throw new Error(`Source-chain proxy exited before readiness with code ${child.exitCode}`);
+    }
+    await delay(50);
+  }
+  throw new Error("Source-chain proxy readiness timed out");
+};
+
+const stopChild = async (
+  child: ChildProcess | undefined,
+  signal: NodeJS.Signals,
+): Promise<void> => {
+  if (!child || child.exitCode !== null) return;
+  child.kill(signal);
+  const exited = new Promise<void>((resolve) => child.once("exit", () => resolve()));
+  await Promise.race([exited, delay(2_000)]);
+  if (child.exitCode === null) {
+    child.kill("SIGKILL");
+    await Promise.race([exited, delay(2_000)]);
+  }
+};
+
+const runChild = async (
+  command: string,
+  commandArgs: string[],
+  env: NodeJS.ProcessEnv,
+): Promise<number> => {
+  const child = spawn(command, commandArgs, { env, stdio: "inherit" });
+  let forwardedSignal: NodeJS.Signals | undefined;
+  const forward = (signal: NodeJS.Signals) => {
+    forwardedSignal = signal;
+    child.kill(signal);
+  };
+  const interrupt = () => forward("SIGINT");
+  const terminate = () => forward("SIGTERM");
+  process.once("SIGINT", interrupt);
+  process.once("SIGTERM", terminate);
+  try {
+    return await new Promise<number>((resolve) => {
+      child.once("error", (error) => {
+        console.error(error);
+        resolve(1);
+      });
+      child.once("exit", (code) => resolve(forwardedSignal ? 1 : code ?? 1));
+    });
+  } finally {
+    process.removeListener("SIGINT", interrupt);
+    process.removeListener("SIGTERM", terminate);
+  }
+};
+
+const hardhatVersion = (): string => {
+  const value = (createRequire(path.join(process.cwd(), "package.json"))("hardhat/package.json") as { version?: unknown }).version;
+  if (typeof value !== "string" || !value) {
+    throw new Error("Cannot resolve the installed Hardhat version");
+  }
+  return value;
+};
+
+const main = async (): Promise<number> => {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (args.checkcode === true) {
+    const forwardedArgs = process.argv.slice(2).filter((item) => item !== "--checkcode");
+    const tsNode = resolveCliTool({ root: process.cwd(), binary: "ts-node" });
+    const result = spawnSync(
+      tsNode.command,
+      [...tsNode.argsPrefix, path.join(__dirname, "checkCode.js"), ...forwardedArgs],
+      { env: process.env, stdio: "inherit" },
+    );
+    if (result.error) console.error(result.error);
+    return result.error ? 1 : result.status ?? 1;
+  }
+
+  if (Object.hasOwn(args, "executionId")) {
+    validateExecutionId(args.executionId);
+  }
+
+  const requestedNetwork = stringArg(args, "network") || "hardhat";
+  const mode = stringArg(args, "mode") || "execute";
+  const target = stringArg(args, "target") || requestedNetwork;
+  const task = stringArg(args, "task") || process.env.WORKFLOW_TASK;
+
+  const workflowArgs = Object.fromEntries(
+    Object.entries(args).filter(([key]) => WORKFLOW_ARG_KEYS.has(key)),
+  ) as Record<string, ArgValue>;
+  const remoteSimulation = mode === "simulate"
+    && target !== "hardhat"
+    && target !== "localhost";
+  if (remoteSimulation && requestedNetwork !== "hardhat") {
+    throw new Error("Remote simulation must be invoked with --network hardhat");
+  }
+
+  const hardhat = resolveCliTool({ root: process.cwd(), binary: "hardhat" });
+  let sourceProcess: ChildProcess | undefined;
+  let zkSyncFork: RunningZkSyncFork | undefined;
+  let temporaryDirectory: string | undefined;
+  try {
+    let runtimeNetwork = requestedNetwork;
+    const runtimeWorkflowArgs = { ...workflowArgs };
+    let forkEnvironment: NodeJS.ProcessEnv = {};
+    if (remoteSimulation) {
+      temporaryDirectory = mkdtempSync(path.join(tmpdir(), "gate-current-chain-fork-"));
+      const handshakePath = path.join(temporaryDirectory, "source-proxy.json");
+      const sourceEnvironment = { ...process.env };
+      delete sourceEnvironment.GATE_SIMULATION_FORK_SNAPSHOT_JSON;
+      delete sourceEnvironment.GATE_SIMULATION_SOURCE_RPC_URL;
+      delete sourceEnvironment.HARDHAT_FORK_CHAIN_ID;
+      sourceEnvironment.GATE_FORK_PROXY_HANDSHAKE = handshakePath;
+      sourceEnvironment.GATE_FORK_SOURCE_READ_ONLY = "1";
+      // Explicit empty values prevent dotenv from reintroducing project
+      // credentials into the real-network source process.
+      sourceEnvironment.WALLET_CREDENTIAL = "";
+      sourceEnvironment.PRIVATE_KEY = "";
+      sourceProcess = spawn(
+        hardhat.command,
+        [
+          ...hardhat.argsPrefix,
+          "run",
+          path.join(__dirname, "forkSourceProxy.js"),
+          "--network",
+          target,
+          "--no-compile",
+        ],
+        { env: sourceEnvironment, stdio: "inherit" },
+      );
+      const source = await waitForSourceProxy(sourceProcess, handshakePath, target);
+      if (source.zksync) {
+        if (!isCapturedZkSyncChainSnapshot(source.snapshot)) {
+          throw new Error("zkSync source snapshot is missing protocol metadata");
+        }
+        const runner = resolveZkSyncForkRunner(source.snapshot.protocolVersion);
+        if (!runner) {
+          throw new Error(
+            `Unsupported zkSync protocol ${source.snapshot.protocolVersion}: `
+            + "install a workflow dependency with an approved EraVM fork runner and retry",
+          );
+        }
+        const snapshot = buildForkSnapshot(source.snapshot, runner);
+        if (snapshot.runner.kind !== "anvil-zksync") {
+          throw new Error("zkSync source snapshot selected an invalid fork runner");
+        }
+        zkSyncFork = await startZkSyncForkRunner({
+          sourceProxyUrl: source.proxyUrl,
+          snapshot,
+        });
+        runtimeNetwork = "zkFork";
+        forkEnvironment = {
+          GATE_SIMULATION_FORK_SNAPSHOT_JSON: JSON.stringify(snapshot),
+          GATE_SIMULATION_SOURCE_RPC_URL: source.proxyUrl,
+          GATE_ZKSYNC_FORK_RPC_URL: zkSyncFork.rpcUrl,
+          HARDHAT_FORK_CHAIN_ID: String(snapshot.chainId),
+        };
+      } else {
+        const snapshot = buildForkSnapshot(source.snapshot, {
+          kind: "hardhat",
+          version: hardhatVersion(),
+        });
+        runtimeNetwork = "hardhat";
+        forkEnvironment = {
+          GATE_SIMULATION_FORK_SNAPSHOT_JSON: JSON.stringify(snapshot),
+          GATE_SIMULATION_SOURCE_RPC_URL: source.proxyUrl,
+          HARDHAT_FORK_CHAIN_ID: String(snapshot.chainId),
+        };
+      }
+    }
+
+    const manifestBaseEnv = { ...process.env, ...forkEnvironment };
+    const manifestEnv = openZeppelinProcessEnvironment({
+      root: process.cwd(),
+      network: runtimeNetwork,
+      mode,
+      target: target,
+      env: manifestBaseEnv,
+    });
+    const env = {
+      ...manifestEnv,
+      ...forkEnvironment,
+      WORKFLOW_ARGS_JSON: JSON.stringify(runtimeWorkflowArgs),
+      ...(task ? { WORKFLOW_TASK: task } : {}),
+    };
+
+    const hardhatArgs = [
+      ...hardhat.argsPrefix,
+      "run",
+      path.join(__dirname, "run.js"),
+      "--network",
+      runtimeNetwork,
+    ];
+    if (args["no-compile"] === true) {
+      hardhatArgs.push("--no-compile");
+    }
+    return await runChild(hardhat.command, hardhatArgs, env);
+  } finally {
+    await zkSyncFork?.stop();
+    await stopChild(sourceProcess, "SIGTERM");
+    if (temporaryDirectory) {
+      rmSync(temporaryDirectory, { recursive: true, force: true });
+    }
+  }
+};
+
+main()
+  .then((status) => {
+    process.exitCode = status;
+  })
+  .catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  });

package/runtime/workflow/commitContractInfo.ts

@@ -0,0 +1,63 @@
+import path from "path";
+import {
+  commitVerifiedContractInfo,
+  RegistryCommitSelection,
+} from "./lib/registryCommit";
+
+const parseArgs = (argv: string[]): Record<string, string[]> => {
+  const args: Record<string, string[]> = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const item = argv[index];
+    if (!item.startsWith("--")) continue;
+    const key = item.slice(2);
+    const value = argv[index + 1];
+    if (!value || value.startsWith("--")) throw new Error(`--${key} requires a value`);
+    (args[key] ||= []).push(value);
+    index += 1;
+  }
+  return args;
+};
+
+const single = (args: Record<string, string[]>, key: string, required = false): string | undefined => {
+  const values = args[key] || [];
+  if (values.length > 1) throw new Error(`--${key} may be provided only once`);
+  const value = values[0]?.trim();
+  if (required && !value) throw new Error(`--${key} is required`);
+  return value;
+};
+
+const selection = (value: string): RegistryCommitSelection => {
+  const index = value.indexOf("=");
+  if (index <= 0 || index === value.length - 1) {
+    throw new Error("--selection must use <network>=<executionId>");
+  }
+  return { network: value.slice(0, index), executionId: value.slice(index + 1) };
+};
+
+const main = (): void => {
+  if (process.env.GATEFLOW_NODE_KEY?.trim() === "DevelopmentDeployExecute") {
+    throw new Error(
+      "GateFlow node DevelopmentDeployExecute cannot run workflow:commit-contract-info",
+    );
+  }
+  const args = parseArgs(process.argv.slice(2));
+  const report = commitVerifiedContractInfo({
+    root: path.resolve(single(args, "root") || process.cwd()),
+    taskId: single(args, "task", true) as string,
+    commitId: single(args, "commitId", true) as string,
+    selections: (args.selection || []).map(selection),
+  });
+  console.log(JSON.stringify({
+    status: report.status,
+    commitId: report.commitId,
+    selections: report.selections,
+    afterHash: report.afterHash,
+  }));
+};
+
+try {
+  main();
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}

package/runtime/workflow/create2Hashes.ts

@@ -0,0 +1,79 @@
+import fs from "node:fs";
+import path from "node:path";
+import type { InterfaceAbi } from "ethers";
+import {
+  canonicalCreate2Hashes,
+  normalizeCreate2Scheme,
+} from "./lib/create2Hashes";
+
+type ArgValue = string | boolean;
+
+const parseArgs = (argv: string[]): Record<string, ArgValue> => {
+  const result: Record<string, ArgValue> = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const item = argv[index];
+    if (!item.startsWith("--")) continue;
+    const key = item.slice(2);
+    const next = argv[index + 1];
+    if (!next || next.startsWith("--")) {
+      result[key] = true;
+    } else {
+      result[key] = next;
+      index += 1;
+    }
+  }
+  return result;
+};
+
+const requiredString = (args: Record<string, ArgValue>, key: string): string => {
+  const value = args[key];
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error(`workflow:create2-hashes requires --${key} <value>`);
+  }
+  return value.trim();
+};
+
+const confinedArtifactPath = (root: string, value: string): string => {
+  const candidate = path.resolve(root, value);
+  const realRoot = fs.realpathSync(root);
+  const realArtifact = fs.realpathSync(candidate);
+  if (!realArtifact.startsWith(`${realRoot}${path.sep}`)) {
+    throw new Error("--artifact must resolve inside the project workspace");
+  }
+  return realArtifact;
+};
+
+const main = (): void => {
+  const args = parseArgs(process.argv.slice(2));
+  const root = process.cwd();
+  const artifactPath = confinedArtifactPath(root, requiredString(args, "artifact"));
+  const artifact = JSON.parse(fs.readFileSync(artifactPath, "utf8")) as Record<string, unknown>;
+  if (!Array.isArray(artifact.abi)) throw new Error("CREATE2 artifact.abi must be an array");
+  if (typeof artifact.bytecode !== "string" || !artifact.bytecode.startsWith("0x")) {
+    throw new Error("CREATE2 artifact.bytecode must be a hex string");
+  }
+
+  const rawArgs = typeof args["args-json"] === "string" ? args["args-json"] : "[]";
+  const constructorArgs = JSON.parse(rawArgs) as unknown;
+  if (!Array.isArray(constructorArgs)) throw new Error("--args-json must contain a JSON array");
+  const scheme = normalizeCreate2Scheme(
+    typeof args.scheme === "string" ? args.scheme : undefined,
+  );
+  const result = canonicalCreate2Hashes({
+    scheme,
+    artifact: {
+      _format: typeof artifact._format === "string" ? artifact._format : undefined,
+      abi: artifact.abi as InterfaceAbi,
+      bytecode: artifact.bytecode,
+    },
+    args: constructorArgs,
+  });
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+};
+
+try {
+  main();
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}

package/runtime/workflow/forkSourceProxy.ts

@@ -0,0 +1,193 @@
+import { randomUUID } from "crypto";
+import http from "http";
+import { ethers, network } from "../projectHardhat";
+import { writeJsonFile } from "./lib/config";
+import {
+  parseCapturedChainSnapshot,
+  parseZkSyncBlockDetails,
+} from "./lib/forkSnapshot";
+import { isAllowedSourceRpcMethod } from "./lib/sourceRpcPolicy";
+import {
+  ANVIL_ZKSYNC_SOURCE_PATH_SUFFIX,
+  rewriteZkSyncForkRunnerRpcResult,
+} from "./lib/zksyncForkRunner";
+
+const MAX_REQUEST_BYTES = 10 * 1024 * 1024;
+
+interface JsonRpcRequest {
+  jsonrpc: "2.0";
+  id?: string | number | null;
+  method: string;
+  params?: unknown[];
+}
+
+const jsonResponse = (
+  response: http.ServerResponse,
+  statusCode: number,
+  body: unknown,
+): void => {
+  const contents = JSON.stringify(body);
+  response.writeHead(statusCode, {
+    "content-type": "application/json",
+    "content-length": Buffer.byteLength(contents),
+  });
+  response.end(contents);
+};
+
+const rpcError = (
+  id: JsonRpcRequest["id"],
+  code: number,
+  message: string,
+) => ({ jsonrpc: "2.0", id: id ?? null, error: { code, message } });
+
+const forwardRequest = async (
+  value: unknown,
+  runnerSourceProtocolVersion?: number,
+): Promise<unknown> => {
+  if (
+    value === null
+    || typeof value !== "object"
+    || Array.isArray(value)
+  ) {
+    return rpcError(null, -32600, "Invalid JSON-RPC request");
+  }
+  const request = value as Partial<JsonRpcRequest>;
+  if (
+    request.jsonrpc !== "2.0"
+    || typeof request.method !== "string"
+    || !request.method
+    || (request.params !== undefined && !Array.isArray(request.params))
+  ) {
+    return rpcError(request.id, -32600, "Invalid JSON-RPC request");
+  }
+  if (!isAllowedSourceRpcMethod(request.method)) {
+    return rpcError(request.id, -32601, "Source RPC method is not allowed");
+  }
+  try {
+    const result = await network.provider.request({
+      method: request.method,
+      params: request.params || [],
+    });
+    return {
+      jsonrpc: "2.0",
+      id: request.id ?? null,
+      result: runnerSourceProtocolVersion === undefined
+        ? result
+        : rewriteZkSyncForkRunnerRpcResult(
+            request.method,
+            result,
+            runnerSourceProtocolVersion,
+          ),
+    };
+  } catch {
+    return rpcError(request.id, -32000, "Source RPC request failed");
+  }
+};
+
+const readRequestBody = (request: http.IncomingMessage): Promise<string> => new Promise(
+  (resolve, reject) => {
+    const chunks: Buffer[] = [];
+    let size = 0;
+    request.on("data", (chunk: Buffer) => {
+      size += chunk.length;
+      if (size > MAX_REQUEST_BYTES) {
+        reject(new Error("JSON-RPC request is too large"));
+        request.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    request.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+    request.on("error", reject);
+  },
+);
+
+const main = async (): Promise<void> => {
+  const handshakePath = process.env.GATE_FORK_PROXY_HANDSHAKE?.trim();
+  if (!handshakePath) throw new Error("GATE_FORK_PROXY_HANDSHAKE is required");
+
+  const [sourceNetwork, latest, providerNetwork] = await Promise.all([
+    Promise.resolve(network.name),
+    ethers.provider.getBlock("latest"),
+    ethers.provider.getNetwork(),
+  ]);
+  if (!latest || !latest.hash) {
+    throw new Error("Target network latest block is missing its block hash");
+  }
+  const zksync = (network.config as { zksync?: boolean }).zksync === true;
+  const zkSyncBlockDetails = zksync
+    ? parseZkSyncBlockDetails(
+        await network.provider.request({
+          method: "zks_getBlockDetails",
+          params: [latest.number],
+        }),
+        latest.number,
+      )
+    : undefined;
+  const snapshot = parseCapturedChainSnapshot({
+    version: 1,
+    sourceNetwork,
+    chainId: Number(providerNetwork.chainId),
+    blockNumber: latest.number,
+    blockHash: latest.hash,
+    ...(zkSyncBlockDetails ? {
+      protocolVersion: zkSyncBlockDetails.protocolVersion,
+      l1BatchNumber: zkSyncBlockDetails.l1BatchNumber,
+    } : {}),
+  }, sourceNetwork, zksync);
+  const token = randomUUID();
+  const endpointPath = `/${token}`;
+  const runnerEndpointPath = `${endpointPath}${ANVIL_ZKSYNC_SOURCE_PATH_SUFFIX}`;
+  const server = http.createServer(async (request, response) => {
+    const runnerRequest = zksync && request.url === runnerEndpointPath;
+    if (
+      request.method !== "POST"
+      || (request.url !== endpointPath && !runnerRequest)
+    ) {
+      jsonResponse(response, 404, rpcError(null, -32600, "Unknown JSON-RPC endpoint"));
+      return;
+    }
+    try {
+      const parsed: unknown = JSON.parse(await readRequestBody(request));
+      const runnerSourceProtocolVersion = runnerRequest
+        ? zkSyncBlockDetails?.protocolVersion
+        : undefined;
+      const result = Array.isArray(parsed)
+        ? await Promise.all(parsed.map(
+            (entry) => forwardRequest(entry, runnerSourceProtocolVersion),
+          ))
+        : await forwardRequest(parsed, runnerSourceProtocolVersion);
+      jsonResponse(response, 200, result);
+    } catch {
+      jsonResponse(response, 400, rpcError(null, -32700, "Invalid JSON-RPC payload"));
+    }
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => resolve());
+  });
+  const address = server.address();
+  if (!address || typeof address === "string") {
+    server.close();
+    throw new Error("Source-chain proxy did not bind a TCP port");
+  }
+  writeJsonFile(handshakePath, {
+    version: 1,
+    proxyUrl: `http://127.0.0.1:${address.port}${endpointPath}`,
+    snapshot,
+    zksync,
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    const shutdown = () => server.close((error) => (error ? reject(error) : resolve()));
+    process.once("SIGINT", shutdown);
+    process.once("SIGTERM", shutdown);
+    server.once("error", reject);
+  });
+};
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+});