gate-evm-tools 1.0.26 → 1.0.28

package/runtime/workflow/lib/forkSnapshot.ts

@@ -0,0 +1,231 @@
+export type ForkRunnerKind = "hardhat" | "anvil-zksync";
+
+interface CapturedChainSnapshotBaseV1 {
+  version: 1;
+  sourceNetwork: string;
+  chainId: number;
+  blockNumber: number;
+  blockHash: string;
+}
+
+export interface CapturedEvmChainSnapshotV1 extends CapturedChainSnapshotBaseV1 {}
+
+export interface CapturedZkSyncChainSnapshotV1 extends CapturedChainSnapshotBaseV1 {
+  protocolVersion: number;
+  l1BatchNumber: number;
+}
+
+export type CapturedChainSnapshotV1 =
+  | CapturedEvmChainSnapshotV1
+  | CapturedZkSyncChainSnapshotV1;
+
+export type ForkSnapshotV1 =
+  | (CapturedEvmChainSnapshotV1 & {
+      runner: { kind: "hardhat"; version: string };
+    })
+  | (CapturedZkSyncChainSnapshotV1 & {
+      runner: { kind: "anvil-zksync"; version: string };
+    });
+
+const NETWORK_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/;
+const BLOCK_HASH = /^0x[0-9a-fA-F]{64}$/;
+const RUNNER_VERSION = /^[A-Za-z0-9][A-Za-z0-9.+_-]{0,63}$/;
+const PROTOCOL_VERSION = /^Version([1-9][0-9]*)$/;
+const BASE_KEYS = [
+  "version",
+  "sourceNetwork",
+  "chainId",
+  "blockNumber",
+  "blockHash",
+] as const;
+const ZKSYNC_KEYS = [...BASE_KEYS, "protocolVersion", "l1BatchNumber"] as const;
+
+const isRecord = (value: unknown): value is Record<string, unknown> => (
+  value !== null && typeof value === "object" && !Array.isArray(value)
+);
+
+const exactKeys = (
+  value: Record<string, unknown>,
+  expected: readonly string[],
+  label: string,
+): void => {
+  const actual = Object.keys(value).sort();
+  const canonical = [...expected].sort();
+  if (
+    actual.length !== canonical.length
+    || actual.some((key, index) => key !== canonical[index])
+  ) {
+    throw new Error(`${label} fields are invalid`);
+  }
+};
+
+const positiveSafeInteger = (value: unknown, label: string): number => {
+  if (!Number.isSafeInteger(value) || Number(value) <= 0) {
+    throw new Error(`${label} must be a positive safe integer`);
+  }
+  return Number(value);
+};
+
+const nonNegativeSafeInteger = (value: unknown, label: string): number => {
+  if (!Number.isSafeInteger(value) || Number(value) < 0) {
+    throw new Error(`${label} must be a non-negative safe integer`);
+  }
+  return Number(value);
+};
+
+const parseProtocolVersion = (value: unknown): number => {
+  if (Number.isSafeInteger(value) && Number(value) > 0) return Number(value);
+  if (typeof value !== "string") {
+    throw new Error("zkSync protocolVersion is invalid");
+  }
+  const match = PROTOCOL_VERSION.exec(value);
+  if (!match) throw new Error("zkSync protocolVersion is invalid");
+  return positiveSafeInteger(Number(match[1]), "zkSync protocolVersion");
+};
+
+const parseBaseSnapshot = (
+  value: Record<string, unknown>,
+  expectedSourceNetwork?: string,
+): CapturedChainSnapshotBaseV1 => {
+  if (value.version !== 1) throw new Error("fork snapshot version is invalid");
+  if (typeof value.sourceNetwork !== "string" || !NETWORK_ID.test(value.sourceNetwork)) {
+    throw new Error("fork snapshot sourceNetwork is invalid");
+  }
+  if (expectedSourceNetwork !== undefined && value.sourceNetwork !== expectedSourceNetwork) {
+    throw new Error("fork snapshot sourceNetwork does not match the requested target");
+  }
+  if (!Number.isSafeInteger(value.chainId) || Number(value.chainId) <= 0) {
+    throw new Error("fork snapshot chainId must be a positive safe integer");
+  }
+  if (!Number.isSafeInteger(value.blockNumber) || Number(value.blockNumber) < 0) {
+    throw new Error("fork snapshot blockNumber must be a non-negative safe integer");
+  }
+  if (typeof value.blockHash !== "string" || !BLOCK_HASH.test(value.blockHash)) {
+    throw new Error("fork snapshot blockHash must be a 32-byte hash");
+  }
+  return {
+    version: 1,
+    sourceNetwork: value.sourceNetwork,
+    chainId: Number(value.chainId),
+    blockNumber: Number(value.blockNumber),
+    blockHash: value.blockHash.toLowerCase(),
+  };
+};
+
+export const isCapturedZkSyncChainSnapshot = (
+  value: CapturedChainSnapshotV1,
+): value is CapturedZkSyncChainSnapshotV1 => "protocolVersion" in value;
+
+export const parseCapturedChainSnapshot = (
+  value: unknown,
+  expectedSourceNetwork?: string,
+  expectedZkSync?: boolean,
+): CapturedChainSnapshotV1 => {
+  if (!isRecord(value)) throw new Error("fork snapshot must be an object");
+  const hasZkSyncFields = Object.hasOwn(value, "protocolVersion")
+    || Object.hasOwn(value, "l1BatchNumber");
+  const zksync = expectedZkSync ?? hasZkSyncFields;
+  exactKeys(value, zksync ? ZKSYNC_KEYS : BASE_KEYS, "fork snapshot");
+  const base = parseBaseSnapshot(value, expectedSourceNetwork);
+  if (!zksync) return base;
+  return {
+    ...base,
+    protocolVersion: parseProtocolVersion(value.protocolVersion),
+    l1BatchNumber: nonNegativeSafeInteger(
+      value.l1BatchNumber,
+      "zkSync l1BatchNumber",
+    ),
+  };
+};
+
+export const parseCapturedChainSnapshotJson = (
+  value: string | undefined,
+  expectedSourceNetwork?: string,
+  expectedZkSync?: boolean,
+): CapturedChainSnapshotV1 => {
+  if (!value) throw new Error("current-state snapshot environment is missing");
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    throw new Error("current-state snapshot environment must contain valid JSON");
+  }
+  return parseCapturedChainSnapshot(parsed, expectedSourceNetwork, expectedZkSync);
+};
+
+export const parseZkSyncBlockDetails = (
+  value: unknown,
+  expectedBlockNumber: number,
+): Pick<CapturedZkSyncChainSnapshotV1, "protocolVersion" | "l1BatchNumber"> => {
+  if (!isRecord(value)) throw new Error("zkSync block details are missing");
+  const blockNumber = nonNegativeSafeInteger(value.number, "zkSync block details number");
+  if (blockNumber !== expectedBlockNumber) {
+    throw new Error("zkSync block details number does not match the captured block number");
+  }
+  return {
+    protocolVersion: parseProtocolVersion(value.protocolVersion),
+    l1BatchNumber: nonNegativeSafeInteger(
+      value.l1BatchNumber,
+      "zkSync block details l1BatchNumber",
+    ),
+  };
+};
+
+export const parseForkSnapshot = (
+  value: unknown,
+  expectedSourceNetwork?: string,
+): ForkSnapshotV1 => {
+  if (!isRecord(value)) throw new Error("fork snapshot must be an object");
+  if (!isRecord(value.runner)) throw new Error("fork snapshot runner must be an object");
+  exactKeys(value.runner, ["kind", "version"], "fork snapshot runner");
+  if (value.runner.kind !== "hardhat" && value.runner.kind !== "anvil-zksync") {
+    throw new Error("fork snapshot runner kind is invalid");
+  }
+  if (
+    typeof value.runner.version !== "string"
+    || !RUNNER_VERSION.test(value.runner.version)
+  ) {
+    throw new Error("fork snapshot runner version is invalid");
+  }
+  const { runner: _runner, ...capturedValue } = value;
+  const captured = parseCapturedChainSnapshot(
+    capturedValue,
+    expectedSourceNetwork,
+    value.runner.kind === "anvil-zksync",
+  );
+  if (value.runner.kind === "anvil-zksync") {
+    if (!isCapturedZkSyncChainSnapshot(captured)) {
+      throw new Error("zkSync fork snapshot protocol metadata is missing");
+    }
+    return {
+      ...captured,
+      runner: { kind: "anvil-zksync", version: value.runner.version },
+    };
+  }
+  if (isCapturedZkSyncChainSnapshot(captured)) {
+    throw new Error("EVM fork snapshot cannot contain zkSync protocol metadata");
+  }
+  return {
+    ...captured,
+    runner: { kind: "hardhat", version: value.runner.version },
+  };
+};
+
+export const parseForkSnapshotJson = (
+  value: string | undefined,
+  expectedSourceNetwork?: string,
+): ForkSnapshotV1 => {
+  if (!value) throw new Error("fork snapshot environment is missing");
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    throw new Error("fork snapshot environment must contain valid JSON");
+  }
+  return parseForkSnapshot(parsed, expectedSourceNetwork);
+};
+
+export const buildForkSnapshot = (
+  captured: CapturedChainSnapshotV1,
+  runner: ForkSnapshotV1["runner"],
+): ForkSnapshotV1 => parseForkSnapshot({ ...captured, runner }, captured.sourceNetwork);

