gate-evm-tools 1.0.28 → 1.2.0

package/runtime/vendor/plan-codec/index.d.cts

@@ -0,0 +1,38 @@
+export const SCHEMA: 'gateflow-plan/v2'
+export const SCHEMA_V1: 'gateflow-plan/v1'
+export const SAFE_KEY: RegExp
+export const SKILL_NAME: RegExp
+export const TASK_STATUSES: readonly ['pending', 'running', 'blocked', 'completed', 'failed', 'cancelled']
+export const FAILURE_CATEGORIES: readonly ['execution_error', 'acceptance_failed', 'review_rejected', 'input_missing']
+export const DEFINITION_CONTRACT: 'gateflow-plan/definition@1'
+export class PlanError extends Error { code: string; constructor(message: string, code?: string) }
+export interface PlanTask {
+  no: number; planKey: string; rev: number; title: string; objective: string; acceptance: string[]; dependsOn: string[]
+  step?: string; scope?: Record<string, unknown>; parameters?: unknown[]; expectedArtifacts?: string[]; allowedChanges?: string[]
+  tools?: string[]; toolsOptional?: string[]; skills?: string[]; status: typeof TASK_STATUSES[number]; adoptedRev?: number
+  blockedReason?: string; cancelReason?: string; result?: Record<string, unknown>; previousResult?: Record<string, unknown>
+  requirementConfirmation?: { rev: number; confirmedAt: string }
+}
+export interface PlanLane { name: string; state: 'enabled' | 'disabled'; reason?: string; skill?: string; steps?: { id: string; name: string }[] }
+export interface Plan {
+  schema: typeof SCHEMA; taskId: string; title: string; flow?: string; revision: number; progressSeq: number; updatedAt: string
+  lanes: Record<string, PlanLane>; goal: string; notes: Record<string, string>; tasks: Record<string, PlanTask[]>; history: Record<string, unknown>[]
+}
+export type DeepReadonly<T> = T extends object ? { readonly [P in keyof T]: DeepReadonly<T[P]> } : T
+export interface DefinitionSelection { roots: string[]; mode: 'upstream' | 'full' }
+export interface DefinitionSnapshot {
+  contract: typeof DEFINITION_CONTRACT; schema: typeof SCHEMA; taskId: string; flow?: string; roots: string[]
+  lanes: Record<string, { state: 'enabled' | 'disabled'; skill?: string; steps: string[] }>
+  tasks: (Pick<PlanTask, 'planKey' | 'rev' | 'objective' | 'acceptance' | 'dependsOn' | 'step' | 'scope' | 'parameters' | 'expectedArtifacts' | 'allowedChanges'> & { lane: string })[]
+}
+export function parsePlan(text: string): Plan
+export function detectSchema(text: string): string | null
+export function projectDefinitions(text: string, selection: DefinitionSelection): Readonly<{ snapshot: DeepReadonly<DefinitionSnapshot>; bytes: string }>
+export function skillNames(value: unknown, where: string): string[]
+export function toolRefs(value: unknown, where: string): string[]
+export function validateEvmContracts(plan: { flow?: string; lanes: Record<string, { skill?: string }>; tasks: Record<string, { planKey: string; step?: string; scope?: Record<string, unknown> }[]> }, fail: (message: string) => never): void
+
+export type DeploymentPurpose = 'analysis' | 'dev-execution' | 'prod-qualification' | 'prod-execution'
+export function deploymentPurpose(task: {step?: string; scope?: Record<string, unknown>}): DeploymentPurpose | undefined
+export function productionActionAllowed(task: {step?: string; scope?: Record<string, unknown>}, intent: string): boolean
+export function deploymentRequirementIssue(plan: { tasks: Record<string, {planKey:string;rev:number;status:string;step?:string;scope?:Record<string,unknown>;requirementConfirmation?:{rev:number;confirmedAt:string}}[]> }, task: Pick<PlanTask, 'step' | 'scope' | 'dependsOn'>): string | null

package/runtime/vendor/plan-codec/provenance.json

