gate-evm-tools 1.0.28 → 1.2.0

package/runtime/workflow/run.ts

@@ -1,8 +1,8 @@
+import { resolvePendingUupsReuse } from "./lib/pendingDeploymentReuse";
 import { bindExecutionRuntime } from "./lib/runtimeVersion";
 import fs from "fs";
 import path from "path";
-import type { Signer } from "ethers";
-import { artifacts, config as hardhatConfig, ethers, network } from "../projectHardhat";
+import hardhat, { artifacts, config as hardhatConfig, ethers, network } from "../projectHardhat";
 import {
   loadConfig,
   resolveAdmin,
@@ -17,6 +17,7 @@ import {
   ParameterLockExecution,
   readParameterLockExecution,
   writeParameterLock,
+  recordParameterLockImplementationSalts,
 } from "./lib/lock";
 import {
   loadManifest,
@@ -44,8 +45,6 @@ import {
 } from "./lib/releaseParameters";
 import { WorkflowReporter } from "./lib/reporter";
 import {
-  ExternalCall,
-  ExternalExecutionRequired,
   writeExternalExecutionPackage,
 } from "./lib/external";
 import { classifyWorkflowError } from "./lib/errors";
@@ -54,7 +53,6 @@ import {
   setupSimulationFork,
   assertSimulationSourceInfrastructure,
   simulationForkEvidence,
-  SimulationFork,
   verifySimulationForkSnapshot,
   WorkflowMode,
 } from "./lib/simulation";
@@ -66,14 +64,8 @@ import {
 import { loadSimulationCallerNetwork } from "./lib/simulationCallers";
 import { WorkflowState } from "./lib/state";
 import { DeploymentRecorder } from "./lib/deploymentRecords";
-import { runDeployStep } from "./steps/deploy";
-import { runCallStep } from "./steps/call";
-import { runUpgradeStep } from "./steps/upgrade";
-import { runViewStep } from "./steps/view";
-import { runCheckStep } from "./steps/check";
 import { runCustomStep } from "./steps/custom";
 import {
-  ExecutionSegmentDeferred,
   loadReleaseExecutionPlan,
   ReleaseExecutionPlan,
   ReleaseExecutionPlanner,
@@ -84,32 +76,9 @@ import {
 import { writeOperatorExecutionResult } from "./lib/operatorExecution";
 import { loadCompletedExecutionPrefix } from "./lib/executionProgress";
 
-export interface WorkflowContext {
-  root: string;
-  taskId: string;
-  executionId: string;
-  taskDir: string;
-  targetId: string;
-  target: TargetConfig & Record<string, unknown> & { id: string };
-  targetParams: Record<string, unknown>;
-  existingDeploymentPolicies: ExistingDeploymentPolicies;
-  releaseArtifactHash?: string;
-  parameterLockExecutionId?: string;
-  parameterLockOperator?: string;
-  config: ReturnType<typeof loadConfig>;
-  mode: WorkflowMode;
-  simulation: SimulationFork;
-  signer?: Signer;
-  signerAddress?: string;
-  configuredSimulationCaller?: boolean;
-  state: WorkflowState;
-  reporter: WorkflowReporter;
-  deploymentRecorder?: DeploymentRecorder;
-  executionPlanner?: ReleaseExecutionPlanner;
-  lockedExecutionPlan?: ReleaseExecutionPlan;
-  externalCalls: ExternalCall[];
-  operatorReceipts: Array<{ transactionId: string; transactionHash: string }>;
-}
+import type { WorkflowContext } from "./lib/context";
+import { runWorkflowSteps, validateWorkflowStepsForMode } from "./engine";
+export type { WorkflowContext } from "./lib/context";
 
 const parseArgs = (argv: string[]): Record<string, string | boolean> => {
   const args: Record<string, string | boolean> = {};
@@ -161,11 +130,10 @@ const parseEnvArgs = (): Record<string, string | boolean> => {
 const assertWalletCredentialForExecution = (mode: WorkflowMode, targetId: string): void => {
   if (mode !== "execute") return;
   if (targetId === "hardhat" || targetId === "localhost") return;
-  if (process.env.WALLET_CREDENTIAL?.trim()) return;
   if (process.env.PRIVATE_KEY?.trim()) return;
 
   throw new Error(
-    `Missing wallet credential in project .env or process env. Execute mode on "${targetId}" requires a deployment signer.`,
+    `Missing PRIVATE_KEY in project .env or process env. Execute mode on "${targetId}" requires a deployment signer.`,
   );
 };
 
@@ -186,31 +154,6 @@ const selectSteps = (
   return steps;
 };
 
-const runStep = async (context: WorkflowContext, step: WorkflowStep): Promise<void> => {
-  switch (step.kind) {
-    case "deploy":
-      await runDeployStep(context, step);
-      return;
-    case "call":
-      await runCallStep(context, step);
-      return;
-    case "upgrade":
-      await runUpgradeStep(context, step);
-      return;
-    case "view":
-      await runViewStep(context, step);
-      return;
-    case "check":
-      await runCheckStep(context, step);
-      return;
-    case "custom":
-      await runCustomStep(context, step);
-      return;
-    default:
-      throw new Error(`Unsupported step kind: ${step.kind}`);
-  }
-};
-
 interface PreparedReleaseExecution {
   sourceSuperTaskId: string;
   mergeCommit: string;
@@ -571,12 +514,7 @@ async function main(): Promise<void> {
     if (mode === "simulate" && steps.length === 0) {
       throw new Error("Simulation must select at least one workflow step");
     }
-    if (mode === "verify") {
-      const unsupported = steps.find((step) => step.kind !== "view" && step.kind !== "check");
-      if (unsupported) {
-        throw new Error(`verify mode only supports view and check steps; ${unsupported.id} is ${unsupported.kind}`);
-      }
-    }
+    validateWorkflowStepsForMode(mode, steps);
     const releaseExecution = await prepareReleaseExecution(
       args,
       mode,
@@ -637,17 +575,20 @@ async function main(): Promise<void> {
             useLock: booleanArg(args, "useLock"),
           })
       : undefined;
-    const simulation = mode === "simulate" ? await setupSimulationFork(targetId) : {};
+    const simulation = mode === "simulate" ? await setupSimulationFork(hardhat, targetId, {
+      snapshotJson: process.env.GATE_SIMULATION_FORK_SNAPSHOT_JSON,
+      sourceRpcUrl: process.env.GATE_SIMULATION_SOURCE_RPC_URL,
+    }) : {};
     if (mode === "simulate") {
-      await assertSimulationSourceInfrastructure(targetId, target, simulation);
+      await assertSimulationSourceInfrastructure(ethers.provider, targetId, target, simulation);
     }
     const signer = mode === "verify"
       ? undefined
       : mode === "simulate"
       ? simulationCallerBinding
         ? undefined
-        : await impersonateWorkflowSimulationSigner(simulationSignerAddress!)
-      : await resolveWorkflowSigner(mode, {
+        : await impersonateWorkflowSimulationSigner(hardhat, simulationSignerAddress!)
+      : await resolveWorkflowSigner(hardhat, mode, {
           taskAddress: taskMetadata.deploymentSignerAddress,
         });
     const signerAddress = simulationCallerBinding?.defaultAddress
@@ -721,7 +662,7 @@ async function main(): Promise<void> {
       });
     }
 
-    const context: WorkflowContext = {
+    const context: WorkflowContext & { executionPlanner?: ReleaseExecutionPlanner } = {
       root,
       taskId,
       executionId,
@@ -733,9 +674,28 @@ async function main(): Promise<void> {
         ? releaseExecution.existingDeploymentPolicies
         : parseExistingDeploymentPolicies(args),
       releaseArtifactHash: releaseExecution?.releaseFingerprint.artifactHash,
-      parameterLockExecutionId: releaseExecution ? executionId : undefined,
-      parameterLockOperator: releaseExecution?.lockedExecution?.operator,
+      pendingUupsReuse: releaseExecution ? {
+        resolve: async (input) => {
+          const result = await resolvePendingUupsReuse({ ...input, root, taskDir, currentExecutionId: executionId });
+          return result ? { implementationAddress: result.implementationAddress, implementationSalt: result.implementationSalt,
+            proxyAddress: result.proxyAddress, artifactDigest: result.evidence.artifactDigest, legacyEvidence: result.evidence } : undefined;
+        },
+      } : undefined,
       config,
+      runtime: {
+        hre: hardhat,
+        ...(mode === "simulate" ? {
+          localFork: {
+            provider: network.provider,
+            impersonate: (address) => impersonateWorkflowSimulationSigner(hardhat, address),
+          },
+        } : {}),
+      },
+      bindings: releaseExecution ? {
+        recordOrAssertDerivedValue: (key, value) => recordParameterLockImplementationSalts(
+          taskDir, executionId, { [key]: value },
+        ),
+      } : undefined,
       mode,
       simulation,
       signer,
@@ -759,7 +719,6 @@ async function main(): Promise<void> {
             completedTransactions: completedExecutionPrefix,
           })
         : undefined,
-      lockedExecutionPlan,
       externalCalls: [],
       operatorReceipts: [],
     };
@@ -787,103 +746,10 @@ async function main(): Promise<void> {
       });
     }
 
-    let executionSegmentDeferred = false;
-    stepLoop: for (const step of steps) {
-      if (
-        context.mode === "execute"
-        && context.externalCalls.length > 0
-        && (step.kind === "view" || step.kind === "check" || step.kind === "custom")
-      ) {
-        reporter.event("step.deferred_until_external_execution", {
-          stepId: step.id,
-          kind: step.kind,
-        });
-        break;
-      }
-      const configuredCaller = simulationCallerBinding?.resolved.find(
-        (entry) => entry.stepId === step.id,
-      );
-      const stepContext: WorkflowContext = configuredCaller
-        ? {
-            ...context,
-            signer: await impersonateWorkflowSimulationSigner(configuredCaller.callerAddress),
-            signerAddress: configuredCaller.callerAddress,
-            configuredSimulationCaller: true,
-          }
-        : context;
-      if (configuredCaller) {
-        reporter.setSimulationCallerAddress(configuredCaller.callerAddress);
-      }
-      try {
-        reporter.event("step.started", { stepId: step.id, kind: step.kind });
-        try {
-          await runStep(stepContext, step);
-        } catch (error) {
-          if (context.mode === "execute" && error instanceof ExecutionSegmentDeferred) {
-            executionSegmentDeferred = true;
-            reporter.event("execution.segment.deferred", {
-              transactionId: error.transactionId,
-            });
-            break stepLoop;
-          }
-          if (
-            context.mode === "execute"
-            && error instanceof ExternalExecutionRequired
-          ) {
-            if (!context.executionPlanner) {
-              throw new Error(
-                "External execution requires a locked mixed-authority plan; run final simulation and execute mode",
-              );
-            }
-            for (const call of error.calls) {
-              let planned;
-              try {
-                planned = context.executionPlanner.add({
-                  stepId: call.stepId,
-                  executor: call.executor,
-                  to: call.to,
-                  value: call.value,
-                  data: call.data,
-                  operation: call.operation,
-                });
-              } catch (planError) {
-                if (planError instanceof ExecutionSegmentDeferred) {
-                  executionSegmentDeferred = true;
-                  reporter.event("execution.segment.deferred", {
-                    transactionId: planError.transactionId,
-                  });
-                  break;
-                }
-                throw planError;
-              }
-              if (planned.route !== "external") {
-                throw new Error(
-                  `Step ${call.stepId} requested external execution for an operator route`,
-                );
-              }
-              if (planned.executionAction !== "replay") {
-                context.externalCalls.push({
-                  ...call,
-                  transactionId: planned.transactionId,
-                  stepId: planned.stepId,
-                  executor: planned.executor,
-                  to: planned.to,
-                  value: planned.value,
-                  data: planned.data,
-                  operation: planned.operation,
-                });
-              }
-            }
-            if (executionSegmentDeferred) break stepLoop;
-            continue;
-          }
-          throw error;
-        }
-        reporter.event("step.completed", { stepId: step.id, kind: step.kind });
-      } finally {
-        if (configuredCaller) reporter.clearSimulationCallerAddress();
-      }
-    }
+    const { executionSegmentDeferred } = await runWorkflowSteps(context, steps, {
+      simulationCallers: simulationCallerBinding?.resolved,
+      runCustomStep,
+    });
 
     const plannedBody = context.executionPlanner?.complete({
       allowPartial: executionSegmentDeferred,
@@ -893,7 +759,7 @@ async function main(): Promise<void> {
       : lockedExecutionPlan;
 
     if (mode === "simulate") {
-      await verifySimulationForkSnapshot(context.simulation);
+      await verifySimulationForkSnapshot(hardhat, context.simulation);
     }
     if (completedPlan && mode === "execute") {
       writeOperatorExecutionResult({

package/runtime/workflow/staticValidate.ts

@@ -2,8 +2,10 @@ import { runStaticValidation } from "./lib/staticValidation";
 
 const taskAt = process.argv.findIndex((item) => item === "--task");
 const deploymentId = taskAt >= 0 ? process.argv[taskAt + 1] : process.env.WORKFLOW_TASK;
-const networkAt = process.argv.findIndex((item) => item === "--network");
-const selectedNetwork = networkAt >= 0 ? process.argv[networkAt + 1] : undefined;
+const evmAt = process.argv.findIndex((item) => item === "--evm-network");
+const zkAt = process.argv.findIndex((item) => item === "--zksync-network");
+const evmNetwork = evmAt >= 0 ? process.argv[evmAt + 1] : undefined;
+const zkNetwork = zkAt >= 0 ? process.argv[zkAt + 1] : undefined;
 
 if (!deploymentId) {
   console.error("workflow:static-validate requires --task <deploymentId> or WORKFLOW_TASK");
@@ -12,7 +14,10 @@ if (!deploymentId) {
   void runStaticValidation({
     root: process.cwd(),
     deploymentId,
-    network: selectedNetwork,
+    compileTargets: evmNetwork && zkNetwork ? [
+      { scheme: "evm", network: evmNetwork },
+      { scheme: "zksync-eravm", network: zkNetwork },
+    ] : [],
   }).then((result) => {
     console.log(JSON.stringify(result));
     if (result.status !== "passed") process.exitCode = 1;

package/runtime/workflow/steps/call.ts

@@ -1,4 +1,4 @@
-import { WorkflowContext } from "../run";
+import type { WorkflowContext } from "../lib/context";
 import { WorkflowStep } from "../lib/parameters";
 import { runContractWriteCalls } from "../lib/calls";
 

package/runtime/workflow/steps/check.ts

@@ -1,4 +1,4 @@
-import { WorkflowContext } from "../run";
+import type { WorkflowContext } from "../lib/context";
 import { WorkflowStep } from "../lib/parameters";
 import { runContractCheckCalls } from "../lib/calls";
 

package/runtime/workflow/steps/custom.ts

@@ -1,6 +1,6 @@
 import path from "path";
 import { createRequire } from "module";
-import type { WorkflowContext } from "../run";
+import type { WorkflowContext } from "../lib/context";
 import type { WorkflowStep } from "../lib/parameters";
 
 type CustomStepRunner = (