package/runtime/workflow/lib/gateTool.ts

@@ -0,0 +1,261 @@
+import fs from "fs";
+import path from "path";
+import hardhat from "../../projectHardhat";
+import {
+  canonicalPreparationJson,
+  hashPreparationRequest,
+  normalizePreparationPlan,
+  normalizePreparationRequest,
+  prepareWorkflow,
+  writePreparationPlanAtomic,
+} from "gate-evm-tools/workflow";
+import type {
+  GateToolPreparationHre,
+  GateToolPreparationPlanV1,
+  GateToolPreparationRequestV1,
+  GateToolTransactionPurpose,
+} from "gate-evm-tools/workflow";
+
+export interface PrepareGateToolWorkflowOptions {
+  root: string;
+  evidenceDir: string;
+  evidenceName: string;
+  request: GateToolPreparationRequestV1;
+  hre?: GateToolPreparationHre;
+  readBlockTag?: number;
+}
+
+export interface PreparedGateToolWorkflow {
+  request: GateToolPreparationRequestV1;
+  requestPath: string;
+  plan: GateToolPreparationPlanV1;
+  planPath: string;
+}
+
+const SAFE_FILE_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,199}$/;
+
+const pinGateToolReadBlockTag = (
+  runtime: GateToolPreparationHre,
+  blockTag: number | undefined,
+): GateToolPreparationHre => {
+  if (blockTag === undefined) return runtime;
+  if (!Number.isSafeInteger(blockTag) || blockTag < 0) {
+    throw new Error("GateTool readBlockTag must be a non-negative safe integer");
+  }
+  const source = runtime as GateToolPreparationHre & {
+    ethers?: {
+      provider?: {
+        getCode(address: string, requestedBlockTag?: number): Promise<string>;
+        getStorage?(address: string, slot: string, requestedBlockTag?: number): Promise<string>;
+        [key: PropertyKey]: unknown;
+      };
+      [key: PropertyKey]: unknown;
+    };
+    [key: PropertyKey]: unknown;
+  };
+  const baseEthers = source.ethers;
+  const baseProvider = baseEthers?.provider;
+  if (!baseEthers || !baseProvider || typeof baseProvider.getCode !== "function") {
+    throw new Error("GateTool pinned reads require the active Hardhat ethers provider");
+  }
+  const provider = new Proxy(baseProvider, {
+    get(target, property) {
+      if (property === "getCode") {
+        return (address: string, requestedBlockTag?: number) => target.getCode(
+          address,
+          requestedBlockTag ?? blockTag,
+        );
+      }
+      if (property === "getStorage" && typeof target.getStorage === "function") {
+        return (address: string, slot: string, requestedBlockTag?: number) => (
+          target.getStorage!(address, slot, requestedBlockTag ?? blockTag)
+        );
+      }
+      const value = Reflect.get(target, property, target);
+      return typeof value === "function" ? value.bind(target) : value;
+    },
+  });
+  const ethers = new Proxy(baseEthers, {
+    get(target, property) {
+      if (property === "provider") return provider;
+      const value = Reflect.get(target, property, target);
+      return typeof value === "function" ? value.bind(target) : value;
+    },
+  });
+  return new Proxy(source, {
+    get(target, property) {
+      if (property === "ethers") return ethers;
+      const value = Reflect.get(target, property, target);
+      return typeof value === "function" ? value.bind(target) : value;
+    },
+  });
+};
+
+const confinedPath = (
+  root: string,
+  requestedPath: string,
+  label: string,
+): string => {
+  const resolvedRoot = path.resolve(root);
+  const resolvedPath = path.resolve(requestedPath);
+  const relative = path.relative(resolvedRoot, resolvedPath);
+  if (relative === "" || relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw new Error(`${label} must be inside the project root`);
+  }
+  let current = resolvedRoot;
+  for (const segment of relative.split(path.sep).filter(Boolean)) {
+    current = path.join(current, segment);
+    if (fs.existsSync(current) && fs.lstatSync(current).isSymbolicLink()) {
+      throw new Error(`${label} path cannot contain a symlink`);
+    }
+  }
+  return resolvedPath;
+};
+
+const writeCanonicalJsonAtomic = (
+  filePath: string,
+  value: unknown,
+  root: string,
+): void => {
+  const confined = confinedPath(root, filePath, "GateTool request output");
+  fs.mkdirSync(path.dirname(confined), { recursive: true });
+  const temporary = `${confined}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    fs.writeFileSync(temporary, `${canonicalPreparationJson(value)}\n`, {
+      flag: "wx",
+      mode: 0o600,
+    });
+    fs.renameSync(temporary, confined);
+  } catch (error) {
+    if (fs.existsSync(temporary)) fs.unlinkSync(temporary);
+    throw error;
+  }
+};
+
+const readRegularJson = (
+  filePath: string,
+  root: string,
+  label: string,
+): unknown => {
+  const confined = confinedPath(root, filePath, label);
+  const stat = fs.statSync(confined);
+  if (!stat.isFile()) throw new Error(`${label} must be a regular file`);
+  try {
+    return JSON.parse(fs.readFileSync(confined, "utf8")) as unknown;
+  } catch (error) {
+    throw new Error(
+      `${label} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+};
+
+const expectedTransactionPurposes = (
+  plan: GateToolPreparationPlanV1,
+): GateToolTransactionPurpose[] => {
+  const requiredRoles = new Set(
+    plan.deployments
+      .filter((deployment) => deployment.status === "required")
+      .map((deployment) => deployment.role),
+  );
+  if (plan.kind === "create2-deploy") {
+    return requiredRoles.has("contract") ? ["deploy-contract"] : [];
+  }
+  if (plan.kind === "uups-placeholder-deploy") {
+    if (!requiredRoles.has("proxy")) {
+      if (requiredRoles.has("implementation")) {
+        throw new Error(
+          "GateTool cannot reuse a UUPS proxy while requiring its predicted implementation",
+        );
+      }
+      return [];
+    }
+    return [
+      ...(requiredRoles.has("implementation") ? ["deploy-implementation" as const] : []),
+      "deploy-proxy",
+      "upgrade-proxy",
+    ];
+  }
+  return [
+    ...(requiredRoles.has("implementation") ? ["deploy-implementation" as const] : []),
+    "upgrade-proxy",
+  ];
+};
+
+const assertPlanMatchesRequest = async (
+  hre: GateToolPreparationHre,
+  request: GateToolPreparationRequestV1,
+  rawPlan: unknown,
+): Promise<GateToolPreparationPlanV1> => {
+  const plan = normalizePreparationPlan(rawPlan);
+  const provider = (hre as GateToolPreparationHre & {
+    ethers?: { provider?: { getNetwork(): Promise<{ chainId: bigint | number | string }> } };
+  }).ethers?.provider;
+  if (!provider) throw new Error("GateTool preparation requires the active Hardhat ethers provider");
+  const chainId = (await provider.getNetwork()).chainId.toString();
+  const expectedPurposes = expectedTransactionPurposes(plan);
+  const actualPurposes = plan.transactions.map((transaction) => transaction.purpose);
+
+  if (plan.requestHash !== hashPreparationRequest(request)) {
+    throw new Error("GateTool plan requestHash does not match its canonical request");
+  }
+  if (
+    plan.kind !== request.kind
+    || plan.scheme !== request.scheme
+    || plan.network !== request.network
+    || plan.target !== request.target
+    || plan.contract !== request.contract
+    || plan.chainId !== chainId
+  ) {
+    throw new Error("GateTool plan identity does not match the active workflow request");
+  }
+  if (
+    actualPurposes.length !== expectedPurposes.length
+    || actualPurposes.some((purpose, index) => purpose !== expectedPurposes[index])
+  ) {
+    throw new Error("GateTool plan transaction order does not match its deployment evidence");
+  }
+  return plan;
+};
+
+export const prepareGateToolWorkflow = async (
+  options: PrepareGateToolWorkflowOptions,
+): Promise<PreparedGateToolWorkflow> => {
+  if (!SAFE_FILE_ID.test(options.evidenceName)) {
+    throw new Error(`GateTool evidenceName must match ${SAFE_FILE_ID}`);
+  }
+  const request = normalizePreparationRequest(options.request);
+  const runtime = pinGateToolReadBlockTag(
+    options.hre ?? hardhat as unknown as GateToolPreparationHre,
+    options.readBlockTag,
+  );
+  const evidenceDir = confinedPath(options.root, options.evidenceDir, "GateTool evidence directory");
+  const requestPath = path.join(evidenceDir, `${options.evidenceName}-request.json`);
+  const planPath = path.join(evidenceDir, `${options.evidenceName}-plan.json`);
+
+  const requestExists = fs.existsSync(requestPath);
+  const planExists = fs.existsSync(planPath);
+  if (requestExists !== planExists) {
+    throw new Error("GateTool preparation evidence is incomplete for this execution");
+  }
+  if (requestExists) {
+    const existingRequest = normalizePreparationRequest(
+      readRegularJson(requestPath, options.root, "GateTool request evidence"),
+    );
+    if (canonicalPreparationJson(existingRequest) !== canonicalPreparationJson(request)) {
+      throw new Error("GateTool request evidence does not match the immutable execution request");
+    }
+    const plan = await assertPlanMatchesRequest(
+      runtime,
+      request,
+      readRegularJson(planPath, options.root, "GateTool plan evidence"),
+    );
+    return { request, requestPath, plan, planPath };
+  }
+
+  writeCanonicalJsonAtomic(requestPath, request, options.root);
+  const prepared = await prepareWorkflow(runtime, request);
+  const plan = await assertPlanMatchesRequest(runtime, request, prepared);
+  writePreparationPlanAtomic(planPath, plan, options.root);
+
+  return { request, requestPath, plan, planPath };
+};