gate-evm-tools 1.0.27 → 1.0.31

package/runtime/delivery/source.ts

@@ -0,0 +1,130 @@
+/** Actual-file source binding only. This API grants no host approval or execution authority. */
+import fs from 'node:fs';
+import { createHash } from 'node:crypto';
+import { coreMarker, projectRoot, confinedFile } from './project-files';
+import { object, parseDeliveryRequest, validateDeliveryRpc, type DeliveryRequest, type ChainIdProvider, type ProjectNetworkSnapshot } from './protocol';
+import { loadPlanCodec } from './codec';
+import type { Plan, PlanTask, DefinitionSelection, DefinitionSnapshot, DeepReadonly } from '../vendor/plan-codec/index.cjs';
+export type { DefinitionSelection, DefinitionSnapshot, DeepReadonly } from '../vendor/plan-codec/index.cjs';
+
+export interface DeliverySourceOptions {
+  workspaceRoot: string;
+  /** Workspace-relative path or '.'. */
+  projectRoot: string;
+  request: unknown;
+  /** Explicit upstream roots, independent of the invocation sourceRef task. */
+  sourceRoots: string[];
+}
+export interface DeliverySourceBinding {
+  request: DeliveryRequest;
+  workspaceRoot: string;
+  projectRoot: string;
+  observation: { path: string; sha256: string };
+  invocation: { lane: string; task: PlanTask };
+  sourceDefinition: DefinitionSnapshot;
+  sourceDefinitionBytes: string;
+  sourceDefinitionHash: string;
+  prodTaskGraph?: DefinitionSnapshot;
+  prodTaskGraphBytes?: string;
+  prodTaskGraphHash?: string;
+}
+const sha256 = (bytes: string | Buffer): string => createHash('sha256').update(bytes).digest('hex');
+function freeze<T>(value: T): DeepReadonly<T> {
+  if (value && typeof value === 'object') { Object.values(value).forEach(freeze); Object.freeze(value); }
+  return value as DeepReadonly<T>;
+}
+export function parseCanonicalPlan(text: string): Plan { return loadPlanCodec().parsePlan(text); }
+export function projectCanonicalDefinitions(text: string, selection: DefinitionSelection): ReturnType<ReturnType<typeof loadPlanCodec>['projectDefinitions']> {
+  return loadPlanCodec().projectDefinitions(text, selection);
+}
+const purposeSteps = {
+  'dev-execution': ['deploy', 'check-code'],
+  'prod-qualification': ['deploy-test'],
+  'prod-execution': ['release-prepare', 'release-execute', 'release-verify'],
+};
+function sameRelease(actual: unknown, expected: DeliveryRequest['releaseRef']): boolean {
+  if (expected === undefined) return actual === undefined;
+  if (!actual || typeof actual !== 'object' || Array.isArray(actual)) return false;
+  const ref = actual as Record<string, unknown>;
+  return Object.keys(ref).length === 3 && ref.path === expected.path && ref.releaseId === expected.releaseId && ref.inputsHash === expected.inputsHash;
+}
+function actualSource(workspace: string, relative: string): Buffer {
+  const file = confinedFile(workspace, relative);
+  const fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+  try {
+    const before = fs.fstatSync(fd);
+    if (!before.isFile() || before.nlink !== 1) throw new Error('Unsafe handoff file type');
+    const bytes = fs.readFileSync(fd);
+    const after = fs.fstatSync(fd);
+    // Fail if the observed file was replaced or changed during reading.
+    confinedFile(workspace, relative);
+    const current = fs.lstatSync(file);
+    if (before.dev !== current.dev || before.ino !== current.ino || before.size !== after.size
+      || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) throw new Error('Handoff changed while reading');
+    return bytes;
+  } finally { fs.closeSync(fd); }
+}
+/** Read one confined handoff snapshot and bind the current invocation to it before any RPC work. */
+export function readDeliverySource(input: DeliverySourceOptions): DeepReadonly<DeliverySourceBinding> {
+  object(input, 'source options', ['workspaceRoot', 'projectRoot', 'request', 'sourceRoots']);
+  return readSource(input);
+}
+/** Owned business selection derives upstream roots from the same actual invocation bytes. */
+export function readOwnedDeliverySource(input: Omit<DeliverySourceOptions, 'sourceRoots'>): DeepReadonly<DeliverySourceBinding> {
+  object(input, 'owned source options', ['workspaceRoot', 'projectRoot', 'request']);
+  return readSource(input);
+}
+function readSource(input: Omit<DeliverySourceOptions, 'sourceRoots'> & { sourceRoots?: string[] }): DeepReadonly<DeliverySourceBinding> {
+  const request = parseDeliveryRequest(input.request);
+  const workspace = projectRoot(input.workspaceRoot, '.');
+  const root = projectRoot(workspace, input.projectRoot);
+  coreMarker(root);
+  const bytes = actualSource(workspace, request.sourceRef.path);
+  const text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+  if (input.sourceRoots === undefined) (require('./input-files') as typeof import('./input-files')).assertUnambiguousHandoff(text);
+  const codec = loadPlanCodec();
+  const plan = codec.parsePlan(text);
+  if (plan.taskId !== request.sourceRef.taskId) throw new Error('sourceRef.taskId does not match actual handoff');
+  const entries = Object.entries(plan.tasks).flatMap(([lane, tasks]) => tasks.map(task => ({ lane, task })));
+  const invocation = entries.find(({ task }) => task.planKey === request.sourceRef.planKey);
+  if (!invocation || invocation.task.rev !== request.sourceRef.rev) throw new Error('sourceRef planKey/rev does not match actual handoff');
+  if (plan.lanes[invocation.lane].state !== 'enabled' || invocation.task.status === 'cancelled') throw new Error('Invocation task is disabled or cancelled');
+  const deployment = object(invocation.task.scope?.deployment, 'invocation scope.deployment');
+  if (deployment.projectRoot !== input.projectRoot) throw new Error('Invocation projectRoot mismatch');
+  if (deployment.chainFamily !== 'evm' || deployment.framework !== 'hardhat2') throw new Error('Invocation requires an EVM Hardhat2 deployment');
+  if (!purposeSteps[request.purpose].includes(invocation.task.step ?? '')) throw new Error('Invocation purpose/step mismatch');
+  if (deployment.environment !== request.environment || deployment.targetNetwork !== request.network) throw new Error('Invocation environment/targetNetwork mismatch');
+  if (!Array.isArray(deployment.allowedActions) || !deployment.allowedActions.includes(request.mode)) throw new Error('Invocation mode is not in allowedActions');
+  if (!sameRelease(deployment.releaseRef, request.releaseRef)) throw new Error('Invocation releaseRef mismatch');
+  const sourceRoots = input.sourceRoots ?? (request.purpose === 'prod-execution'
+    ? entries.filter(({ task }) => task.step === 'deploy-test'
+      && (task.scope?.deployment as Record<string, unknown> | undefined)?.projectRoot === input.projectRoot
+      && (task.scope?.deployment as Record<string, unknown> | undefined)?.deploymentId === deployment.deploymentId).map(({ task }) => task.planKey)
+    : [invocation.task.planKey]);
+  if (!sourceRoots.length) throw new Error('Owned source requires an upstream qualification definition');
+  const source = codec.projectDefinitions(text, { roots: sourceRoots, mode: 'upstream' });
+  for (const task of source.snapshot.tasks) {
+    const selectedDeployment = task.scope?.deployment as Readonly<Record<string, unknown>> | undefined;
+    if (selectedDeployment && selectedDeployment.projectRoot !== input.projectRoot) throw new Error(`Selected upstream deployment projectRoot mismatch: ${task.planKey}`);
+  }
+  let production: ReturnType<typeof codec.projectDefinitions> | undefined;
+  if (request.purpose === 'prod-execution') {
+    const roots = entries.filter(({ task }) => purposeSteps['prod-execution'].includes(task.step ?? '')
+      && task.scope?.deployment && (task.scope.deployment as Record<string, unknown>).projectRoot === input.projectRoot
+      && sameRelease((task.scope.deployment as Record<string, unknown>).releaseRef, request.releaseRef)).map(({ task }) => task.planKey);
+    production = codec.projectDefinitions(text, { roots, mode: 'full' });
+  }
+  // All values came from detached request parsing and actual handoff text; freeze before exposing.
+  return freeze({ request, workspaceRoot: workspace, projectRoot: root, observation: { path: request.sourceRef.path, sha256: sha256(bytes) },
+    invocation, sourceDefinition: source.snapshot, sourceDefinitionBytes: source.bytes, sourceDefinitionHash: sha256(source.bytes),
+    ...(production ? { prodTaskGraph: production.snapshot, prodTaskGraphBytes: production.bytes, prodTaskGraphHash: sha256(production.bytes) } : {}),
+  }) as DeepReadonly<DeliverySourceBinding>;
+}
+/** Read/validate actual source before a provider can be loaded; still not host authorization. */
+export async function validateDeliverySourceRpc(input: DeliverySourceOptions, snapshot: ProjectNetworkSnapshot,
+  loadProvider: (snapshot: ProjectNetworkSnapshot) => Promise<ChainIdProvider>,
+): Promise<DeepReadonly<DeliverySourceBinding & { chainId: number }>> {
+  const binding = readDeliverySource(input);
+  const { chainId } = await validateDeliveryRpc(binding.request, snapshot, loadProvider);
+  return freeze({ ...binding, chainId }) as DeepReadonly<DeliverySourceBinding & { chainId: number }>;
+}

