gate-evm-tools 1.0.28 → 1.2.0

package/runtime/workflow/lib/runtime.ts

@@ -0,0 +1,46 @@
+import type { Signer } from "ethers";
+import type { WorkflowHre, WorkflowRuntime } from "./context";
+
+export const assertLocalForkHre = (hre: WorkflowHre): void => {
+  if (hre.network.name !== "hardhat" && hre.network.name !== "zkFork") {
+    throw new Error("Simulation requires an explicit local fork network");
+  }
+  const url = (hre.network.config as { url?: string }).url;
+  if (url !== undefined) {
+    let parsed: URL;
+    try { parsed = new URL(url); } catch { throw new Error("Local fork RPC must use a loopback URL"); }
+    if (
+      parsed.protocol !== "http:"
+      || !["127.0.0.1", "localhost", "[::1]"].includes(parsed.hostname)
+      || parsed.username || parsed.password
+    ) {
+      throw new Error("Local fork RPC must use a loopback URL");
+    }
+  }
+};
+
+export const assertLocalForkRuntime = (runtime: WorkflowRuntime): void => {
+  if (!runtime?.hre || !runtime.localFork) {
+    throw new Error("Simulation requires an explicit local fork capability");
+  }
+  assertLocalForkHre(runtime.hre);
+  if (runtime.localFork.provider !== runtime.hre.network.provider) {
+    throw new Error("Simulation local fork capability does not match the runtime provider");
+  }
+};
+
+export const assertLocalForkSigner = (runtime: WorkflowRuntime, signer: Signer): void => {
+  if (signer.provider !== runtime.hre.ethers.provider) {
+    throw new Error("Simulation signer must be connected to the explicit local fork provider");
+  }
+};
+
+export const impersonateLocalForkSigner = async (
+  runtime: WorkflowRuntime,
+  address: string,
+): Promise<Signer> => {
+  assertLocalForkRuntime(runtime);
+  const signer = await runtime.localFork!.impersonate(address);
+  assertLocalForkSigner(runtime, signer);
+  return signer;
+};

package/runtime/workflow/lib/signer.ts

@@ -6,7 +6,8 @@ import {
   createZkSyncSigner,
   resolveWalletCredential,
 } from "gate-evm-tools/custody";
-import { ethers, network } from "../../projectHardhat";
+import type { WorkflowHre } from "./context";
+import { assertLocalForkHre } from "./runtime";
 import { assertExecutionSignerAddress } from "./signerIdentity";
 import type { WorkflowMode } from "./simulation";
 
