gate-evm-tools 1.0.28 → 1.2.0

package/runtime/miner/cli.ts

@@ -0,0 +1,87 @@
+import { randomUUID } from "node:crypto";
+import { readFile, realpath, rename, stat, unlink, writeFile } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { mineCreate2 } from "./runner";
+import { normalizeCreate2MinerRequest } from "./request";
+
+const help = `Usage: gate-tool miner --request request.json [--output result.json] [--binary /absolute/path] [--timeout-ms N]
+
+Prepare and verify CREATE2 salts locally; no RPC, signing or deployment.
+  --request <path>     Request JSON file, or - to read stdin (required)
+  --output <path>      Atomically save verified result JSON after success
+  --binary <path>      Trusted native executable override
+  --timeout-ms <N>     Positive integer milliseconds (default: 300000)
+  -h, --help          Show this help
+
+Requires ethers v6. See docs/create2-miner.md for schemes and backend limits.
+`;
+async function sameFile(input: string, output: string): Promise<boolean> {
+  if (resolve(input) === resolve(output)) return true;
+  try {
+    const [a, b] = await Promise.all([stat(input), stat(output)]);
+    return a.dev === b.dev && a.ino === b.ino;
+  } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; return false; }
+}
+async function stdinJson(signal: AbortSignal): Promise<string> {
+  return new Promise((resolveInput, reject) => {
+    const chunks: Buffer[] = []; let size = 0;
+    const cleanup = (): void => { process.stdin.off("data", data); process.stdin.off("end", end); process.stdin.off("error", fail); signal.removeEventListener("abort", abort); process.stdin.pause(); };
+    const fail = (error: Error): void => { cleanup(); reject(error); };
+    const abort = (): void => fail(new Error("CREATE2 mining aborted while reading stdin"));
+    const data = (chunk: Buffer): void => { size += chunk.length; if (size > 1024 * 1024) fail(new Error("request stdin exceeds 1 MiB limit")); else chunks.push(chunk); };
+    const end = (): void => { cleanup(); resolveInput(Buffer.concat(chunks).toString("utf8")); };
+    process.stdin.on("data", data); process.stdin.once("end", end); process.stdin.once("error", fail); signal.addEventListener("abort", abort, { once: true });
+    if (signal.aborted) abort();
+  });
+}
+function checkCancellation(signal: AbortSignal): void {
+  if (signal.aborted) throw new Error("CREATE2 mining aborted");
+}
+async function atomicOutput(file: string, content: string, signal: AbortSignal): Promise<void> {
+  // Resolve the parent, not the target: rename replaces a symlink rather than following it.
+  const parent = await realpath(dirname(resolve(file)));
+  const target = join(parent, basename(file));
+  const temporary = join(parent, `.${basename(file)}.${randomUUID()}.tmp`);
+  try {
+    checkCancellation(signal);
+    await writeFile(temporary, content, { flag: "wx", mode: 0o600, signal });
+    checkCancellation(signal);
+    await rename(temporary, target);
+    // A signal during rename cannot undo its atomic commit, but must suppress success reporting.
+    checkCancellation(signal);
+  }
+  finally { await unlink(temporary).catch(error => { if (error.code !== "ENOENT") throw error; }); }
+}
+export async function runCreate2MinerCli(args: string[] = process.argv.slice(3)): Promise<void> {
+  const controller = new AbortController();
+  const interrupt = (): void => { controller.abort(); };
+  process.on("SIGINT", interrupt); process.on("SIGTERM", interrupt);
+  try {
+    if (args.length === 1 && (args[0] === "--help" || args[0] === "-h")) { process.stdout.write(help); return; }
+    const values: Record<string, string> = {};
+    for (let index = 0; index < args.length; index += 2) {
+      const flag = args[index]; const value = args[index + 1];
+      if (!["--request", "--output", "--binary", "--timeout-ms"].includes(flag)) throw new Error(`Unknown miner option ${flag}; use miner --help`);
+      if (flag in values) throw new Error(`Duplicate miner option ${flag}`);
+      if (!value || value.startsWith("--")) throw new Error(`${flag} requires a value`);
+      values[flag] = value;
+    }
+    if (!values["--request"]) throw new Error("--request is required; use miner --help");
+    const input = values["--request"]; const output = values["--output"];
+    if (input !== "-" && output && await sameFile(input, output)) throw new Error("--output must not be the request file");
+    const timeout = values["--timeout-ms"];
+    if (timeout !== undefined && !/^[0-9]+$/.test(timeout)) throw new Error("--timeout-ms must be a positive integer");
+    const content = input === "-" ? await stdinJson(controller.signal) : await readFile(input, { encoding: "utf8", signal: controller.signal });
+    let request: unknown;
+    try { request = JSON.parse(content); } catch (cause) { throw new Error("Request is not valid JSON", { cause }); }
+    const result = await mineCreate2(normalizeCreate2MinerRequest(request), { binaryPath: values["--binary"], timeoutMs: timeout === undefined ? undefined : Number(timeout), signal: controller.signal });
+    const json = JSON.stringify(result, null, 2) + "\n";
+    checkCancellation(controller.signal);
+    if (output) await atomicOutput(output, json, controller.signal);
+    checkCancellation(controller.signal);
+    process.stdout.write(json);
+  } catch (error) {
+    process.stderr.write(`CREATE2 miner: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+  } finally { process.off("SIGINT", interrupt); process.off("SIGTERM", interrupt); }
+}

package/runtime/miner/index.ts

@@ -0,0 +1,5 @@
+export type * from "./types";
+export { normalizeCreate2MinerRequest, create2MinerRequestFromArtifact } from "./request";
+export { verifyCreate2MinerResponse } from "./verify";
+export { resolveCreate2MinerBinary } from "./binary";
+export { mineCreate2 } from "./runner";

package/runtime/miner/request.ts

@@ -0,0 +1,54 @@
+import { canonicalCreate2Hashes } from "../workflow/lib/create2Hashes";
+import type { Create2MinerActualBackend, Create2MinerArtifactInput, Create2MinerBackend, NormalizedCreate2MinerRequest } from "./types";
+
+export function 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>;
+}
+export function onlyKeys(value: Record<string, unknown>, keys: readonly string[], label: string): void {
+  for (const key of Object.keys(value)) if (!keys.includes(key)) throw new Error(`${label}: unsupported field ${key}`);
+}
+export function fixedHex(value: unknown, bytes: number, label: string): string {
+  if (typeof value !== "string" || !new RegExp(`^0x[0-9a-fA-F]{${bytes * 2}}$`).test(value)) throw new Error(`${label} must be a 0x-prefixed ${bytes}-byte hex value`);
+  return value.toLowerCase();
+}
+function integer(value: unknown, fallback: number, min: number, max: number, label: string): number {
+  const number = value === undefined ? fallback : value;
+  if (typeof number !== "number" || !Number.isInteger(number) || number < min || number > max) throw new Error(`${label} must be an integer from ${min} to ${max}`);
+  return number;
+}
+export function actualBackend(backend: Create2MinerBackend): Create2MinerActualBackend {
+  return backend === "auto" || backend === "gpu" ? (process.platform === "darwin" ? "metal" : "opencl") : backend;
+}
+const controls = ["factory", "caller", "leadingZeroBytes", "leadingPattern", "targetCount", "backend"];
+export function normalizeCreate2MinerRequest(input: unknown): NormalizedCreate2MinerRequest {
+  const value = record(input, "request");
+  const scheme = value.scheme === undefined ? "evm" : value.scheme;
+  if (scheme !== "evm" && scheme !== "zksync-eravm") throw new Error("scheme must be evm or zksync-eravm");
+  onlyKeys(value, [...controls, "scheme", ...(scheme === "evm" ? ["initCodeHash"] : ["bytecodeHash", "constructorInputHash"])], "request");
+  const backend = value.backend === undefined ? "auto" : value.backend;
+  if (backend !== "auto" && backend !== "cpu" && backend !== "gpu" && backend !== "metal" && backend !== "opencl") throw new Error("backend must be auto, cpu, gpu, metal or opencl");
+  const leadingPattern = integer(value.leadingPattern, 0, 0, 255, "leadingPattern");
+  if (backend !== "cpu" && (leadingPattern & 15) !== (leadingPattern >> 4)) throw new Error("GPU leadingPattern requires a repeated-nibble byte (0x00, 0x11, …, 0xff); use backend cpu for other patterns");
+  if (backend === "metal" && process.platform !== "darwin") throw new Error("Metal backend requires macOS; use cpu or opencl on this platform");
+  const common = {
+    factory: fixedHex(value.factory, 20, "factory"), caller: fixedHex(value.caller, 20, "caller"),
+    leadingZeroBytes: integer(value.leadingZeroBytes, 0, 0, 20, "leadingZeroBytes"), leadingPattern,
+    targetCount: integer(value.targetCount, 1, 1, 100, "targetCount"), backend: backend as Create2MinerBackend,
+  };
+  return scheme === "evm"
+    ? { ...common, scheme, initCodeHash: fixedHex(value.initCodeHash, 32, "initCodeHash") }
+    : { ...common, scheme, bytecodeHash: fixedHex(value.bytecodeHash, 32, "bytecodeHash"), constructorInputHash: fixedHex(value.constructorInputHash, 32, "constructorInputHash") };
+}
+export function create2MinerRequestFromArtifact(input: Create2MinerArtifactInput): NormalizedCreate2MinerRequest {
+  const value = record(input, "artifact request");
+  onlyKeys(value, [...controls, "scheme", "artifact", "args"], "artifact request");
+  const artifact = record(value.artifact, "artifact");
+  if (typeof artifact.bytecode !== "string" || !/^0x(?:[0-9a-fA-F]{2})+$/.test(artifact.bytecode)) throw new Error("artifact bytecode must be non-empty, linked, byte-aligned hex");
+  if (!Array.isArray(value.args)) throw new Error("artifact args must be an array");
+  // Validate format and hash constructor arguments through the workflow's canonical implementation.
+  if (value.scheme !== undefined && value.scheme !== "evm" && value.scheme !== "zksync-eravm") throw new Error("scheme must be evm or zksync-eravm");
+  const { artifact: _artifact, args: _args, scheme: _scheme, ...rest } = value;
+  const hashes = canonicalCreate2Hashes(input);
+  return normalizeCreate2MinerRequest({ ...rest, ...hashes });
+}

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 };
+}