gate-evm-tools 1.0.25 → 1.0.27

package/runtime/workflow/importState.ts

@@ -0,0 +1,190 @@
+import { spawnSync } from "child_process";
+import fs from "fs";
+import path from "path";
+import { JsonRpcProvider, Provider } from "ethers";
+import { loadConfig, readJsonFile, writeJsonFile } from "./lib/config";
+import {
+  importMigrationState,
+  migrationConfirmationToken,
+  MigrationContractPlan,
+  resolveConfinedMigrationPath,
+  resolveGateToolCandidateCheck,
+  validateMigrationStatePlan,
+} from "./lib/migrationState";
+import {
+  getERC1967Admin,
+  getERC1967Implementation,
+} from "./lib/erc1967";
+
+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("--")) throw new Error(`Unsupported argument: ${item}`);
+    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 confinedPlanPath = (root: string, requested: string): string => {
+  return resolveConfinedMigrationPath(root, requested, {
+    label: "Migration plan",
+    requireFile: true,
+  });
+};
+
+const commandName = (command: string): string => (
+  process.platform === "win32" ? `${command}.cmd` : command
+);
+
+const main = async (): Promise<void> => {
+  const args = parseArgs(process.argv.slice(2));
+  const root = path.resolve(singleArg(args, "root") || process.cwd());
+  const planPath = confinedPlanPath(
+    root,
+    singleArg(args, "plan", { required: true }) as string,
+  );
+  const plan = validateMigrationStatePlan(readJsonFile<unknown>(planPath));
+  const confirmations = Object.keys(plan.networks).sort().map((network) => ({
+    network,
+    token: migrationConfirmationToken(plan, network),
+  }));
+
+  if (args["print-confirmations"]?.length) {
+    console.log(JSON.stringify({ migrationId: plan.migrationId, confirmations }, null, 2));
+    return;
+  }
+
+  process.env.GATE_MIGRATION_READ_ONLY = "1";
+  const {
+    artifacts,
+    config: hardhatConfig,
+    ethers: hardhatEthers,
+    network: hardhatNetwork,
+    run: hardhatRun,
+  } = await import("../projectHardhat");
+
+  const workflowConfig = loadConfig(root);
+  const rpcProviders = new Map<string, JsonRpcProvider>();
+  const providerFor = (
+    networkName: string,
+  ): Pick<Provider, "getCode" | "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`);
+    }
+    const provider = new JsonRpcProvider(networkConfig.url);
+    rpcProviders.set(networkName, provider);
+    return provider;
+  };
+
+  const inspect = async (
+    networkName: string,
+    contract: MigrationContractPlan,
+  ) => {
+    const provider = providerFor(networkName);
+    const chainId = Number((await provider.getNetwork()).chainId);
+    const implementationAddress = await getERC1967Implementation(provider, contract.address);
+    const adminAddress = implementationAddress
+      ? await getERC1967Admin(provider, contract.address)
+      : undefined;
+    const proxyKind = implementationAddress
+      ? (adminAddress ? "transparent" as const : "uups" as const)
+      : "none" as const;
+    const contractCode = await provider.getCode(contract.address);
+    const implementationCode = implementationAddress
+      ? await provider.getCode(implementationAddress)
+      : undefined;
+    let artifactExists = true;
+    try {
+      await artifacts.readArtifact(contract.actualContract);
+    } catch {
+      artifactExists = false;
+    }
+    return {
+      chainId,
+      hasCode: contractCode !== "0x"
+        && (implementationCode === undefined || implementationCode !== "0x"),
+      artifactExists,
+      proxyKind,
+      ...(implementationAddress ? { implementationAddress } : {}),
+      address: contract.address,
+    };
+  };
+
+  await hardhatRun("compile", { quiet: true });
+  try {
+    const evidence = await importMigrationState({
+      root,
+      plan,
+      targets: workflowConfig,
+      confirmations: args.confirm || [],
+      inspect,
+      verifyCandidate: async (contractInfo) => {
+        const checkRoot = fs.mkdtempSync(path.join(root, ".gate-migration-check-"));
+        const candidatePath = path.join(checkRoot, "contractInfo.json");
+        const reportPath = path.join(checkRoot, "bytecode-check.json");
+        try {
+          writeJsonFile(candidatePath, contractInfo);
+          const result = spawnSync(commandName("npx"), [
+            "--no-install",
+            "gate-tool",
+            "check",
+            "--config",
+            candidatePath,
+            "--output",
+            reportPath,
+          ], {
+            cwd: root,
+            env: process.env,
+            stdio: "inherit",
+          });
+          return resolveGateToolCandidateCheck(result, reportPath);
+        } finally {
+          fs.rmSync(checkRoot, { recursive: true, force: true });
+        }
+      },
+    });
+    console.log(JSON.stringify({
+      status: evidence.status,
+      migrationId: evidence.migrationId,
+      planHash: evidence.planHash,
+      evidencePath: `scripts/migrations/${evidence.migrationId}/state-import.json`,
+    }));
+  } finally {
+    for (const provider of rpcProviders.values()) provider.destroy();
+  }
+};
+
+void main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  console.error("Use --print-confirmations with the same --plan before importing state.");
+  process.exitCode = 1;
+});

package/runtime/workflow/lib/authority.ts

