gate-evm-tools 1.0.25 → 1.0.27

package/runtime/workflow/lib/pendingDeploymentReuse.ts

@@ -0,0 +1,428 @@
+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 {
+  validateContractInfoCandidate,
+  type ContractInfoCandidate,
+} from "./contractInfoCandidates";
+import {
+  loadDeploymentExecutionRecord,
+  type DeploymentChange,
+  type PendingDeploymentReuseEvidence,
+} from "./deploymentRecords";
+import { getERC1967Implementation } from "./erc1967";
+import { loadReleaseExecutionPlan } from "./executionPlan";
+import { readParameterLockExecution } from "./lock";
+import { loadOperatorExecutionResult } from "./operatorExecution";
+import type { ReleaseFingerprint } from "./release";
+
+interface PendingUupsReuseInput {
+  root: string;
+  taskDir: string;
+  taskId: string;
+  currentExecutionId: 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 ResolvedPendingUupsReuse {
+  implementationAddress: string;
+  implementationSalt: string;
+  proxyAddress: string;
+  evidence: PendingDeploymentReuseEvidence;
+}
+
+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
+  && left.parametersHash === right.parametersHash
+  && left.configHash === right.configHash
+);
+
+const relativePath = (root: string, filePath: string): string => {
+  const relative = path.relative(path.resolve(root), path.resolve(filePath));
+  if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw new Error("Pending deployment reuse evidence escapes the project root");
+  }
+  return relative.split(path.sep).join("/");
+};
+
+const confinedEvidencePath = (root: string, filePath: string): string => {
+  const resolved = path.resolve(root, filePath);
+  relativePath(root, resolved);
+  const stat = fs.lstatSync(resolved);
+  if (!stat.isFile() || stat.isSymbolicLink()) {
+    throw new Error("Pending deployment reuse evidence must be a regular file: " + filePath);
+  }
+  return resolved;
+};
+
+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,
+): string => {
+  const filePath = path.join(
+    input.taskDir,
+    "results",
+    input.network,
+    executionId,
+    "execute",
+    "verification.json",
+  );
+  const result = readJsonFile<unknown>(confinedEvidencePath(input.root, filePath));
+  if (!isRecord(result) || !Array.isArray(result.steps)) {
+    throw new Error("Execute verification evidence is invalid");
+  }
+  if (
+    result.taskId !== input.taskId
+    || result.target !== input.network
+    || result.executionId !== executionId
+    || result.mode !== "execute"
+    || result.steps.length === 0
+  ) {
+    throw new Error("Execute verification evidence identity or steps are invalid");
+  }
+  for (const [stepIndex, rawStep] of result.steps.entries()) {
+    if (!isRecord(rawStep) || !isRecord(rawStep.results)) {
+      throw new Error(`Execute verification step ${stepIndex} is invalid`);
+    }
+    for (const [checkId, rawCheck] of Object.entries(rawStep.results)) {
+      if (
+        !isRecord(rawCheck)
+        || JSON.stringify(rawCheck.actual) !== JSON.stringify(rawCheck.expected)
+      ) {
+        throw new Error(`Execute verification check ${checkId} did not succeed`);
+      }
+    }
+  }
+  return relativePath(input.root, filePath);
+};
+
+const assertExecutionResult = (
+  input: PendingUupsReuseInput,
+  executionId: string,
+  change: DeploymentChange,
+): string => {
+  const filePath = path.join(
+    input.taskDir,
+    "results",
+    input.network,
+    executionId,
+    "execute",
+    "execution.json",
+  );
+  const result = readJsonFile<unknown>(confinedEvidencePath(input.root, filePath));
+  if (!isRecord(result) || !Array.isArray(result.steps)) {
+    throw new Error("Execute result evidence is invalid");
+  }
+  const matching = result.steps.filter((rawStep) => (
+    isRecord(rawStep)
+    && rawStep.stepId === input.stepId
+    && sameAddress(rawStep.address, change.address)
+    && sameAddress(rawStep.implementationAddress, change.implementationAddress)
+  ));
+  if (
+    result.taskId !== input.taskId
+    || result.target !== input.network
+    || result.executionId !== executionId
+    || result.mode !== "execute"
+    || matching.length !== 1
+  ) {
+    throw new Error("Execute result does not prove the pending UUPS deployment");
+  }
+  return relativePath(input.root, filePath);
+};
+
+const assertCandidateIdentity = (
+  input: PendingUupsReuseInput,
+  candidate: ContractInfoCandidate,
+): DeploymentChange => {
+  if (
+    candidate.status !== "pending"
+    || candidate.deploymentId !== input.taskId
+    || candidate.network !== input.network
+  ) {
+    throw new Error("Pending candidate identity does not match this deployment task");
+  }
+  const replacements = candidate.replacements.filter((replacement) => (
+    replacement.network === input.network && replacement.instanceId === input.instanceId
+  ));
+  if (replacements.length !== 1) {
+    throw new Error("Pending candidate must contain exactly one matching replacement");
+  }
+  const replacement = replacements[0];
+  if (
+    replacement.candidateKey !== input.contractInfoKey
+    || (input.expectedAddress && !sameAddress(replacement.candidateAddress, input.expectedAddress))
+  ) {
+    throw new Error("Pending candidate replacement does not match the current deployment");
+  }
+  const record = loadDeploymentExecutionRecord({
+    taskDir: input.taskDir,
+    taskId: input.taskId,
+    network: input.network,
+    executionId: candidate.executionId,
+  });
+  const changes = record.changes.filter((change) => (
+    change.stepId === input.stepId && change.instanceId === input.instanceId
+  ));
+  if (
+    record.status !== "waiting_code_check"
+    || record.candidateStatus !== "pending"
+    || record.candidatePath !== `contractInfo.pending.${candidate.executionId}.json`
+    || changes.length !== 1
+  ) {
+    throw new Error("Pending deployment record is not waiting for CheckCode");
+  }
+  const change = changes[0];
+  if (
+    change.status !== "waiting_code_check"
+    || change.kind !== "deploy"
+    || change.actualContract !== input.actualContract
+    || change.contractInfoKey !== input.contractInfoKey
+    || change.strategy !== "create2"
+    || change.proxyKind !== "uups"
+    || !sameAddress(change.address, replacement.candidateAddress)
+    || !sameAddress(change.proxyAddress, replacement.candidateAddress)
+    || !sameAddress(change.factory, input.factory)
+    || !sameAddress(change.multicall, input.multicall)
+    || change.salt?.toLowerCase() !== input.proxySalt.toLowerCase()
+    || !sameAddress(
+      change.placeholderImplementationAddress,
+      input.placeholderImplementationAddress,
+    )
+    || typeof change.implementationSalt !== "string"
+    || !/^0x[0-9a-fA-F]{64}$/.test(change.implementationSalt)
+    || typeof change.implementationAddress !== "string"
+  ) {
+    throw new Error("Pending deployment change does not match the current UUPS release");
+  }
+  return change;
+};
+
+const verifyCandidate = async (
+  input: PendingUupsReuseInput,
+  candidatePath: string,
+  candidate: ContractInfoCandidate,
+): Promise<ResolvedPendingUupsReuse> => {
+  const change = assertCandidateIdentity(input, candidate);
+  const currentLock = readParameterLockExecution(input.taskDir, input.currentExecutionId);
+  const sourceLock = readParameterLockExecution(input.taskDir, candidate.executionId);
+  if (
+    !sameFingerprint(currentLock.releaseFingerprint, sourceLock.releaseFingerprint)
+    || sourceLock.finalSimulation.status !== "succeeded"
+    || !sourceLock.selectedStepIds.includes(input.stepId)
+    || sourceLock.target.network !== input.network
+    || sourceLock.target.create2Scheme !== input.scheme
+    || !sameAddress(sourceLock.target.create2Factory, input.factory)
+    || !sameAddress(sourceLock.target.controlledMulticall, input.multicall)
+    || !sameAddress(
+      sourceLock.target.uupsPlaceholderImplementation,
+      input.placeholderImplementationAddress,
+    )
+  ) {
+    throw new Error("Pending deployment parameter lock does not match the current release");
+  }
+
+  if (!isRecord(change.gateTool) || typeof change.gateTool.outputPath !== "string") {
+    throw new Error("Pending deployment is missing GateTool evidence");
+  }
+  const planPath = confinedEvidencePath(input.root, change.gateTool.outputPath);
+  const rawPlan = readJsonFile<unknown>(planPath);
+  const plan = normalizePreparationPlan(rawPlan);
+  if (canonicalPreparationJson(plan) !== canonicalPreparationJson(change.gateTool.data)) {
+    throw new Error("Pending deployment embedded GateTool plan differs from its evidence file");
+  }
+  const requestPath = path.join(path.dirname(planPath), `${input.stepId}-request.json`);
+  const request = normalizePreparationRequest(readJsonFile<unknown>(
+    confinedEvidencePath(input.root, requestPath),
+  ));
+  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");
+  }
+
+  const executionPlan = loadReleaseExecutionPlan({
+    root: input.root,
+    taskDir: input.taskDir,
+    target: input.network,
+    executionId: candidate.executionId,
+    expectedHash: sourceLock.finalSimulation.executionPlanHash,
+  });
+  const operatorTransactions = executionPlan.transactions.filter((transaction) => (
+    transaction.route === "operator"
+  ));
+  let operatorExecutionPath: string | undefined;
+  if (operatorTransactions.length > 0) {
+    const operatorResult = loadOperatorExecutionResult({ taskDir: input.taskDir, plan: executionPlan });
+    if (operatorResult.receipts.length !== operatorTransactions.length) {
+      throw new Error("Pending deployment operator execution is incomplete");
+    }
+    operatorExecutionPath = relativePath(input.root, path.join(
+      input.taskDir,
+      "results",
+      input.network,
+      candidate.executionId,
+      "operator-execution.json",
+    ));
+  }
+  if (
+    executionPlan.transactions.some((transaction) => transaction.route === "external")
+  ) {
+    const record = loadDeploymentExecutionRecord({
+      taskDir: input.taskDir,
+      taskId: input.taskId,
+      network: input.network,
+      executionId: candidate.executionId,
+    });
+    if (!isRecord(record.external?.reconciliation) || record.external?.reconciliation.status !== "reconciled") {
+      throw new Error("Pending deployment external execution is not reconciled");
+    }
+  }
+
+  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");
+  }
+
+  const deploymentRecordPath = path.join(
+    input.taskDir,
+    "results",
+    `${input.network}.${candidate.executionId}.deployment.json`,
+  );
+  return {
+    implementationAddress: implementation.address,
+    implementationSalt: implementation.salt,
+    proxyAddress: proxy.address,
+    evidence: {
+      status: "verified",
+      sourceExecutionId: candidate.executionId,
+      sourceCandidatePath: relativePath(input.root, candidatePath),
+      sourceDeploymentRecordPath: relativePath(input.root, deploymentRecordPath),
+      sourceExecutionPlanPath: relativePath(input.root, path.join(
+        input.taskDir,
+        "results",
+        input.network,
+        candidate.executionId,
+        "execution-plan.json",
+      )),
+      ...(operatorExecutionPath ? { sourceOperatorExecutionPath: operatorExecutionPath } : {}),
+      sourceExecutionResultPath: assertExecutionResult(input, candidate.executionId, change),
+      sourceVerificationPath: assertSuccessfulVerification(input, candidate.executionId),
+      releaseFingerprint: currentLock.releaseFingerprint,
+      artifactDigest: plan.artifact.digest,
+      proxyAddress: proxy.address,
+      implementationAddress: implementation.address,
+    },
+  };
+};
+
+export const resolvePendingUupsReuse = async (
+  input: PendingUupsReuseInput,
+): Promise<ResolvedPendingUupsReuse | undefined> => {
+  const conflicts: Array<{ path: string; candidate: ContractInfoCandidate }> = [];
+  for (const candidatePath of pendingCandidateFiles(input.root)) {
+    const candidate = validateContractInfoCandidate(readJsonFile<unknown>(candidatePath));
+    if (candidate.executionId === input.currentExecutionId || candidate.status !== "pending") continue;
+    if (candidate.replacements.some((replacement) => (
+      replacement.network === input.network && replacement.instanceId === input.instanceId
+    ))) {
+      conflicts.push({ path: candidatePath, candidate });
+    }
+  }
+  if (conflicts.length === 0) return undefined;
+
+  const verified: ResolvedPendingUupsReuse[] = [];
+  const failures: string[] = [];
+  for (const conflict of conflicts) {
+    try {
+      verified.push(await verifyCandidate(input, conflict.path, conflict.candidate));
+    } catch (error) {
+      failures.push(
+        `${path.basename(conflict.path)}: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
+  if (verified.length !== 1) {
+    throw new Error(
+      verified.length > 1
+        ? `Multiple trusted pending deployments match ${input.network}.${input.instanceId}`
+        : `Pending deployment for ${input.network}.${input.instanceId} cannot be reused: ${failures.join("; ")}`,
+    );
+  }
+  return verified[0];
+};

package/runtime/workflow/lib/proxy.ts

@@ -0,0 +1,45 @@
+import { keccak256, toUtf8Bytes } from "ethers";
+import { ethers } from "../../projectHardhat";
+import {
+  getERC1967Admin,
+  getERC1967Implementation,
+} from "./erc1967";
+
+export interface ProxyOptions {
+  kind?: string;
+  initializer?: string | false;
+  unsafeAllow?: string[];
+  constructorArgs?: unknown[];
+}
+
+export interface FirstUpgradeOptions {
+  contractName: string;
+  call?: {
+    fn: string;
+    args: unknown[];
+  };
+  constructorArgs?: unknown[];
+  unsafeAllow?: string[];
+}
+
+export const deriveImplementationSalt = (
+  executionId: string,
+  contractName: string,
+  scope: string,
+): string => keccak256(
+  toUtf8Bytes(`gateflow:${executionId}:${contractName}:${scope}`),
+);
+
+export const getImplementationAddress = async (
+  proxyAddress: string,
+): Promise<string> => {
+  const implementation = await getERC1967Implementation(ethers.provider, proxyAddress);
+  if (!implementation) {
+    throw new Error(`Proxy ${proxyAddress} has no ERC-1967 implementation`);
+  }
+  return implementation;
+};
+
+export const getProxyAdminAddress = async (
+  proxyAddress: string,
+): Promise<string | undefined> => getERC1967Admin(ethers.provider, proxyAddress);