gate-evm-tools 1.0.25 → 1.0.27

package/runtime/workflow/lib/calls.ts

@@ -0,0 +1,407 @@
+import type { BaseContract } from "ethers";
+import { getAddress, isAddress } from "ethers";
+import { ethers } from "../../projectHardhat";
+import {
+  assertSelectedSimulationSignerAuthorized,
+  decideAuthority,
+} from "./authority";
+import { encodeCall } from "./calldata";
+import { findExecutionCandidateAddress } from "./contractInfoCandidates";
+import { getDeploymentAddress } from "./deployments";
+import { ExternalCall, ExternalExecutionRequired } from "./external";
+import { resolveValue, WorkflowStep } from "./parameters";
+import type { WorkflowContext } from "../run";
+import { impersonateWorkflowSimulationSigner } from "./signer";
+
+export interface ContractCall {
+  method: string;
+  args?: unknown[];
+  value?: string | number;
+  expect?: unknown;
+}
+
+export interface ResolvedContract {
+  contractName: string;
+  abiName: string;
+  address: string;
+  contract: BaseContract;
+}
+
+type ContractMethod = (...args: unknown[]) => Promise<unknown>;
+
+const resultKey = (call: ContractCall, index: number, calls: ContractCall[]): string => {
+  return calls.length === 1 ? call.method : `${index + 1}.${call.method}`;
+};
+
+const calldataStepId = (step: WorkflowStep, call: ContractCall, index: number, calls: ContractCall[]): string => {
+  return calls.length === 1 ? step.id : `${step.id}-${index + 1}-${call.method}`;
+};
+
+const methodOf = (contract: BaseContract, method: string): ContractMethod => {
+  const callable = contract as unknown as Record<string, unknown>;
+  const contractMethod = callable[method];
+  if (typeof contractMethod !== "function") {
+    throw new Error(`Contract does not expose method "${method}"`);
+  }
+  return contractMethod as ContractMethod;
+};
+
+const findStateAddress = (
+  context: WorkflowContext,
+  name: string,
+): string | undefined => {
+  for (const pathExpression of [`${name}.address`, `${name}.proxyAddress`]) {
+    try {
+      const value = context.state.get(pathExpression);
+      if (typeof value === "string" && value) {
+        return value;
+      }
+    } catch {
+      // State references are opportunistic here; persisted contractInfo remains the fallback.
+    }
+  }
+  return undefined;
+};
+
+const stringStepField = (
+  step: WorkflowStep,
+  key: string,
+): string | undefined => {
+  const value = step[key];
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+};
+
+export const resolveContract = async (
+  context: WorkflowContext,
+  step: WorkflowStep,
+): Promise<ResolvedContract> => {
+  const contractName = String(step.contract);
+  const abiName = String(step.abi || contractName);
+  const deploymentName =
+    typeof step.deployment === "string" && step.deployment.trim()
+      ? step.deployment.trim()
+      : undefined;
+  const lookupName =
+    deploymentName ||
+    stringStepField(step, "saveAs") ||
+    contractName;
+  const address = String(
+    step.address
+      ? resolveValue(step.address, {
+        targetId: context.targetId,
+        target: context.target,
+        params: context.targetParams,
+        state: context.state,
+      })
+      : findStateAddress(context, lookupName) ||
+        findExecutionCandidateAddress({
+          root: context.root,
+          deploymentId: context.taskId,
+          executionId: context.executionId,
+          network: context.targetId,
+          name: lookupName,
+        }) ||
+        getDeploymentAddress(context.root, context.config, context.targetId, lookupName),
+  );
+  const contract = await ethers.getContractAt(abiName, address, context.signer);
+
+  return {
+    contractName,
+    abiName,
+    address,
+    contract,
+  };
+};
+
+export const resolveStepCalls = (step: WorkflowStep): ContractCall[] => {
+  const calls = step.calls as ContractCall[] | undefined;
+  if (!calls || calls.length === 0) {
+    throw new Error(`Step ${step.id} requires calls`);
+  }
+  return calls;
+};
+
+export const resolveCallArgs = (
+  context: WorkflowContext,
+  call: ContractCall,
+): unknown[] => {
+  const args = resolveValue(call.args || [], {
+    targetId: context.targetId,
+    target: context.target,
+    params: context.targetParams,
+    state: context.state,
+  });
+
+  if (!Array.isArray(args)) {
+    throw new Error(`Call ${call.method} args must resolve to an array`);
+  }
+
+  return args;
+};
+
+export const stringifyCallResult = (value: unknown): string => {
+  return value?.toString?.() ?? String(value);
+};
+
+const comparableCallResults = (
+  actual: string,
+  expected: string,
+): { actual: string; expected: string } => {
+  if (isAddress(actual) && isAddress(expected)) {
+    return {
+      actual: getAddress(actual),
+      expected: getAddress(expected),
+    };
+  }
+
+  return { actual, expected };
+};
+
+export const normalizeCallValue = (value: unknown): string => {
+  if (value === undefined) return "0";
+
+  if (typeof value === "string") {
+    const candidate = value.trim();
+    if (candidate.length === 0) return "0";
+    if (!/^(?:[0-9]+|0[xX][0-9a-fA-F]+)$/.test(candidate)) {
+      throw new Error(
+        "Call value must be a nonnegative decimal/hex string or a safe nonnegative integer",
+      );
+    }
+    return BigInt(candidate).toString(10);
+  }
+
+  if (typeof value === "number" && Number.isSafeInteger(value) && value >= 0) {
+    return value.toString(10);
+  }
+
+  throw new Error(
+    "Call value must be undefined, empty, a nonnegative decimal/hex string, or a safe nonnegative integer",
+  );
+};
+
+export const runContractWriteCalls = async (
+  context: WorkflowContext,
+  step: WorkflowStep,
+): Promise<void> => {
+  const resolved = await resolveContract(context, step);
+  const calls = resolveStepCalls(step);
+  const callValues = calls.map((call) => normalizeCallValue(call.value));
+  if (!context.signerAddress) {
+    throw new Error(`Call step ${step.id} requires a signer address`);
+  }
+  const authority = await decideAuthority(
+    resolved.contract,
+    context.target,
+    context.signerAddress,
+  );
+
+  if (
+    context.mode === "simulate"
+    && !context.executionPlanner
+    && !context.configuredSimulationCaller
+  ) {
+    assertSelectedSimulationSignerAuthorized(authority, step.id);
+  }
+
+  if (
+    authority.mode === "calldata"
+    && context.mode === "execute"
+    && !context.executionPlanner
+  ) {
+    if (!authority.executor) {
+      throw new Error(`Call step ${step.id} cannot resolve an external executor`);
+    }
+    const externalExecutor = authority.executor;
+    const externalCalls: ExternalCall[] = calls.map((call, index) => {
+      const args = resolveCallArgs(context, call);
+      const stepId = calldataStepId(step, call, index, calls);
+      return {
+        transactionId: stepId,
+        stepId,
+        to: resolved.address,
+        value: callValues[index],
+        data: encodeCall(resolved.contract.interface, call.method, args),
+        operation: 0,
+        method: call.method,
+        args,
+        executor: externalExecutor,
+        reason: authority.reason,
+      };
+    });
+    throw new ExternalExecutionRequired(step.id, externalCalls);
+  }
+
+  for (const [index, call] of calls.entries()) {
+    const args = resolveCallArgs(context, call);
+    const value = callValues[index];
+
+    if (context.executionPlanner) {
+      const stepId = calldataStepId(step, call, index, calls);
+      const executor = authority.mode === "execute"
+        ? context.signerAddress
+        : authority.executor;
+      if (!executor) {
+        throw new Error(`Call step ${step.id} cannot resolve its required executor`);
+      }
+      const data = encodeCall(resolved.contract.interface, call.method, args);
+      const zkSync = context.target.create2?.scheme === "zksync-eravm";
+      const planned = context.executionPlanner.add({
+        stepId,
+        executor,
+        to: resolved.address,
+        value,
+        data,
+        operation: 0,
+        ...(zkSync ? { scheme: "zksync-eravm" as const, factoryDeps: [] } : {}),
+      });
+      if (planned.executionAction === "replay") {
+        context.reporter.result("execution", {
+          stepId: planned.stepId,
+          kind: step.kind,
+          mode: "replay",
+          transactionId: planned.transactionId,
+          transactionHash: planned.transactionHash,
+          executor: planned.executor,
+        });
+        continue;
+      }
+      if (planned.route === "external" && context.mode !== "simulate") {
+        context.externalCalls.push({
+          transactionId: planned.transactionId,
+          stepId: planned.stepId,
+          to: planned.to,
+          value: planned.value,
+          data: planned.data,
+          operation: planned.operation,
+          method: call.method,
+          args,
+          executor: planned.executor,
+          reason: authority.reason,
+        });
+        context.reporter.result("execution", {
+          stepId: planned.stepId,
+          kind: step.kind,
+          mode: "external",
+          transactionId: planned.transactionId,
+          executor: planned.executor,
+        });
+        continue;
+      }
+
+      const selectedContract = planned.route === "external"
+        ? await ethers.getContractAt(
+            resolved.abiName,
+            resolved.address,
+            await impersonateWorkflowSimulationSigner(planned.executor),
+          )
+        : resolved.contract;
+      const txArgs = value !== "0" ? [...args, { value }] : args;
+      const tx = await methodOf(selectedContract, call.method)(...txArgs) as {
+        hash: string;
+        wait: () => Promise<unknown>;
+      };
+      await tx.wait();
+      if (context.mode === "execute" && planned.route === "operator") {
+        context.operatorReceipts.push({
+          transactionId: planned.transactionId,
+          transactionHash: tx.hash,
+        });
+      }
+      context.reporter.result("execution", {
+        stepId: planned.stepId,
+        kind: step.kind,
+        mode: context.mode === "simulate" ? `simulate-${planned.route}` : planned.route,
+        transactionId: planned.transactionId,
+        executor: planned.executor,
+        contract: resolved.contractName,
+        address: resolved.address,
+        method: call.method,
+        args,
+        value,
+        txHash: tx.hash,
+      });
+      continue;
+    }
+
+    const txArgs = value !== "0" ? [...args, { value }] : args;
+    const tx = await methodOf(resolved.contract, call.method)(...txArgs) as {
+      hash: string;
+      wait: () => Promise<unknown>;
+    };
+    await tx.wait();
+    context.reporter.result("execution", {
+      stepId: step.id,
+      kind: step.kind,
+      mode: "execute",
+      contract: resolved.contractName,
+      address: resolved.address,
+      method: call.method,
+      args,
+      value,
+      txHash: tx.hash,
+    });
+  }
+};
+
+export const runContractViewCalls = async (
+  context: WorkflowContext,
+  step: WorkflowStep,
+): Promise<void> => {
+  const resolved = await resolveContract(context, step);
+  const calls = resolveStepCalls(step);
+  const results: Record<string, string> = {};
+
+  for (const [index, call] of calls.entries()) {
+    const args = resolveCallArgs(context, call);
+    const value = await methodOf(resolved.contract, call.method)(...args);
+    results[resultKey(call, index, calls)] = stringifyCallResult(value);
+  }
+
+  context.reporter.result("view", {
+    stepId: step.id,
+    kind: step.kind,
+    contract: resolved.contractName,
+    address: resolved.address,
+    results,
+  });
+};
+
+export const runContractCheckCalls = async (
+  context: WorkflowContext,
+  step: WorkflowStep,
+): Promise<void> => {
+  const resolved = await resolveContract(context, step);
+  const calls = resolveStepCalls(step);
+  const results: Record<string, { actual: string; expected: string }> = {};
+
+  for (const [index, call] of calls.entries()) {
+    const args = resolveCallArgs(context, call);
+    const actualValue = await methodOf(resolved.contract, call.method)(...args);
+    const expectedValue = resolveValue(call.expect, {
+      targetId: context.targetId,
+      target: context.target,
+      params: context.targetParams,
+      state: context.state,
+    });
+    const actual = stringifyCallResult(actualValue);
+    const expected = stringifyCallResult(expectedValue);
+    const comparable = comparableCallResults(actual, expected);
+
+    if (comparable.actual !== comparable.expected) {
+      throw new Error(
+        `Check failed for ${step.id}.${call.method}: expected ${comparable.expected}, got ${comparable.actual}`,
+      );
+    }
+
+    results[resultKey(call, index, calls)] = comparable;
+  }
+
+  context.reporter.result("verification", {
+    stepId: step.id,
+    kind: step.kind,
+    contract: resolved.contractName,
+    address: resolved.address,
+    results,
+  });
+};

