gate-evm-tools 1.0.31 → 1.2.1

package/runtime/workflow/run.ts

@@ -130,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.`,
   );
 };
 

package/runtime/workflow/steps/deploy.ts

@@ -2,6 +2,7 @@ import { resolveWorkflowValue } from '../lib/validation';
 import { recordPreparedDeployment } from "../lib/preparationEvidence";
 import { CONTROLLED_MULTICALL_AUTHORITY_ABI } from "../lib/controlledMulticallAbi";
 import path from "path";
+import {verifyTransparentAdmin, transparentAdminAddress} from "gate-evm-tools/workflow";
 import type {
   GateToolDeploymentPlan,
   GateToolPreparationPlanV1,
@@ -79,6 +80,7 @@ const resolveProxyOptions = (
     options: {
       kind: typeof proxy.kind === "string" ? proxy.kind : undefined,
       initializer,
+      adminOwner: typeof proxy.adminOwner === "string" ? proxy.adminOwner : undefined,
       unsafeAllow: Array.isArray(proxy.unsafeAllow)
         ? proxy.unsafeAllow.map((item) => String(item))
         : undefined,
@@ -401,6 +403,46 @@ export const runDeployStep = async (
     throw new Error(`Deploy step ${step.id} requires an execution deployment recorder`);
   }
 
+  if (proxy?.options.kind === 'transparent') {
+    if(create2Options.scheme!=='evm'||step.upgradeableStrategy!=='transparent-proxy'||step.firstUpgrade!==undefined)throw Error('Transparent deployment requires EVM transparent-proxy strategy');
+    const adminOwner=proxy.options.adminOwner;
+    if(!adminOwner)throw Error('Transparent deployment requires explicit proxy.adminOwner');
+    if(proxy.options.initializer===undefined)throw Error('Transparent deployment requires explicit initializer method or false');
+    const actualContract=actualContractName(contractName),registryKey=contractInfoKey(saveAs,contractName);
+    const initialChange:DeploymentChange={stepId:step.id,kind:'deploy',instanceId:saveAs,actualContract,contractInfoKey:registryKey,strategy:'create2',proxyKind:'transparent',factory:create2Options.factory,multicall:create2Options.controlledMulticall,salt:create2Options.salt};
+    const existing=await applyExistingDeploymentPolicy(context,step,saveAs,initialChange,create2Options,true);
+    if(existing.completed){await verifyTransparentAdmin({hre:context.runtime.hre as any,proxy:existing.existingAddress!,admin:transparentAdminAddress(existing.existingAddress!),owner:adminOwner});return;}
+    const effective=existing.create2Options,implementationSalt=deriveImplementationSalt(context.bindings?.derivationSeed??context.executionId,contractName,effective.salt);
+    const request:GateToolPreparationRequestV1={version:1,kind:'transparent-deploy',scheme:'evm',network:context.runtime.hre.network.name,target:context.targetId,contract:contractName,
+      constructorArgs:proxy.options.constructorArgs??[],factory:effective.factory,proxyKind:'transparent',implementationSalt,proxySalt:effective.salt,proxyAdminOwner:adminOwner,
+      ...(proxy.options.unsafeAllow?{unsafeAllow:proxy.options.unsafeAllow}:{}),...(addressPolicy(effective)?{proxyAddressPolicy:addressPolicy(effective)}:{}),
+      ...(proxy.options.initializer===false?{}:{call:{method:proxy.options.initializer,args:resolveArray(context,step.args??[],`Step ${step.id} args`)}})};
+    const prepared=await prepareGateToolWorkflow({hre:context.runtime.hre,validation:context.validation,root:context.root,evidenceDir:gateToolEvidenceDir(context),evidenceName:step.id,request,
+      expected:context.preparations?.expected(step.id,request),readBlockTag:context.mode==='simulate'?context.simulation.snapshot?.blockNumber:undefined});
+    const implementation=deploymentForRole(prepared.plan,'implementation'),deployed=deploymentForRole(prepared.plan,'proxy'),admin=prepared.plan.proxyAdmin!;
+    if(existing.existingAddress?.toLowerCase()===deployed.address.toLowerCase())throw Error('Transparent redeploy predicted the existing address');
+    const change:DeploymentChange={...initialChange,salt:effective.salt,predictedAddress:deployed.address,implementationAddress:implementation.address,implementationSalt,
+      proxyAdminAddress:admin.address,proxyAdminOwner:admin.owner,constructorArgs:request.constructorArgs,gateTool:gateToolChange(context,prepared.planPath,prepared.plan),
+      ...(existing.existingAddress?{previousAddress:existing.existingAddress}:{}),...(existing.redeployReason?{redeployReason:existing.redeployReason}:{})};
+    context.bindings?.recordOrAssertDerivedValue(`${step.id}.implementation`,implementationSalt);recorder?.prepare(change);
+    recordPreparedDeployment(context,change,prepared,[`${step.id}.implementation`]);
+    if(context.mode==='execute')recorder?.stageAddressCandidate(change,deployed.address);
+    const execution=await runGateToolControlledMulticall(context,step,effective,prepared.plan.transactions);
+    if(context.mode==='execute'&&execution.transactionId)recorder?.bindProxyTransaction(step.id,execution.transactionId);
+    if(!execution.external){
+      await verifyTransparentAdmin({hre:context.runtime.hre as any,proxy:deployed.address,admin:admin.address,owner:admin.owner});
+      if((await getERC1967Implementation(context.runtime.hre.ethers.provider,deployed.address))?.toLowerCase()!==implementation.address.toLowerCase())throw Error('Transparent implementation mismatch');
+    }
+    const gateToolSync=context.mode==='execute'&&!execution.external&&deployed.status!=='reused'?await syncGateToolUups({hre:context.runtime.hre,root:context.root,evidenceDir:gateToolEvidenceDir(context),evidenceName:step.id,
+      scheme:'evm',network:context.runtime.hre.network.name,target:context.targetId,manifestDir:context.target.openzeppelin.manifestDir,proxy:deployed.address,implementation:implementation.address,
+      contract:actualContract,constructorArgs:request.constructorArgs,transactionHash:execution.txHash??'',proxyKind:'transparent',proxyAdminAddress:admin.address,proxyAdminOwner:admin.owner}):undefined;
+    if(context.mode==='execute'&&!execution.external)recorder?.applyAddress({...change,address:deployed.address,proxyAddress:deployed.address,txHash:execution.txHash,gateToolSync,reused:deployed.status==='reused'},deployed.address);
+    context.state.set(saveAs,{address:deployed.address,proxyAddress:deployed.address,implementationAddress:implementation.address,implementationSalt,proxyAdminAddress:admin.address,proxyAdminOwner:admin.owner,txHash:execution.txHash,external:execution.external});
+    context.reporter.result('execution',{stepId:step.id,kind:step.kind,mode:execution.external?'external':context.mode,contract:contractName,actualContract,saveAs,contractInfoKey:registryKey,strategy:'create2',scheme:'evm',proxy:'transparent',
+      address:deployed.address,implementationAddress:implementation.address,proxyAdminAddress:admin.address,proxyAdminOwner:admin.owner,transactionId:execution.transactionId,txHash:execution.txHash,gateToolPlan:change.gateTool!.outputPath});
+    return;
+  }
+
   if (proxy) {
     const firstUpgrade = resolveFirstUpgradeOptions(context, step);
     if (step.upgradeableStrategy !== "uups-placeholder-proxy" || !firstUpgrade) {

package/runtime/workflow/steps/upgrade.ts

@@ -2,6 +2,7 @@ import { resolveWorkflowValue } from '../lib/validation';
 import { recordPreparedDeployment } from "../lib/preparationEvidence";
 import { CONTROLLED_MULTICALL_AUTHORITY_ABI } from "../lib/controlledMulticallAbi";
 import { isAddress } from "ethers";
+import {transparentAdminAddress, verifyTransparentAdmin, PROXY_ADMIN_INTERFACE} from "gate-evm-tools/workflow";
 import path from "path";
 import type {
   GateToolDeploymentPlan,
@@ -108,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"),
@@ -198,9 +200,9 @@ 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`);
-  }
+  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');
@@ -243,16 +245,16 @@ export const runUpgradeStep = async (
     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: context.runtime.hre.network.name,
     target: context.targetId,
     contract: contractName,
     constructorArgs,
     factory,
-    proxyKind: "uups",
     proxy: proxy.proxyAddress,
     implementationSalt,
     ...(proxy.proxy.unsafeAllow ? { unsafeAllow: proxy.proxy.unsafeAllow } : {}),
@@ -291,7 +293,8 @@ 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,
@@ -312,13 +315,13 @@ export const runUpgradeStep = async (
   recordPreparedDeployment(context, preparedChange, prepared, [`${step.id}.implementation`]);
 
   const proxyContract = await context.runtime.hre.ethers.getContractAt(
-    String(step.abi || contractName),
-    proxy.proxyAddress,
+    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 (
@@ -399,6 +402,7 @@ export const runUpgradeStep = async (
       context.signer,
     );
     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,
@@ -410,6 +414,7 @@ export const runUpgradeStep = async (
           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,
@@ -544,8 +549,8 @@ 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,
     });
@@ -569,6 +574,7 @@ export const runUpgradeStep = async (
     && upgradeTransaction.route === "operator"
   ) {
     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,
@@ -579,6 +585,7 @@ export const runUpgradeStep = async (
       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,
@@ -592,6 +599,7 @@ export const runUpgradeStep = async (
     });
   } else if (context.mode === "simulate") {
     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/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', 'plan-read':'planRead', 'plan-write':'planWrite', 'plan-add':'planAdd', 'plan-status':'planStatus'};
-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;}
-}