gate-evm-tools 1.0.25 → 1.0.27

package/runtime/workflow/lib/simulationCallers.ts

@@ -0,0 +1,335 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { getAddress, ZeroAddress } from "ethers";
+import YAML from "yaml";
+import { hashValue } from "./release";
+
+export interface SimulationCallerNetworkInput {
+  default: string;
+  steps?: Record<string, string>;
+}
+
+export interface SimulationCallersDocument {
+  version: 1;
+  networks: Record<string, SimulationCallerNetworkInput>;
+}
+
+export interface ResolvedSimulationCaller {
+  stepId: string;
+  callerAddress: string;
+  source: "step" | "network_default";
+}
+
+export interface SimulationCallerNetworkBinding {
+  network: string;
+  manifestHash: string;
+  defaultAddress: string;
+  resolved: ResolvedSimulationCaller[];
+  networkHash: string;
+}
+
+interface ManifestStepInput {
+  id: string;
+  kind: string;
+}
+
+const UNSAFE_KEYS = new Set(["__proto__", "prototype", "constructor"]);
+
+const record = <T>(): Record<string, T> => (
+  Object.create(null) as Record<string, T>
+);
+
+const stringKey = (value: unknown, label: string): string => {
+  if (typeof value !== "string" || !value || value !== value.trim()) {
+    throw new Error(`${label} must be a non-empty string without surrounding whitespace`);
+  }
+  if (value === "<<" || UNSAFE_KEYS.has(value)) {
+    throw new Error(`${label} contains an unsafe key`);
+  }
+  return value;
+};
+
+const normalizedAddress = (value: unknown, label: string): string => {
+  if (typeof value !== "string" || !value || value !== value.trim()) {
+    throw new Error(`${label} must be a valid non-zero EVM address`);
+  }
+  try {
+    const address = getAddress(value);
+    if (address === ZeroAddress) throw new Error("zero address");
+    return address;
+  } catch {
+    throw new Error(`${label} must be a valid non-zero EVM address`);
+  }
+};
+
+const entriesOf = (value: unknown, label: string): Array<[string, unknown]> => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must be a mapping`);
+  }
+  return Object.keys(value as Record<string, unknown>).map((key) => [
+    stringKey(key, `${label} key`),
+    (value as Record<string, unknown>)[key],
+  ]);
+};
+
+const normalizeDocument = (value: unknown): SimulationCallersDocument => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("simulation callers document must be a mapping");
+  }
+  const document = value as Record<string, unknown>;
+  const keys = Object.keys(document);
+  if (keys.length !== 2 || !keys.includes("version") || !keys.includes("networks")) {
+    throw new Error("simulation callers document contains unsupported or missing fields");
+  }
+  if (document.version !== 1 && document.version !== "1") {
+    throw new Error("simulation callers version must equal 1");
+  }
+
+  const networks = record<SimulationCallerNetworkInput>();
+  for (const [network, networkValue] of entriesOf(
+    document.networks,
+    "simulation callers networks",
+  )) {
+    const networkEntries = entriesOf(networkValue, `simulation caller network ${network}`);
+    const networkKeys = new Set(networkEntries.map(([key]) => key));
+    if (!networkKeys.has("default")) {
+      throw new Error(`simulation caller network ${network} is missing required field default`);
+    }
+    if ([...networkKeys].some((key) => key !== "default" && key !== "steps")) {
+      throw new Error(`simulation caller network ${network} contains unsupported fields`);
+    }
+    const networkRecord = Object.fromEntries(networkEntries) as Record<string, unknown>;
+    const defaultAddress = normalizedAddress(
+      networkRecord.default,
+      `simulation caller network ${network} default`,
+    );
+    const stepsValue = networkRecord.steps;
+    let steps: Record<string, string> | undefined;
+    if (stepsValue !== undefined) {
+      steps = record<string>();
+      for (const [stepId, address] of entriesOf(
+        stepsValue,
+        `simulation caller network ${network} steps`,
+      )) {
+        steps[stepId] = normalizedAddress(
+          address,
+          `simulation caller network ${network} step ${stepId}`,
+        );
+      }
+    }
+    networks[network] = {
+      default: defaultAddress,
+      ...(steps ? { steps } : {}),
+    };
+  }
+  return { version: 1, networks };
+};
+
+const parseYamlValue = (text: string): unknown => {
+  if (typeof text !== "string") throw new Error("simulation callers YAML must be text");
+  const document = YAML.parseDocument(text, {
+    merge: false,
+    prettyErrors: true,
+    schema: "failsafe",
+    uniqueKeys: true,
+  });
+  if (document.errors.length > 0) {
+    throw new Error(`invalid simulation callers YAML: ${document.errors[0].message}`);
+  }
+  const compatibleDocument = document as unknown as {
+    toJS?: (options: { mapAsMap: boolean; maxAliasCount: number }) => unknown;
+    toJSON: () => unknown;
+  };
+  return typeof compatibleDocument.toJS === "function"
+    ? compatibleDocument.toJS({ mapAsMap: true, maxAliasCount: 0 })
+    : compatibleDocument.toJSON();
+};
+
+const mapToNullRecords = (value: unknown, label: string): unknown => {
+  if (value instanceof Map) {
+    const output = record<unknown>();
+    for (const [keyValue, child] of value.entries()) {
+      const key = stringKey(keyValue, `${label} key`);
+      output[key] = mapToNullRecords(child, `${label}.${key}`);
+    }
+    return output;
+  }
+  if (Array.isArray(value)) {
+    return value.map((child, index) => mapToNullRecords(child, `${label}[${index}]`));
+  }
+  return value;
+};
+
+const validatedManifestSteps = (steps: ManifestStepInput[]): ManifestStepInput[] => {
+  if (!Array.isArray(steps) || steps.length === 0) {
+    throw new Error("Manifest must contain at least one simulation caller step");
+  }
+  const seen = new Set<string>();
+  return steps.map((step, index) => {
+    if (!step || typeof step !== "object") {
+      throw new Error(`Manifest step ${index} is invalid`);
+    }
+    const id = stringKey(step.id, `Manifest step ${index} id`);
+    if (seen.has(id)) throw new Error(`Duplicate Manifest step ${id}`);
+    seen.add(id);
+    if (typeof step.kind !== "string" || !step.kind || step.kind !== step.kind.trim()) {
+      throw new Error(`Manifest step ${id} kind must be a non-empty string`);
+    }
+    return { id, kind: step.kind };
+  });
+};
+
+const manifestHash = (value: string): string => (
+  crypto.createHash("sha256").update(value).digest("hex")
+);
+
+export const parseSimulationCallersYaml = (text: string): SimulationCallersDocument => {
+  return normalizeDocument(
+    mapToNullRecords(parseYamlValue(text), "simulation callers document"),
+  );
+};
+
+export const validateSimulationCallersDocument = (input: {
+  document: SimulationCallersDocument;
+  targetNetworks: string[];
+  manifestSteps: ManifestStepInput[];
+}): SimulationCallersDocument => {
+  const document = normalizeDocument(input.document);
+  if (!Array.isArray(input.targetNetworks) || input.targetNetworks.length === 0) {
+    throw new Error("simulation caller target networks must be a non-empty array");
+  }
+  const targetNetworks = input.targetNetworks.map((network, index) => (
+    stringKey(network, `simulation caller target network ${index}`)
+  ));
+  if (new Set(targetNetworks).size !== targetNetworks.length) {
+    throw new Error("Duplicate simulation caller target network");
+  }
+  const configuredNetworks = Object.keys(document.networks);
+  const expectedSet = [...targetNetworks].sort();
+  const configuredSet = [...configuredNetworks].sort();
+  if (
+    expectedSet.length !== configuredSet.length
+    || expectedSet.some((network, index) => network !== configuredSet[index])
+  ) {
+    throw new Error("simulation caller target networks do not match configured target networks");
+  }
+
+  const manifestSteps = validatedManifestSteps(input.manifestSteps);
+  const manifestStepIds = new Set(manifestSteps.map((step) => step.id));
+  const networks = record<SimulationCallerNetworkInput>();
+  for (const network of targetNetworks) {
+    const configured = document.networks[network];
+    const steps = record<string>();
+    for (const stepId of Object.keys(configured.steps ?? {})) {
+      if (!manifestStepIds.has(stepId)) {
+        throw new Error(
+          `simulation caller network ${network} references unknown Manifest step ${stepId}`,
+        );
+      }
+    }
+    for (const step of manifestSteps) {
+      const override = configured.steps?.[step.id];
+      if (override !== undefined) steps[step.id] = override;
+    }
+    networks[network] = {
+      default: configured.default,
+      ...(Object.keys(steps).length > 0 ? { steps } : {}),
+    };
+  }
+  return { version: 1, networks };
+};
+
+export const buildSimulationCallerNetworkBinding = (input: {
+  document: SimulationCallersDocument;
+  network: string;
+  manifestText: string;
+  manifestSteps: ManifestStepInput[];
+}): SimulationCallerNetworkBinding => {
+  const document = normalizeDocument(input.document);
+  const network = stringKey(input.network, "simulation caller binding network");
+  const configured = document.networks[network];
+  if (!configured) throw new Error(`Unknown simulation caller network ${network}`);
+  const manifestSteps = validatedManifestSteps(input.manifestSteps);
+  const manifestStepIds = new Set(manifestSteps.map((step) => step.id));
+  for (const stepId of Object.keys(configured.steps ?? {})) {
+    if (!manifestStepIds.has(stepId)) {
+      throw new Error(
+        `simulation caller network ${network} references unknown Manifest step ${stepId}`,
+      );
+    }
+  }
+  const resolved: ResolvedSimulationCaller[] = manifestSteps.map((step) => {
+    const callerAddress = configured.steps?.[step.id];
+    return callerAddress === undefined
+      ? {
+          stepId: step.id,
+          callerAddress: configured.default,
+          source: "network_default" as const,
+        }
+      : { stepId: step.id, callerAddress, source: "step" as const };
+  });
+  const exactManifestHash = manifestHash(input.manifestText);
+  const networkHash = hashValue({
+    version: 1,
+    manifestHash: exactManifestHash,
+    network,
+    default: configured.default.toLowerCase(),
+    resolved: resolved.map((entry) => ({
+      stepId: entry.stepId,
+      callerAddress: entry.callerAddress.toLowerCase(),
+    })),
+  });
+  return {
+    network,
+    manifestHash: exactManifestHash,
+    defaultAddress: configured.default,
+    resolved,
+    networkHash,
+  };
+};
+
+const simulationCallersPath = (taskDir: string): string => {
+  const realTaskDir = fs.realpathSync(taskDir);
+  const filePath = path.resolve(realTaskDir, "simulation-callers.yaml");
+  if (path.dirname(filePath) !== realTaskDir) {
+    throw new Error("simulation callers path escapes the task directory");
+  }
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`Missing simulation callers file: ${filePath}`);
+  }
+  const stat = fs.lstatSync(filePath);
+  if (stat.isSymbolicLink()) {
+    throw new Error("simulation callers file cannot be a symlink");
+  }
+  if (!stat.isFile()) {
+    throw new Error("simulation callers path must be a regular file");
+  }
+  const realFilePath = fs.realpathSync(filePath);
+  if (path.dirname(realFilePath) !== realTaskDir) {
+    throw new Error("simulation callers file escapes the task directory");
+  }
+  return filePath;
+};
+
+export const loadSimulationCallerNetwork = (input: {
+  taskDir: string;
+  targetNetworks: string[];
+  network: string;
+  manifestText: string;
+  manifestSteps: ManifestStepInput[];
+}): SimulationCallerNetworkBinding => {
+  const document = validateSimulationCallersDocument({
+    document: parseSimulationCallersYaml(
+      fs.readFileSync(simulationCallersPath(input.taskDir), "utf8"),
+    ),
+    targetNetworks: input.targetNetworks,
+    manifestSteps: input.manifestSteps,
+  });
+  return buildSimulationCallerNetworkBinding({
+    document,
+    network: input.network,
+    manifestText: input.manifestText,
+    manifestSteps: input.manifestSteps,
+  });
+};

package/runtime/workflow/lib/sourceRpcPolicy.ts

@@ -0,0 +1,41 @@
+// The source-chain proxy exists only to hydrate a pinned local fork and verify
+// its source snapshot. Keep this surface explicit: adding a method requires a
+// review that it cannot sign, submit, mine, or otherwise mutate remote state.
+const ALLOWED_SOURCE_RPC_METHODS = new Set([
+  "debug_traceTransaction",
+  "eth_blockNumber",
+  "eth_call",
+  "eth_chainId",
+  "eth_estimateGas",
+  "eth_feeHistory",
+  "eth_gasPrice",
+  "eth_getBalance",
+  "eth_getBlockByHash",
+  "eth_getBlockByNumber",
+  "eth_getBlockReceipts",
+  "eth_getBlockTransactionCountByHash",
+  "eth_getBlockTransactionCountByNumber",
+  "eth_getCode",
+  "eth_getLogs",
+  "eth_getProof",
+  "eth_getStorageAt",
+  "eth_getTransactionByBlockHashAndIndex",
+  "eth_getTransactionByBlockNumberAndIndex",
+  "eth_getTransactionByHash",
+  "eth_getTransactionCount",
+  "eth_getTransactionReceipt",
+  "eth_maxPriorityFeePerGas",
+  "net_version",
+  "web3_clientVersion",
+  "zks_getBlockDetails",
+  "zks_getBridgeContracts",
+  "zks_getBytecodeByHash",
+  "zks_getFeeParams",
+  "zks_getProof",
+  "zks_getRawBlockTransactions",
+  "zks_getTransactionDetails",
+]);
+
+export const isAllowedSourceRpcMethod = (method: string): boolean => (
+  ALLOWED_SOURCE_RPC_METHODS.has(method)
+);

package/runtime/workflow/lib/state.ts

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

package/runtime/workflow/lib/staticValidation.ts

@@ -0,0 +1,142 @@
+import { spawnSync } from "child_process";
+import fs from "fs";
+import path from "path";
+import YAML from "yaml";
+
+export interface StaticValidationCommandResult {
+  status: number;
+  error?: string;
+}
+
+export interface StaticValidationOptions {
+  root: string;
+  deploymentId: string;
+  network?: string;
+  testCommand?: { command: string; args: string[] };
+  runCommand?: (
+    command: string,
+    args: string[],
+    options: { cwd: string },
+  ) => Promise<StaticValidationCommandResult> | StaticValidationCommandResult;
+  now?: () => string;
+}
+
+export interface StaticValidationResult {
+  status: "passed" | "failed";
+  reportPath: string;
+}
+
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,199}$/;
+
+const defaultRunCommand = (
+  command: string,
+  args: string[],
+  options: { cwd: string },
+): StaticValidationCommandResult => {
+  const executable = process.platform === "win32" && (command === "npm" || command === "npx")
+    ? `${command}.cmd`
+    : command;
+  const result = spawnSync(executable, args, { cwd: options.cwd, env: process.env, stdio: "inherit" });
+  return { status: result.status ?? 1, error: result.error?.message };
+};
+
+const taskDocuments = (taskDir: string): string[] => {
+  const files: string[] = [];
+  const visit = (directory: string): void => {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      const filePath = path.join(directory, entry.name);
+      if (entry.isSymbolicLink()) throw new Error(`Task validation does not follow symlinks: ${filePath}`);
+      if (entry.isDirectory()) {
+        visit(filePath);
+      } else if (/\.(?:json|ya?ml)$/i.test(entry.name)) {
+        files.push(filePath);
+      }
+    }
+  };
+  visit(taskDir);
+  return files.sort();
+};
+
+const parseTaskDocuments = (taskDir: string): StaticValidationCommandResult => {
+  try {
+    for (const filePath of taskDocuments(taskDir)) {
+      const contents = fs.readFileSync(filePath, "utf8");
+      if (/\.json$/i.test(filePath)) JSON.parse(contents);
+      else YAML.parse(contents);
+    }
+    return { status: 0 };
+  } catch (error) {
+    return { status: 1, error: error instanceof Error ? error.message : String(error) };
+  }
+};
+
+const writeTextAtomic = (filePath: string, contents: string): void => {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const temporary = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    fs.writeFileSync(temporary, contents);
+    fs.renameSync(temporary, filePath);
+  } catch (error) {
+    if (fs.existsSync(temporary)) fs.unlinkSync(temporary);
+    throw error;
+  }
+};
+
+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)) {
+    throw new Error("network is invalid");
+  }
+  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"] },
+    {
+      label: (options.testCommand
+        ? [options.testCommand.command, ...options.testCommand.args]
+        : ["npm", "test"]).join(" "),
+      command: options.testCommand?.command || "npm",
+      args: options.testCommand?.args || ["test"],
+    },
+  ];
+  const evidence: Array<{ label: string; result: StaticValidationCommandResult }> = [];
+  for (const command of 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: "YAML/JSON parse", result: parseTaskDocuments(taskDir) });
+  const status = 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 lines = [
+    "# Static Validation",
+    "",
+    `status: ${status}`,
+    `completedAt: ${completedAt}`,
+    "",
+    ...evidence.flatMap((entry) => [
+      `## ${entry.label}`,
+      `command: ${entry.label}`,
+      `result: ${entry.result.status === 0 ? "passed" : "failed"}`,
+      `exit: ${entry.result.status}`,
+      ...(entry.result.error ? [`error: ${entry.result.error}`] : []),
+      "",
+    ]),
+  ];
+  writeTextAtomic(path.join(options.root, ...reportPath.split("/")), lines.join("\n"));
+  return { status, reportPath };
+};

