gate-evm-tools 1.0.28 → 1.0.31

package/runtime/miner/runner.ts

@@ -0,0 +1,90 @@
+import { spawn } from "node:child_process";
+import { performance } from "node:perf_hooks";
+import { resolveCreate2MinerBinary } from "./binary";
+import { normalizeCreate2MinerRequest } from "./request";
+import { verifyCreate2MinerResponse } from "./verify";
+import type { Create2MinerOptions, Create2MinerRequest, Create2MinerResponse } from "./types";
+
+const STDOUT_LIMIT = 1024 * 1024;
+const STDERR_LIMIT = 64 * 1024;
+const DEFAULT_TIMEOUT_MS = 300_000;
+const KILL_GRACE_MS = 250;
+function aborted(): Error { const error = new Error("CREATE2 mining aborted"); error.name = "AbortError"; return error; }
+
+export async function mineCreate2(input: Create2MinerRequest, options: Create2MinerOptions = {}): Promise<Create2MinerResponse> {
+  // Snapshot normalized inputs before any asynchronous work so callers cannot change verification intent.
+  const request = normalizeCreate2MinerRequest(input);
+  const timeoutMs = options.timeoutMs === undefined ? DEFAULT_TIMEOUT_MS : options.timeoutMs;
+  if (!Number.isInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2_147_483_647) throw new Error("timeoutMs must be a positive integer at most 2147483647");
+  const { signal, onProgress } = options;
+  if (signal !== undefined && !(signal instanceof AbortSignal)) throw new Error("signal must be an AbortSignal");
+  if (onProgress !== undefined && typeof onProgress !== "function") throw new Error("onProgress must be a function");
+  if (signal?.aborted) throw aborted();
+  const binary = resolveCreate2MinerBinary(options);
+  return new Promise((resolve, reject) => {
+    const started = performance.now();
+    const child = spawn(binary, [], { shell: false, windowsHide: true, stdio: ["pipe", "pipe", "pipe"] });
+    let failure: Error | undefined;
+    let closed = false;
+    let stdoutBytes = 0; let stderrBytes = 0;
+    const stdout: Buffer[] = []; const stderr: Buffer[] = [];
+    let killTimer: NodeJS.Timeout | undefined;
+    let progressTimer: NodeJS.Timeout | undefined;
+    const stop = (error: Error): void => {
+      if (closed || failure) return;
+      failure = error;
+      clearTimeout(timeoutTimer);
+      clearInterval(progressTimer);
+      child.kill("SIGTERM");
+      killTimer = setTimeout(() => { if (!closed) child.kill("SIGKILL"); }, KILL_GRACE_MS);
+    };
+    const onAbort = (): void => stop(aborted());
+    const onError = (cause: Error): void => stop(new Error(`Could not spawn CREATE2 miner ${binary}: ${cause.message}`, { cause }));
+    const onStdinError = (cause: Error): void => stop(new Error(`CREATE2 miner stdin failed: ${cause.message}`, { cause }));
+    const onStdout = (chunk: Buffer): void => {
+      if (failure) return;
+      stdoutBytes += chunk.length;
+      if (stdoutBytes > STDOUT_LIMIT) stop(new Error(`CREATE2 miner stdout exceeded ${STDOUT_LIMIT}-byte limit`));
+      else stdout.push(chunk);
+    };
+    const onStderr = (chunk: Buffer): void => {
+      if (failure) return;
+      stderrBytes += chunk.length;
+      if (stderrBytes > STDERR_LIMIT) stop(new Error(`CREATE2 miner stderr exceeded ${STDERR_LIMIT}-byte limit`));
+      else stderr.push(chunk);
+    };
+    const timeoutTimer = setTimeout(() => stop(new Error(`CREATE2 mining timed out after ${timeoutMs} ms`)), timeoutMs);
+    child.on("error", onError);
+    child.stdin.on("error", onStdinError);
+    child.stdout.on("data", onStdout);
+    child.stderr.on("data", onStderr);
+    child.once("close", (code, terminationSignal) => {
+      closed = true;
+      clearTimeout(timeoutTimer); clearTimeout(killTimer); clearInterval(progressTimer);
+      signal?.removeEventListener("abort", onAbort);
+      child.removeListener("error", onError); child.stdin.removeListener("error", onStdinError);
+      child.stdout.removeListener("data", onStdout); child.stderr.removeListener("data", onStderr);
+      // Settle only after close, which follows exit and closure of stdio: cancellation reaps the child.
+      if (failure) { reject(failure); return; }
+      const text = Buffer.concat(stdout).toString("utf8");
+      if (code !== 0) {
+        const diagnostic = (Buffer.concat(stderr).toString("utf8") || text).trim().slice(0, 4096);
+        reject(new Error(`CREATE2 miner exited with ${terminationSignal ? `signal ${terminationSignal}` : `code ${code}`}${diagnostic ? `: ${diagnostic}` : ""}`)); return;
+      }
+      let response: unknown;
+      try { response = JSON.parse(text); }
+      catch (cause) { reject(new Error("CREATE2 miner returned malformed JSON", { cause })); return; }
+      try { resolve(verifyCreate2MinerResponse(request, response)); } catch (error) { reject(error); }
+    });
+    signal?.addEventListener("abort", onAbort, { once: true });
+    if (signal?.aborted) { onAbort(); return; }
+    if (onProgress) progressTimer = setInterval(() => {
+      if (closed || failure) return;
+      try {
+        // Also consume accidental async callback rejections without leaking an unhandled rejection.
+        Promise.resolve(onProgress({ status: "running", elapsedMs: Math.max(0, performance.now() - started) })).catch(cause => stop(cause instanceof Error ? cause : new Error(String(cause))));
+      } catch (cause) { stop(cause instanceof Error ? cause : new Error(String(cause))); }
+    }, 250);
+    child.stdin.end(JSON.stringify(request));
+  });
+}