package/runtime/workflow/lib/checkCode/args.ts

@@ -0,0 +1,76 @@
+import path from "path";
+import type { CheckCodeOptions } from "../checkCodeRunner";
+
+type ParsedArgs = Record<string, string[]>;
+
+const parseArgs = (argv: string[]): ParsedArgs => {
+  const parsed: ParsedArgs = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const item = argv[index];
+    if (!item.startsWith("--")) continue;
+
+    const equalIndex = item.indexOf("=");
+    const key = item.slice(2, equalIndex > 2 ? equalIndex : undefined);
+    const inlineValue = equalIndex > 2 ? item.slice(equalIndex + 1) : undefined;
+    const next = argv[index + 1];
+    const value = inlineValue ?? (
+      next && !next.startsWith("--") ? next : "true"
+    );
+    if (inlineValue === undefined && next && !next.startsWith("--")) index += 1;
+    (parsed[key] ||= []).push(value);
+  }
+  return parsed;
+};
+
+const singleArg = (
+  args: ParsedArgs,
+  key: string,
+  options: { required?: boolean } = {},
+): string | undefined => {
+  const values = args[key] || [];
+  if (values.length > 1) throw new Error("--" + key + " may be provided only once");
+  const value = values[0]?.trim();
+  if (options.required && (!value || value === "true")) {
+    throw new Error("--" + key + " is required");
+  }
+  return value && value !== "true" ? value : undefined;
+};
+
+const listArg = (args: ParsedArgs, key: string): string[] | undefined => {
+  const values = (args[key] || [])
+    .flatMap((value) => value.split(","))
+    .map((value) => value.trim())
+    .filter(Boolean);
+  return values.length > 0 ? [...new Set(values)] : undefined;
+};
+
+const defaultRunId = (): string => {
+  const timestamp = new Date().toISOString().replace(/\D/g, "");
+  return "checkcode-" + timestamp + "-" + Math.random().toString(36).slice(2, 8);
+};
+
+export const parseCheckCodeOptions = (
+  argv: string[],
+  defaultRoot: string = process.cwd(),
+  createRunId: () => string = defaultRunId,
+): CheckCodeOptions => {
+  const args = parseArgs(argv);
+  const root = path.resolve(singleArg(args, "root") || defaultRoot);
+  const artifactHash = singleArg(args, "artifactHash", { required: true }) as string;
+  const options: CheckCodeOptions = {
+    root,
+    runId: singleArg(args, "runId") || createRunId(),
+    artifactHash,
+    networks: listArg(args, "network"),
+    contracts: listArg(args, "contract"),
+  };
+  const deploymentId = singleArg(args, "deploymentId");
+  const registryCommitId = singleArg(args, "registryCommitId");
+  if (Boolean(deploymentId) !== Boolean(registryCommitId)) {
+    throw new Error("--deploymentId and --registryCommitId must be provided together");
+  }
+  if (deploymentId && registryCommitId) {
+    options.deploymentAudit = { deploymentId, registryCommitId };
+  }
+  return options;
+};