@@ -0,0 +1,170 @@
+import type { BaseContract } from "ethers";
+import { getAddress, isAddress } from "ethers";
+import { TargetConfig, resolveAdmin } from "./config";
+
+export interface AuthorityDecision {
+  mode: "execute" | "calldata";
+  signer: string;
+  configuredAdmin: string;
+  chainAdmin?: string;
+  executor?: string;
+  reason: string;
+}
+
+export const assertSelectedSimulationSignerAuthorized = (
+  decision: AuthorityDecision,
+  stepId: string,
+): void => {
+  if (decision.mode === "execute") return;
+  const requiredExecutor = decision.executor || decision.configuredAdmin;
+  throw new Error(
+    `selected simulation signer is not authorized for step ${stepId}; required executor ${requiredExecutor}`,
+  );
+};
+
+const readChainAdmin = async (
+  contract: BaseContract,
+  blockTag?: number,
+): Promise<string | undefined> => {
+  const callable = contract as unknown as Record<string, unknown>;
+
+  for (const methodName of ["owner", "admin"]) {
+    const method = callable[methodName];
+    if (typeof method !== "function") continue;
+
+    try {
+      const value = await (method as (...args: unknown[]) => Promise<unknown>)(
+        ...(blockTag === undefined ? [] : [{ blockTag }]),
+      );
+      if (typeof value === "string" && isAddress(value)) {
+        return getAddress(value);
+      }
+    } catch {
+      // Some proxy admin methods intentionally revert for non-admin callers.
+    }
+  }
+
+  return undefined;
+};
+
+interface ControlledMulticallAuthorityContract {
+  callers: (caller: string, overrides?: { blockTag: number }) => Promise<boolean>;
+  factoryCallers: (
+    factory: string,
+    caller: string,
+    overrides?: { blockTag: number },
+  ) => Promise<boolean>;
+  owner?: (overrides?: { blockTag: number }) => Promise<unknown>;
+  admin?: (overrides?: { blockTag: number }) => Promise<unknown>;
+}
+
+export const decideControlledMulticallAuthority = async (
+  contract: ControlledMulticallAuthorityContract,
+  factory: string,
+  target: TargetConfig,
+  signerAddress: string,
+  blockTag?: number,
+): Promise<AuthorityDecision> => {
+  const normalizedSignerAddress = getAddress(signerAddress);
+  const normalizedFactory = getAddress(factory);
+  let callerAllowed: boolean;
+  let factoryAllowed: boolean;
+  try {
+    [callerAllowed, factoryAllowed] = await Promise.all([
+      blockTag === undefined
+        ? contract.callers(normalizedSignerAddress)
+        : contract.callers(normalizedSignerAddress, { blockTag }),
+      blockTag === undefined
+        ? contract.factoryCallers(normalizedFactory, normalizedSignerAddress)
+        : contract.factoryCallers(normalizedFactory, normalizedSignerAddress, { blockTag }),
+    ]);
+  } catch (error) {
+    throw new Error(
+      "Cannot determine controlled multicall authority: "
+      + (error instanceof Error ? error.message : String(error)),
+    );
+  }
+
+  const configuredAdmin = resolveAdmin(target, normalizedSignerAddress);
+  const chainAdmin = await readChainAdmin(contract as unknown as BaseContract, blockTag);
+  if (callerAllowed && factoryAllowed) {
+    return {
+      mode: "execute",
+      signer: normalizedSignerAddress,
+      configuredAdmin,
+      chainAdmin,
+      reason: "operator has controlled multicall caller and factory authority",
+    };
+  }
+
+  const explicitConfiguredAdmin = typeof target.admin === "string" && isAddress(target.admin)
+    ? getAddress(target.admin)
+    : undefined;
+  const executor = chainAdmin || explicitConfiguredAdmin;
+  if (!executor || executor.toLowerCase() === normalizedSignerAddress.toLowerCase()) {
+    throw new Error(
+      "Controlled multicall permissions are missing and cannot resolve an external executor",
+    );
+  }
+  return {
+    mode: "calldata",
+    signer: normalizedSignerAddress,
+    configuredAdmin,
+    chainAdmin,
+    executor,
+    reason: [
+      "controlled multicall authority requires external execution",
+      callerAllowed ? undefined : "caller permission missing",
+      factoryAllowed ? undefined : "factory caller permission missing",
+    ].filter(Boolean).join("; "),
+  };
+};
+
+export const decideAuthority = async (
+  contract: BaseContract,
+  target: TargetConfig,
+  signerAddress: string,
+  blockTag?: number,
+): Promise<AuthorityDecision> => {
+  const normalizedSignerAddress = getAddress(signerAddress);
+  const configuredAdmin = resolveAdmin(target, normalizedSignerAddress);
+  const chainAdmin = await readChainAdmin(contract, blockTag);
+
+  if (chainAdmin) {
+    if (chainAdmin.toLowerCase() === normalizedSignerAddress.toLowerCase()) {
+      return {
+        mode: "execute",
+        signer: normalizedSignerAddress,
+        configuredAdmin,
+        chainAdmin,
+        reason: "signer is chain admin",
+      };
+    }
+
+    return {
+      mode: "calldata",
+      signer: normalizedSignerAddress,
+      configuredAdmin,
+      chainAdmin,
+      executor: chainAdmin,
+      reason: "signer is not chain admin",
+    };
+  }
+
+  if (configuredAdmin.toLowerCase() !== normalizedSignerAddress.toLowerCase()) {
+    return {
+      mode: "calldata",
+      signer: normalizedSignerAddress,
+      configuredAdmin,
+      executor: configuredAdmin,
+      reason: "configured admin differs from signer",
+    };
+  }
+
+  return {
+    mode: "execute",
+    signer: normalizedSignerAddress,
+    configuredAdmin,
+    reason: "no chain admin check available",
+  };
+};

package/runtime/workflow/lib/calldata.ts

@@ -0,0 +1,9 @@
+import { Interface } from "ethers";
+
+export const encodeCall = (
+  contractInterface: Interface,
+  method: string,
+  args: unknown[],
+): string => {
+  return contractInterface.encodeFunctionData(method, args);
+};