package/runtime/miner/types.ts

@@ -0,0 +1,71 @@
+import type { Create2HashArtifact } from "../workflow/lib/create2Hashes";
+
+export type Create2MinerScheme = "evm" | "zksync-eravm";
+export type Create2MinerBackend = "auto" | "cpu" | "gpu" | "metal" | "opencl";
+export type Create2MinerActualBackend = "cpu" | "metal" | "opencl";
+export type Create2MinerHashes =
+  | { scheme: "evm"; initCodeHash: string; bytecodeHash?: never; constructorInputHash?: never }
+  | { scheme: "zksync-eravm"; bytecodeHash: string; constructorInputHash: string; initCodeHash?: never };
+
+export interface Create2MinerIdentity {
+  factory: string;
+  /** First 20 bytes of the salt; this is not necessarily the transaction sender. */
+  caller: string;
+  /** Number of leading address bytes that must equal leadingPattern. */
+  leadingZeroBytes: number;
+  leadingPattern: number;
+}
+export type NormalizedCreate2MinerRequest = Create2MinerHashes & Create2MinerIdentity & {
+  targetCount: number;
+  backend: Create2MinerBackend;
+};
+/** Caller input: omitted controls receive documented defaults. */
+export type Create2MinerRequest = (
+  | { scheme?: "evm"; initCodeHash: string; bytecodeHash?: never; constructorInputHash?: never }
+  | { scheme: "zksync-eravm"; bytecodeHash: string; constructorInputHash: string; initCodeHash?: never }
+) & Pick<Create2MinerIdentity, "factory" | "caller"> & Partial<Pick<Create2MinerIdentity, "leadingZeroBytes" | "leadingPattern">> & {
+  targetCount?: number;
+  backend?: Create2MinerBackend;
+};
+export interface Create2MinerArtifactInput {
+  scheme?: Create2MinerScheme;
+  artifact: Create2HashArtifact;
+  args: unknown[];
+  factory: string;
+  caller: string;
+  leadingZeroBytes?: number;
+  leadingPattern?: number;
+  targetCount?: number;
+  backend?: Create2MinerBackend;
+}
+export interface Create2MinerTelemetry {
+  /** Native telemetry only; GPU zero means unavailable, not zero work. */
+  attempts: number;
+  durationMs: number;
+  hashRate: number;
+}
+export type Create2MinerResult = Create2MinerHashes & Create2MinerIdentity & Create2MinerTelemetry & {
+  status: "found";
+  salt: string;
+  address: string;
+  nonce: string;
+  randomPrefix: string;
+};
+export type Create2MinerResponse = Create2MinerHashes & Create2MinerIdentity & Create2MinerTelemetry & {
+  status: "found";
+  backend: Create2MinerActualBackend;
+  targetCount: number;
+  startedAtUnixMs: number;
+  endedAtUnixMs: number;
+  results: Create2MinerResult[];
+};
+/** Alias for the verified result of a complete mining run. */
+export type Create2MinerRunResult = Create2MinerResponse;
+export interface Create2MinerProgress { status: "running"; elapsedMs: number }
+export interface Create2MinerBinaryOptions { binaryPath?: string }
+export interface Create2MinerOptions extends Create2MinerBinaryOptions {
+  signal?: AbortSignal;
+  /** Positive integer milliseconds; defaults to 300000 (5 minutes). */
+  timeoutMs?: number;
+  onProgress?: (progress: Create2MinerProgress) => void;
+}

package/runtime/miner/verify.ts