package/runtime/delivery/target-fields.ts

@@ -0,0 +1,7 @@
+/** Complete scalar public target boundary shared by native references and custom ports. */
+export const PUBLIC_TARGET_FIELDS = new Set([
+  'version', 'id', 'network', 'environment', 'chainId', 'admin',
+  'finality.confirmations', 'openzeppelin.manifestDir',
+  'create2.scheme', 'create2.factory', 'create2.leadingZeroBytes', 'create2.caller',
+  'uups.placeholderImplementation', 'multicall.controlledMulticall',
+]);

package/runtime/delivery/validation.ts

@@ -0,0 +1,247 @@
+import { validateCreate2Fields } from "./create2";
+import { canonicalCreate2Hashes } from "../workflow/lib/create2Hashes";
+import { ParamType, getCreate2Address } from "ethers";
+import type { WorkflowContext } from "../workflow/lib/context";
+import type { WorkflowStep } from "../workflow/lib/parameters";
+import type { WorkflowValidationPort } from "../workflow/lib/validation";
+import { strictData } from "./data";
+import {
+  resolveBusinessValue,
+  containsDeferred,
+  type ReferenceObservation,
+} from "./references";
+import {
+  validateAbiArguments,
+  validateAbiValue,
+  validateTransactionValue,
+  validateAbiResult,
+  compareAbiResults,
+  stringifyRuntimeValue,
+} from "./abi";
+import {
+  deliveryArtifact,
+  deliveryPreparationData,
+  validatePreparationSemantics,
+  ERC1967_PROXY,
+} from "./preparation";
+import { parseNativeOperation } from "./custom";
+import { deepFreeze } from "../workflow/lib/canonicalData";
+import { ownedDeliveryCompiler, compilerPreparationHooks, validateCompilerPreparationPlan, verifyCompilerSameForkUpgrade } from './compiler';
+
+export interface DeliveryValidation extends WorkflowValidationPort {
+  preflight(steps: readonly WorkflowStep[]): Promise<void>;
+  observations(): readonly ReferenceObservation[];
+}
+export function createDeliveryValidation(
+  context: WorkflowContext,
+): DeliveryValidation {
+  if (context.target.create2?.scheme && context.target.create2.scheme !== "evm")
+    throw new Error("Delivery validation requires EVM");
+  const observations: ReferenceObservation[] = [];
+  const compiler = ownedDeliveryCompiler(context.runtime.hre);
+  const params = deepFreeze(strictData(context.targetParams));
+  const resolve = (value: unknown, deferState = false): unknown => {
+    const result = resolveBusinessValue(
+      value,
+      { params, target: context.target, state: () => context.state.snapshot() },
+      { deferState },
+    );
+    observations.push(...result.observations);
+    return result.value;
+  };
+  // Artifact reader is an explicit runtime capability, never an address/contract resolver.
+  const read = async (name: string) => {
+    if (!context.runtime.hre.artifacts?.readArtifact)
+      throw new Error(
+        "Delivery validation requires explicit runtime artifact reader",
+      );
+    return deliveryArtifact(
+      await context.runtime.hre.artifacts.readArtifact(name),
+    );
+  };
+  const argumentsFor = async (
+    name: string,
+    method: string | null,
+    args: unknown,
+    deferState = false,
+  ) =>
+    validateAbiArguments(
+      (await read(name)).abi,
+      method,
+      resolve(args, deferState),
+      { allowDeferred: deferState },
+    );
+  const call = async (
+    name: string,
+    method: string,
+    args: unknown,
+    value?: unknown,
+  ) => {
+    validateAbiArguments((await read(name)).abi, method, args);
+    if (value !== undefined) validateTransactionValue(value);
+  };
+  const preflight = async (steps: readonly WorkflowStep[]) => {
+    const data = strictData(steps);
+    for (const step of data) {
+      // Internal operation IDs can exceed the source parser's 200-character limit.
+      parseNativeOperation({ ...step, id: "validation" });
+      resolve(step, true); // Parse every reference without reading future state.
+      if (step.address !== undefined)
+        validateAbiValue(
+          ParamType.from("address"),
+          resolve(step.address, true),
+          "operation address",
+          true,
+        );
+      if (["call", "view", "check"].includes(step.kind)) {
+        for (const c of step.calls as Array<Record<string, unknown>>) {
+          await argumentsFor(
+            String(step.abi ?? step.contract),
+            c.method as string,
+            c.args === undefined ? [] : c.args,
+            true,
+          );
+          if (step.kind === "check")
+            validateAbiResult(
+              (await read(String(step.abi ?? step.contract))).abi,
+              c.method as string,
+              resolve(c.expect, true),
+              true,
+            );
+          if (c.value !== undefined)
+            validateTransactionValue(resolve(c.value, true), true);
+        }
+      } else {
+        const first = step.firstUpgrade as Record<string, unknown> | undefined;
+        const proxy = step.proxy as Record<string, unknown> | undefined;
+        const name = first?.contract ?? step.contract;
+        const args = first
+          ? (first.constructorArgs ?? [])
+          : step.kind === "deploy"
+            ? (step.args ?? [])
+            : (step.constructorArgs ??
+              (typeof proxy === "object"
+                ? proxy?.constructorArgs
+                : undefined) ??
+              []);
+        await argumentsFor(name as string, null, args, true);
+        const init = (first?.call ?? step.call) as
+          | Record<string, unknown>
+          | undefined;
+        if (init)
+          await argumentsFor(
+            name as string,
+            (init.method ?? init.fn) as string,
+            init.args ?? [],
+            true,
+          );
+        if (first)
+          await argumentsFor(
+            ERC1967_PROXY,
+            null,
+            [context.target.uups?.placeholderImplementation, "0x"],
+            true,
+          );
+        const fields = (value: unknown, kind: Parameters<typeof validateCreate2Fields>[1]) =>
+          validateCreate2Fields(resolve(value === undefined ? {} : value, true), kind, true);
+        const targetCreate2 = fields(context.target.create2, "target");
+        fields(context.target.uups, "uups");
+        const targetMulticall = fields(context.target.multicall, "multicall");
+        if (
+          step.kind === "upgrade" &&
+          (targetCreate2.factory === undefined || targetMulticall.controlledMulticall === undefined)
+        )
+          throw new Error(`Upgrade step ${step.id} requires target create2 factory and controlledMulticall`);
+        const declaredCreate2 = step.create2 === undefined
+          ? undefined
+          : fields(step.create2, "step");
+        const policy =
+          context.existingDeploymentPolicies?.[String(step.saveAs)];
+        const create2 =
+          declaredCreate2 && policy?.mode === "redeploy"
+            ? validateCreate2Fields(
+                {
+                  ...declaredCreate2,
+                  salt: policy.salt,
+                  expectedAddress: policy.expectedAddress,
+                },
+                "step",
+                true,
+              )
+            : declaredCreate2;
+        if (step.kind === "deploy" && create2) {
+          const a = await read(first ? ERC1967_PROXY : (name as string));
+          const constructor = resolve(
+            first
+              ? [context.target.uups?.placeholderImplementation, "0x"]
+              : args,
+            true,
+          );
+          const factory = create2.factory ?? targetCreate2.factory,
+            salt = create2.salt;
+          if (factory === undefined)
+            throw new Error("CREATE2 requires a factory address");
+          if (!containsDeferred([constructor, factory, salt])) {
+            const hashes = canonicalCreate2Hashes({
+              scheme: "evm",
+              artifact: a,
+              args: constructor as unknown[],
+            });
+            if (hashes.scheme !== "evm")
+              throw new Error("Invalid CREATE2 scheme");
+            const predicted = getCreate2Address(
+              factory as string,
+              salt as string,
+              hashes.initCodeHash,
+            ).toLowerCase();
+            if (create2.expectedAddress !== undefined) {
+              const expected = create2.expectedAddress;
+              if (
+                !containsDeferred(expected) &&
+                (typeof expected !== "string" ||
+                  predicted !== expected.toLowerCase())
+              )
+                throw new Error(
+                  "Actual CREATE2 predicted address differs from expectedAddress",
+                );
+            }
+            const zeroes =
+              create2.leadingZeroBytes ??
+              targetCreate2.leadingZeroBytes;
+            if (
+              zeroes !== undefined &&
+              !containsDeferred(zeroes) &&
+              !predicted.slice(2).startsWith("00".repeat(Number(zeroes)))
+            )
+              throw new Error("Actual CREATE2 violates leadingZeroBytes");
+          }
+        }
+      }
+    }
+  };
+  return {
+    resolve,
+    create2Fields: validateCreate2Fields,
+    call,
+    address: (value) =>
+      validateAbiValue(ParamType.from("address"), value, "operation address"),
+    callInterface: validateAbiArguments,
+    check: validateAbiResult,
+    compare: compareAbiResults,
+    stringify: stringifyRuntimeValue,
+    preparation: {
+      data: deliveryPreparationData,
+      artifact: (name, raw) => deepFreeze(deliveryArtifact(compiler ? compiler.artifact(name, raw) : raw)),
+      arguments: (artifact, method, args) =>
+        validateAbiArguments(artifact.abi, method, args),
+      ...compilerPreparationHooks(context.runtime.hre),
+    },
+    preparationPlan: async (request, plan) => {
+      await validatePreparationSemantics(request, plan, read);
+      await validateCompilerPreparationPlan(context.runtime.hre,request,plan);
+    },
+    sameForkUpgrade: proxy => verifyCompilerSameForkUpgrade(context.runtime.hre,context.targetId,proxy,context.simulation.snapshot?.blockNumber),
+    preflight,
+    observations: () => deepFreeze(strictData(observations)),
+  };
+}

