gate-evm-tools 1.0.31 → 1.2.0

package/runtime/workflow/lib/checkCodeRunner.ts

@@ -657,6 +657,7 @@ const manifestIsCurrent = (input: {
   proxyAddress: string;
   implementationAddress: string;
   storageLayoutHash: string;
+  proxyKind?: string;
 }): boolean => {
   const proxy = input.proxyAddress.toLowerCase();
   const implementation = input.implementationAddress.toLowerCase();
@@ -669,6 +670,7 @@ const manifestIsCurrent = (input: {
       isRecord(item)
       && typeof item.address === "string"
       && item.address.toLowerCase() === proxy
+      && (input.proxyKind === undefined || item.kind === input.proxyKind)
     ));
   }
   if (isRecord(document.impls)) {
@@ -1114,7 +1116,7 @@ export const runCheckCode = async (
       manifestFile: exactManifest.relative,
       beforeHash,
     };
-    if (metadata?.proxyKind === "uups" && !implementationAddress) {
+    if ((metadata?.proxyKind === "uups" || metadata?.proxyKind === "transparent") && !implementationAddress) {
       entries.push({ ...base, syncStatus: "failed", afterHash: directoryHash(directory) });
       continue;
     }
@@ -1135,11 +1137,11 @@ export const runCheckCode = async (
       }
       continue;
     }
-    if (!implementationAddress || metadata?.proxyKind && metadata.proxyKind !== "uups") {
+    if (!implementationAddress || metadata?.proxyKind && metadata.proxyKind !== "uups" && metadata.proxyKind !== "transparent") {
       entries.push({ ...base, syncStatus: "not_required", afterHash: directoryHash(directory) });
       continue;
     }
-    if (!metadata || metadata.proxyKind !== "uups") {
+    if (!metadata || (metadata.proxyKind !== "uups" && metadata.proxyKind !== "transparent")) {
       entries.push({ ...base, syncStatus: "proxy_kind_unknown", afterHash: directoryHash(directory) });
       continue;
     }
@@ -1159,6 +1161,7 @@ export const runCheckCode = async (
       proxyAddress: selected.address,
       implementationAddress,
       storageLayoutHash,
+      proxyKind:metadata.proxyKind,
     })) {
       entries.push({ ...base, syncStatus: "already_current", afterHash: beforeHash });
       continue;
@@ -1178,6 +1181,7 @@ export const runCheckCode = async (
       "--target",
       selected.network,
       "--skip-tx-hash",
+      ...(metadata.proxyKind === "transparent" ? ["--proxy-kind","transparent","--proxy-admin-address",metadata.proxyAdminAddress??"","--proxy-admin-owner",metadata.proxyAdminOwner??""] : []),
     ], {
       network: selected.network,
       scheme,

package/runtime/workflow/lib/context.ts

@@ -67,6 +67,7 @@ export interface WorkflowContext {
   validation?: WorkflowValidationPort;
   pendingUupsReuse?: PendingUupsResolverPort;
   verification?: VerificationSink;
+  calldataReview?: import('../../delivery/calldata-review').CalldataReviewSink;
   deploymentRecorder?: DeploymentRecorder;
   executionPlanner?: TransactionPlannerPort;
   externalCalls: ExternalCall[];

package/runtime/workflow/lib/create2.ts

@@ -1,16 +1,14 @@
 import { resolveWorkflowValue, type Create2FieldKind } from './validation';
 import type { Signer } from "ethers";
-import { getAddress, Interface, isAddress } from "ethers";
+import { getAddress, isAddress } from "ethers";
 import { WorkflowStep } from "./parameters";
 import type { WorkflowContext } from "./context";
 
-const CONTROLLED_MULTICALL_INTERFACE = new Interface([
-  "function aggregate3(tuple(address target,bool allowFailure,bytes callData)[] calls) payable returns (tuple(bool success, bytes returnData)[] returnData)",
-  "function aggregate3Value(tuple(address target,bool allowFailure,uint256 value,bytes callData)[] calls) payable returns (tuple(bool success, bytes returnData)[] returnData)",
-]);
-
-export type Create2Scheme = "evm" | "zksync-eravm";
-
+import { prepareControlledMulticallTransaction } from 'gate-evm-tools/workflow';
+import type { PreparedWorkflowTransaction, PreparedControlledMulticallTransaction } from 'gate-evm-tools/workflow';
+export { prepareControlledMulticallTransaction } from 'gate-evm-tools/workflow';
+export type { PreparedWorkflowTransaction, PreparedControlledMulticallTransaction, ControlledMulticallInnerCall } from 'gate-evm-tools/workflow';
+export type Create2Scheme = 'evm' | 'zksync-eravm';
 export interface Create2Options {
   scheme: Create2Scheme;
   factory: string;
@@ -23,106 +21,7 @@ export interface Create2Options {
   uupsPlaceholderImplementation?: string;
 }
 
-export interface PreparedWorkflowTransaction {
-  target: string;
-  value: string;
-  data: string;
-  operation: 0;
-  scheme?: "zksync-eravm";
-  factoryDeps?: string[];
-}
-
-export interface ControlledMulticallInnerCall {
-  target: string;
-  value: string;
-  data: string;
-  factoryDeps?: string[];
-}
-
-export interface PreparedControlledMulticallTransaction
-  extends PreparedWorkflowTransaction {
-  method: "aggregate3" | "aggregate3Value";
-  calls: Array<{
-    target: string;
-    allowFailure: false;
-    value: string;
-    callData: string;
-  }>;
-}
-
-interface SentTransaction {
-  hash: string;
-  wait: () => Promise<unknown>;
-}
-
-const bigintValue = (value: string | undefined): bigint => {
-  if (!value || value === "0") return 0n;
-  const parsed = BigInt(value);
-  if (parsed < 0n) throw new Error("transaction value must be nonnegative");
-  return parsed;
-};
-
-const normalizeFactoryDeps = (
-  input: string[],
-  label: string,
-): string[] => {
-  const seen = new Set<string>();
-  const output: string[] = [];
-  for (const [index, dependency] of input.entries()) {
-    if (!/^0x(?:[0-9a-fA-F]{2})+$/.test(dependency)) {
-      throw new Error(`${label}[${index}] must be non-empty byte-aligned bytecode`);
-    }
-    const normalized = dependency.toLowerCase();
-    if (seen.has(normalized)) continue;
-    seen.add(normalized);
-    output.push(normalized);
-  }
-  return output;
-};
-
-export const prepareControlledMulticallTransaction = (
-  controlledMulticall: string,
-  inputCalls: ControlledMulticallInnerCall[],
-  scheme: Create2Scheme = "evm",
-): PreparedControlledMulticallTransaction => {
-  if (!isAddress(controlledMulticall)) {
-    throw new Error("controlledMulticall must be an EVM address");
-  }
-  if (inputCalls.length === 0) {
-    throw new Error("controlled multicall requires at least one inner call");
-  }
-  if (scheme === "evm" && inputCalls.some((call) => call.factoryDeps !== undefined)) {
-    throw new Error("factoryDeps are only supported for zkSync transactions");
-  }
-  if (scheme === "zksync-eravm" && inputCalls.some((call) => call.factoryDeps === undefined)) {
-    throw new Error("every zkSync GateTool call must include factoryDeps");
-  }
-  const calls = inputCalls.map((call) => ({
-    target: getAddress(call.target),
-    allowFailure: false as const,
-    value: bigintValue(call.value).toString(10),
-    callData: call.data,
-  }));
-  const totalValue = calls.reduce((sum, call) => sum + BigInt(call.value), 0n);
-  const method = totalValue === 0n ? "aggregate3" as const : "aggregate3Value" as const;
-  const encodedCalls = method === "aggregate3"
-    ? calls.map(({ value: _value, ...call }) => call)
-    : calls;
-  const factoryDeps = scheme === "zksync-eravm"
-    ? normalizeFactoryDeps(inputCalls.flatMap((call) => call.factoryDeps!), "factoryDeps")
-    : undefined;
-  return {
-    target: getAddress(controlledMulticall),
-    value: totalValue.toString(10),
-    data: CONTROLLED_MULTICALL_INTERFACE.encodeFunctionData(method, [encodedCalls]),
-    operation: 0,
-    method,
-    calls,
-    ...(scheme === "zksync-eravm"
-      ? { scheme: "zksync-eravm" as const, factoryDeps: factoryDeps! }
-      : {}),
-  };
-};
+interface SentTransaction { hash:string; wait:()=>Promise<unknown>; }
 
 export const sendPreparedWorkflowTransaction = async (
   prepared: PreparedWorkflowTransaction,

package/runtime/workflow/lib/deploymentInfo.ts

@@ -11,6 +11,8 @@ export interface DeploymentInfoEntry {
   actualContract: string;
   proxyKind?: "uups" | "transparent";
   implementationAddress?: string;
+  proxyAdminAddress?: string;
+  proxyAdminOwner?: string;
   source: DeploymentInfoSource;
   updatedAt: string;
 }
@@ -114,6 +116,8 @@ const validateEntry = (value: unknown, label: string): DeploymentInfoEntry => {
     "actualContract",
     "proxyKind",
     "implementationAddress",
+    "proxyAdminAddress",
+    "proxyAdminOwner",
     "source",
     "updatedAt",
   ]);
@@ -140,6 +144,8 @@ const validateEntry = (value: unknown, label: string): DeploymentInfoEntry => {
     ...(value.implementationAddress
       ? { implementationAddress: address(value.implementationAddress, `${label}.implementationAddress`) }
       : {}),
+    ...(value.proxyAdminAddress?{proxyAdminAddress:address(value.proxyAdminAddress,`${label}.proxyAdminAddress`)}:{}),
+    ...(value.proxyAdminOwner?{proxyAdminOwner:address(value.proxyAdminOwner,`${label}.proxyAdminOwner`)}:{}),
     source: validateSource(value.source, `${label}.source`),
     updatedAt: value.updatedAt,
   };
@@ -243,6 +249,7 @@ export function prepareDeploymentInfoFromRecords(input: {
         actualContract,
         ...(proxyKind ? { proxyKind } : {}),
         ...(implementationAddress ? { implementationAddress } : {}),
+        ...(proxyKind === "transparent" ? {proxyAdminAddress:optionalAddress(rawChange.proxyAdminAddress??existing?.proxyAdminAddress,"ProxyAdmin address"),proxyAdminOwner:optionalAddress(rawChange.proxyAdminOwner??existing?.proxyAdminOwner,"ProxyAdmin owner")}:{}),
         source: {
           kind: "deployment" as const,
           deploymentId,
@@ -259,6 +266,7 @@ export function prepareDeploymentInfoFromRecords(input: {
             ...(existing.implementationAddress
               ? { implementationAddress: existing.implementationAddress }
               : {}),
+            ...(existing.proxyKind === "transparent" ? {proxyAdminAddress:existing.proxyAdminAddress,proxyAdminOwner:existing.proxyAdminOwner}:{}),
             source: existing.source,
           }
         : undefined;

package/runtime/workflow/lib/deploymentRecords.ts

@@ -63,6 +63,8 @@ export interface DeploymentChange {
   proxyKind?: string;
   address?: string;
   proxyAddress?: string;
+  proxyAdminAddress?: string;
+  proxyAdminOwner?: string;
   implementationAddress?: string;
   preparedImplementationAddress?: string;
   placeholderImplementationAddress?: string;
@@ -272,7 +274,7 @@ export class DeploymentRecorder {
       throw new Error("Deployment proxy transactionId is invalid");
     }
     const change = this.record.changes.find((entry) => entry.stepId === stepId);
-    if (!change || change.proxyKind !== "uups") {
+    if (!change || (change.proxyKind !== "uups" && change.proxyKind !== "transparent")) {
       throw new Error(`Cannot bind a proxy transaction for deployment change ${stepId}`);
     }
     if (

package/runtime/workflow/lib/externalExecutionScanner.ts

@@ -790,7 +790,7 @@ export const reconcileExternalExecution = async (input: {
       orderedMatches.map((match) => [match.transactionId, match]),
     );
     for (const change of deployment.changes) {
-      if (change.proxyKind !== "uups") continue;
+      if (change.proxyKind !== "uups" && change.proxyKind !== "transparent") continue;
       if (
         !change.proxyAddress
         || !change.implementationAddress
@@ -846,6 +846,7 @@ export const reconcileExternalExecution = async (input: {
         target: input.network,
         manifestDir: target.openzeppelin.manifestDir,
         proxy: change.proxyAddress,
+        ...(change.proxyKind === 'transparent'?{proxyKind:'transparent' as const,proxyAdminAddress:change.proxyAdminAddress,proxyAdminOwner:change.proxyAdminOwner}:{}),
         implementation: change.implementationAddress,
         contract: change.actualContract,
         constructorArgs: change.constructorArgs,

package/runtime/workflow/lib/gateTool.ts

@@ -162,7 +162,7 @@ export 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(
@@ -174,7 +174,7 @@ export const expectedTransactionPurposes = (
     return [
       ...(requiredRoles.has("implementation") ? ["deploy-implementation" as const] : []),
       "deploy-proxy",
-      "upgrade-proxy",
+      ...(plan.kind === "uups-placeholder-deploy" ? ["upgrade-proxy" as const] : []),
     ];
   }
   return [

package/runtime/workflow/lib/gateToolSync.ts

@@ -20,6 +20,9 @@ export interface SyncGateToolUupsOptions {
   target: string;
   manifestDir: string;
   proxy: string;
+  proxyKind?: "uups" | "transparent";
+  proxyAdminAddress?: string;
+  proxyAdminOwner?: string;
   implementation: string;
   contract: string;
   constructorArgs: unknown[];
@@ -163,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)
@@ -239,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,
@@ -335,6 +342,7 @@ 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"

package/runtime/workflow/lib/parameters.ts

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

package/runtime/workflow/lib/proxy.ts

@@ -10,6 +10,7 @@ export interface ProxyOptions {
   initializer?: string | false;
   unsafeAllow?: string[];
   constructorArgs?: unknown[];
+  adminOwner?: string;
 }
 
 export interface FirstUpgradeOptions {

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;}
-}