gate-evm-tools 1.0.25 → 1.0.27

package/runtime/workflow/steps/deploy.ts

@@ -0,0 +1,771 @@
+import path from "path";
+import { ethers, network } from "../../projectHardhat";
+import type {
+  GateToolDeploymentPlan,
+  GateToolPreparationPlanV1,
+  GateToolPreparationRequestV1,
+  GateToolTransactionPlan,
+} from "gate-evm-tools/workflow";
+import type { WorkflowContext } from "../run";
+import {
+  requireExistingDeploymentPolicy,
+  resolveExistingDeploymentPolicyAction,
+  resolveValue,
+  WorkflowStep,
+} from "../lib/parameters";
+import {
+  actualContractName,
+  contractInfoKey,
+  findDeploymentAddress,
+} from "../lib/deployments";
+import type { DeploymentChange } from "../lib/deploymentRecords";
+import {
+  assertCreate2AddressPolicy,
+  Create2Options,
+  prepareControlledMulticallTransaction,
+  resolveCreate2Options,
+  sendPreparedControlledMulticallTransaction,
+} from "../lib/create2";
+import { assertReusableDeployment } from "../lib/checkCodeReport";
+import { getERC1967Implementation } from "../lib/erc1967";
+import { recordParameterLockImplementationSalts } from "../lib/lock";
+import {
+  deriveImplementationSalt,
+  FirstUpgradeOptions,
+  ProxyOptions,
+} from "../lib/proxy";
+import { decideControlledMulticallAuthority } from "../lib/authority";
+import { impersonateWorkflowSimulationSigner } from "../lib/signer";
+import { prepareGateToolWorkflow } from "../lib/gateTool";
+import { syncGateToolUups } from "../lib/gateToolSync";
+import { resolvePendingUupsReuse } from "../lib/pendingDeploymentReuse";
+
+const resolveInContext = (
+  context: WorkflowContext,
+  value: unknown,
+): unknown => resolveValue(value, {
+  targetId: context.targetId,
+  target: context.target,
+  params: context.targetParams,
+  state: context.state,
+});
+
+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 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 resolveProxyOptions = (
+  context: WorkflowContext,
+  step: WorkflowStep,
+): { options: ProxyOptions } | undefined => {
+  if (step.proxy === undefined) return undefined;
+  const proxy = resolveObject(context, step.proxy);
+  const initializer = proxy.initializer === false
+    ? false
+    : typeof proxy.initializer === "string"
+      ? proxy.initializer
+      : undefined;
+  return {
+    options: {
+      kind: typeof proxy.kind === "string" ? proxy.kind : undefined,
+      initializer,
+      unsafeAllow: Array.isArray(proxy.unsafeAllow)
+        ? proxy.unsafeAllow.map((item) => String(item))
+        : undefined,
+      constructorArgs: proxy.constructorArgs === undefined
+        ? undefined
+        : resolveArray(context, proxy.constructorArgs, `Step ${step.id} proxy.constructorArgs`),
+    },
+  };
+};
+
+const assertCreate2Options = (
+  step: WorkflowStep,
+  options: Create2Options | undefined,
+): Create2Options => {
+  if (!options) throw new Error(`Deploy step ${step.id} requires strategy: create2`);
+  return options;
+};
+
+const setDeploymentState = (
+  context: WorkflowContext,
+  names: string[],
+  value: Record<string, unknown>,
+): void => {
+  for (const name of new Set(names)) context.state.set(name, value);
+};
+
+const stringObjectField = (
+  source: Record<string, unknown>,
+  key: string,
+): string | undefined => {
+  const value = source[key];
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+};
+
+const resolveFirstUpgradeOptions = (
+  context: WorkflowContext,
+  step: WorkflowStep,
+): FirstUpgradeOptions | undefined => {
+  if (step.firstUpgrade === undefined) return undefined;
+  const firstUpgrade = resolveObject(context, step.firstUpgrade);
+  const contractName = stringObjectField(firstUpgrade, "contract");
+  if (!contractName) throw new Error(`Deploy step ${step.id} firstUpgrade requires contract`);
+  const callObject = resolveObject(context, firstUpgrade.call);
+  const fn = stringObjectField(callObject, "fn") || stringObjectField(callObject, "method");
+  return {
+    contractName,
+    call: fn
+      ? {
+          fn,
+          args: resolveArray(
+            context,
+            callObject.args || [],
+            `Step ${step.id} firstUpgrade.call.args`,
+          ),
+        }
+      : undefined,
+    constructorArgs: resolveArray(
+      context,
+      firstUpgrade.constructorArgs || [],
+      `Step ${step.id} firstUpgrade.constructorArgs`,
+    ),
+    unsafeAllow: Array.isArray(firstUpgrade.unsafeAllow)
+      ? firstUpgrade.unsafeAllow.map((item) => String(item))
+      : undefined,
+  };
+};
+
+const applyExistingDeploymentPolicy = async (
+  context: WorkflowContext,
+  step: WorkflowStep,
+  saveAs: string,
+  preparedChange: DeploymentChange,
+  create2Options: Create2Options,
+  declaredUpgradeable: boolean,
+): Promise<{
+  completed: boolean;
+  create2Options: Create2Options;
+  existingAddress?: string;
+  redeployReason?: string;
+}> => {
+  const existing = findDeploymentAddress(context.root, context.config, context.targetId, saveAs);
+  if (!existing) return { completed: false, create2Options };
+  const policy = requireExistingDeploymentPolicy(context.existingDeploymentPolicies, saveAs);
+  const implementationAddress = await getERC1967Implementation(ethers.provider, existing);
+  const action = resolveExistingDeploymentPolicyAction(policy, {
+    instanceId: saveAs,
+    existingAddress: existing,
+    currentSalt: create2Options.salt,
+    upgradeable: declaredUpgradeable || implementationAddress !== undefined,
+  });
+  if (action.mode === "reuse") {
+    if (!context.releaseArtifactHash) {
+      throw new Error(
+        `Deploy step ${step.id} cannot reuse ${context.targetId}.${saveAs} without an execution artifactHash`,
+      );
+    }
+    const evidence = assertReusableDeployment(context.root, {
+      network: context.targetId,
+      scheme: create2Options.scheme,
+      instanceId: saveAs,
+      address: existing,
+      artifactHash: context.releaseArtifactHash,
+    });
+    context.deploymentRecorder?.prepare(preparedChange);
+    context.deploymentRecorder?.apply({
+      ...preparedChange,
+      address: existing,
+      proxyAddress: implementationAddress ? existing : undefined,
+      implementationAddress,
+      reused: true,
+      alreadyDeployed: true,
+      gateTool: {
+        outputPath: "scripts/checkcode/index.json",
+        data: { runId: evidence.runId, artifactHash: evidence.artifactHash },
+      },
+    });
+    setDeploymentState(context, [saveAs], {
+      address: existing,
+      implementationAddress,
+      reused: true,
+      alreadyDeployed: true,
+    });
+    context.reporter.result("execution", {
+      stepId: step.id,
+      kind: step.kind,
+      contract: preparedChange.actualContract,
+      saveAs,
+      strategy: "reuse",
+      address: existing,
+      implementationAddress,
+      checkCodeRunId: evidence.runId,
+      reused: true,
+      alreadyDeployed: true,
+    });
+    return { completed: true, create2Options, existingAddress: existing };
+  }
+  return {
+    completed: false,
+    existingAddress: existing,
+    redeployReason: action.reason,
+    create2Options: {
+      ...create2Options,
+      salt: action.salt,
+      expectedAddress: action.expectedAddress,
+    },
+  };
+};
+
+const deploymentForRole = (
+  plan: GateToolPreparationPlanV1,
+  role: GateToolDeploymentPlan["role"],
+): GateToolDeploymentPlan => {
+  const deployment = plan.deployments.find((entry) => entry.role === role);
+  if (!deployment) throw new Error(`GateTool plan is missing ${role} deployment evidence`);
+  return deployment;
+};
+
+const assertDeployedCode = async (
+  label: string,
+  address: string,
+): Promise<void> => {
+  const code = await ethers.provider.getCode(address);
+  if (!code || code === "0x") {
+    throw new Error(`${label} is missing deployed code at ${address}`);
+  }
+};
+
+const gateToolEvidenceDir = (context: WorkflowContext): string => path.join(
+  context.taskDir,
+  "results",
+  context.targetId,
+  context.executionId,
+  "gate-tool",
+  context.mode,
+);
+
+const runGateToolControlledMulticall = async (
+  context: WorkflowContext,
+  step: WorkflowStep,
+  create2: Create2Options,
+  transactions: GateToolTransactionPlan[],
+): Promise<{ external: boolean; transactionId?: string; txHash?: string }> => {
+  if (transactions.length === 0) return { external: false };
+  if (!create2.controlledMulticall) {
+    throw new Error(`Deploy step ${step.id} requires controlledMulticall`);
+  }
+  if (!context.signer || !context.signerAddress) {
+    throw new Error(`Deploy step ${step.id} requires a signer`);
+  }
+  const prepared = prepareControlledMulticallTransaction(
+    create2.controlledMulticall,
+    transactions.map((transaction) => ({
+      target: transaction.to,
+      value: transaction.value,
+      data: transaction.data,
+      ...(transaction.factoryDeps === undefined
+        ? {}
+        : { factoryDeps: transaction.factoryDeps }),
+    })),
+    create2.scheme,
+  );
+  const multicall = await ethers.getContractAt(
+    "Multicall3",
+    create2.controlledMulticall,
+    context.signer,
+  );
+  const authority = await decideControlledMulticallAuthority(
+    multicall as unknown as {
+      callers: (caller: string) => Promise<boolean>;
+      factoryCallers: (factoryAddress: string, caller: string) => Promise<boolean>;
+      owner?: () => Promise<unknown>;
+    },
+    create2.factory,
+    context.target,
+    context.signerAddress,
+  );
+  const executor = authority.mode === "execute" ? context.signerAddress : authority.executor;
+  if (!executor) throw new Error(`Deploy step ${step.id} cannot resolve its required executor`);
+  if (create2.scheme === "zksync-eravm" && authority.mode !== "execute") {
+    throw new Error(
+      `Deploy step ${step.id} requires unsupported zkSync external Admin execution`,
+    );
+  }
+
+  if (!context.executionPlanner) {
+    if (authority.mode !== "execute") {
+      throw new Error(`Deploy step ${step.id} requires a locked mixed-authority execution plan`);
+    }
+    const transaction = await sendPreparedControlledMulticallTransaction(prepared, context.signer);
+    return { external: false, txHash: transaction.hash };
+  }
+
+  const planned = context.executionPlanner.add({
+    stepId: step.id,
+    executor,
+    to: prepared.target,
+    value: prepared.value,
+    data: prepared.data,
+    operation: 0,
+    ...(prepared.scheme === undefined ? {} : { scheme: prepared.scheme }),
+    ...(prepared.factoryDeps === undefined ? {} : { factoryDeps: prepared.factoryDeps }),
+  });
+  if (planned.executionAction === "replay") {
+    return {
+      external: planned.route === "external",
+      transactionId: planned.transactionId,
+      txHash: planned.transactionHash,
+    };
+  }
+  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: prepared.method,
+      args: prepared.calls,
+      executor: planned.executor,
+      reason: authority.reason,
+    });
+    return { external: true, transactionId: planned.transactionId };
+  }
+  const selectedSigner = planned.route === "external"
+    ? await impersonateWorkflowSimulationSigner(planned.executor)
+    : context.signer;
+  const transaction = await sendPreparedControlledMulticallTransaction(prepared, selectedSigner);
+  if (context.mode === "execute" && planned.route === "operator") {
+    context.operatorReceipts.push({
+      transactionId: planned.transactionId,
+      transactionHash: transaction.hash,
+    });
+  }
+  return {
+    external: false,
+    transactionId: planned.transactionId,
+    txHash: transaction.hash,
+  };
+};
+
+const addressPolicy = (options: Create2Options) => (
+  options.expectedAddress === undefined && options.leadingZeroBytes === undefined
+    ? undefined
+    : {
+        ...(options.expectedAddress === undefined
+          ? {}
+          : { expectedAddress: options.expectedAddress }),
+        ...(options.leadingZeroBytes === undefined
+          ? {}
+          : { leadingZeroBytes: options.leadingZeroBytes }),
+      }
+);
+
+const gateToolChange = (
+  context: WorkflowContext,
+  planPath: string,
+  plan: GateToolPreparationPlanV1,
+) => ({
+  outputPath: path.relative(context.root, planPath).split(path.sep).join("/"),
+  data: plan as unknown as Record<string, unknown>,
+});
+
+export const runDeployStep = async (
+  context: WorkflowContext,
+  step: WorkflowStep,
+): Promise<void> => {
+  const contractName = String(step.contract);
+  const saveAs = typeof step.saveAs === "string" ? step.saveAs.trim() : "";
+  if (!saveAs) throw new Error(`Deploy step ${step.id} requires saveAs`);
+  const create2Options = assertCreate2Options(step, resolveCreate2Options(context, step));
+  const proxy = resolveProxyOptions(context, step);
+  const recorder = context.mode === "execute" ? context.deploymentRecorder : undefined;
+  if (context.mode === "execute" && !recorder) {
+    throw new Error(`Deploy step ${step.id} requires an execution deployment recorder`);
+  }
+
+  if (proxy) {
+    const firstUpgrade = resolveFirstUpgradeOptions(context, step);
+    if (step.upgradeableStrategy !== "uups-placeholder-proxy" || !firstUpgrade) {
+      throw new Error(`Deploy step ${step.id} requires firstUpgrade for uups-placeholder-proxy`);
+    }
+    if ((proxy.options.kind || "uups") !== "uups") {
+      throw new Error(`Deploy step ${step.id} only supports UUPS placeholder proxies`);
+    }
+    if (proxy.options.initializer !== false) {
+      throw new Error(
+        `Deploy step ${step.id} must use proxy.initializer: false for uups-placeholder-proxy`,
+      );
+    }
+    if (!create2Options.controlledMulticall) {
+      throw new Error(`Deploy step ${step.id} requires controlledMulticall for atomic firstUpgrade`);
+    }
+    if (!create2Options.uupsPlaceholderImplementation) {
+      throw new Error(`Deploy step ${step.id} requires target.uups.placeholderImplementation`);
+    }
+
+    const actualContract = actualContractName(firstUpgrade.contractName);
+    const registryKey = contractInfoKey(saveAs, firstUpgrade.contractName);
+    const preparedChange: DeploymentChange = {
+      stepId: step.id,
+      kind: "deploy",
+      instanceId: saveAs,
+      actualContract,
+      contractInfoKey: registryKey,
+      strategy: "create2",
+      proxyKind: "uups",
+      factory: create2Options.factory,
+      multicall: create2Options.controlledMulticall,
+      salt: create2Options.salt,
+      expectedAddress: create2Options.expectedAddress,
+      leadingZeroBytes: create2Options.leadingZeroBytes,
+      placeholderImplementationAddress: create2Options.uupsPlaceholderImplementation,
+    };
+    const existingResolution = await applyExistingDeploymentPolicy(
+      context,
+      step,
+      saveAs,
+      preparedChange,
+      create2Options,
+      true,
+    );
+    if (existingResolution.completed) return;
+    const effectiveCreate2 = existingResolution.create2Options;
+    const pendingReuse = context.parameterLockExecutionId
+      ? await resolvePendingUupsReuse({
+          root: context.root,
+          taskDir: context.taskDir,
+          taskId: context.taskId,
+          currentExecutionId: context.parameterLockExecutionId,
+          network: context.targetId,
+          stepId: step.id,
+          instanceId: saveAs,
+          actualContract,
+          contractInfoKey: registryKey,
+          scheme: effectiveCreate2.scheme,
+          factory: effectiveCreate2.factory,
+          multicall: effectiveCreate2.controlledMulticall!,
+          proxySalt: effectiveCreate2.salt,
+          expectedAddress: effectiveCreate2.expectedAddress,
+          placeholderImplementationAddress: effectiveCreate2.uupsPlaceholderImplementation!,
+          provider: ethers.provider,
+          blockTag: context.mode === "simulate"
+            ? context.simulation.snapshot?.blockNumber
+            : undefined,
+        })
+      : undefined;
+    const implementationSalt = pendingReuse?.implementationSalt ?? deriveImplementationSalt(
+      context.executionId,
+      firstUpgrade.contractName,
+      effectiveCreate2.salt,
+    );
+    const request: GateToolPreparationRequestV1 = {
+      version: 1,
+      kind: "uups-placeholder-deploy",
+      scheme: effectiveCreate2.scheme,
+      network: network.name,
+      target: context.targetId,
+      contract: firstUpgrade.contractName,
+      constructorArgs: firstUpgrade.constructorArgs || [],
+      factory: effectiveCreate2.factory,
+      proxyKind: "uups",
+      implementationSalt,
+      proxySalt: effectiveCreate2.salt,
+      placeholderImplementation: effectiveCreate2.uupsPlaceholderImplementation!,
+      ...(firstUpgrade.unsafeAllow || proxy.options.unsafeAllow
+        ? { unsafeAllow: firstUpgrade.unsafeAllow || proxy.options.unsafeAllow }
+        : {}),
+      ...(addressPolicy(effectiveCreate2)
+        ? { proxyAddressPolicy: addressPolicy(effectiveCreate2) }
+        : {}),
+      ...(firstUpgrade.call
+        ? { call: { method: firstUpgrade.call.fn, args: firstUpgrade.call.args } }
+        : {}),
+    };
+    const prepared = await prepareGateToolWorkflow({
+      root: context.root,
+      evidenceDir: gateToolEvidenceDir(context),
+      evidenceName: step.id,
+      request,
+      readBlockTag: context.mode === "simulate"
+        ? context.simulation.snapshot?.blockNumber
+        : undefined,
+    });
+    const implementation = deploymentForRole(prepared.plan, "implementation");
+    const proxyDeployment = deploymentForRole(prepared.plan, "proxy");
+    if (pendingReuse && (
+      prepared.plan.transactions.length !== 0
+      || prepared.plan.artifact.digest !== pendingReuse.evidence.artifactDigest
+      || implementation.address.toLowerCase() !== pendingReuse.implementationAddress.toLowerCase()
+      || proxyDeployment.address.toLowerCase() !== pendingReuse.proxyAddress.toLowerCase()
+    )) {
+      throw new Error(
+        `Deploy step ${step.id} current GateTool plan does not match trusted pending reuse evidence`,
+      );
+    }
+    assertCreate2AddressPolicy(
+      `${firstUpgrade.contractName} proxy`,
+      proxyDeployment.address,
+      effectiveCreate2,
+    );
+    if (
+      existingResolution.existingAddress
+      && proxyDeployment.address.toLowerCase() === existingResolution.existingAddress.toLowerCase()
+    ) {
+      throw new Error(`Deploy step ${step.id} redeploy predicted the existing address`);
+    }
+    const gateTool = gateToolChange(context, prepared.planPath, prepared.plan);
+    const plannedChange: DeploymentChange = {
+      ...preparedChange,
+      salt: effectiveCreate2.salt,
+      previousAddress: existingResolution.existingAddress,
+      redeployReason: existingResolution.redeployReason,
+      implementationAddress: implementation.address,
+      implementationSalt,
+      constructorArgs: firstUpgrade.constructorArgs || [],
+      predictedAddress: proxyDeployment.address,
+      gateTool,
+      ...(pendingReuse ? { pendingReuse: pendingReuse.evidence } : {}),
+    };
+    if (context.parameterLockExecutionId) {
+      recordParameterLockImplementationSalts(
+        context.taskDir,
+        context.parameterLockExecutionId,
+        { [`${step.id}.implementation`]: implementationSalt },
+      );
+    }
+    recorder?.prepare(plannedChange);
+    if (context.mode === "execute") {
+      recorder?.stageAddressCandidate(plannedChange, proxyDeployment.address);
+    }
+    const execution = await runGateToolControlledMulticall(
+      context,
+      step,
+      effectiveCreate2,
+      prepared.plan.transactions,
+    );
+    if (context.mode === "execute" && execution.transactionId) {
+      recorder?.bindProxyTransaction(step.id, execution.transactionId);
+    }
+    if (!execution.external) {
+      await assertDeployedCode(
+        `${firstUpgrade.contractName} implementation`,
+        implementation.address,
+      );
+      await assertDeployedCode("ERC1967Proxy", proxyDeployment.address);
+      const currentImplementation = await getERC1967Implementation(
+        ethers.provider,
+        proxyDeployment.address,
+      );
+      if (
+        !currentImplementation
+        || currentImplementation.toLowerCase() !== implementation.address.toLowerCase()
+      ) {
+        throw new Error(
+          `ERC1967Proxy ${proxyDeployment.address} does not point to GateTool implementation ${implementation.address}`,
+        );
+      }
+    }
+    const gateToolSync = context.mode === "execute"
+      && !execution.external
+      && proxyDeployment.status !== "reused"
+      ? await syncGateToolUups({
+          root: context.root,
+          evidenceDir: gateToolEvidenceDir(context),
+          evidenceName: step.id,
+          scheme: prepared.plan.scheme,
+          network: network.name,
+          target: context.targetId,
+          manifestDir: context.target.openzeppelin.manifestDir,
+          proxy: proxyDeployment.address,
+          implementation: implementation.address,
+          contract: actualContract,
+          constructorArgs: firstUpgrade.constructorArgs || [],
+          transactionHash: execution.txHash || "",
+        })
+      : undefined;
+    if (context.mode === "execute" && !execution.external) {
+      recorder?.applyAddress({
+        ...plannedChange,
+        address: proxyDeployment.address,
+        proxyAddress: proxyDeployment.address,
+        txHash: execution.txHash,
+        gateToolSync,
+        reused: proxyDeployment.status === "reused",
+        alreadyDeployed: proxyDeployment.status === "reused",
+      }, proxyDeployment.address);
+    }
+    setDeploymentState(context, [saveAs], {
+      address: proxyDeployment.address,
+      proxyAddress: proxyDeployment.address,
+      implementationAddress: implementation.address,
+      implementationSalt,
+      placeholderImplementationAddress: effectiveCreate2.uupsPlaceholderImplementation,
+      txHash: execution.txHash,
+      external: execution.external,
+    });
+    context.reporter.result("execution", {
+      stepId: step.id,
+      kind: step.kind,
+      mode: execution.external ? "external" : context.mode,
+      transactionId: execution.transactionId,
+      contract: contractName,
+      actualContract,
+      saveAs,
+      contractInfoKey: registryKey,
+      strategy: "create2",
+      scheme: prepared.plan.scheme,
+      proxy: "uups",
+      address: proxyDeployment.address,
+      implementationAddress: implementation.address,
+      firstUpgradeImplementationAddress: implementation.address,
+      placeholderImplementationAddress: effectiveCreate2.uupsPlaceholderImplementation,
+      predictedAddress: proxyDeployment.address,
+      reused: proxyDeployment.status === "reused",
+      alreadyDeployed: proxyDeployment.status === "reused",
+      txHash: execution.txHash,
+      gateToolPlan: gateTool.outputPath,
+      gateToolSync: gateToolSync?.outputPath,
+      pendingReuse: pendingReuse?.evidence,
+    });
+    return;
+  }
+
+  const args = resolveArray(context, step.args || [], `Step ${step.id} args`);
+  const actualContract = actualContractName(contractName);
+  const registryKey = contractInfoKey(saveAs, contractName);
+  let preparedChange: DeploymentChange = {
+    stepId: step.id,
+    kind: "deploy",
+    instanceId: saveAs,
+    actualContract,
+    contractInfoKey: registryKey,
+    strategy: "create2",
+    factory: create2Options.factory,
+    multicall: create2Options.controlledMulticall,
+    salt: create2Options.salt,
+    expectedAddress: create2Options.expectedAddress,
+    leadingZeroBytes: create2Options.leadingZeroBytes,
+  };
+  const existingResolution = await applyExistingDeploymentPolicy(
+    context,
+    step,
+    saveAs,
+    preparedChange,
+    create2Options,
+    false,
+  );
+  if (existingResolution.completed) return;
+  const effectiveCreate2 = existingResolution.create2Options;
+  const request: GateToolPreparationRequestV1 = {
+    version: 1,
+    kind: "create2-deploy",
+    scheme: effectiveCreate2.scheme,
+    network: network.name,
+    target: context.targetId,
+    contract: contractName,
+    constructorArgs: args,
+    factory: effectiveCreate2.factory,
+    salt: effectiveCreate2.salt,
+    ...(effectiveCreate2.create2ForwardValue === undefined
+      ? {}
+      : { create2ForwardValue: effectiveCreate2.create2ForwardValue }),
+    ...(effectiveCreate2.callForwardValue === undefined
+      ? {}
+      : { callForwardValue: effectiveCreate2.callForwardValue }),
+    ...(addressPolicy(effectiveCreate2)
+      ? { addressPolicy: addressPolicy(effectiveCreate2) }
+      : {}),
+  };
+  const prepared = await prepareGateToolWorkflow({
+    root: context.root,
+    evidenceDir: gateToolEvidenceDir(context),
+    evidenceName: step.id,
+    request,
+    readBlockTag: context.mode === "simulate"
+      ? context.simulation.snapshot?.blockNumber
+      : undefined,
+  });
+  const deployment = deploymentForRole(prepared.plan, "contract");
+  assertCreate2AddressPolicy(contractName, deployment.address, effectiveCreate2);
+  if (
+    existingResolution.existingAddress
+    && deployment.address.toLowerCase() === existingResolution.existingAddress.toLowerCase()
+  ) {
+    throw new Error(`Deploy step ${step.id} redeploy predicted the existing address`);
+  }
+  const gateTool = gateToolChange(context, prepared.planPath, prepared.plan);
+  preparedChange = {
+    ...preparedChange,
+    salt: effectiveCreate2.salt,
+    expectedAddress: effectiveCreate2.expectedAddress,
+    previousAddress: existingResolution.existingAddress,
+    redeployReason: existingResolution.redeployReason,
+    predictedAddress: deployment.address,
+    gateTool,
+  };
+  recorder?.prepare(preparedChange);
+  if (context.mode === "execute") {
+    recorder?.stageAddressCandidate(preparedChange, deployment.address);
+  }
+  const execution = await runGateToolControlledMulticall(
+    context,
+    step,
+    effectiveCreate2,
+    prepared.plan.transactions,
+  );
+  if (!execution.external) {
+    await assertDeployedCode(contractName, deployment.address);
+  }
+  if (context.mode === "execute" && !execution.external) {
+    recorder?.applyAddress({
+      ...preparedChange,
+      address: deployment.address,
+      txHash: execution.txHash,
+      reused: deployment.status === "reused",
+      alreadyDeployed: deployment.status === "reused",
+    }, deployment.address);
+  }
+  context.state.set(saveAs, {
+    address: deployment.address,
+    predictedAddress: deployment.address,
+    txHash: execution.txHash,
+    external: execution.external,
+    alreadyDeployed: deployment.status === "reused",
+  });
+  context.reporter.result("execution", {
+    stepId: step.id,
+    kind: step.kind,
+    mode: execution.external ? "external" : context.mode,
+    transactionId: execution.transactionId,
+    contract: contractName,
+    actualContract,
+    saveAs,
+    contractInfoKey: registryKey,
+    strategy: "create2",
+    scheme: prepared.plan.scheme,
+    address: deployment.address,
+    predictedAddress: deployment.address,
+    reused: deployment.status === "reused",
+    alreadyDeployed: deployment.status === "reused",
+    txHash: execution.txHash,
+    gateToolPlan: gateTool.outputPath,
+  });
+};