package/runtime/workflow/lib/checkCode/command.ts

@@ -0,0 +1,36 @@
+import { spawnSync } from "child_process";
+import type { CommandResult } from "../checkCodeRunner";
+import { resolveCliTool } from "../cliTool";
+
+const commandName = (command: string): string => {
+  if (process.platform !== "win32") return command;
+  return command === "npm" || command === "npx" ? command + ".cmd" : command;
+};
+
+export const runCheckCodeCommand = (
+  command: string,
+  commandArgs: string[],
+  options: { cwd: string; env?: NodeJS.ProcessEnv } = { cwd: process.cwd() },
+): CommandResult => {
+  const env = { ...process.env, ...options.env };
+  let executable = commandName(command);
+  let executableArgs = commandArgs;
+  if (command === "npx" && commandArgs.includes("gate-tool")) {
+    env.NODE_OPTIONS = [env.NODE_OPTIONS, "--require", "ts-node/register"]
+      .filter(Boolean)
+      .join(" ");
+    const gateTool = resolveCliTool({ root: options.cwd, binary: "gate-tool" });
+    const binaryAt = commandArgs.indexOf("gate-tool");
+    executable = gateTool.command;
+    executableArgs = [...gateTool.argsPrefix, ...commandArgs.slice(binaryAt + 1)];
+  }
+  const result = spawnSync(executable, executableArgs, {
+    cwd: options.cwd,
+    env,
+    stdio: "inherit",
+  });
+  return {
+    status: result.status ?? 1,
+    error: result.error?.message,
+  };
+};