package/runtime/workflow/lib/zksyncForkCapability.ts

@@ -0,0 +1,80 @@
+export interface ZkSyncForkRunnerIdentity {
+  kind: "anvil-zksync";
+  version: string;
+}
+
+export interface ResolvedZkSyncForkCapability {
+  runner: ZkSyncForkRunnerIdentity;
+  sourceProtocolVersion: number;
+  runnerProtocolVersion: number;
+}
+
+export interface ZkSyncForkRunnerArtifact {
+  assetName: string;
+  archiveSha256: string;
+  binarySha256: string;
+}
+
+interface ProtocolInputOverride {
+  sourceProtocolVersion: number;
+  runnerProtocolVersion: number;
+}
+
+const ZKSYNC_FORK_RUNNER_ARTIFACTS = Object.freeze<Record<string, ZkSyncForkRunnerArtifact>>({
+  "darwin/arm64": Object.freeze({
+    assetName: "anvil-zksync-v0.6.11-aarch64-apple-darwin.tar.gz",
+    archiveSha256: "79c15e079a4e7ac490e4c44572f81b918a81af315eacdd6e3639e66a2be8635c",
+    binarySha256: "881fc4d1a0ae43eea01da9e750da782b60e3babacae5f8b327eb0406024fa417",
+  }),
+  "linux/arm64": Object.freeze({
+    assetName: "anvil-zksync-v0.6.11-aarch64-unknown-linux-gnu.tar.gz",
+    archiveSha256: "f7d85fd20a41004e4c8662f6748a89ee45e9dc940bbca3a29b2a1634648a7285",
+    binarySha256: "565ea5418561937d704c5ef0b2fcea1cb01cd2338e45fdd32ac0516395938216",
+  }),
+  "darwin/x64": Object.freeze({
+    assetName: "anvil-zksync-v0.6.11-x86_64-apple-darwin.tar.gz",
+    archiveSha256: "7cff268d2a0a216f8d690d1e37e3f03ca2e45f8cef7657066d8c238efc89a2b4",
+    binarySha256: "0c39d3237e9f895633bf7d14d7ead7e08daf9ba7c5845e1b83d8dbe724bb04aa",
+  }),
+  "linux/x64": Object.freeze({
+    assetName: "anvil-zksync-v0.6.11-x86_64-unknown-linux-gnu.tar.gz",
+    archiveSha256: "127f1a75b6c4ccc5eaef00ca62753f243a76ba927cbd64a7b1bd99a5b5fb8728",
+    binarySha256: "4a801b25f543099838fa88df50f0e59f5e5c93b7a22330948ca7ed029f48228b",
+  }),
+});
+
+export const ZKSYNC_FORK_RUNNER = Object.freeze({
+  kind: "anvil-zksync" as const,
+  version: "0.6.11",
+  minimumSourceProtocolVersion: 26,
+  protocolInputOverrides: Object.freeze<readonly ProtocolInputOverride[]>([
+    Object.freeze({ sourceProtocolVersion: 30, runnerProtocolVersion: 29 }),
+  ]),
+});
+
+export const resolveZkSyncForkRunnerArtifact = (
+  platform: string = process.platform,
+  arch: string = process.arch,
+): ZkSyncForkRunnerArtifact | undefined => ZKSYNC_FORK_RUNNER_ARTIFACTS[`${platform}/${arch}`];
+
+export const resolveZkSyncForkCapability = (
+  sourceProtocolVersion: number,
+): ResolvedZkSyncForkCapability | undefined => {
+  if (
+    !Number.isSafeInteger(sourceProtocolVersion)
+    || sourceProtocolVersion < ZKSYNC_FORK_RUNNER.minimumSourceProtocolVersion
+  ) {
+    return undefined;
+  }
+  const protocolOverride = ZKSYNC_FORK_RUNNER.protocolInputOverrides.find(
+    (entry) => entry.sourceProtocolVersion === sourceProtocolVersion,
+  );
+  return {
+    runner: {
+      kind: ZKSYNC_FORK_RUNNER.kind,
+      version: ZKSYNC_FORK_RUNNER.version,
+    },
+    sourceProtocolVersion,
+    runnerProtocolVersion: protocolOverride?.runnerProtocolVersion ?? sourceProtocolVersion,
+  };
+};