gate-evm-tools 1.0.28 → 1.2.0

package/runtime/workflow/lib/gateTool.ts

@@ -1,6 +1,6 @@
+import type { WorkflowValidationPort } from './validation';
 import fs from "fs";
 import path from "path";
-import hardhat from "../../projectHardhat";
 import {
   canonicalPreparationJson,
   hashPreparationRequest,
@@ -21,8 +21,10 @@ export interface PrepareGateToolWorkflowOptions {
   evidenceDir: string;
   evidenceName: string;
   request: GateToolPreparationRequestV1;
-  hre?: GateToolPreparationHre;
+  hre: GateToolPreparationHre;
   readBlockTag?: number;
+  expected?: PreparedGateToolWorkflow;
+  validation?: WorkflowValidationPort;
 }
 
 export interface PreparedGateToolWorkflow {
@@ -149,7 +151,7 @@ const readRegularJson = (
   }
 };
 
-const expectedTransactionPurposes = (
+export const expectedTransactionPurposes = (
   plan: GateToolPreparationPlanV1,
 ): GateToolTransactionPurpose[] => {
   const requiredRoles = new Set(
@@ -160,7 +162,7 @@ const expectedTransactionPurposes = (
   if (plan.kind === "create2-deploy") {
     return requiredRoles.has("contract") ? ["deploy-contract"] : [];
   }
-  if (plan.kind === "uups-placeholder-deploy") {
+  if (plan.kind === "uups-placeholder-deploy" || plan.kind === "transparent-deploy") {
     if (!requiredRoles.has("proxy")) {
       if (requiredRoles.has("implementation")) {
         throw new Error(
@@ -172,7 +174,7 @@ const expectedTransactionPurposes = (
     return [
       ...(requiredRoles.has("implementation") ? ["deploy-implementation" as const] : []),
       "deploy-proxy",
-      "upgrade-proxy",
+      ...(plan.kind === "uups-placeholder-deploy" ? ["upgrade-proxy" as const] : []),
     ];
   }
   return [
@@ -185,8 +187,9 @@ const assertPlanMatchesRequest = async (
   hre: GateToolPreparationHre,
   request: GateToolPreparationRequestV1,
   rawPlan: unknown,
+  validation?: WorkflowValidationPort,
 ): Promise<GateToolPreparationPlanV1> => {
-  const plan = normalizePreparationPlan(rawPlan);
+  const plan = normalizePreparationPlan(validation ? validation.preparation.data(rawPlan) : rawPlan);
   const provider = (hre as GateToolPreparationHre & {
     ethers?: { provider?: { getNetwork(): Promise<{ chainId: bigint | number | string }> } };
   }).ethers?.provider;
@@ -214,20 +217,28 @@ const assertPlanMatchesRequest = async (
   ) {
     throw new Error("GateTool plan transaction order does not match its deployment evidence");
   }
+  await validation?.preparationPlan(request, plan);
   return plan;
 };
 
 export const prepareGateToolWorkflow = async (
   options: PrepareGateToolWorkflowOptions,
 ): Promise<PreparedGateToolWorkflow> => {
+  if (!options.hre) throw new Error("GateTool requires an explicit Hardhat runtime");
   if (!SAFE_FILE_ID.test(options.evidenceName)) {
     throw new Error(`GateTool evidenceName must match ${SAFE_FILE_ID}`);
   }
-  const request = normalizePreparationRequest(options.request);
+  const request = normalizePreparationRequest(options.validation ? options.validation.preparation.data(options.request) : options.request);
   const runtime = pinGateToolReadBlockTag(
-    options.hre ?? hardhat as unknown as GateToolPreparationHre,
+    options.hre,
     options.readBlockTag,
   );
+  if (options.expected) {
+    const expectedRequest = normalizePreparationRequest(options.validation ? options.validation.preparation.data(options.expected.request) : options.expected.request);
+    if (canonicalPreparationJson(expectedRequest) !== canonicalPreparationJson(request)) throw new Error("Expected GateTool request differs from replay");
+    const plan = await assertPlanMatchesRequest(runtime, request, options.expected.plan, options.validation);
+    return { ...options.expected, request, plan };
+  }
   const evidenceDir = confinedPath(options.root, options.evidenceDir, "GateTool evidence directory");
   const requestPath = path.join(evidenceDir, `${options.evidenceName}-request.json`);
   const planPath = path.join(evidenceDir, `${options.evidenceName}-plan.json`);
@@ -248,13 +259,14 @@ export const prepareGateToolWorkflow = async (
       runtime,
       request,
       readRegularJson(planPath, options.root, "GateTool plan evidence"),
+      options.validation,
     );
     return { request, requestPath, plan, planPath };
   }
 
+  const prepared = await prepareWorkflow(runtime, request, options.validation?.preparation);
+  const plan = await assertPlanMatchesRequest(runtime, request, prepared, options.validation);
   writeCanonicalJsonAtomic(requestPath, request, options.root);
-  const prepared = await prepareWorkflow(runtime, request);
-  const plan = await assertPlanMatchesRequest(runtime, request, prepared);
   writePreparationPlanAtomic(planPath, plan, options.root);
 
   return { request, requestPath, plan, planPath };

package/runtime/workflow/lib/gateToolSync.ts

@@ -1,7 +1,6 @@
 import crypto from "crypto";
 import fs from "fs";
 import path from "path";
-import hardhat from "../../projectHardhat";
 import { syncWithHre } from "gate-evm-tools/sync";
 import { writeJsonFile } from "./config";
 
@@ -21,11 +20,14 @@ export interface SyncGateToolUupsOptions {
   target: string;
   manifestDir: string;
   proxy: string;
+  proxyKind?: "uups" | "transparent";
+  proxyAdminAddress?: string;
+  proxyAdminOwner?: string;
   implementation: string;
   contract: string;
   constructorArgs: unknown[];
   transactionHash: string;
-  hre?: GateToolSyncHre;
+  hre: GateToolSyncHre;
 }
 
 const SAFE_FILE_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,199}$/;
@@ -164,6 +166,9 @@ const validateEvidenceIdentity = (
     || raw.scheme !== options.scheme
     || raw.network !== options.network
     || raw.target !== options.target
+    || raw.proxyKind !== options.proxyKind
+    || raw.proxyAdminAddress !== options.proxyAdminAddress
+    || raw.proxyAdminOwner !== options.proxyAdminOwner
     || raw.manifestDir !== options.manifestDir
     || raw.contract !== options.contract
     || JSON.stringify(raw.constructorArgs) !== JSON.stringify(options.constructorArgs)
@@ -240,6 +245,7 @@ const buildSyncEvidence = (
   network: options.network,
   target: options.target,
   manifestDir: options.manifestDir,
+  ...(options.proxyKind?{proxyKind:options.proxyKind,proxyAdminAddress:options.proxyAdminAddress,proxyAdminOwner:options.proxyAdminOwner}:{}),
   proxy: options.proxy.toLowerCase(),
   implementation: options.implementation.toLowerCase(),
   contract: options.contract,
@@ -254,6 +260,7 @@ const buildSyncEvidence = (
 export const syncGateToolUups = async (
   options: SyncGateToolUupsOptions,
 ): Promise<GateToolSyncEvidence> => {
+  if (!options.hre) throw new Error("GateTool requires an explicit Hardhat runtime");
   if (!SAFE_FILE_ID.test(options.evidenceName)) {
     throw new Error(`GateTool sync evidenceName must match ${SAFE_FILE_ID}`);
   }
@@ -335,12 +342,13 @@ export const syncGateToolUups = async (
     network: options.network,
     target: options.target,
     proxy: options.proxy,
+    ...(options.proxyKind?{proxyKind:options.proxyKind,proxyAdminAddress:options.proxyAdminAddress,proxyAdminOwner:options.proxyAdminOwner}:{}),
     contract: options.contract,
     constructorArgs: options.constructorArgs,
     ...(options.scheme === "evm"
       ? { skipTxHash: true }
       : { transactionHash: options.transactionHash }),
-  }, options.hre ?? hardhat, options.root), "GateTool sync result");
+  }, options.hre, options.root), "GateTool sync result");
   const returnedProxy = typeof rawResult.proxyAddress === "string"
     ? rawResult.proxyAddress
     : stringField(rawResult, "proxy");

package/runtime/workflow/lib/operationNames.ts

@@ -0,0 +1,32 @@
+import type { WorkflowStep } from "./parameters";
+export const validateDeploySaveAs = (steps: WorkflowStep[]): void => {
+  const seen = new Set<string>();
+
+  for (const step of steps) {
+    if (step.kind !== "deploy") continue;
+
+    const saveAs = typeof step.saveAs === "string" ? step.saveAs.trim() : "";
+    if (!saveAs) {
+      throw new Error(`Deploy step ${step.id} requires saveAs`);
+    }
+    if (saveAs.includes(":")) {
+      throw new Error(`Deploy step ${step.id} saveAs "${saveAs}" must not contain ":"`);
+    }
+    if (seen.has(saveAs)) {
+      throw new Error(`Duplicate deploy saveAs "${saveAs}"`);
+    }
+    seen.add(saveAs);
+  }
+};
+
+export const deploymentInstanceId = (instanceId: string): string => {
+  const normalizedInstanceId = instanceId.trim();
+  if (!normalizedInstanceId) {
+    throw new Error("Deployment saveAs must not be empty");
+  }
+  if (normalizedInstanceId.includes(":")) {
+    throw new Error(`Deployment saveAs "${normalizedInstanceId}" must not contain ":"`);
+  }
+  return normalizedInstanceId;
+};
+

package/runtime/workflow/lib/parameters.ts

@@ -77,25 +77,8 @@ export const validateWorkflowStepIds = (steps: WorkflowStep[]): void => {
   }
 };
 
-export const validateDeploySaveAs = (steps: WorkflowStep[]): void => {
-  const seen = new Set<string>();
-
-  for (const step of steps) {
-    if (step.kind !== "deploy") continue;
-
-    const saveAs = typeof step.saveAs === "string" ? step.saveAs.trim() : "";
-    if (!saveAs) {
-      throw new Error(`Deploy step ${step.id} requires saveAs`);
-    }
-    if (saveAs.includes(":")) {
-      throw new Error(`Deploy step ${step.id} saveAs "${saveAs}" must not contain ":"`);
-    }
-    if (seen.has(saveAs)) {
-      throw new Error(`Duplicate deploy saveAs "${saveAs}"`);
-    }
-    seen.add(saveAs);
-  }
-};
+export { validateDeploySaveAs } from "./operationNames";
+import { validateDeploySaveAs } from "./operationNames";
 
 export const validateWorkflowStepKinds = (steps: WorkflowStep[]): void => {
   for (const step of steps) {
@@ -263,6 +246,10 @@ export const validateDeployCreate2Strategy = (steps: WorkflowStep[]): void => {
     }
 
     if (step.proxy !== undefined) {
+      if(asObject(step.proxy).kind === "transparent") {
+        if(step.upgradeableStrategy!=="transparent-proxy"||step.firstUpgrade!==undefined)throw new Error(`Deploy step ${step.id} requires transparent-proxy strategy without firstUpgrade`);
+        continue;
+      }
       if (step.upgradeableStrategy !== "uups-placeholder-proxy") {
         throw new Error(`Deploy step ${step.id} requires upgradeableStrategy: uups-placeholder-proxy`);
       }
@@ -386,7 +373,7 @@ const readPath = (source: Record<string, unknown>, pathExpression: string): unkn
   let current: unknown = source;
 
   for (const part of parts) {
-    if (typeof current !== "object" || current === null || !(part in current)) {
+    if (typeof current !== "object" || current === null || !Object.hasOwn(current, part)) {
       throw new Error(`Reference not found: ${pathExpression}`);
     }
     current = (current as Record<string, unknown>)[part];
@@ -412,7 +399,7 @@ export const resolveValue = (value: unknown, context: ResolveContext): unknown =
 
   if (typeof value === "object" && value !== null) {
     const objectValue = value as Record<string, unknown>;
-    if (typeof objectValue.$ref === "string") {
+    if (Object.hasOwn(objectValue, "$ref") && typeof objectValue.$ref === "string") {
       const ref = objectValue.$ref;
       if (ref.startsWith("state.")) {
         return context.state.get(ref.slice("state.".length));

package/runtime/workflow/lib/pendingDeploymentReuse.ts

@@ -1,12 +1,11 @@
+import { assertPendingUupsPreparation, assertPendingUupsCurrentState, planDeployment, sameAddress } from "./pendingUupsBinding";
 import fs from "fs";
 import path from "path";
 import type { Provider } from "ethers";
 import {
   canonicalPreparationJson,
-  hashPreparationRequest,
   normalizePreparationPlan,
   normalizePreparationRequest,
-  type GateToolPreparationPlanV1,
 } from "gate-evm-tools/workflow";
 import { readJsonFile } from "./config";
 import {
@@ -18,7 +17,6 @@ import {
   type DeploymentChange,
   type PendingDeploymentReuseEvidence,
 } from "./deploymentRecords";
-import { getERC1967Implementation } from "./erc1967";
 import { loadReleaseExecutionPlan } from "./executionPlan";
 import { readParameterLockExecution } from "./lock";
 import { loadOperatorExecutionResult } from "./operatorExecution";
@@ -55,12 +53,6 @@ const isRecord = (value: unknown): value is Record<string, unknown> => (
   !!value && typeof value === "object" && !Array.isArray(value)
 );
 
-const sameAddress = (left: unknown, right: unknown): boolean => (
-  typeof left === "string"
-  && typeof right === "string"
-  && left.toLowerCase() === right.toLowerCase()
-);
-
 const sameFingerprint = (left: ReleaseFingerprint, right: ReleaseFingerprint): boolean => (
   left.manifestHash === right.manifestHash
   && left.artifactHash === right.artifactHash
@@ -90,17 +82,6 @@ const pendingCandidateFiles = (root: string): string[] => fs.readdirSync(root)
   .filter((name) => /^contractInfo\.pending\.[A-Za-z0-9][A-Za-z0-9_-]{0,199}\.json$/.test(name))
   .map((name) => path.join(root, name));
 
-const planDeployment = (
-  plan: GateToolPreparationPlanV1,
-  role: "implementation" | "proxy",
-) => {
-  const matches = plan.deployments.filter((deployment) => deployment.role === role);
-  if (matches.length !== 1) {
-    throw new Error(`GateTool plan must contain exactly one ${role} deployment`);
-  }
-  return matches[0];
-};
-
 const assertSuccessfulVerification = (
   input: PendingUupsReuseInput,
   executionId: string,
@@ -283,28 +264,8 @@ const verifyCandidate = async (
   ));
   const implementation = planDeployment(plan, "implementation");
   const proxy = planDeployment(plan, "proxy");
-  if (
-    plan.kind !== "uups-placeholder-deploy"
-    || plan.scheme !== input.scheme
-    || plan.network !== input.network
-    || plan.target !== input.network
-    || request.kind !== "uups-placeholder-deploy"
-    || request.scheme !== input.scheme
-    || request.network !== input.network
-    || request.target !== input.network
-    || hashPreparationRequest(request) !== plan.requestHash
-    || !sameAddress(request.factory, input.factory)
-    || request.proxySalt.toLowerCase() !== input.proxySalt.toLowerCase()
-    || request.implementationSalt.toLowerCase() !== change.implementationSalt!.toLowerCase()
-    || !sameAddress(request.placeholderImplementation, input.placeholderImplementationAddress)
-    || !sameAddress(proxy.address, change.address)
-    || proxy.salt.toLowerCase() !== input.proxySalt.toLowerCase()
-    || !sameAddress(implementation.address, change.implementationAddress)
-    || implementation.salt.toLowerCase() !== change.implementationSalt!.toLowerCase()
-    || !/^[0-9a-f]{64}$/.test(plan.artifact.digest)
-  ) {
-    throw new Error("Pending GateTool evidence does not match the current UUPS deployment");
-  }
+  if (plan.network !== input.network || request.network !== input.network) throw new Error("Pending GateTool network differs from the legacy target");
+  assertPendingUupsPreparation(input, change, request, plan);
 
   const executionPlan = loadReleaseExecutionPlan({
     root: input.root,
@@ -344,20 +305,7 @@ const verifyCandidate = async (
     }
   }
 
-  const proxyCode = await input.provider.getCode(proxy.address, input.blockTag);
-  const implementationCode = await input.provider.getCode(implementation.address, input.blockTag);
-  const currentImplementation = await getERC1967Implementation(
-    input.provider,
-    proxy.address,
-    input.blockTag,
-  );
-  if (
-    !proxyCode || proxyCode === "0x"
-    || !implementationCode || implementationCode === "0x"
-    || !sameAddress(currentImplementation, implementation.address)
-  ) {
-    throw new Error("Pending deployment does not match current on-chain UUPS state");
-  }
+  await assertPendingUupsCurrentState(input, proxy.address, implementation.address);
 
   const deploymentRecordPath = path.join(
     input.taskDir,

package/runtime/workflow/lib/pendingUupsBinding.ts

@@ -0,0 +1,43 @@
+import type { Provider } from 'ethers';
+import { hashPreparationRequest, type GateToolPreparationPlanV1, type GateToolPreparationRequestV1 } from 'gate-evm-tools/workflow';
+import type { DeploymentChange, PendingDeploymentReuseEvidence } from './deploymentRecords';
+import { getERC1967Implementation } from './erc1967';
+export interface PendingUupsBindingInput {
+  taskId: string; network: string; stepId: string; instanceId: string; actualContract: string;
+  contractInfoKey: string; scheme: 'evm' | 'zksync-eravm'; factory: string; multicall: string;
+  proxySalt: string; expectedAddress?: string; placeholderImplementationAddress: string;
+  provider: Pick<Provider, 'getCode' | 'getStorage'>; blockTag?: number;
+}
+export interface PendingReuseBinding { executionId: string; target: string; planHash: string; artifactDigest: string; observationIds: string[] }
+export interface PendingUupsResolution {
+  implementationAddress: string; implementationSalt: string; proxyAddress: string; artifactDigest: string;
+  legacyEvidence?: PendingDeploymentReuseEvidence;
+  binding?: PendingReuseBinding;
+}
+export interface PendingUupsResolverPort { resolve(input: PendingUupsBindingInput): Promise<PendingUupsResolution | undefined> }
+export const sameAddress = (left: unknown, right: unknown): boolean => typeof left === 'string' && typeof right === 'string' && left.toLowerCase() === right.toLowerCase();
+export function planDeployment(plan: GateToolPreparationPlanV1, role: 'implementation' | 'proxy') {
+  const matches = plan.deployments.filter(d => d.role === role);
+  if (matches.length !== 1) throw new Error(`GateTool plan must contain exactly one ${role} deployment`);
+  return matches[0];
+}
+/** Common semantic predicate; no lock, filesystem, finalSimulation or recorder lifecycle. */
+export function assertPendingUupsPreparation(input: PendingUupsBindingInput, change: DeploymentChange, request: GateToolPreparationRequestV1, plan: GateToolPreparationPlanV1): void {
+  const implementation = planDeployment(plan, 'implementation'), proxy = planDeployment(plan, 'proxy');
+  if (change.stepId !== input.stepId || change.instanceId !== input.instanceId || change.kind !== 'deploy' || change.actualContract !== input.actualContract || change.contractInfoKey !== input.contractInfoKey || change.strategy !== 'create2' || change.proxyKind !== 'uups'
+    || !sameAddress(change.factory, input.factory) || !sameAddress(change.multicall, input.multicall) || change.salt?.toLowerCase() !== input.proxySalt.toLowerCase() || !sameAddress(change.placeholderImplementationAddress, input.placeholderImplementationAddress)
+    || (input.expectedAddress && !sameAddress(input.expectedAddress, proxy.address))
+    || plan.kind !== 'uups-placeholder-deploy' || plan.scheme !== input.scheme || plan.target !== input.network
+    || request.kind !== 'uups-placeholder-deploy' || request.scheme !== input.scheme || request.target !== input.network
+    || request.network !== plan.network || plan.contract !== request.contract || plan.artifact.contractName !== input.actualContract
+    || hashPreparationRequest(request) !== plan.requestHash || !sameAddress(request.factory, input.factory)
+    || request.proxySalt.toLowerCase() !== input.proxySalt.toLowerCase() || request.implementationSalt.toLowerCase() !== change.implementationSalt?.toLowerCase()
+    || !sameAddress(request.placeholderImplementation, input.placeholderImplementationAddress)
+    || !sameAddress(proxy.address, change.address ?? change.predictedAddress) || proxy.salt.toLowerCase() !== input.proxySalt.toLowerCase()
+    || !sameAddress(implementation.address, change.implementationAddress) || implementation.salt.toLowerCase() !== change.implementationSalt?.toLowerCase()
+    || !/^[0-9a-f]{64}$/.test(plan.artifact.digest)) throw new Error('Pending GateTool evidence does not match the current UUPS deployment');
+}
+export async function assertPendingUupsCurrentState(input: Pick<PendingUupsBindingInput, 'provider' | 'blockTag'>, proxy: string, implementation: string): Promise<void> {
+  const [proxyCode, implementationCode, current] = await Promise.all([input.provider.getCode(proxy, input.blockTag), input.provider.getCode(implementation, input.blockTag), getERC1967Implementation(input.provider, proxy, input.blockTag)]);
+  if (!proxyCode || proxyCode === '0x' || !implementationCode || implementationCode === '0x' || !sameAddress(current, implementation)) throw new Error('Pending deployment does not match current on-chain UUPS state');
+}