@@ -0,0 +1,25 @@
+{
+  "formatVersion": 1,
+  "name": "gateflow-plan-read-only",
+  "version": 1,
+  "schema": "gateflow-plan/v2",
+  "definitionContract": "gateflow-plan/definition@1",
+  "sourceCommit": "ee0f90991ca1a94c3f58c8893df16d0c8c41b230",
+  "sourceMode": "working-tree",
+  "sources": {
+    "builtin-skills/gateflow-plan/scripts/lib/evm-contract.mjs": "c41dd9e6d630ea033001dd0922911bf365ff2baaa894107f6a80a3019eca1c17",
+    "builtin-skills/gateflow-plan/scripts/lib/handoff-v2.mjs": "05c89b794b65d6c73dc2427df8dc1b21f06c377c30f2c3baf8517459b8df56e0",
+    "builtin-skills/gateflow-plan/scripts/lib/read-only.d.mts": "716d1252adf79d5c7e6c3b7ed17984203ae3e1853695dc04fa9e769c9ac24c50",
+    "builtin-skills/gateflow-plan/scripts/lib/read-only.mjs": "1cb928d76ce14b07028efe002e624d91d36168494b5cc2cc0ba35153a311ff3e",
+    "builtin-skills/gateflow-plan/scripts/lib/yaml-lite.mjs": "b53b8322b27bb73bbbf2a4254be4698ee43ec79c27828068954afd6d05902784",
+    "scripts/build-plan-codec.mjs": "048e647687da5a55a9f1899af510b9f1b0eb0872876e5eef278ede89c53c5d75"
+  },
+  "builder": {
+    "name": "esbuild",
+    "version": "0.21.5"
+  },
+  "artifacts": {
+    "index.cjs": "1014b59dad45b47510602791e426eaf2ee6d58720583670134fa14431b935d0d",
+    "index.d.cts": "716d1252adf79d5c7e6c3b7ed17984203ae3e1853695dc04fa9e769c9ac24c50"
+  }
+}

package/runtime/workflow/engine.ts

