gate-evm-tools 1.0.26 → 1.0.28

package/runtime/workflow/lib/signerIdentity.ts

@@ -0,0 +1,22 @@
+import { getAddress, isAddress, ZeroAddress } from "ethers";
+
+const normalizedAddress = (value: string, label: string): string => {
+  const candidate = value.trim();
+  if (!isAddress(candidate) || getAddress(candidate) === ZeroAddress) {
+    throw new Error(`${label} must be a valid non-zero EVM address`);
+  }
+  return getAddress(candidate);
+};
+
+export const assertExecutionSignerAddress = (
+  actualAddress: string,
+  expectedTaskAddress?: string,
+): string => {
+  const actual = normalizedAddress(actualAddress, "execution signer");
+  if (expectedTaskAddress === undefined) return actual;
+  const expected = normalizedAddress(expectedTaskAddress, "deployment signer address");
+  if (actual.toLowerCase() !== expected.toLowerCase()) {
+    throw new Error("execution signer does not match deployment signer address");
+  }
+  return actual;
+};

package/runtime/workflow/lib/simulation.ts

@@ -0,0 +1,415 @@
+import { isAddress } from "ethers";
+import { config as hardhatConfig, ethers, network } from "../../projectHardhat";
+import {
+  CapturedChainSnapshotV1,
+  ForkSnapshotV1,
+  isCapturedZkSyncChainSnapshot,
+  parseForkSnapshotJson,
+  parseZkSyncBlockDetails,
+} from "./forkSnapshot";
+import { getERC1967Implementation } from "./erc1967";
+import { resolveZkSyncForkCapability } from "./zksyncForkCapability";
+import { resolveZkSyncForkRunner } from "./zksyncForkRunner";
+
+export type WorkflowMode = "execute" | "simulate" | "verify";
+
+export interface SimulationFork {
+  snapshot?: ForkSnapshotV1;
+}
+
+type WithoutVersion<T> = T extends unknown ? Omit<T, "version"> : never;
+
+type ZkSyncForkSnapshot = Extract<
+  ForkSnapshotV1,
+  { runner: { kind: "anvil-zksync" } }
+>;
+type EvmForkSnapshot = Exclude<ForkSnapshotV1, ZkSyncForkSnapshot>;
+
+export type SimulationForkEvidence =
+  | WithoutVersion<EvmForkSnapshot>
+  | (WithoutVersion<ZkSyncForkSnapshot> & { runnerProtocolVersion: number });
+
+export const resolveWorkflowMode = (
+  args: Record<string, string | boolean>,
+): WorkflowMode => {
+  const mode = typeof args.mode === "string" ? args.mode : "execute";
+  if (
+    mode !== "execute"
+    && mode !== "simulate"
+    && mode !== "verify"
+  ) {
+    throw new Error(`Unsupported workflow mode: ${mode}`);
+  }
+  return mode;
+};
+
+const sourceProxyUrl = (): string => {
+  const value = process.env.GATE_SIMULATION_SOURCE_RPC_URL?.trim();
+  if (!value) throw new Error("Simulation source-chain proxy URL is missing");
+  let parsed: URL;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw new Error("Simulation source-chain proxy URL is invalid");
+  }
+  if (
+    parsed.protocol !== "http:"
+    || parsed.hostname !== "127.0.0.1"
+    || !parsed.port
+    || parsed.pathname === "/"
+    || parsed.username
+    || parsed.password
+    || parsed.search
+    || parsed.hash
+  ) {
+    throw new Error("Simulation source-chain proxy must use a tokenized loopback URL");
+  }
+  return parsed.toString();
+};
+
+const rpcRequest = async <T>(
+  url: string,
+  method: string,
+  params: unknown[],
+): Promise<T> => {
+  let response: Response;
+  try {
+    response = await fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),
+    });
+  } catch {
+    throw new Error(`Simulation source RPC ${method} request failed`);
+  }
+  if (!response.ok) {
+    throw new Error(`Simulation source RPC ${method} request failed`);
+  }
+  let body: unknown;
+  try {
+    body = await response.json();
+  } catch {
+    throw new Error(`Simulation source RPC ${method} returned invalid JSON`);
+  }
+  if (!body || typeof body !== "object" || Array.isArray(body)) {
+    throw new Error(`Simulation source RPC ${method} returned an invalid response`);
+  }
+  const envelope = body as { result?: T; error?: unknown };
+  if (envelope.error !== undefined || envelope.result === undefined) {
+    throw new Error(`Simulation source RPC ${method} failed`);
+  }
+  return envelope.result;
+};
+
+const blockTag = (blockNumber: number): string => `0x${blockNumber.toString(16)}`;
+
+const rpcQuantity = (value: unknown, label: string): number => {
+  if (typeof value !== "string" || !/^0x(?:0|[1-9a-fA-F][0-9a-fA-F]*)$/.test(value)) {
+    throw new Error(`${label} must be a canonical RPC quantity`);
+  }
+  const parsed = BigInt(value);
+  if (parsed > BigInt(Number.MAX_SAFE_INTEGER)) {
+    throw new Error(`${label} exceeds the safe integer range`);
+  }
+  return Number(parsed);
+};
+
+const assertBlockHash = (
+  block: unknown,
+  snapshot: CapturedChainSnapshotV1,
+  label: string,
+): void => {
+  if (!block || typeof block !== "object" || Array.isArray(block)) {
+    throw new Error(`${label} fork block is missing`);
+  }
+  const hash = (block as { hash?: unknown }).hash;
+  if (
+    typeof hash !== "string"
+    || hash.toLowerCase() !== snapshot.blockHash.toLowerCase()
+  ) {
+    throw new Error(`${label} fork block hash mismatch at ${snapshot.blockNumber}`);
+  }
+};
+
+interface SimulationInfrastructureTarget {
+  create2?: { factory?: string };
+  multicall?: { controlledMulticall?: string };
+  uups?: { placeholderImplementation?: string };
+}
+
+const requiredInfrastructureAddress = (
+  value: string | undefined,
+  label: string,
+): string => {
+  if (!value || !isAddress(value)) {
+    throw new Error(`${label} must be configured as an EVM address for simulation`);
+  }
+  return value;
+};
+
+export const assertCurrentStateInfrastructure = async (
+  targetId: string,
+  target: SimulationInfrastructureTarget,
+  snapshot: CapturedChainSnapshotV1 | undefined,
+): Promise<void> => {
+  if (!snapshot) return;
+  const infrastructure = [
+    {
+      label: "CREATE2 Factory",
+      address: requiredInfrastructureAddress(target.create2?.factory, "CREATE2 Factory"),
+    },
+    {
+      label: "Controlled Multicall",
+      address: requiredInfrastructureAddress(
+        target.multicall?.controlledMulticall,
+        "Controlled Multicall",
+      ),
+    },
+    {
+      label: "UUPS Placeholder",
+      address: requiredInfrastructureAddress(
+        target.uups?.placeholderImplementation,
+        "UUPS Placeholder",
+      ),
+    },
+  ];
+  const code = await Promise.all(infrastructure.map((entry) => (
+    ethers.provider.getCode(entry.address, snapshot.blockNumber)
+  )));
+  for (const [index, entry] of infrastructure.entries()) {
+    if (!code[index] || code[index] === "0x") {
+      throw new Error(
+        `${entry.label} on ${targetId} captured block ${snapshot.blockNumber} is missing code at ${entry.address}`,
+      );
+    }
+  }
+};
+
+export const assertSimulationSourceInfrastructure = async (
+  targetId: string,
+  target: SimulationInfrastructureTarget,
+  simulation: SimulationFork,
+): Promise<void> => assertCurrentStateInfrastructure(targetId, target, simulation.snapshot);
+
+export const assertCurrentStateUupsSourceState = async (
+  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),
+  ]);
+  if (!proxyCode || proxyCode === "0x") {
+    throw new Error(
+      `UUPS proxy ${proxy} is missing code at captured block ${snapshot.blockNumber}`,
+    );
+  }
+  if (!oldImplementation) {
+    throw new Error(
+      `UUPS proxy ${proxy} has no implementation at captured block ${snapshot.blockNumber}`,
+    );
+  }
+  const implementationCode = await ethers.provider.getCode(
+    oldImplementation,
+    snapshot.blockNumber,
+  );
+  if (!implementationCode || implementationCode === "0x") {
+    throw new Error(
+      `UUPS implementation ${oldImplementation} is missing code at captured block ${snapshot.blockNumber}`,
+    );
+  }
+};
+
+export const assertSimulationUupsSourceState = async (
+  simulation: SimulationFork,
+  proxy: string,
+): Promise<void> => assertCurrentStateUupsSourceState(simulation.snapshot, proxy);
+
+export const verifySimulationForkSnapshot = async (
+  simulation: SimulationFork,
+): Promise<void> => {
+  const snapshot = simulation.snapshot;
+  if (!snapshot) return;
+  const [sourceBlock, localBlock, sourceZkSyncBlockDetails] = await Promise.all([
+    rpcRequest<unknown>(
+      sourceProxyUrl(),
+      "eth_getBlockByNumber",
+      [blockTag(snapshot.blockNumber), false],
+    ),
+    network.provider.request({
+      method: "eth_getBlockByNumber",
+      params: [blockTag(snapshot.blockNumber), false],
+    }),
+    snapshot.runner.kind === "anvil-zksync"
+      ? rpcRequest<unknown>(
+          sourceProxyUrl(),
+          "zks_getBlockDetails",
+          [snapshot.blockNumber],
+        )
+      : Promise.resolve(undefined),
+  ]);
+  assertBlockHash(sourceBlock, snapshot, "Source-chain");
+  assertBlockHash(
+    localBlock,
+    snapshot,
+    snapshot.runner.kind === "hardhat" ? "Local EVM" : "Local EraVM",
+  );
+  if (
+    snapshot.runner.kind === "anvil-zksync"
+    && isCapturedZkSyncChainSnapshot(snapshot)
+  ) {
+    const metadata = parseZkSyncBlockDetails(
+      sourceZkSyncBlockDetails,
+      snapshot.blockNumber,
+    );
+    if (
+      metadata.protocolVersion !== snapshot.protocolVersion
+      || metadata.l1BatchNumber !== snapshot.l1BatchNumber
+    ) {
+      throw new Error("Source-chain zkSync protocol metadata mismatch");
+    }
+  }
+};
+
+export const simulationForkEvidence = (
+  simulation: SimulationFork,
+): SimulationForkEvidence | undefined => {
+  const snapshot = simulation.snapshot;
+  if (!snapshot) return undefined;
+  if (snapshot.runner.kind === "anvil-zksync") {
+    if (!isCapturedZkSyncChainSnapshot(snapshot)) {
+      throw new Error("zkSync simulation snapshot is missing protocol metadata");
+    }
+    const capability = resolveZkSyncForkCapability(snapshot.protocolVersion);
+    if (!capability || capability.runner.version !== snapshot.runner.version) {
+      throw new Error(
+        `zkSync protocol ${snapshot.protocolVersion} does not have an approved fork runner`,
+      );
+    }
+    return {
+      sourceNetwork: snapshot.sourceNetwork,
+      chainId: snapshot.chainId,
+      blockNumber: snapshot.blockNumber,
+      blockHash: snapshot.blockHash,
+      protocolVersion: snapshot.protocolVersion,
+      runnerProtocolVersion: capability.runnerProtocolVersion,
+      l1BatchNumber: snapshot.l1BatchNumber,
+      runner: { ...snapshot.runner },
+    };
+  }
+  return {
+    sourceNetwork: snapshot.sourceNetwork,
+    chainId: snapshot.chainId,
+    blockNumber: snapshot.blockNumber,
+    blockHash: snapshot.blockHash,
+    runner: { ...snapshot.runner },
+  };
+};
+
+export const setupSimulationFork = async (targetId: string): Promise<SimulationFork> => {
+  const targetNetwork = (
+    hardhatConfig.networks as Record<string, { zksync?: boolean }>
+  )[targetId];
+  if (targetNetwork?.zksync === true) {
+    if (
+      network.name !== "zkFork"
+      || (network.config as { zksync?: boolean }).zksync !== true
+    ) {
+      throw new Error(
+        `zkSync target "${targetId}" requires the pinned EraVM fork network`,
+      );
+    }
+    const snapshot = parseForkSnapshotJson(
+      process.env.GATE_SIMULATION_FORK_SNAPSHOT_JSON,
+      targetId,
+    );
+    if (
+      snapshot.runner.kind !== "anvil-zksync"
+      || !isCapturedZkSyncChainSnapshot(snapshot)
+    ) {
+      throw new Error(`zkSync target "${targetId}" requires an anvil-zksync fork snapshot`);
+    }
+    const approvedRunner = resolveZkSyncForkRunner(snapshot.protocolVersion);
+    if (!approvedRunner || snapshot.runner.version !== approvedRunner.version) {
+      throw new Error(
+        `zkSync protocol ${snapshot.protocolVersion} does not have an approved fork runner`,
+      );
+    }
+    const [runtimeChainId, forkBlock] = await Promise.all([
+      network.provider.request({ method: "eth_chainId", params: [] }),
+      network.provider.request({
+        method: "eth_getBlockByNumber",
+        params: [blockTag(snapshot.blockNumber), false],
+      }),
+    ]);
+    if (
+      typeof runtimeChainId !== "string"
+      || !/^0x[0-9a-fA-F]+$/.test(runtimeChainId)
+      || BigInt(runtimeChainId) !== BigInt(snapshot.chainId)
+    ) {
+      throw new Error(
+        `EraVM simulation chainId does not match target chainId ${snapshot.chainId}`,
+      );
+    }
+    assertBlockHash(forkBlock, snapshot, "Local EraVM");
+    return { snapshot };
+  }
+  if (network.name !== "hardhat") {
+    throw new Error("Simulation mode must run with --network hardhat");
+  }
+  if (targetId === "hardhat") {
+    return {};
+  }
+  const snapshot = parseForkSnapshotJson(
+    process.env.GATE_SIMULATION_FORK_SNAPSHOT_JSON,
+    targetId,
+  );
+  if (snapshot.runner.kind !== "hardhat") {
+    throw new Error(`EVM target "${targetId}" requires a Hardhat fork snapshot`);
+  }
+  const forkRpcUrl = sourceProxyUrl();
+  const sourceBlock = await rpcRequest<unknown>(
+    forkRpcUrl,
+    "eth_getBlockByNumber",
+    [blockTag(snapshot.blockNumber), false],
+  );
+  assertBlockHash(sourceBlock, snapshot, "Source-chain");
+
+  await network.provider.request({
+    method: "hardhat_reset",
+    params: [
+      {
+        forking: {
+          jsonRpcUrl: forkRpcUrl,
+          blockNumber: snapshot.blockNumber,
+        },
+      },
+    ],
+  });
+
+  const [runtimeChainId, forkBlock] = await Promise.all([
+    network.provider.request({ method: "eth_chainId", params: [] }),
+    network.provider.request({
+      method: "eth_getBlockByNumber",
+      params: [blockTag(snapshot.blockNumber), false],
+    }),
+  ]);
+  if (
+    typeof runtimeChainId !== "string"
+    || !/^0x[0-9a-fA-F]+$/.test(runtimeChainId)
+    || BigInt(runtimeChainId) !== BigInt(snapshot.chainId)
+  ) {
+    throw new Error(
+      `Simulation fork chainId does not match target chainId ${snapshot.chainId}`,
+    );
+  }
+  assertBlockHash(forkBlock, snapshot, "Local EVM");
+
+  await network.provider.request({
+    method: "hardhat_mine",
+    params: ["0x1"],
+  });
+
+  return { snapshot };
+};