@@ -0,0 +1,61 @@
+import { concat, getCreate2Address, keccak256, toUtf8Bytes, zeroPadValue } from "ethers";
+import { actualBackend, fixedHex, normalizeCreate2MinerRequest, record } from "./request";
+import type { Create2MinerResponse, Create2MinerResult, Create2MinerTelemetry } from "./types";
+
+function equal(value: unknown, expected: unknown, label: string): void {
+  if (value !== expected) throw new Error(`miner ${label} mismatch (expected ${String(expected)})`);
+}
+function metric(value: unknown, label: string): number {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) throw new Error(`miner ${label} must be finite and nonnegative`);
+  return value;
+}
+function telemetry(value: Record<string, unknown>, label: string): Create2MinerTelemetry {
+  return { attempts: metric(value.attempts, `${label}.attempts`), durationMs: metric(value.durationMs, `${label}.durationMs`), hashRate: metric(value.hashRate, `${label}.hashRate`) };
+}
+export function verifyCreate2MinerResponse(input: unknown, response: unknown): Create2MinerResponse {
+  const request = normalizeCreate2MinerRequest(input);
+  const value = record(response, "response");
+  equal(value.status, "found", "status");
+  equal(value.scheme, request.scheme, "scheme");
+  const backend = actualBackend(request.backend);
+  equal(value.backend, backend, "backend");
+  equal(value.targetCount, request.targetCount, "targetCount");
+  if (!Array.isArray(value.results) || value.results.length !== request.targetCount) throw new Error("miner results must contain exactly targetCount results");
+  const stats = telemetry(value, "response");
+  const startedAtUnixMs = metric(value.startedAtUnixMs, "startedAtUnixMs");
+  const endedAtUnixMs = metric(value.endedAtUnixMs, "endedAtUnixMs");
+  if (endedAtUnixMs < startedAtUnixMs) throw new Error("miner endedAtUnixMs precedes startedAtUnixMs");
+  const { backend: _backend, targetCount: _targetCount, ...identity } = request;
+  const salts = new Set<string>(); const addresses = new Set<string>();
+  const rawResults = value.results;
+  const results = Array.from({ length: request.targetCount }, (_, index): Create2MinerResult => {
+    const raw = rawResults[index];
+    const label = `results[${index}]`;
+    const item = record(raw, label);
+    equal(item.status, "found", `${label}.status`);
+    equal(item.scheme, request.scheme, `${label}.scheme`);
+    for (const name of ["factory", "caller"] as const) equal(fixedHex(item[name], 20, `${label}.${name}`), request[name], `${label}.${name}`);
+    const hashes = request.scheme === "evm" ? ["initCodeHash"] as const : ["bytecodeHash", "constructorInputHash"] as const;
+    const foreign = request.scheme === "evm" ? ["bytecodeHash", "constructorInputHash"] : ["initCodeHash"];
+    for (const name of foreign) if (name in item) throw new Error(`miner ${label} contains foreign ${name}`);
+    for (const name of hashes) equal(fixedHex(item[name], 32, `${label}.${name}`), request[name], `${label}.${name}`);
+    equal(item.leadingZeroBytes, request.leadingZeroBytes, `${label}.leadingZeroBytes`);
+    equal(item.leadingPattern, request.leadingPattern, `${label}.leadingPattern`);
+    const salt = fixedHex(item.salt, 32, `${label}.salt`);
+    equal(salt.slice(0, 42), request.caller, `${label}.salt caller prefix`);
+    const randomPrefix = fixedHex(item.randomPrefix, 4, `${label}.randomPrefix`);
+    const nonce = fixedHex(item.nonce, 8, `${label}.nonce`);
+    equal(randomPrefix, `0x${salt.slice(42, 50)}`, `${label}.randomPrefix`);
+    equal(nonce, `0x${salt.slice(50)}`, `${label}.nonce`);
+    const address = fixedHex(item.address, 20, `${label}.address`);
+    const expected = request.scheme === "evm"
+      ? getCreate2Address(request.factory, salt, request.initCodeHash).toLowerCase()
+      : `0x${keccak256(concat([keccak256(toUtf8Bytes("zksyncCreate2")), zeroPadValue(request.factory, 32), salt, request.bytecodeHash, request.constructorInputHash])).slice(-40)}`;
+    equal(address, expected, `${label}.address`);
+    if (!address.slice(2).startsWith(request.leadingPattern.toString(16).padStart(2, "0").repeat(request.leadingZeroBytes))) throw new Error(`miner ${label}.address does not match requested leadingPattern`);
+    if (salts.has(salt) || addresses.has(address)) throw new Error("miner contains duplicate salt or address");
+    salts.add(salt); addresses.add(address);
+    return { ...identity, ...telemetry(item, label), status: "found", salt, address, randomPrefix, nonce };
+  });
+  return { ...identity, ...stats, status: "found", backend, targetCount: request.targetCount, startedAtUnixMs, endedAtUnixMs, results };
+}