gate-evm-tools 1.0.26 → 1.0.27

package/runtime/workflow/steps/upgrade.ts

@@ -0,0 +1,598 @@
+import { isAddress } from "ethers";
+import { ethers, network } from "../../projectHardhat";
+import path from "path";
+import type {
+  GateToolDeploymentPlan,
+  GateToolPreparationRequestV1,
+  GateToolTransactionPlan,
+} from "gate-evm-tools/workflow";
+import {
+  assertSelectedSimulationSignerAuthorized,
+  decideAuthority,
+  decideControlledMulticallAuthority,
+} from "../lib/authority";
+import {
+  actualContractName,
+  contractInfoKey,
+  deploymentInstanceId,
+  loadContractInfo,
+  resolveDeployment,
+} from "../lib/deployments";
+import type { DeploymentChange } from "../lib/deploymentRecords";
+import { prepareGateToolWorkflow } from "../lib/gateTool";
+import { syncGateToolUups } from "../lib/gateToolSync";
+import { getERC1967Implementation } from "../lib/erc1967";
+import { recordParameterLockImplementationSalts } from "../lib/lock";
+import { resolveValue, WorkflowStep } from "../lib/parameters";
+import {
+  prepareControlledMulticallTransaction,
+  sendPreparedControlledMulticallTransaction,
+  sendPreparedWorkflowTransaction,
+} from "../lib/create2";
+import { deriveImplementationSalt, ProxyOptions } from "../lib/proxy";
+import type { WorkflowContext } from "../run";
+import { impersonateWorkflowSimulationSigner } from "../lib/signer";
+import { assertSimulationUupsSourceState } from "../lib/simulation";
+
+const resolveInContext = (
+  context: WorkflowContext,
+  value: unknown,
+): unknown => resolveValue(value, {
+  targetId: context.targetId,
+  target: context.target,
+  params: context.targetParams,
+  state: context.state,
+});
+
+const resolveObject = (
+  context: WorkflowContext,
+  value: unknown,
+): Record<string, unknown> => {
+  const resolved = resolveInContext(context, value || {});
+  if (!resolved || typeof resolved !== "object" || Array.isArray(resolved)) return {};
+  return resolved as Record<string, unknown>;
+};
+
+const resolveArray = (
+  context: WorkflowContext,
+  value: unknown,
+  label: string,
+): unknown[] => {
+  const resolved = resolveInContext(context, value || []);
+  if (!Array.isArray(resolved)) throw new Error(`${label} must resolve to an array`);
+  return resolved;
+};
+
+const stringField = (
+  source: Record<string, unknown>,
+  key: string,
+): string | undefined => (
+  typeof source[key] === "string" && source[key] ? String(source[key]) : undefined
+);
+
+const proxyReference = (
+  context: WorkflowContext,
+  step: WorkflowStep,
+): {
+  proxyAddress: string;
+  saveAs: string;
+  contractInfoKey: string;
+  proxy: ProxyOptions;
+} => {
+  const proxyObject = resolveObject(context, step.proxy);
+  const rawProxy = stringField(proxyObject, "address")
+    || stringField(proxyObject, "name")
+    || stringField(proxyObject, "contract")
+    || (typeof step.proxy === "string" ? String(resolveInContext(context, step.proxy)) : undefined)
+    || (typeof step.address === "string" ? String(resolveInContext(context, step.address)) : undefined);
+  if (!rawProxy) throw new Error(`Step ${step.id} requires proxy address or deployment name`);
+
+  const registryDeployment = isAddress(rawProxy)
+    ? undefined
+    : resolveDeployment(loadContractInfo(context.root, context.config), context.targetId, rawProxy);
+  if (!isAddress(rawProxy) && !registryDeployment) {
+    throw new Error(`Missing contractInfo address: ${context.targetId}.${rawProxy}`);
+  }
+  const proxyAddress = isAddress(rawProxy) ? rawProxy : registryDeployment!.address;
+  const defaultSaveAs = isAddress(rawProxy)
+    ? actualContractName(String(step.contract))
+    : registryDeployment!.key.split(":", 1)[0];
+  const saveAs = deploymentInstanceId(String(step.saveAs || defaultSaveAs));
+  const registryKey = registryDeployment?.key || contractInfoKey(saveAs, String(step.contract));
+  return {
+    proxyAddress,
+    saveAs,
+    contractInfoKey: registryKey,
+    proxy: {
+      kind: stringField(proxyObject, "kind")
+        || (typeof step.proxyKind === "string" ? step.proxyKind : "uups"),
+      initializer: proxyObject.initializer === false
+        ? false
+        : stringField(proxyObject, "initializer"),
+      unsafeAllow: Array.isArray(proxyObject.unsafeAllow)
+        ? proxyObject.unsafeAllow.map((item) => String(item))
+        : undefined,
+      constructorArgs: proxyObject.constructorArgs === undefined
+        ? undefined
+        : resolveArray(context, proxyObject.constructorArgs, `Step ${step.id} proxy.constructorArgs`),
+    },
+  };
+};
+
+const upgradeCall = (
+  context: WorkflowContext,
+  step: WorkflowStep,
+): { fn: string; args: unknown[] } | undefined => {
+  const call = resolveObject(context, step.call);
+  const fn = stringField(call, "fn") || stringField(call, "method");
+  return fn
+    ? { fn, args: resolveArray(context, call.args || [], `Step ${step.id} call.args`) }
+    : undefined;
+};
+
+const requiredPlanTransaction = (
+  transactions: GateToolTransactionPlan[],
+  purpose: GateToolTransactionPlan["purpose"],
+): GateToolTransactionPlan => {
+  const selected = transactions.filter((transaction) => transaction.purpose === purpose);
+  if (selected.length !== 1) {
+    throw new Error(`GateTool plan must contain exactly one ${purpose} transaction`);
+  }
+  return selected[0];
+};
+
+const implementationDeployment = (
+  deployments: GateToolDeploymentPlan[],
+): GateToolDeploymentPlan => {
+  const selected = deployments.filter((deployment) => deployment.role === "implementation");
+  if (selected.length !== 1) {
+    throw new Error("GateTool plan must contain exactly one implementation deployment");
+  }
+  return selected[0];
+};
+
+const transactionEnvelope = (transaction: GateToolTransactionPlan) => ({
+  target: transaction.to,
+  value: transaction.value,
+  data: transaction.data,
+  operation: transaction.operation,
+  ...(transaction.factoryDeps === undefined
+    ? {}
+    : { scheme: "zksync-eravm" as const, factoryDeps: transaction.factoryDeps }),
+});
+
+const assertUupsChainState = async (
+  proxy: string,
+  implementation: string,
+): Promise<void> => {
+  const [proxyCode, implementationCode, currentImplementation] = await Promise.all([
+    ethers.provider.getCode(proxy),
+    ethers.provider.getCode(implementation),
+    getERC1967Implementation(ethers.provider, proxy),
+  ]);
+  if (!proxyCode || proxyCode === "0x") {
+    throw new Error(`UUPS proxy is missing deployed code at ${proxy}`);
+  }
+  if (!implementationCode || implementationCode === "0x") {
+    throw new Error(`UUPS implementation is missing deployed code at ${implementation}`);
+  }
+  if (
+    !currentImplementation
+    || currentImplementation.toLowerCase() !== implementation.toLowerCase()
+  ) {
+    throw new Error(
+      `UUPS proxy ${proxy} does not point to GateTool implementation ${implementation}`,
+    );
+  }
+};
+
+export const runUpgradeStep = async (
+  context: WorkflowContext,
+  step: WorkflowStep,
+): Promise<void> => {
+  if (!context.signer || !context.signerAddress) {
+    throw new Error(`Upgrade step ${step.id} requires a signer`);
+  }
+  const contractName = String(step.contract);
+  const proxy = proxyReference(context, step);
+  if ((proxy.proxy.kind || "uups") !== "uups") {
+    throw new Error(`Upgrade step ${step.id} only supports UUPS proxies`);
+  }
+  if (context.mode === "simulate") {
+    await assertSimulationUupsSourceState(context.simulation, proxy.proxyAddress);
+  }
+  const call = upgradeCall(context, step);
+  const actualContract = actualContractName(contractName);
+  const targetCreate2 = context.target.create2;
+  const targetMulticall = context.target.multicall;
+  const scheme = targetCreate2?.scheme || "evm";
+  if (scheme !== "evm" && scheme !== "zksync-eravm") {
+    throw new Error(`Upgrade step ${step.id} target create2 scheme is invalid`);
+  }
+  if (!targetCreate2?.factory || !targetMulticall?.controlledMulticall) {
+    throw new Error(
+      `Upgrade step ${step.id} requires target create2 factory and controlledMulticall`,
+    );
+  }
+  const constructorArgs = resolveArray(
+    context,
+    step.constructorArgs || proxy.proxy.constructorArgs || [],
+    `Step ${step.id} constructorArgs`,
+  );
+  const implementationSalt = deriveImplementationSalt(
+    context.executionId,
+    contractName,
+    proxy.proxyAddress,
+  );
+  const request: GateToolPreparationRequestV1 = {
+    version: 1,
+    kind: "uups-upgrade",
+    scheme,
+    network: network.name,
+    target: context.targetId,
+    contract: contractName,
+    constructorArgs,
+    factory: targetCreate2.factory,
+    proxyKind: "uups",
+    proxy: proxy.proxyAddress,
+    implementationSalt,
+    ...(proxy.proxy.unsafeAllow ? { unsafeAllow: proxy.proxy.unsafeAllow } : {}),
+    ...(call ? { call: { method: call.fn, args: call.args } } : {}),
+  };
+  const gateToolEvidenceDir = path.join(
+    context.taskDir,
+    "results",
+    context.targetId,
+    context.executionId,
+    "gate-tool",
+    context.mode,
+  );
+  const prepared = await prepareGateToolWorkflow({
+    root: context.root,
+    evidenceDir: gateToolEvidenceDir,
+    evidenceName: step.id,
+    request,
+    readBlockTag: context.mode === "simulate"
+      ? context.simulation.snapshot?.blockNumber
+      : undefined,
+  });
+  const implementation = implementationDeployment(prepared.plan.deployments);
+  const implementationCall = prepared.plan.transactions.find(
+    (transaction) => transaction.purpose === "deploy-implementation",
+  );
+  const proxyUpgradeCall = requiredPlanTransaction(prepared.plan.transactions, "upgrade-proxy");
+  const gateToolPlan = path.relative(context.root, prepared.planPath).split(path.sep).join("/");
+  const preparedChange: DeploymentChange = {
+    stepId: step.id,
+    kind: "upgrade",
+    instanceId: proxy.saveAs,
+    actualContract,
+    contractInfoKey: proxy.contractInfoKey,
+    strategy: "gate-tool",
+    proxyKind: "uups",
+    proxyAddress: proxy.proxyAddress,
+    implementationAddress: implementation.address,
+    implementationSalt,
+    constructorArgs,
+    factory: targetCreate2.factory,
+    gateTool: {
+      outputPath: gateToolPlan,
+      data: prepared.plan as unknown as Record<string, unknown>,
+    },
+  };
+  if (context.parameterLockExecutionId) {
+    recordParameterLockImplementationSalts(
+      context.taskDir,
+      context.parameterLockExecutionId,
+      { [`${step.id}.implementation`]: implementationSalt },
+    );
+  }
+  const recorder = context.mode === "execute" ? context.deploymentRecorder : undefined;
+  if (context.mode === "execute" && !recorder) {
+    throw new Error(`Upgrade step ${step.id} requires an execution deployment recorder`);
+  }
+  recorder?.prepare(preparedChange);
+
+  const proxyContract = await ethers.getContractAt(
+    String(step.abi || contractName),
+    proxy.proxyAddress,
+    context.signer,
+  );
+  const upgradeAuthority = await decideAuthority(
+    proxyContract,
+    context.target,
+    context.signerAddress,
+  );
+  if (
+    context.mode === "simulate"
+    && !context.configuredSimulationCaller
+    && !context.executionPlanner
+  ) {
+    assertSelectedSimulationSignerAuthorized(upgradeAuthority, step.id);
+  }
+
+  const implementationMulticall = implementationCall
+    ? prepareControlledMulticallTransaction(
+        targetMulticall.controlledMulticall,
+        [{
+          target: implementationCall.to,
+          value: implementationCall.value,
+          data: implementationCall.data,
+          ...(implementationCall.factoryDeps === undefined
+            ? {}
+            : { factoryDeps: implementationCall.factoryDeps }),
+        }],
+        scheme,
+      )
+    : undefined;
+  const multicall = implementationMulticall
+    ? await ethers.getContractAt(
+        "Multicall3",
+        targetMulticall.controlledMulticall,
+        context.signer,
+      )
+    : undefined;
+  const implementationAuthority = multicall
+    ? await decideControlledMulticallAuthority(
+        multicall as unknown as {
+          callers: (caller: string) => Promise<boolean>;
+          factoryCallers: (factoryAddress: string, caller: string) => Promise<boolean>;
+          owner?: () => Promise<unknown>;
+        },
+        targetCreate2.factory,
+        context.target,
+        context.signerAddress,
+      )
+    : undefined;
+  if (
+    scheme === "zksync-eravm"
+    && (
+      upgradeAuthority.mode !== "execute"
+      || implementationAuthority?.mode === "calldata"
+    )
+  ) {
+    throw new Error(
+      `Upgrade step ${step.id} requires unsupported zkSync external Admin execution`,
+    );
+  }
+
+  if (!context.executionPlanner) {
+    const configuredCallerSimulation = context.mode === "simulate"
+      && context.configuredSimulationCaller === true;
+    if (
+      !configuredCallerSimulation
+      && (
+        upgradeAuthority.mode !== "execute"
+        || implementationAuthority?.mode === "calldata"
+      )
+    ) {
+      throw new Error(`Upgrade step ${step.id} requires a locked mixed-authority execution plan`);
+    }
+    let implementationTxHash: string | undefined;
+    if (implementationMulticall) {
+      const tx = await sendPreparedControlledMulticallTransaction(
+        implementationMulticall,
+        context.signer,
+      );
+      implementationTxHash = tx.hash;
+    }
+    const upgradeTx = await sendPreparedWorkflowTransaction(
+      transactionEnvelope(proxyUpgradeCall),
+      context.signer,
+    );
+    await assertUupsChainState(proxy.proxyAddress, implementation.address);
+    const gateToolSync = context.mode === "execute"
+      ? await syncGateToolUups({
+          root: context.root,
+          evidenceDir: gateToolEvidenceDir,
+          evidenceName: step.id,
+          scheme: prepared.plan.scheme,
+          network: network.name,
+          target: context.targetId,
+          manifestDir: context.target.openzeppelin.manifestDir,
+          proxy: proxy.proxyAddress,
+          implementation: implementation.address,
+          contract: actualContract,
+          constructorArgs,
+          transactionHash: upgradeTx.hash,
+        })
+      : undefined;
+    if (context.mode === "execute") {
+      recorder?.apply({
+        ...preparedChange,
+        implementationTxHash,
+        txHash: upgradeTx.hash,
+        gateToolSync,
+      });
+    }
+    context.state.set(`${proxy.saveAs}Upgrade`, {
+      proxyAddress: proxy.proxyAddress,
+      implementationAddress: implementation.address,
+      implementationSalt,
+      implementationTxHash,
+      txHash: upgradeTx.hash,
+      gateToolPlan,
+      gateToolSync: gateToolSync?.outputPath,
+    });
+    context.reporter.result("execution", {
+      stepId: step.id,
+      kind: step.kind,
+      mode: "execute",
+      scheme,
+      contract: contractName,
+      actualContract,
+      saveAs: proxy.saveAs,
+      contractInfoKey: proxy.contractInfoKey,
+      proxy: proxy.proxyAddress,
+      implementationAddress: implementation.address,
+      implementationTxHash,
+      txHash: upgradeTx.hash,
+      gateToolPlan,
+    });
+    return;
+  }
+
+  let implementationTransactionId: string | undefined;
+  let implementationTxHash: string | undefined;
+  let implementationExternal = false;
+  if (implementationMulticall && implementationAuthority) {
+    const implementationExecutor = implementationAuthority.mode === "execute"
+      ? context.signerAddress
+      : implementationAuthority.executor;
+    if (!implementationExecutor) {
+      throw new Error(`Upgrade step ${step.id} cannot resolve implementation executor`);
+    }
+    const planned = context.executionPlanner.add({
+      stepId: `${step.id}-implementation`,
+      executor: implementationExecutor,
+      to: implementationMulticall.target,
+      value: implementationMulticall.value,
+      data: implementationMulticall.data,
+      operation: 0,
+      ...(implementationMulticall.scheme === undefined
+        ? {}
+        : { scheme: implementationMulticall.scheme }),
+      ...(implementationMulticall.factoryDeps === undefined
+        ? {}
+        : { factoryDeps: implementationMulticall.factoryDeps }),
+    });
+    implementationTransactionId = planned.transactionId;
+    implementationExternal = planned.route === "external";
+    if (planned.executionAction === "replay") {
+      implementationTxHash = planned.transactionHash;
+    } else 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: implementationMulticall.method,
+        args: implementationMulticall.calls,
+        executor: planned.executor,
+        reason: implementationAuthority.reason,
+      });
+    } else {
+      const selectedSigner = planned.route === "external"
+        ? await impersonateWorkflowSimulationSigner(planned.executor)
+        : context.signer;
+      const tx = await sendPreparedControlledMulticallTransaction(
+        implementationMulticall,
+        selectedSigner,
+      );
+      implementationTxHash = tx.hash;
+      if (context.mode === "execute" && planned.route === "operator") {
+        context.operatorReceipts.push({
+          transactionId: planned.transactionId,
+          transactionHash: tx.hash,
+        });
+      }
+    }
+  }
+
+  const upgradeExecutor = upgradeAuthority.mode === "execute"
+    ? context.signerAddress
+    : upgradeAuthority.executor;
+  if (!upgradeExecutor) throw new Error(`Upgrade step ${step.id} cannot resolve proxy executor`);
+  const upgradeEnvelope = transactionEnvelope(proxyUpgradeCall);
+  const upgradeTransaction = context.executionPlanner.add({
+    stepId: step.id,
+    executor: upgradeExecutor,
+    to: upgradeEnvelope.target,
+    value: upgradeEnvelope.value,
+    data: upgradeEnvelope.data,
+    operation: 0,
+    ...(upgradeEnvelope.scheme === undefined ? {} : { scheme: upgradeEnvelope.scheme }),
+    ...(upgradeEnvelope.factoryDeps === undefined
+      ? {}
+      : { factoryDeps: upgradeEnvelope.factoryDeps }),
+  });
+  if (context.mode === "execute") {
+    recorder?.bindProxyTransaction(step.id, upgradeTransaction.transactionId);
+  }
+  let upgradeTxHash: string | undefined;
+  if (upgradeTransaction.executionAction === "replay") {
+    upgradeTxHash = upgradeTransaction.transactionHash;
+  } else if (upgradeTransaction.route === "external" && context.mode !== "simulate") {
+    context.externalCalls.push({
+      transactionId: upgradeTransaction.transactionId,
+      stepId: upgradeTransaction.stepId,
+      to: upgradeTransaction.to,
+      value: upgradeTransaction.value,
+      data: upgradeTransaction.data,
+      operation: upgradeTransaction.operation,
+      method: "upgradeToAndCall",
+      args: [implementation.address],
+      executor: upgradeTransaction.executor,
+      reason: upgradeAuthority.reason,
+    });
+  } else {
+    const selectedSigner = upgradeTransaction.route === "external"
+      ? await impersonateWorkflowSimulationSigner(upgradeTransaction.executor)
+      : context.signer;
+    const tx = await sendPreparedWorkflowTransaction(upgradeEnvelope, selectedSigner);
+    upgradeTxHash = tx.hash;
+    if (context.mode === "execute" && upgradeTransaction.route === "operator") {
+      context.operatorReceipts.push({
+        transactionId: upgradeTransaction.transactionId,
+        transactionHash: tx.hash,
+      });
+    }
+  }
+  if (
+    context.mode === "execute"
+    && !implementationExternal
+    && upgradeTransaction.route === "operator"
+  ) {
+    await assertUupsChainState(proxy.proxyAddress, implementation.address);
+    const gateToolSync = await syncGateToolUups({
+      root: context.root,
+      evidenceDir: gateToolEvidenceDir,
+      evidenceName: step.id,
+      scheme: prepared.plan.scheme,
+      network: network.name,
+      target: context.targetId,
+      manifestDir: context.target.openzeppelin.manifestDir,
+      proxy: proxy.proxyAddress,
+      implementation: implementation.address,
+      contract: actualContract,
+      constructorArgs,
+      transactionHash: upgradeTxHash || "",
+    });
+    recorder?.apply({
+      ...preparedChange,
+      implementationTxHash,
+      txHash: upgradeTxHash,
+      gateToolSync,
+    });
+  } else if (context.mode === "simulate") {
+    await assertUupsChainState(proxy.proxyAddress, implementation.address);
+  }
+  context.state.set(`${proxy.saveAs}Upgrade`, {
+    proxyAddress: proxy.proxyAddress,
+    implementationAddress: implementation.address,
+    implementationSalt,
+    implementationTxHash,
+    txHash: upgradeTxHash,
+    external: implementationExternal || upgradeTransaction.route === "external",
+    gateToolPlan,
+  });
+  context.reporter.result("execution", {
+    stepId: step.id,
+    kind: step.kind,
+    mode: upgradeTransaction.route,
+    scheme,
+    implementationTransactionId,
+    upgradeTransactionId: upgradeTransaction.transactionId,
+    contract: contractName,
+    actualContract,
+    saveAs: proxy.saveAs,
+    contractInfoKey: proxy.contractInfoKey,
+    proxy: proxy.proxyAddress,
+    implementationAddress: implementation.address,
+    implementationTxHash,
+    txHash: upgradeTxHash,
+    gateToolPlan,
+  });
+};

package/runtime/workflow/steps/view.ts

@@ -0,0 +1,10 @@
+import { WorkflowContext } from "../run";
+import { WorkflowStep } from "../lib/parameters";
+import { runContractViewCalls } from "../lib/calls";
+
+export const runViewStep = async (
+  context: WorkflowContext,
+  step: WorkflowStep,
+): Promise<void> => {
+  await runContractViewCalls(context, step);
+};