@@ -47,11 +48,11 @@ export const resolveSimulationSignerAddress = (options: WorkflowSignerOptions):
 };
 
 export const impersonateWorkflowSimulationSigner = async (
+  hre: WorkflowHre,
   signerAddress: string,
 ): Promise<Signer> => {
-  if (network.name !== "hardhat" && network.name !== "zkFork") {
-    throw new Error("Simulation signer impersonation requires a local fork network");
-  }
+  assertLocalForkHre(hre);
+  const { ethers, network } = hre;
   await network.provider.request({
     method: "hardhat_impersonateAccount",
     params: [signerAddress],
@@ -70,11 +71,13 @@ export const impersonateWorkflowSimulationSigner = async (
 };
 
 export const resolveWorkflowSigner = async (
+  hre: WorkflowHre,
   mode: WorkflowMode,
   options: WorkflowSignerOptions = {},
 ): Promise<Signer> => {
+  const { ethers, network } = hre;
   if (mode === "simulate") {
-    return impersonateWorkflowSimulationSigner(resolveSimulationSignerAddress(options));
+    return impersonateWorkflowSimulationSigner(hre, resolveSimulationSignerAddress(options));
   }
 
   const executionCredential = mode === "execute"

package/runtime/workflow/lib/simulation.ts

@@ -1,5 +1,8 @@
 import { isAddress } from "ethers";
-import { config as hardhatConfig, ethers, network } from "../../projectHardhat";
+import type { Provider } from "ethers";
+import type { WorkflowHre } from "./context";
+import { assertLocalForkHre } from "./runtime";
+import { isAllowedSourceRpcMethod } from "./sourceRpcPolicy";
 import {
   CapturedChainSnapshotV1,
   ForkSnapshotV1,
@@ -15,6 +18,7 @@ export type WorkflowMode = "execute" | "simulate" | "verify";
 
 export interface SimulationFork {
   snapshot?: ForkSnapshotV1;
+  sourceRpcUrl?: string;
 }
 
 type WithoutVersion<T> = T extends unknown ? Omit<T, "version"> : never;
@@ -43,8 +47,8 @@ export const resolveWorkflowMode = (
   return mode;
 };
 
-const sourceProxyUrl = (): string => {
-  const value = process.env.GATE_SIMULATION_SOURCE_RPC_URL?.trim();
+const sourceProxyUrl = (sourceRpcUrl: string | undefined): string => {
+  const value = sourceRpcUrl?.trim();
   if (!value) throw new Error("Simulation source-chain proxy URL is missing");
   let parsed: URL;
   try {
@@ -72,6 +76,7 @@ const rpcRequest = async <T>(
   method: string,
   params: unknown[],
 ): Promise<T> => {
+  if (!isAllowedSourceRpcMethod(method)) throw new Error(`Source RPC method is not read-only: ${method}`);
   let response: Response;
   try {
     response = await fetch(url, {
@@ -148,6 +153,7 @@ const requiredInfrastructureAddress = (
 };
 
 export const assertCurrentStateInfrastructure = async (
+  provider: Pick<Provider, "getCode" | "getStorage">,
   targetId: string,
   target: SimulationInfrastructureTarget,
   snapshot: CapturedChainSnapshotV1 | undefined,
@@ -174,7 +180,7 @@ export const assertCurrentStateInfrastructure = async (
     },
   ];
   const code = await Promise.all(infrastructure.map((entry) => (
-    ethers.provider.getCode(entry.address, snapshot.blockNumber)
+    provider.getCode(entry.address, snapshot.blockNumber)
   )));
   for (const [index, entry] of infrastructure.entries()) {
     if (!code[index] || code[index] === "0x") {
@@ -186,19 +192,21 @@ export const assertCurrentStateInfrastructure = async (
 };
 
 export const assertSimulationSourceInfrastructure = async (
+  provider: Pick<Provider, "getCode" | "getStorage">,
   targetId: string,
   target: SimulationInfrastructureTarget,
   simulation: SimulationFork,
-): Promise<void> => assertCurrentStateInfrastructure(targetId, target, simulation.snapshot);
+): Promise<void> => assertCurrentStateInfrastructure(provider, targetId, target, simulation.snapshot);
 
 export const assertCurrentStateUupsSourceState = async (
+  provider: Pick<Provider, "getCode" | "getStorage">,
   snapshot: CapturedChainSnapshotV1 | undefined,
   proxy: string,
 ): Promise<void> => {
   if (!snapshot) return;
   const [proxyCode, oldImplementation] = await Promise.all([
-    ethers.provider.getCode(proxy, snapshot.blockNumber),
-    getERC1967Implementation(ethers.provider, proxy, snapshot.blockNumber),
+    provider.getCode(proxy, snapshot.blockNumber),
+    getERC1967Implementation(provider, proxy, snapshot.blockNumber),
   ]);
   if (!proxyCode || proxyCode === "0x") {
     throw new Error(
@@ -210,7 +218,7 @@ export const assertCurrentStateUupsSourceState = async (
       `UUPS proxy ${proxy} has no implementation at captured block ${snapshot.blockNumber}`,
     );
   }
-  const implementationCode = await ethers.provider.getCode(
+  const implementationCode = await provider.getCode(
     oldImplementation,
     snapshot.blockNumber,
   );
@@ -222,18 +230,22 @@ export const assertCurrentStateUupsSourceState = async (
 };
 
 export const assertSimulationUupsSourceState = async (
+  provider: Pick<Provider, "getCode" | "getStorage">,
   simulation: SimulationFork,
   proxy: string,
-): Promise<void> => assertCurrentStateUupsSourceState(simulation.snapshot, proxy);
+): Promise<void> => assertCurrentStateUupsSourceState(provider, simulation.snapshot, proxy);
 
 export const verifySimulationForkSnapshot = async (
+  hre: WorkflowHre,
   simulation: SimulationFork,
 ): Promise<void> => {
+  assertLocalForkHre(hre);
+  const { network } = hre;
   const snapshot = simulation.snapshot;
   if (!snapshot) return;
   const [sourceBlock, localBlock, sourceZkSyncBlockDetails] = await Promise.all([
     rpcRequest<unknown>(
-      sourceProxyUrl(),
+      sourceProxyUrl(simulation.sourceRpcUrl),
       "eth_getBlockByNumber",
       [blockTag(snapshot.blockNumber), false],
     ),
@@ -243,7 +255,7 @@ export const verifySimulationForkSnapshot = async (
     }),
     snapshot.runner.kind === "anvil-zksync"
       ? rpcRequest<unknown>(
-          sourceProxyUrl(),
+          sourceProxyUrl(simulation.sourceRpcUrl),
           "zks_getBlockDetails",
           [snapshot.blockNumber],
         )
@@ -307,7 +319,19 @@ export const simulationForkEvidence = (
   };
 };
 
-export const setupSimulationFork = async (targetId: string): Promise<SimulationFork> => {
+export interface SimulationForkOptions {
+  snapshotJson?: string;
+  sourceRpcUrl?: string;
+}
+
+// Legacy/launcher helper. The shared step engine never resets or launches a fork.
+export const setupSimulationFork = async (
+  hre: WorkflowHre,
+  targetId: string,
+  options: SimulationForkOptions,
+): Promise<SimulationFork> => {
+  assertLocalForkHre(hre);
+  const { config: hardhatConfig, network } = hre;
   const targetNetwork = (
     hardhatConfig.networks as Record<string, { zksync?: boolean }>
   )[targetId];
@@ -321,7 +345,7 @@ export const setupSimulationFork = async (targetId: string): Promise<SimulationF
       );
     }
     const snapshot = parseForkSnapshotJson(
-      process.env.GATE_SIMULATION_FORK_SNAPSHOT_JSON,
+      options.snapshotJson,
       targetId,
     );
     if (
@@ -353,7 +377,7 @@ export const setupSimulationFork = async (targetId: string): Promise<SimulationF
       );
     }
     assertBlockHash(forkBlock, snapshot, "Local EraVM");
-    return { snapshot };
+    return { snapshot, sourceRpcUrl: sourceProxyUrl(options.sourceRpcUrl) };
   }
   if (network.name !== "hardhat") {
     throw new Error("Simulation mode must run with --network hardhat");
@@ -362,13 +386,13 @@ export const setupSimulationFork = async (targetId: string): Promise<SimulationF
     return {};
   }
   const snapshot = parseForkSnapshotJson(
-    process.env.GATE_SIMULATION_FORK_SNAPSHOT_JSON,
+    options.snapshotJson,
     targetId,
   );
   if (snapshot.runner.kind !== "hardhat") {
     throw new Error(`EVM target "${targetId}" requires a Hardhat fork snapshot`);
   }
-  const forkRpcUrl = sourceProxyUrl();
+  const forkRpcUrl = sourceProxyUrl(options.sourceRpcUrl);
   const sourceBlock = await rpcRequest<unknown>(
     forkRpcUrl,
     "eth_getBlockByNumber",
@@ -411,5 +435,5 @@ export const setupSimulationFork = async (targetId: string): Promise<SimulationF
     params: ["0x1"],
   });
 
-  return { snapshot };
+  return { snapshot, sourceRpcUrl: sourceProxyUrl(options.sourceRpcUrl) };
 };

package/runtime/workflow/lib/state.ts

@@ -1,5 +1,5 @@
 export class WorkflowState {
-  private readonly values: Record<string, unknown> = {};
+  private readonly values: Record<string, unknown> = Object.create(null);
 
   set(key: string, value: unknown): void {
     this.values[key] = value;
@@ -10,7 +10,7 @@ export class WorkflowState {
     let current: unknown = this.values;
 
     for (const part of parts) {
-      if (typeof current !== "object" || current === null || !(part in current)) {
+      if (typeof current !== "object" || current === null || !Object.hasOwn(current, part)) {
         throw new Error(`State reference not found: state.${pathExpression}`);
       }
       current = (current as Record<string, unknown>)[part];
@@ -20,6 +20,6 @@ export class WorkflowState {
   }
 
   snapshot(): Record<string, unknown> {
-    return { ...this.values };
+    return Object.assign(Object.create(null), this.values);
   }
 }

package/runtime/workflow/lib/staticValidation.ts

@@ -2,16 +2,48 @@ import { spawnSync } from "child_process";
 import fs from "fs";
 import path from "path";
 import YAML from "yaml";
+import { isSafeNetworkAlias } from "../../delivery/policy";
 
 export interface StaticValidationCommandResult {
   status: number;
   error?: string;
 }
 
+export type StaticValidationScheme = "evm" | "zksync-eravm";
+
+export interface StaticValidationCompileTarget {
+  scheme: StaticValidationScheme;
+  network: string;
+}
+
+export interface StaticValidationCheckEvidence {
+  label: string;
+  command: string;
+  status: "passed" | "failed";
+  exitCode: number;
+  scheme?: StaticValidationScheme;
+  network?: string;
+  error?: string;
+}
+
+export interface StaticValidationEvidence {
+  schemaVersion: 1;
+  status: "passed" | "failed";
+  deploymentId: string;
+  completedAt: string;
+  checks: StaticValidationCheckEvidence[];
+  compileTargets: StaticValidationCompileTarget[];
+  compiledSchemes: StaticValidationScheme[];
+  blockingReasons: string[];
+}
+
 export interface StaticValidationOptions {
+  /** Omit to retain the legacy dual-scheme requirement. */
+  requiredSchemes?: StaticValidationScheme[];
   root: string;
   deploymentId: string;
   network?: string;
+  compileTargets?: StaticValidationCompileTarget[];
   testCommand?: { command: string; args: string[] };
   runCommand?: (
     command: string,
@@ -24,6 +56,7 @@ export interface StaticValidationOptions {
 export interface StaticValidationResult {
   status: "passed" | "failed";
   reportPath: string;
+  evidencePath: string;
 }
 
 const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,199}$/;
@@ -86,42 +119,86 @@ export const runStaticValidation = async (
   options: StaticValidationOptions,
 ): Promise<StaticValidationResult> => {
   if (!SAFE_ID.test(options.deploymentId)) throw new Error("deploymentId is invalid");
-  if (options.network !== undefined && !SAFE_ID.test(options.network)) {
+  if (options.network !== undefined && !isSafeNetworkAlias(options.network)) {
     throw new Error("network is invalid");
   }
+  const compileTargets = options.compileTargets || (options.network
+    ? [{ scheme: "evm" as const, network: options.network }]
+    : []);
+  const requiredSchemes = options.requiredSchemes ?? ["evm", "zksync-eravm"];
+  const invalidTargets = (
+    requiredSchemes.length === 0
+    || new Set(requiredSchemes).size !== requiredSchemes.length
+    || requiredSchemes.some(scheme => !["evm", "zksync-eravm"].includes(scheme))
+    || compileTargets.length !== requiredSchemes.length
+    || new Set(compileTargets.map(target => target.scheme)).size !== requiredSchemes.length
+    || requiredSchemes.some(scheme => !compileTargets.some(target => target.scheme === scheme))
+    || compileTargets.some(target => !isSafeNetworkAlias(target.network))
+  );
   const taskDir = path.join(options.root, "scripts", "tasks", options.deploymentId);
   if (!fs.existsSync(taskDir) || !fs.statSync(taskDir).isDirectory()) {
     throw new Error(`Deployment task does not exist: ${options.deploymentId}`);
   }
   const runCommand = options.runCommand || defaultRunCommand;
-  const compileArgs = options.network
-    ? ["run", "compile", "--", "--network", options.network]
-    : ["run", "compile"];
   const commands = [
-    { label: ["npm", ...compileArgs].join(" "), command: "npm", args: compileArgs },
-    { label: "npx tsc --noEmit", command: "npx", args: ["tsc", "--noEmit"] },
+    ...compileTargets.map((target) => ({
+      label: `npm run compile -- --network ${target.network}`,
+      command: "npm",
+      args: ["run", "compile", "--", "--network", target.network],
+      scheme: target.scheme,
+      network: target.network,
+    })),
+    { label: "npx tsc --noEmit", command: "npx", args: ["tsc", "--noEmit"], scheme: undefined, network: undefined },
     {
       label: (options.testCommand
         ? [options.testCommand.command, ...options.testCommand.args]
         : ["npm", "test"]).join(" "),
       command: options.testCommand?.command || "npm",
       args: options.testCommand?.args || ["test"],
+      scheme: undefined,
+      network: undefined,
     },
   ];
-  const evidence: Array<{ label: string; result: StaticValidationCommandResult }> = [];
-  for (const command of commands) {
+  const evidence: Array<{ label: string; result: StaticValidationCommandResult; scheme?: StaticValidationScheme; network?: string }> = [];
+  for (const command of invalidTargets ? [] : commands) {
     let result: StaticValidationCommandResult;
     try {
       result = await runCommand(command.command, command.args, { cwd: options.root });
     } catch (error) {
       result = { status: 1, error: error instanceof Error ? error.message : String(error) };
     }
-    evidence.push({ label: command.label, result });
+    evidence.push({ label: command.label, result, scheme: command.scheme, network: command.network });
   }
   evidence.push({ label: "YAML/JSON parse", result: parseTaskDocuments(taskDir) });
-  const status = evidence.every((entry) => entry.result.status === 0) ? "passed" : "failed";
+  const status = !invalidTargets && evidence.every((entry) => entry.result.status === 0) ? "passed" : "failed";
   const completedAt = (options.now || (() => new Date().toISOString()))();
   const reportPath = `scripts/tasks/${options.deploymentId}/docs/static-validation.md`;
+  const evidencePath = `scripts/tasks/${options.deploymentId}/docs/static-validation.json`;
+  const checks: StaticValidationCheckEvidence[] = evidence.map((entry) => ({
+    label: entry.label,
+    command: entry.label,
+    status: entry.result.status === 0 ? "passed" : "failed",
+    exitCode: entry.result.status,
+    ...(entry.scheme ? { scheme: entry.scheme } : {}),
+    ...(entry.network ? { network: entry.network } : {}),
+    ...(entry.result.error ? { error: entry.result.error } : {}),
+  }));
+  const structuredEvidence: StaticValidationEvidence = {
+    schemaVersion: 1,
+    status,
+    deploymentId: options.deploymentId,
+    completedAt,
+    checks,
+    compileTargets,
+    compiledSchemes: compileTargets
+      .filter((target) => checks.some((check) => check.scheme === target.scheme && check.status === "passed"))
+      .map((target) => target.scheme),
+    blockingReasons: [
+      ...(invalidTargets ? [options.requiredSchemes ? `compileTargets must include exactly one target for each required scheme: ${requiredSchemes.join(", ")}` : "compileTargets must include exactly one evm and one zksync-eravm target"] : []),
+      ...checks.filter((check) => check.status !== "passed")
+        .map((check) => check.scheme ? `${check.scheme} (${check.network}) compile failed` : `${check.label} failed`),
+    ],
+  };
   const lines = [
     "# Static Validation",
     "",
@@ -138,5 +215,9 @@ export const runStaticValidation = async (
     ]),
   ];
   writeTextAtomic(path.join(options.root, ...reportPath.split("/")), lines.join("\n"));
-  return { status, reportPath };
+  writeTextAtomic(
+    path.join(options.root, ...evidencePath.split("/")),
+    `${JSON.stringify(structuredEvidence, null, 2)}\n`,
+  );
+  return { status, reportPath, evidencePath };
 };