@@ -0,0 +1,174 @@
+import type { WorkflowContext } from "./lib/context";
+import type { WorkflowStep } from "./lib/parameters";
+import type { WorkflowMode } from "./lib/simulation";
+import { assertLocalForkRuntime, assertLocalForkSigner, impersonateLocalForkSigner } from "./lib/runtime";
+import { ExternalExecutionRequired } from "./lib/external";
+import { ExecutionSegmentDeferred } from "./lib/transactionPlanner";
+import { runDeployStep } from "./steps/deploy";
+import { runCallStep } from "./steps/call";
+import { runUpgradeStep } from "./steps/upgrade";
+import { runViewStep } from "./steps/view";
+import { runCheckStep } from "./steps/check";
+
+export interface WorkflowEngineOptions {
+  simulationCallers?: readonly { stepId: string; callerAddress: string }[];
+  runCustomStep?: (context: WorkflowContext, step: WorkflowStep) => Promise<void>;
+}
+
+export const validateWorkflowStepsForMode = (
+  mode: WorkflowMode,
+  steps: readonly WorkflowStep[],
+): void => {
+  if (!["simulate", "verify", "execute"].includes(mode)) throw new Error(`Unsupported workflow mode: ${mode}`);
+  if (mode === "verify") {
+    const unsupported = steps.find((step) => step.kind !== "view" && step.kind !== "check");
+    if (unsupported) throw new Error(`verify mode only supports view and check steps; ${unsupported.id} is ${unsupported.kind}`);
+  }
+};
+
+const dispatchStep = async (context: WorkflowContext, step: WorkflowStep, options: WorkflowEngineOptions): Promise<void> => {
+  switch (step.kind) {
+    case "deploy":
+      await runDeployStep(context, step);
+      return;
+    case "call":
+      await runCallStep(context, step);
+      return;
+    case "upgrade":
+      await runUpgradeStep(context, step);
+      return;
+    case "view":
+      await runViewStep(context, step);
+      return;
+    case "check":
+      await runCheckStep(context, step);
+      return;
+    case "custom":
+      if (!options.runCustomStep) throw new Error("Custom steps require an explicit legacy or planning adapter");
+      await options.runCustomStep(context, step);
+      return;
+    default:
+      throw new Error(`Unsupported step kind: ${step.kind}`);
+  }
+};
+
+export const runWorkflowSteps = async (
+  context: WorkflowContext,
+  steps: readonly WorkflowStep[],
+  options: WorkflowEngineOptions = {},
+): Promise<{ executionSegmentDeferred: boolean }> => {
+  // Validate the entire selection before a read, custom adapter, or signer runs.
+  validateWorkflowStepsForMode(context.mode, steps);
+  if (
+    context.mode === "verify"
+    && context.signer
+    && (!context.signer.provider || context.signer.provider !== context.runtime.hre.ethers.provider)
+  ) {
+    throw new Error("Verify signer must be connected to the explicit runtime provider");
+  }
+  if (context.mode === "simulate") {
+    assertLocalForkRuntime(context.runtime);
+    if (context.signer) assertLocalForkSigner(context.runtime, context.signer);
+  } else if (options.simulationCallers?.length) {
+    throw new Error("Simulation callers are only available in simulate mode");
+  }
+  const reporter = context.reporter;
+  let executionSegmentDeferred = false;
+  stepLoop: for (const step of steps) {
+    if (
+      context.mode === "execute"
+      && context.externalCalls.length > 0
+      && (step.kind === "view" || step.kind === "check" || step.kind === "custom")
+    ) {
+      reporter.event("step.deferred_until_external_execution", {
+        stepId: step.id,
+        kind: step.kind,
+      });
+      break;
+    }
+    const configuredCaller = options.simulationCallers?.find(
+      (entry) => entry.stepId === step.id,
+    );
+    const stepContext: WorkflowContext = configuredCaller
+      ? {
+          ...context,
+          signer: await impersonateLocalForkSigner(context.runtime, configuredCaller.callerAddress),
+          signerAddress: configuredCaller.callerAddress,
+          configuredSimulationCaller: true,
+        }
+      : context;
+    if (configuredCaller) {
+      reporter.setSimulationCallerAddress?.(configuredCaller.callerAddress);
+    }
+    try {
+      reporter.event("step.started", { stepId: step.id, kind: step.kind });
+      try {
+        await dispatchStep(stepContext, step, options);
+      } catch (error) {
+        if (context.mode === "execute" && error instanceof ExecutionSegmentDeferred) {
+          executionSegmentDeferred = true;
+          reporter.event("execution.segment.deferred", {
+            transactionId: error.transactionId,
+          });
+          break stepLoop;
+        }
+        if (
+          context.mode === "execute"
+          && error instanceof ExternalExecutionRequired
+        ) {
+          if (!context.executionPlanner) {
+            throw new Error(
+              "External execution requires a locked mixed-authority plan; run final simulation and execute mode",
+            );
+          }
+          for (const call of error.calls) {
+            let planned;
+            try {
+              planned = context.executionPlanner.add({
+                stepId: call.stepId,
+                executor: call.executor,
+                to: call.to,
+                value: call.value,
+                data: call.data,
+                operation: call.operation,
+              });
+            } catch (planError) {
+              if (planError instanceof ExecutionSegmentDeferred) {
+                executionSegmentDeferred = true;
+                reporter.event("execution.segment.deferred", {
+                  transactionId: planError.transactionId,
+                });
+                break;
+              }
+              throw planError;
+            }
+            if (planned.route !== "external") {
+              throw new Error(
+                `Step ${call.stepId} requested external execution for an operator route`,
+              );
+            }
+            if (planned.executionAction !== "replay") {
+              context.externalCalls.push({
+                ...call,
+                transactionId: planned.transactionId,
+                stepId: planned.stepId,
+                executor: planned.executor,
+                to: planned.to,
+                value: planned.value,
+                data: planned.data,
+                operation: planned.operation,
+              });
+            }
+          }
+          if (executionSegmentDeferred) break stepLoop;
+          continue;
+        }
+        throw error;
+      }
+      reporter.event("step.completed", { stepId: step.id, kind: step.kind });
+    } finally {
+      if (configuredCaller) reporter.clearSimulationCallerAddress?.();
+    }
+  }
+  return { executionSegmentDeferred };
+};

package/runtime/workflow/lib/authority.ts

@@ -1,6 +1,6 @@
 import type { BaseContract } from "ethers";
 import { getAddress, isAddress } from "ethers";