package/runtime/delivery/verification.ts

@@ -0,0 +1,47 @@
+import { canonicalData, canonicalJson, deepFreeze, exactObject, nonempty } from '../workflow/lib/canonicalData';
+import { parseTypedValue } from '../workflow/lib/typedValue';
+import type { VerificationObservation, VerificationSink } from '../workflow/lib/evidencePorts';
+export interface ExpectedAssertion { stepId: string; callIndex: number; assertionId: string }
+export function parseVerificationObservation(raw: unknown): VerificationObservation {
+  const v = exactObject(raw, ['stepId', 'callIndex', 'assertionId', 'contract', 'abiName', 'abi', 'address', 'method', 'args', 'definition', 'actual', 'expected'], 'verification observation');
+  for (const key of ['stepId', 'assertionId', 'contract', 'abiName', 'method']) nonempty(v[key], key);
+  if (!Number.isSafeInteger(v.callIndex) || (v.callIndex as number) < 0 || v.assertionId !== `${v.stepId}:${v.callIndex}`) throw new Error('Invalid assertion identity');
+  if (typeof v.address !== 'string' || !/^0x[\da-fA-F]{40}$/.test(v.address)) throw new Error('Invalid verification address');
+  if (!Array.isArray(v.abi) || v.abi.length === 0 || v.abi.some(item => typeof item !== 'string' || !item)) throw new Error('Invalid verification ABI');
+  const definition = exactObject(v.definition, ['method', 'args', 'expect'], 'check definition');
+  nonempty(definition.method, 'definition method');
+  if (definition.method !== v.method) throw new Error('Check definition method mismatch');
+  parseTypedValue(definition.args); parseTypedValue(definition.expect);
+  parseTypedValue(v.args); parseTypedValue(v.actual); parseTypedValue(v.expected);
+  return deepFreeze(canonicalData(v) as unknown as VerificationObservation);
+}
+export class VerificationJournal implements VerificationSink {
+  private readonly expected: ExpectedAssertion[];
+  private readonly observations: VerificationObservation[] = [];
+  private sealed = false;
+  constructor(expected: readonly ExpectedAssertion[]) {
+    this.expected = [];
+    this.declare(expected);
+  }
+  declare(expected: readonly ExpectedAssertion[]): void {
+    if (this.sealed) throw new Error("verification journal sealed");
+    this.expected.push(...deepFreeze(canonicalData(expected) as ExpectedAssertion[]));
+    if (new Set(this.expected.map(e => e.assertionId)).size !== this.expected.length) throw new Error('Duplicate expected assertion');
+    for (const e of this.expected) {
+      exactObject(e, ['stepId', 'callIndex', 'assertionId'], 'expected assertion');
+      if (!Number.isSafeInteger(e.callIndex) || e.callIndex < 0 || e.assertionId !== `${e.stepId}:${e.callIndex}`) throw new Error('Invalid expected assertion');
+    }
+  }
+  record(raw: VerificationObservation): void {
+    if (this.sealed) throw new Error('verification journal sealed');
+    const observation = parseVerificationObservation(raw), expected = this.expected[this.observations.length];
+    if (!expected || canonicalJson(expected) !== canonicalJson({ stepId: observation.stepId, callIndex: observation.callIndex, assertionId: observation.assertionId })) throw new Error('Unexpected verification step/call mapping');
+    this.observations.push(observation);
+  }
+  seal(): VerificationObservation[] {
+    if (this.expected.length !== this.observations.length) throw new Error('missing expected verification observations');
+    this.sealed = true;
+    // Empty is valid collection, never business acceptance or qualification authority.
+    return deepFreeze([...this.observations]);
+  }
+}

