gate-evm-tools 1.0.28 → 1.2.0

package/runtime/workflow/steps/upgrade.ts

@@ -1,6 +1,8 @@
+import { resolveWorkflowValue } from '../lib/validation';
+import { recordPreparedDeployment } from "../lib/preparationEvidence";
 import { CONTROLLED_MULTICALL_AUTHORITY_ABI } from "../lib/controlledMulticallAbi";
 import { isAddress } from "ethers";
-import { ethers, network } from "../../projectHardhat";
+import {transparentAdminAddress, verifyTransparentAdmin, PROXY_ADMIN_INTERFACE} from "gate-evm-tools/workflow";
 import path from "path";
 import type {
   GateToolDeploymentPlan,
@@ -23,27 +25,21 @@ 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 { 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 type { WorkflowContext } from "../lib/context";
+import { impersonateLocalForkSigner } from "../lib/runtime";
 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,
-});
+): unknown => resolveWorkflowValue(context, value);
 
 const resolveObject = (
   context: WorkflowContext,
@@ -80,12 +76,18 @@ const proxyReference = (
   contractInfoKey: string;
   proxy: ProxyOptions;
 } => {
-  const proxyObject = resolveObject(context, step.proxy);
-  const rawProxy = stringField(proxyObject, "address")
+  const resolvedProxy = step.proxy === undefined ? undefined : resolveInContext(context, step.proxy);
+  const proxyObject = resolvedProxy && typeof resolvedProxy === "object" && !Array.isArray(resolvedProxy)
+    ? resolvedProxy as Record<string, unknown>
+    : {};
+  let 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);
+    || (typeof resolvedProxy === "string" ? resolvedProxy : undefined);
+  if (!rawProxy) {
+    const resolvedAddress = step.address === undefined ? undefined : resolveInContext(context, step.address);
+    rawProxy = typeof resolvedAddress === "string" ? resolvedAddress : undefined;
+  }
   if (!rawProxy) throw new Error(`Step ${step.id} requires proxy address or deployment name`);
 
   const registryDeployment = isAddress(rawProxy)
@@ -107,6 +109,7 @@ const proxyReference = (
     proxy: {
       kind: stringField(proxyObject, "kind")
         || (typeof step.proxyKind === "string" ? step.proxyKind : "uups"),
+      adminOwner: stringField(proxyObject, "adminOwner"),
       initializer: proxyObject.initializer === false
         ? false
         : stringField(proxyObject, "initializer"),
@@ -163,13 +166,14 @@ const transactionEnvelope = (transaction: GateToolTransactionPlan) => ({
 });
 
 const assertUupsChainState = async (
+  context: WorkflowContext,
   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),
+    context.runtime.hre.ethers.provider.getCode(proxy),
+    context.runtime.hre.ethers.provider.getCode(implementation),
+    getERC1967Implementation(context.runtime.hre.ethers.provider, proxy),
   ]);
   if (!proxyCode || proxyCode === "0x") {
     throw new Error(`UUPS proxy is missing deployed code at ${proxy}`);
@@ -196,21 +200,37 @@ export const runUpgradeStep = async (
   }
   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 transparent=proxy.proxy.kind === "transparent";
+  if (!transparent && (proxy.proxy.kind || "uups") !== "uups") throw new Error(`Upgrade step ${step.id} has unsupported proxy kind`);
+  if(transparent&&!proxy.proxy.adminOwner)throw Error("Transparent upgrade requires explicit proxy.adminOwner");
+  const sameFork = context.preparations?.assertUpgradeBaseline(proxy.proxyAddress) === true;
+  if (sameFork) {
+    if (context.mode !== 'simulate' || !context.validation?.sameForkUpgrade) throw new Error('Same-fork upgrade requires owned local-fork validation');
+    await context.validation.sameForkUpgrade(proxy.proxyAddress);
+  } else if (context.mode === "simulate") {
+    await assertSimulationUupsSourceState(context.runtime.hre.ethers.provider, context.simulation, proxy.proxyAddress);
   }
   const call = upgradeCall(context, step);
   const actualContract = actualContractName(contractName);
-  const targetCreate2 = context.target.create2;
-  const targetMulticall = context.target.multicall;
+  const targetCreate2 = context.validation
+    ? context.validation.create2Fields(
+        resolveInContext(context, context.target.create2 === undefined ? {} : context.target.create2),
+        "target",
+      )
+    : context.target.create2;
+  const targetMulticall = context.validation
+    ? context.validation.create2Fields(
+        resolveInContext(context, context.target.multicall === undefined ? {} : context.target.multicall),
+        "multicall",
+      )
+    : context.target.multicall;
+  const factory = targetCreate2?.factory;
+  const controlledMulticall = targetMulticall?.controlledMulticall;
   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) {
+  if (typeof factory !== "string" || !factory || typeof controlledMulticall !== "string" || !controlledMulticall) {
     throw new Error(
       `Upgrade step ${step.id} requires target create2 factory and controlledMulticall`,
     );
@@ -221,20 +241,20 @@ export const runUpgradeStep = async (
     `Step ${step.id} constructorArgs`,
   );
   const implementationSalt = deriveImplementationSalt(
-    context.executionId,
+    context.bindings?.derivationSeed ?? context.executionId,
     contractName,
     proxy.proxyAddress,
   );
+  if(transparent&&scheme!=="evm")throw Error("Transparent upgrade requires ordinary EVM");
   const request: GateToolPreparationRequestV1 = {
     version: 1,
-    kind: "uups-upgrade",
+    ...(transparent?{kind:"transparent-upgrade" as const,proxyKind:"transparent" as const,proxyAdmin:transparentAdminAddress(proxy.proxyAddress),proxyAdminOwner:proxy.proxy.adminOwner!}:{kind:"uups-upgrade" as const,proxyKind:"uups" as const}),
     scheme,
-    network: network.name,
+    network: context.runtime.hre.network.name,
     target: context.targetId,
     contract: contractName,
     constructorArgs,
-    factory: targetCreate2.factory,
-    proxyKind: "uups",
+    factory,
     proxy: proxy.proxyAddress,
     implementationSalt,
     ...(proxy.proxy.unsafeAllow ? { unsafeAllow: proxy.proxy.unsafeAllow } : {}),
@@ -249,10 +269,13 @@ export const runUpgradeStep = async (
     context.mode,
   );
   const prepared = await prepareGateToolWorkflow({
+    hre: context.runtime.hre,
+    validation: context.validation,
     root: context.root,
     evidenceDir: gateToolEvidenceDir,
     evidenceName: step.id,
     request,
+    expected: context.preparations?.expected(step.id, request),
     readBlockTag: context.mode === "simulate"
       ? context.simulation.snapshot?.blockNumber
       : undefined,
@@ -270,38 +293,35 @@ export const runUpgradeStep = async (
     actualContract,
     contractInfoKey: proxy.contractInfoKey,
     strategy: "gate-tool",
-    proxyKind: "uups",
+    proxyKind: transparent?"transparent":"uups",
+    ...(transparent?{proxyAdminAddress:prepared.plan.proxyAdmin!.address,proxyAdminOwner:prepared.plan.proxyAdmin!.owner}:{}),
     proxyAddress: proxy.proxyAddress,
     implementationAddress: implementation.address,
     implementationSalt,
     constructorArgs,
-    factory: targetCreate2.factory,
+    factory,
+    multicall: controlledMulticall,
     gateTool: {
       outputPath: gateToolPlan,
       data: prepared.plan as unknown as Record<string, unknown>,
     },
   };
-  if (context.parameterLockExecutionId) {
-    recordParameterLockImplementationSalts(
-      context.taskDir,
-      context.parameterLockExecutionId,
-      { [`${step.id}.implementation`]: implementationSalt },
-    );
-  }
+  context.bindings?.recordOrAssertDerivedValue(`${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);
+  recordPreparedDeployment(context, preparedChange, prepared, [`${step.id}.implementation`]);
 
-  const proxyContract = await ethers.getContractAt(
-    String(step.abi || contractName),
-    proxy.proxyAddress,
+  const proxyContract = await context.runtime.hre.ethers.getContractAt(
+    transparent?[...PROXY_ADMIN_INTERFACE.fragments]:String(step.abi || contractName),
+    transparent?prepared.plan.proxyAdmin!.address:proxy.proxyAddress,
     context.signer,
   );
   const upgradeAuthority = await decideAuthority(
     proxyContract,
-    context.target,
+    transparent?{...context.target,admin:proxy.proxy.adminOwner}:context.target,
     context.signerAddress,
   );
   if (
@@ -314,7 +334,7 @@ export const runUpgradeStep = async (
 
   const implementationMulticall = implementationCall
     ? prepareControlledMulticallTransaction(
-        targetMulticall.controlledMulticall,
+        controlledMulticall,
         [{
           target: implementationCall.to,
           value: implementationCall.value,
@@ -327,9 +347,9 @@ export const runUpgradeStep = async (
       )
     : undefined;
   const multicall = implementationMulticall
-    ? await ethers.getContractAt(
+    ? await context.runtime.hre.ethers.getContractAt(
         CONTROLLED_MULTICALL_AUTHORITY_ABI,
-        targetMulticall.controlledMulticall,
+        controlledMulticall,
         context.signer,
       )
     : undefined;
@@ -340,7 +360,7 @@ export const runUpgradeStep = async (
           factoryCallers: (factoryAddress: string, caller: string) => Promise<boolean>;
           owner?: () => Promise<unknown>;
         },
-        targetCreate2.factory,
+        factory,
         context.target,
         context.signerAddress,
       )
@@ -381,17 +401,20 @@ export const runUpgradeStep = async (
       transactionEnvelope(proxyUpgradeCall),
       context.signer,
     );
-    await assertUupsChainState(proxy.proxyAddress, implementation.address);
+    await assertUupsChainState(context, proxy.proxyAddress, implementation.address);
+    if(transparent)await verifyTransparentAdmin({hre:context.runtime.hre as any,proxy:proxy.proxyAddress,admin:prepared.plan.proxyAdmin!.address,owner:prepared.plan.proxyAdmin!.owner});
     const gateToolSync = context.mode === "execute"
       ? await syncGateToolUups({
+          hre: context.runtime.hre,
           root: context.root,
           evidenceDir: gateToolEvidenceDir,
           evidenceName: step.id,
           scheme: prepared.plan.scheme,
-          network: network.name,
+          network: context.runtime.hre.network.name,
           target: context.targetId,
           manifestDir: context.target.openzeppelin.manifestDir,
           proxy: proxy.proxyAddress,
+          ...(transparent?{proxyKind:"transparent" as const,proxyAdminAddress:prepared.plan.proxyAdmin!.address,proxyAdminOwner:prepared.plan.proxyAdmin!.owner}:{}),
           implementation: implementation.address,
           contract: actualContract,
           constructorArgs,
@@ -457,6 +480,7 @@ export const runUpgradeStep = async (
         ? {}
         : { factoryDeps: implementationMulticall.factoryDeps }),
     });
+    context.preparations?.bind(step.id, { transactionId: planned.transactionId, gateToolTransactionIds: [implementationCall!.id], kind: "multicall" });
     implementationTransactionId = planned.transactionId;
     implementationExternal = planned.route === "external";
     if (planned.executionAction === "replay") {
@@ -476,12 +500,13 @@ export const runUpgradeStep = async (
       });
     } else {
       const selectedSigner = planned.route === "external"
-        ? await impersonateWorkflowSimulationSigner(planned.executor)
+        ? await impersonateLocalForkSigner(context.runtime, planned.executor)
         : context.signer;
       const tx = await sendPreparedControlledMulticallTransaction(
         implementationMulticall,
         selectedSigner,
       );
+      context.transactionObserver?.record({ transactionId: planned.transactionId, transactionHash: tx.hash });
       implementationTxHash = tx.hash;
       if (context.mode === "execute" && planned.route === "operator") {
         context.operatorReceipts.push({
@@ -509,6 +534,7 @@ export const runUpgradeStep = async (
       ? {}
       : { factoryDeps: upgradeEnvelope.factoryDeps }),
   });
+  context.preparations?.bind(step.id, { transactionId: upgradeTransaction.transactionId, gateToolTransactionIds: [proxyUpgradeCall.id], kind: "direct" });
   if (context.mode === "execute") {
     recorder?.bindProxyTransaction(step.id, upgradeTransaction.transactionId);
   }
@@ -523,16 +549,17 @@ export const runUpgradeStep = async (
       value: upgradeTransaction.value,
       data: upgradeTransaction.data,
       operation: upgradeTransaction.operation,
-      method: "upgradeToAndCall",
-      args: [implementation.address],
+      method: transparent ? "upgradeAndCall" : "upgradeToAndCall",
+      args: transparent ? [proxy.proxyAddress, implementation.address, PROXY_ADMIN_INTERFACE.decodeFunctionData("upgradeAndCall", proxyUpgradeCall.data)[2]] : [implementation.address],
       executor: upgradeTransaction.executor,
       reason: upgradeAuthority.reason,
     });
   } else {
     const selectedSigner = upgradeTransaction.route === "external"
-      ? await impersonateWorkflowSimulationSigner(upgradeTransaction.executor)
+      ? await impersonateLocalForkSigner(context.runtime, upgradeTransaction.executor)
       : context.signer;
     const tx = await sendPreparedWorkflowTransaction(upgradeEnvelope, selectedSigner);
+    context.transactionObserver?.record({ transactionId: upgradeTransaction.transactionId, transactionHash: tx.hash });
     upgradeTxHash = tx.hash;
     if (context.mode === "execute" && upgradeTransaction.route === "operator") {
       context.operatorReceipts.push({
@@ -546,16 +573,19 @@ export const runUpgradeStep = async (
     && !implementationExternal
     && upgradeTransaction.route === "operator"
   ) {
-    await assertUupsChainState(proxy.proxyAddress, implementation.address);
+    await assertUupsChainState(context, proxy.proxyAddress, implementation.address);
+    if(transparent)await verifyTransparentAdmin({hre:context.runtime.hre as any,proxy:proxy.proxyAddress,admin:prepared.plan.proxyAdmin!.address,owner:prepared.plan.proxyAdmin!.owner});
     const gateToolSync = await syncGateToolUups({
+      hre: context.runtime.hre,
       root: context.root,
       evidenceDir: gateToolEvidenceDir,
       evidenceName: step.id,
       scheme: prepared.plan.scheme,
-      network: network.name,
+      network: context.runtime.hre.network.name,
       target: context.targetId,
       manifestDir: context.target.openzeppelin.manifestDir,
       proxy: proxy.proxyAddress,
+      ...(transparent?{proxyKind:"transparent" as const,proxyAdminAddress:prepared.plan.proxyAdmin!.address,proxyAdminOwner:prepared.plan.proxyAdmin!.owner}:{}),
       implementation: implementation.address,
       contract: actualContract,
       constructorArgs,
@@ -568,7 +598,8 @@ export const runUpgradeStep = async (
       gateToolSync,
     });
   } else if (context.mode === "simulate") {
-    await assertUupsChainState(proxy.proxyAddress, implementation.address);
+    await assertUupsChainState(context, proxy.proxyAddress, implementation.address);
+    if(transparent)await verifyTransparentAdmin({hre:context.runtime.hre as any,proxy:proxy.proxyAddress,admin:prepared.plan.proxyAdmin!.address,owner:prepared.plan.proxyAdmin!.owner});
   }
   context.state.set(`${proxy.saveAs}Upgrade`, {
     proxyAddress: proxy.proxyAddress,

package/runtime/workflow/steps/view.ts

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

package/bin/workflow.cjs

@@ -1,19 +0,0 @@
-#!/usr/bin/env node
-const path = require('node:path');
-const fs = require('node:fs');
-const commands = {run:'cli', checkcode:'checkCode', 'checkcode-plan':'checkCodePlan', 'checkcode-finalize':'checkCodeFinalize', 'static-validate':'staticValidate', 'create2-hashes':'create2Hashes', 'release-finalize':'releaseFinalize', 'import-state':'importState', 'reconcile-external':'reconcileExternal', 'commit-contract-info':'commitContractInfo'};
-const args = process.argv.slice(2);
-if (!args.length || args[0] === '--help') {
- console.log('gate-workflow <'+[...Object.keys(commands),'migrate'].join('|')+'> [--project-root <path>] [existing workflow arguments]');
-} else {
- try {
-  const command=args.shift();
-  if (command !== 'migrate' && !Object.hasOwn(commands,command)) throw new Error('Unknown workflow command');
-  const at=args.indexOf('--project-root');
-  if(at>=0){if(!args[at+1]||args[at+1].startsWith('--'))throw new Error('--project-root requires a path');process.chdir(fs.realpathSync(args[at+1]));args.splice(at,2);}
-  if(!fs.existsSync(path.join(process.cwd(),'package.json')))throw new Error('Workflow requires a project root with package.json');
-  process.argv=[process.argv[0],process.argv[1],...args];
-  if(command === 'migrate') console.log(JSON.stringify(require('../dist-runtime/migrate.js').migrateTemplate(process.cwd(),args.includes('--apply')),null,2));
-  else require('../dist-runtime/workflow/'+commands[command]+'.js');
- } catch(error){console.error(error.message);process.exitCode=1;}
-}