-import { TargetConfig, resolveAdmin } from "./config";
+import { resolveAdmin } from "./config";
 
 export interface AuthorityDecision {
   mode: "execute" | "calldata";
@@ -61,7 +61,7 @@ interface ControlledMulticallAuthorityContract {
 export const decideControlledMulticallAuthority = async (
   contract: ControlledMulticallAuthorityContract,
   factory: string,
-  target: TargetConfig,
+  target: { admin?: string },
   signerAddress: string,
   blockTag?: number,
 ): Promise<AuthorityDecision> => {
@@ -122,7 +122,7 @@ export const decideControlledMulticallAuthority = async (
 
 export const decideAuthority = async (
   contract: BaseContract,
-  target: TargetConfig,
+  target: { admin?: string },
   signerAddress: string,
   blockTag?: number,
 ): Promise<AuthorityDecision> => {

package/runtime/workflow/lib/calls.ts

@@ -1,6 +1,7 @@
+import { resolveWorkflowValue } from './validation';
+import { typedValue } from "./typedValue";
 import type { BaseContract } from "ethers";
 import { getAddress, isAddress } from "ethers";
-import { ethers } from "../../projectHardhat";
 import {
   assertSelectedSimulationSignerAuthorized,
   decideAuthority,
@@ -9,9 +10,9 @@ import { encodeCall } from "./calldata";
 import { findExecutionCandidateAddress } from "./contractInfoCandidates";
 import { getDeploymentAddress } from "./deployments";
 import { ExternalCall, ExternalExecutionRequired } from "./external";
-import { resolveValue, WorkflowStep } from "./parameters";
-import type { WorkflowContext } from "../run";
-import { impersonateWorkflowSimulationSigner } from "./signer";
+import { WorkflowStep } from "./parameters";
+import type { WorkflowContext } from "./context";
+import { impersonateLocalForkSigner } from "./runtime";
 
 export interface ContractCall {
   method: string;
@@ -52,7 +53,7 @@ const findStateAddress = (
 ): string | undefined => {
   for (const pathExpression of [`${name}.address`, `${name}.proxyAddress`]) {
     try {
-      const value = context.state.get(pathExpression);
+      const value = context.validation ? context.validation.resolve({ $ref: `state.${pathExpression}` }) : context.state.get(pathExpression);
       if (typeof value === "string" && value) {
         return value;
       }
@@ -85,14 +86,9 @@ export const resolveContract = async (
     deploymentName ||
     stringStepField(step, "saveAs") ||
     contractName;
-  const address = String(
+  const rawAddress = (
     step.address
-      ? resolveValue(step.address, {
-        targetId: context.targetId,
-        target: context.target,
-        params: context.targetParams,
-        state: context.state,
-      })
+      ? resolveWorkflowValue(context, step.address)
       : findStateAddress(context, lookupName) ||
         findExecutionCandidateAddress({
           root: context.root,
@@ -101,9 +97,11 @@ export const resolveContract = async (
           network: context.targetId,
           name: lookupName,
         }) ||
-        getDeploymentAddress(context.root, context.config, context.targetId, lookupName),
+        getDeploymentAddress(context.root, context.config, context.targetId, lookupName)
   );
-  const contract = await ethers.getContractAt(abiName, address, context.signer);
+  context.validation?.address(rawAddress);
+  const address = String(rawAddress);
+  const contract = await context.runtime.hre.ethers.getContractAt(abiName, address, context.signer);
 
   return {
     contractName,
@@ -125,12 +123,7 @@ export const resolveCallArgs = (
   context: WorkflowContext,
   call: ContractCall,
 ): unknown[] => {
-  const args = resolveValue(call.args || [], {
-    targetId: context.targetId,
-    target: context.target,
-    params: context.targetParams,
-    state: context.state,
-  });
+  const args = resolveWorkflowValue(context, context.validation ? (call.args === undefined ? [] : call.args) : (call.args || []));
 
   if (!Array.isArray(args)) {
     throw new Error(`Call ${call.method} args must resolve to an array`);
@@ -186,7 +179,8 @@ export const runContractWriteCalls = async (
 ): Promise<void> => {
   const resolved = await resolveContract(context, step);
   const calls = resolveStepCalls(step);
-  const callValues = calls.map((call) => normalizeCallValue(call.value));
+  const rawCallValues = calls.map((call) => resolveWorkflowValue(context, call.value === undefined ? 0 : call.value));
+  const callValues = rawCallValues.map(normalizeCallValue);
   if (!context.signerAddress) {
     throw new Error(`Call step ${step.id} requires a signer address`);
   }
@@ -215,7 +209,8 @@ export const runContractWriteCalls = async (
     const externalExecutor = authority.executor;
     const externalCalls: ExternalCall[] = calls.map((call, index) => {
       const args = resolveCallArgs(context, call);
-      const stepId = calldataStepId(step, call, index, calls);
+      context.validation?.callInterface(resolved.contract.interface.fragments, call.method, args);
+      const stepId = context.transactionIdentity?.transactionStepId(step.id, "call", index) ?? calldataStepId(step, call, index, calls);
       return {
         transactionId: stepId,
         stepId,
@@ -234,10 +229,12 @@ export const runContractWriteCalls = async (
 
   for (const [index, call] of calls.entries()) {
     const args = resolveCallArgs(context, call);
+    await context.validation?.call(resolved.abiName, call.method, args, rawCallValues[index]);
+    context.validation?.callInterface(resolved.contract.interface.fragments, call.method, args);
     const value = callValues[index];
 
     if (context.executionPlanner) {
-      const stepId = calldataStepId(step, call, index, calls);
+      const stepId = context.transactionIdentity?.transactionStepId(step.id, "call", index) ?? calldataStepId(step, call, index, calls);
       const executor = authority.mode === "execute"
         ? context.signerAddress
         : authority.executor;
@@ -255,6 +252,7 @@ export const runContractWriteCalls = async (
         operation: 0,
         ...(zkSync ? { scheme: "zksync-eravm" as const, factoryDeps: [] } : {}),
       });
+      context.calldataReview?.record(planned, { abi: resolved.contract.interface.fragments, method: call.method, args });
       if (planned.executionAction === "replay") {
         context.reporter.result("execution", {
           stepId: planned.stepId,
@@ -290,10 +288,10 @@ export const runContractWriteCalls = async (
       }
 
       const selectedContract = planned.route === "external"
-        ? await ethers.getContractAt(
+        ? await context.runtime.hre.ethers.getContractAt(
             resolved.abiName,
             resolved.address,
-            await impersonateWorkflowSimulationSigner(planned.executor),
+            await impersonateLocalForkSigner(context.runtime, planned.executor),
           )
         : resolved.contract;
       const txArgs = value !== "0" ? [...args, { value }] : args;
@@ -301,6 +299,7 @@ export const runContractWriteCalls = async (
         hash: string;
         wait: () => Promise<unknown>;
       };
+      context.transactionObserver?.record({ transactionId: planned.transactionId, transactionHash: tx.hash });
       await tx.wait();
       if (context.mode === "execute" && planned.route === "operator") {
         context.operatorReceipts.push({
@@ -354,8 +353,10 @@ export const runContractViewCalls = async (
 
   for (const [index, call] of calls.entries()) {
     const args = resolveCallArgs(context, call);
-    const value = await methodOf(resolved.contract, call.method)(...args);
-    results[resultKey(call, index, calls)] = stringifyCallResult(value);
+    await context.validation?.call(resolved.abiName, call.method, args, call.value === undefined ? undefined : resolveWorkflowValue(context, call.value));
+    context.validation?.callInterface(resolved.contract.interface.fragments, call.method, args);
+    const value = await resolved.contract.getFunction(call.method).staticCall(...args);
+    results[resultKey(call, index, calls)] = context.validation ? context.validation.stringify(value) : stringifyCallResult(value);
   }
 
   context.reporter.result("view", {
@@ -377,16 +378,18 @@ export const runContractCheckCalls = async (
 
   for (const [index, call] of calls.entries()) {
     const args = resolveCallArgs(context, call);
-    const actualValue = await methodOf(resolved.contract, call.method)(...args);
-    const expectedValue = resolveValue(call.expect, {
-      targetId: context.targetId,
-      target: context.target,
-      params: context.targetParams,
-      state: context.state,
-    });
-    const actual = stringifyCallResult(actualValue);
-    const expected = stringifyCallResult(expectedValue);
-    const comparable = comparableCallResults(actual, expected);
+    await context.validation?.call(resolved.abiName, call.method, args, call.value === undefined ? undefined : resolveWorkflowValue(context, call.value));
+    context.validation?.callInterface(resolved.contract.interface.fragments, call.method, args);
+    let expectedValue: unknown;
+    if (context.validation) {
+      expectedValue = resolveWorkflowValue(context, call.expect);
+      context.validation.check(resolved.contract.interface.fragments, call.method, expectedValue);
+    }
+    const actualValue = await resolved.contract.getFunction(call.method).staticCall(...args);
+    if (!context.validation) expectedValue = resolveWorkflowValue(context, call.expect);
+    const comparable = context.validation
+      ? context.validation.compare(resolved.contract.interface.fragments, call.method, actualValue, expectedValue)
+      : comparableCallResults(stringifyCallResult(actualValue), stringifyCallResult(expectedValue));
 
     if (comparable.actual !== comparable.expected) {
       throw new Error(
@@ -394,6 +397,13 @@ export const runContractCheckCalls = async (
       );
     }
 
+    context.verification?.record({
+      stepId: step.id, callIndex: index, assertionId: `${step.id}:${index}`,
+      contract: resolved.contractName, abiName: resolved.abiName, abi: resolved.contract.interface.format(true),
+      address: resolved.address, method: call.method, args: typedValue(args),
+      definition: { method: call.method, args: typedValue(call.args ?? []), expect: typedValue(call.expect) },
+      actual: typedValue(actualValue), expected: typedValue(expectedValue),
+    });
     results[resultKey(call, index, calls)] = comparable;
   }
 

package/runtime/workflow/lib/canonicalData.ts

@@ -0,0 +1,45 @@
+import { createHash } from 'node:crypto';
+
+/** Only own enumerable data is semantic. Never invokes getters/toJSON or resolves prototypes. */
+export function canonicalData(value: unknown, label = 'data'): unknown {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return value;
+  if (typeof value === 'number' && Number.isSafeInteger(value)) return value;
+  if (!value || typeof value !== 'object') throw new Error(`${label} must contain canonical JSON data`);
+  if (Array.isArray(value)) {
+    if (Object.keys(value).length !== value.length) throw new Error(`${label} has sparse or extra array data`);
+    return Array.from({ length: value.length }, (_, i) => canonicalData(own(value, String(i), label), `${label}[${i}]`));
+  }
+  if (![Object.prototype, null].includes(Object.getPrototypeOf(value))) throw new Error(`${label} must contain own plain data`);
+  if (Object.getOwnPropertySymbols(value).length) throw new Error(`${label} contains symbol fields`);
+  const result: Record<string, unknown> = {};
+  for (const key of Object.getOwnPropertyNames(value).sort()) {
+    Object.defineProperty(result, key, { value: canonicalData(own(value, key, label), `${label}.${key}`), enumerable: true, writable: true, configurable: true });
+  }
+  return result;
+}
+function own(value: object, key: string, label: string): unknown {
+  const d = Object.getOwnPropertyDescriptor(value, key);
+  if (!d || !d.enumerable || !('value' in d)) throw new Error(`${label}.${key} must be own enumerable data`);
+  return d.value;
+}
+export function canonicalJson(value: unknown): string { return JSON.stringify(canonicalData(value)); }
+export function semanticHash(value: unknown): string { return createHash('sha256').update(canonicalJson(value)).digest('hex'); }
+export function deepFreeze<T>(value: T): T {
+  if (value && typeof value === 'object') { Object.values(value).forEach(deepFreeze); Object.freeze(value); }
+  return value;
+}
+export function exactObject(value: unknown, keys: readonly string[], label: string): Record<string, unknown> {
+  const data = canonicalData(value, label);
+  if (!data || typeof data !== 'object' || Array.isArray(data)) throw new Error(`${label} must be an object`);
+  const actual = Object.keys(data).sort(), wanted = [...keys].sort();
+  if (actual.length !== wanted.length || actual.some((k, i) => k !== wanted[i])) throw new Error(`${label} contains unsupported or missing fields`);
+  return data as Record<string, unknown>;
+}
+export function digest(value: unknown, label: string): string {
+  if (typeof value !== 'string' || !/^[a-f0-9]{64}$/.test(value)) throw new Error(`Invalid ${label} digest`);
+  return value;
+}
+export function nonempty(value: unknown, label: string): string {
+  if (typeof value !== 'string' || !value || value.trim() !== value) throw new Error(`Invalid ${label}`);
+  return value;
+}

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/config.ts

@@ -116,7 +116,7 @@ export const resolveTarget = (config: WorkflowConfig, networkName: string): Targ
   return target;
 };
 
-export const resolveAdmin = (target: TargetConfig, signerAddress: string): string => {
+export const resolveAdmin = (target: { admin?: string }, signerAddress: string): string => {
   const admin = target.admin?.trim();
   if (!admin || admin.toLowerCase() === "deployer") {
     return getAddress(signerAddress);

package/runtime/workflow/lib/context.ts

@@ -0,0 +1,77 @@
+import type { WorkflowValidationPort } from './validation';
+import type { PendingUupsResolverPort } from "./pendingUupsBinding";
+import type { PreparationSink, VerificationSink } from "./evidencePorts";
+import type { TransactionPlannerPort } from "./transactionPlanner";
+import type { Signer } from "ethers";
+import type { TargetConfig } from "./config";
+import type { ExistingDeploymentPolicies } from "./parameters";
+import type { SimulationFork, WorkflowMode } from "./simulation";
+import type { WorkflowState } from "./state";
+import type { DeploymentRecorder } from "./deploymentRecords";
+import type { ExternalCall } from "./external";
+import type { WorkflowResultName } from "./resultPaths";
+
+// Type-only: importing shared steps must never initialize a project Hardhat runtime.
+export type WorkflowHre = typeof import("hardhat");
+
+export interface LocalForkCapability {
+  provider: WorkflowHre["network"]["provider"];
+  impersonate(address: string): Promise<Signer>;
+}
+
+export interface WorkflowRuntime {
+  hre: WorkflowHre;
+  localFork?: LocalForkCapability;
+}
+
+export interface WorkflowReporterPort {
+  event(type: string, payload?: Record<string, unknown>): void;
+  result(name: WorkflowResultName, payload: Record<string, unknown>): void;
+  setSimulationCallerAddress?(address: string): void;
+  clearSimulationCallerAddress?(): void;
+}
+
+export interface ExecutionBindings {
+  readonly derivationSeed?: string;
+  recordOrAssertDerivedValue(key: string, value: string): void;
+}
+
+// Only the fields used by step algorithms; environment interpretation belongs
+// to each launcher. A delivery target does not have to pass the legacy parser.
+export type WorkflowTarget = Pick<TargetConfig,
+  "openzeppelin" | "finality" | "admin" | "create2" | "uups" | "multicall"
+> & Record<string, unknown> & { id: string };
+export type WorkflowConfiguration = Readonly<Record<string, unknown>>;
+
+export interface WorkflowContext {
+  root: string;
+  taskId: string;
+  executionId: string;
+  taskDir: string;
+  targetId: string;
+  target: WorkflowTarget;
+  targetParams: Record<string, unknown>;
+  existingDeploymentPolicies: ExistingDeploymentPolicies;
+  releaseArtifactHash?: string;
+  config: WorkflowConfiguration;
+  runtime: WorkflowRuntime;
+  mode: WorkflowMode;
+  simulation: SimulationFork;
+  signer?: Signer;
+  signerAddress?: string;
+  configuredSimulationCaller?: boolean;
+  state: WorkflowState;
+  reporter: WorkflowReporterPort;
+  bindings?: ExecutionBindings;
+  preparations?: PreparationSink;
+  validation?: WorkflowValidationPort;
+  pendingUupsReuse?: PendingUupsResolverPort;
+  verification?: VerificationSink;
+  calldataReview?: import('../../delivery/calldata-review').CalldataReviewSink;
+  deploymentRecorder?: DeploymentRecorder;
+  executionPlanner?: TransactionPlannerPort;
+  externalCalls: ExternalCall[];
+  transactionIdentity?: { transactionStepId(stepId: string, role: "call", ordinal: number): string };
+  transactionObserver?: { record(observation: { transactionId: string; transactionHash: string }): void };
+  operatorReceipts: Array<{ transactionId: string; transactionHash: string }>;
+}