package/runtime/migrate.ts

@@ -12,6 +12,7 @@ const commands: Record<string, string> = {
   create2Hashes: 'create2-hashes', releaseFinalize: 'release-finalize',
   importState: 'import-state', reconcileExternal: 'reconcile-external',
   commitContractInfo: 'commit-contract-info',
+  planRead: 'plan-read', planWrite: 'plan-write', planAdd: 'plan-add', planStatus: 'plan-status',
 };
 
 /** Plan first; preserve custom files/state. Only known sources/shims are removable. */

package/runtime/miner/binary.ts

@@ -0,0 +1,41 @@
+import { createHash } from "node:crypto";
+import { accessSync, constants, readFileSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import type { Create2MinerBinaryOptions } from "./types";
+
+// These trusted pins are compiled into the runtime. A mutable manifest alone is not a trust anchor.
+const bundled: Record<string, { sha256: string; bytes: number }> = {
+  "darwin-arm64": { sha256: "9611c1ca900c24f9b14924a144b7a3ab431111b855e676f2e145e7ab8c05f954", bytes: 1297616 },
+  "darwin-x64": { sha256: "a38279143658a8849db484e248c62af6ae2db78de4251021f195efd9bf987d82", bytes: 1306112 },
+};
+function executable(file: string): void {
+  try {
+    if (!statSync(file).isFile()) throw new Error("not a regular file");
+    accessSync(file, constants.X_OK);
+    if (process.platform !== "win32" && (statSync(file).mode & 0o111) === 0) throw new Error("missing executable permission");
+  } catch (cause) {
+    throw new Error(`CREATE2 miner is not an executable file: ${file}`, { cause });
+  }
+}
+export function resolveCreate2MinerBinary(options: Create2MinerBinaryOptions = {}): string {
+  const override = options.binaryPath !== undefined ? options.binaryPath : process.env.GATE_TOOL_CREATE2_MINER_BIN;
+  if (override !== undefined) {
+    if (typeof override !== "string" || override.trim().length === 0) throw new Error("CREATE2 miner binaryPath override must be a non-empty path");
+    const file = resolve(override);
+    executable(file);
+    return file;
+  }
+  const host = `${process.platform}-${process.arch}`;
+  const pin = bundled[host];
+  if (!pin) throw new Error(`No bundled CREATE2 miner for ${host}. Build a compatible smartflow_miner and set GATE_TOOL_CREATE2_MINER_BIN or binaryPath to its executable path.`);
+  const directory = resolve(__dirname, "../../resources/create2");
+  const file = resolve(directory, host, "smartflow_miner");
+  executable(file);
+  const bytes = readFileSync(file);
+  if (bytes.length !== pin.bytes || createHash("sha256").update(bytes).digest("hex") !== pin.sha256) throw new Error(`Bundled CREATE2 miner SHA-256 mismatch: ${file}; reinstall the package or supply a trusted binaryPath`);
+  let entry: { sha256?: unknown; bytes?: unknown } | undefined;
+  try { entry = JSON.parse(readFileSync(resolve(directory, "manifest.json"), "utf8")).binaries?.[host]; }
+  catch (cause) { throw new Error("Bundled CREATE2 miner manifest is invalid", { cause }); }
+  if (!entry || entry.sha256 !== pin.sha256 || entry.bytes !== pin.bytes) throw new Error(`Bundled CREATE2 miner manifest mismatch for ${host}`);
+  return file;
+}

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