package/runtime/workflow/lib/checkCode/dependencies.ts

@@ -0,0 +1,112 @@
+import crypto from "crypto";
+import path from "path";
+import { JsonRpcProvider, type Provider } from "ethers";
+import {
+  getStorageLayout,
+  getVersion,
+} from "@openzeppelin/upgrades-core";
+import { readValidations } from "@openzeppelin/hardhat-upgrades/dist/utils/validations";
+import hre, {
+  artifacts,
+  config as hardhatConfig,
+  ethers as hardhatEthers,
+  network as hardhatNetwork,
+} from "../../../projectHardhat";
+import { loadOpenZeppelinManifestDir } from "../../../config/openzeppelin";
+import { loadConfig } from "../config";
+import { loadContractInfo } from "../deployments";
+import { loadDeploymentInfo } from "../deploymentInfo";
+import { getERC1967Implementation } from "../erc1967";
+import type { CheckCodeDependencies } from "../checkCodeRunner";
+import { runCheckCodeCommand } from "./command";
+
+const resolveScheme = (
+  workflowConfig: ReturnType<typeof loadConfig>,
+  networkName: string,
+): "evm" | "zksync-eravm" => {
+  const target = workflowConfig[networkName];
+  if (!target) {
+    throw new Error(`Missing config.yaml entry for CheckCode network ${networkName}`);
+  }
+  const scheme: unknown = target.create2?.scheme;
+  if (scheme === undefined || scheme === null || scheme === "" || scheme === "evm") {
+    return "evm";
+  }
+  if (scheme === "zksync-eravm") return scheme;
+  throw new Error(`config.yaml ${networkName}.create2.scheme must be evm or zksync-eravm`);
+};
+
+export interface CheckCodeRuntimeDependencies {
+  dependencies: CheckCodeDependencies;
+  dispose: () => void;
+}
+
+const normalize = (value: unknown): unknown => {
+  if (Array.isArray(value)) return value.map(normalize);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.keys(value as Record<string, unknown>)
+      .sort()
+      .map((key) => [key, normalize((value as Record<string, unknown>)[key])]));
+  }
+  return value;
+};
+
+export const createCheckCodeDependencies = (
+  root: string,
+): CheckCodeRuntimeDependencies => {
+  const workflowConfig = loadConfig(root);
+  const rpcProviders = new Map<string, JsonRpcProvider>();
+
+  const providerFor = (
+    networkName: string,
+  ): Pick<Provider, "getNetwork" | "getStorage"> => {
+    if (networkName === hardhatNetwork.name) return hardhatEthers.provider;
+    const existing = rpcProviders.get(networkName);
+    if (existing) return existing;
+
+    const networkConfig = hardhatConfig.networks[networkName];
+    if (!networkConfig || !("url" in networkConfig) || typeof networkConfig.url !== "string") {
+      throw new Error(
+        "Hardhat network " + networkName + " does not define an HTTP RPC URL for CheckCode",
+      );
+    }
+    const provider = new JsonRpcProvider(networkConfig.url);
+    rpcProviders.set(networkName, provider);
+    return provider;
+  };
+
+  return {
+    dependencies: {
+      runCommand: runCheckCodeCommand,
+      loadContractInfo: () => loadContractInfo(root, workflowConfig),
+      loadDeploymentInfo: () => loadDeploymentInfo(root),
+      resolveScheme: (networkName) => resolveScheme(workflowConfig, networkName),
+      resolveManifestDir: (networkName) => (
+        loadOpenZeppelinManifestDir(root, networkName)
+      ),
+      resolveManifestFile: async (networkName, manifestDir) => {
+        const chainId = Number((await providerFor(networkName).getNetwork()).chainId);
+        if (!Number.isSafeInteger(chainId) || chainId <= 0) {
+          throw new Error(`Invalid chainId for ${networkName}: ${chainId}`);
+        }
+        const { networkNames } = await import("@openzeppelin/upgrades-core");
+        const manifestName = networkNames[chainId] ?? `unknown-${chainId}`;
+        return path.join(root, manifestDir, `${manifestName}.json`);
+      },
+      getImplementation: async (networkName, address) => (
+        getERC1967Implementation(providerFor(networkName), address)
+      ),
+      getStorageLayoutHash: async (contractName) => {
+        const artifact = await artifacts.readArtifact(contractName);
+        const validations = await readValidations(hre);
+        const layout = getStorageLayout(validations, getVersion(artifact.bytecode));
+        return crypto.createHash("sha256")
+          .update(JSON.stringify(normalize(layout)))
+          .digest("hex");
+      },
+    },
+    dispose: () => {
+      for (const provider of rpcProviders.values()) provider.destroy();
+    },
+  };
+};