gate-evm-tools 1.0.28 → 1.2.0

package/runtime/delivery/planning.ts

@@ -0,0 +1,411 @@
+import { yieldCompilerIo } from './compiler-io';
+import { createCalldataInvocation, reviewTransaction, parseCalldataReviews, type CalldataTransactionReview } from './calldata-review';
+import { preparationCalldataReviews } from './calldata-preparations';
+import {assertOwnedTargetWorker} from './aggregate-bootstrap';
+import type { ReferenceObservation } from "./references";
+import { createDeliveryValidation } from "./validation";
+import { strictData } from "./data";
+/** Internal simulation collection only. No release_ready, business acceptance or broadcast API. */
+import {
+  DeliveryOperationIdentities,
+  bindDeliveryTransactions,
+} from "./identities";
+import {
+  CustomPlanningSession,
+  ownedCustomSession,
+  parseCustomEvidence,
+  type CustomEvidence,
+  type CustomPlanningInputSession,
+} from "./custom";
+import { LocalForkAudit, type ForkAuditEvidence } from "./forkAudit";
+import type { WorkflowStep } from "../workflow/lib/parameters";
+import type { CompletedExecutionTransaction } from "../workflow/lib/transactionPlanner";
+import { TransactionPlanner } from "../workflow/lib/transactionPlanner";
+import {
+  canonicalData,
+  canonicalJson,
+  deepFreeze,
+  semanticHash,
+} from "../workflow/lib/canonicalData";
+import { assertLocalForkRuntime } from "../workflow/lib/runtime";
+import { runDeliverySteps, type DeliveryStepContext } from "./engine";
+import {
+  parseDeliveryPlan,
+  parseDeliveryPlanHeader,
+  sealDeliveryPlan,
+  type DeliveryPlan,
+  type DeliveryPlanHeader,
+  type DeliveryPlanBody,
+} from "./plan";
+import { DeliveryExecutionBindings } from "./bindings";
+import {
+  PreparationJournal,
+  parsePreparationJournal,
+  type PreparationEntry,
+} from "./journal";
+import {
+  VerificationJournal,
+  parseVerificationObservation,
+} from "./verification";
+import type { VerificationObservation } from "../workflow/lib/evidencePorts";
+import type { PendingReuseBinding } from "../workflow/lib/pendingUupsBinding";
+import { ownedDeliveryCompiler, hasCompilerSameForkInitial, type DeliveryCompilerCollector, type CompilerEvidence } from './compiler';
+export interface PlanningIdentityPort {
+  /** Launcher supplies validated source/inputs/runtime identity; parser does not inspect project files. */
+  read(): Promise<DeliveryPlanHeader>;
+  /** Launcher-owned read-only source connection. It must read the requested pinned block. */
+  readSourceBlock(
+    blockNumber: number
+  ): Promise<{ chainId: string; blockNumber: number; blockHash: string }>;
+}
+export interface DeliveryRuntimeEvidence {
+  /** Validated during this collection only; never hashed or compared as canonical replay content. */
+  pendingUupsReuse: { stepId: string; binding: PendingReuseBinding }[];
+  forkAudit: ForkAuditEvidence;
+  references: {
+    sourceStepId: string;
+    observations: readonly ReferenceObservation[];
+  }[];
+}
+export interface DeliveryCollection {
+  plan: DeliveryPlan;
+  calldata: CalldataTransactionReview[];
+  preparations: PreparationEntry[];
+  verification: VerificationObservation[];
+  runtimeEvidence: DeliveryRuntimeEvidence;
+}
+async function readCompilerEvidence(compiler: DeliveryCompilerCollector): Promise<CompilerEvidence> {
+  try {
+    return compiler.evidence();
+  } finally {
+    // Full payload rereads can outlast an idle HTTP connection. Yield before
+    // the first collection RPC as well as before returning to its caller.
+    await yieldCompilerIo();
+  }
+}
+/** Strict compiler-owned contribution path. Header identities are still launcher-owned until aggregate c.2. */
+export async function collectCompilerQualifiedDeliveryPlan(
+  input: Parameters<typeof collectDeliveryPlan>[0] & { compiler: DeliveryCompilerCollector },
+): Promise<{ collection: DeliveryCollection; compilerEvidence: CompilerEvidence }> {
+  if (ownedDeliveryCompiler(input.context.runtime.hre) !== input.compiler) throw new Error('Compiler-qualified collection requires its actual owned HRE collector');
+  await readCompilerEvidence(input.compiler);
+  const collection = await collectDeliveryPlan(input);
+  return { collection, compilerEvidence: await readCompilerEvidence(input.compiler) };
+}
+export interface DeliveryPlanningOptions {
+  context: DeliveryStepContext;
+  header: DeliveryPlanHeader;
+  identities: PlanningIdentityPort;
+  steps: readonly WorkflowStep[];
+  derivationSeed: string;
+  expected?: Pick<DeliveryCollection, "plan" | "preparations" | "verification"> & Partial<Pick<DeliveryCollection, 'calldata'>>;
+  completedTransactions?: CompletedExecutionTransaction[];
+  customSession?: CustomPlanningInputSession;
+}
+export interface StagedDeliveryCollection {
+  readonly payload: Omit<DeliveryPlanBody,'inputsHash'>;
+  readonly invariantHash:string;
+  readonly snapshot: {payload:Omit<DeliveryPlanBody,'inputsHash'>;calldata:CalldataTransactionReview[];preparations:PreparationEntry[];verification:VerificationObservation[];runtimeEvidence:Omit<DeliveryRuntimeEvidence,'forkAudit'>&{forkAudit:Omit<ForkAuditEvidence,'planHash'|'evidenceHash'>}};
+  assertUnchanged(): Promise<void>;
+  bind(inputsHash:string): DeliveryCollection;
+  close():void;
+}
+export async function collectDeliveryPlan(input:DeliveryPlanningOptions):Promise<DeliveryCollection> {
+  return collectOwned(input,false) as Promise<DeliveryCollection>;
+}
+/** Internal worker seam. JSON cannot manufacture this live interval/closure authority. */
+export async function stageDeliveryPlan(input:Omit<DeliveryPlanningOptions,'header'|'identities'> & {
+  header:Omit<DeliveryPlanHeader,'inputsHash'>;
+  identities:Omit<PlanningIdentityPort,'read'> & {read():Promise<Omit<DeliveryPlanHeader,'inputsHash'>>};
+}):Promise<StagedDeliveryCollection> {
+  assertOwnedTargetWorker();
+  if(input.expected)throw new Error('Staged replay requires independently closed current inputs; use known-final collection');
+  if(input.context.pendingUupsReuse)throw new Error('Unknown aggregate inputs cannot authorize pending reuse');
+  const hash='0'.repeat(64);
+  return collectOwned({...input,header:{...input.header,inputsHash:hash},identities:{...input.identities,read:async()=>({...await input.identities.read(),inputsHash:hash})}},true) as Promise<StagedDeliveryCollection>;
+}
+async function collectOwned(input:DeliveryPlanningOptions,staging:boolean):Promise<DeliveryCollection|StagedDeliveryCollection> {
+  const sourceSteps = strictData(input.steps);
+  const header = parseDeliveryPlanHeader(input.header),
+    context = input.context;
+  if (context.mode !== "simulate")
+    throw new Error("Delivery planning requires simulate mode");
+  if (context.target.create2?.scheme && context.target.create2.scheme !== "evm")
+    throw new Error("Delivery planning requires EVM");
+  if (new Set(sourceSteps.map((s) => s.id)).size !== input.steps.length)
+    throw new Error("Duplicate selected step IDs");
+  assertLocalForkRuntime(context.runtime);
+  if (
+    context.executionId !== header.executionId ||
+    context.taskId !== header.deploymentId ||
+    context.targetId !== header.target ||
+    context.signerAddress?.toLowerCase() !== header.operator ||
+    !context.signer ||
+    (await context.signer.getAddress()).toLowerCase() !== header.operator
+  )
+    throw new Error("Delivery context/header/operator identity mismatch");
+  const snapshot = context.simulation.snapshot;
+  if (
+    !snapshot ||
+    !Number.isSafeInteger(snapshot.blockNumber) ||
+    snapshot.blockNumber < 0 ||
+    !/^0x[\da-fA-F]{64}$/.test(snapshot.blockHash)
+  )
+    throw new Error("Delivery planning requires pinned fork identity");
+  const pinned = {
+    blockNumber: snapshot.blockNumber,
+    blockHash: snapshot.blockHash.toLowerCase(),
+  };
+  const verifyIdentities = async () => {
+    assertLocalForkRuntime(context.runtime);
+    const [identity, source, local, network] = await Promise.all([
+      input.identities.read(),
+      input.identities.readSourceBlock(pinned.blockNumber),
+      context.runtime.hre.network.provider.request({
+        method: "eth_getBlockByNumber",
+        params: [`0x${pinned.blockNumber.toString(16)}`, false],
+      }),
+      context.runtime.hre.ethers.provider.getNetwork(),
+    ]);
+    if (
+      canonicalJson(parseDeliveryPlanHeader(identity)) !== canonicalJson(header)
+    )
+      throw new Error("Planning source/input/runtime identity drift");
+    if (
+      network.chainId.toString() !== header.chainId ||
+      source.chainId !== header.chainId ||
+      source.blockNumber !== pinned.blockNumber ||
+      source.blockHash.toLowerCase() !== pinned.blockHash ||
+      !local ||
+      typeof local !== "object" ||
+      (local as { hash?: string }).hash?.toLowerCase() !== pinned.blockHash
+    )
+      throw new Error("Planning pinned fork/source identity mismatch");
+  };
+  await verifyIdentities();
+  await createDeliveryValidation(context).preflight(
+    sourceSteps.filter((step) => step.kind !== "custom")
+  );
+  const audit = await LocalForkAudit.start({
+    provider: context.runtime.hre.network.provider,
+    chainId: header.chainId,
+    sourceSnapshot: pinned,
+  });
+  let retained=false;
+  try {
+    const expected =
+      input.expected && parseDeliveryPlan(input.expected.plan, header);
+    const journalIdentity = {
+      target: header.target,
+      chainId: header.chainId,
+      expectedStepIds: expected?.deploymentBindings.map((b) => b.stepId) ?? [],
+    };
+    const prior =
+      expected &&
+      parsePreparationJournal(
+        input.expected!.preparations,
+        expected.transactions,
+        expected.derivedBindings,
+        journalIdentity
+      );
+    const bindings = new DeliveryExecutionBindings({
+      executionId: header.executionId,
+      derivationSeed: input.derivationSeed,
+      expected: expected?.derivedBindings,
+    });
+    const planner = new TransactionPlanner({
+      operator: header.operator,
+      expectedTransactions: expected?.transactions,
+      replayCompletedPrefix: true,
+      completedTransactions: input.completedTransactions,
+    });
+    const preparations = new PreparationJournal({
+      ...journalIdentity,
+      expectedStepIds: [],
+      expected: prior,
+      qualifiedSameFork: initial => hasCompilerSameForkInitial(context.runtime.hre,initial),
+    });
+    const verification = new VerificationJournal([]);
+    const pendingObservations: DeliveryRuntimeEvidence["pendingUupsReuse"] = [];
+    const callReviews = new Map<string, CalldataTransactionReview>();
+    const operationIds = new DeliveryOperationIdentities();
+    const references: DeliveryRuntimeEvidence["references"] = [];
+    const customBindings: CustomEvidence[] = [],
+      executed: WorkflowStep[] = [];
+    const session = sourceSteps.some((step) => step.kind === "custom")
+      ? ownedCustomSession(
+          input.customSession ??
+            new CustomPlanningSession({
+              root: context.root,
+              businessRoot: context.taskDir,
+              params: context.targetParams,
+              target: context.target,
+              state: () => context.state.snapshot(),
+            }),
+          context.root,
+          context.taskDir
+        )
+      : undefined;
+    const pendingUupsReuse = context.pendingUupsReuse;
+    const stepContext: DeliveryStepContext = {
+      ...context,
+      deploymentRecorder: undefined,
+      bindings,
+      preparations,
+      verification,
+      calldataReview: { record(tx, intent) {
+        if (callReviews.has(tx.transactionId)) throw Error('Duplicate calldata ABI intent');
+        callReviews.set(tx.transactionId, reviewTransaction(tx, createCalldataInvocation({ ...intent, data: tx.data })));
+      } },
+      executionPlanner: planner,
+      transactionIdentity: operationIds,
+      transactionObserver: audit,
+      runtime: {
+        ...context.runtime,
+        localFork: {
+          ...context.runtime.localFork!,
+          impersonate: (address) =>
+            audit.setup(address, () =>
+              context.runtime.localFork!.impersonate(address)
+            ),
+        },
+      },
+      pendingUupsReuse: pendingUupsReuse && {
+        resolve: async (query) => {
+          const resolution = await pendingUupsReuse.resolve(query);
+          if (resolution?.binding)
+            pendingObservations.push({
+              stepId: query.stepId,
+              binding: canonicalData(
+                resolution.binding
+              ) as unknown as PendingReuseBinding,
+            });
+          return resolution;
+        },
+      },
+    };
+    for (const sourceStep of sourceSteps) {
+      let operations: readonly WorkflowStep[];
+      if (sourceStep.kind === "custom") {
+        const evidence = parseCustomEvidence(
+          await session!.evaluate(sourceStep)
+        );
+        if (evidence.sourceStepId !== sourceStep.id)
+          throw new Error("Custom session source identity mismatch");
+        customBindings.push(evidence);
+        operations = evidence.operations;
+      } else operations = [sourceStep];
+      // Register and validate the complete emitted list before dispatching its first operation.
+      const steps: WorkflowStep[] = operations.map((operation) => ({
+        ...operation,
+        id: operationIds.register(
+          sourceStep.id,
+          sourceStep.kind === "custom" ? operation.id : null,
+          operation.kind
+        ),
+      }));
+      preparations.declare(
+        steps
+          .filter((s) => s.kind === "deploy" || s.kind === "upgrade")
+          .map((s) => s.id)
+      );
+      verification.declare(
+        steps
+          .filter((s) => s.kind === "check")
+          .flatMap((s) => {
+            if (!Array.isArray(s.calls) || !s.calls.length)
+              throw new Error(`Check ${s.id} requires calls`);
+            return s.calls.map((_, callIndex) => ({
+              stepId: s.id,
+              callIndex,
+              assertionId: `${s.id}:${callIndex}`,
+            }));
+          })
+      );
+      executed.push(...steps);
+      const result = await runDeliverySteps(stepContext, steps);
+      references.push({
+        sourceStepId: sourceStep.id,
+        observations: result.references,
+      });
+    }
+    await verifyIdentities();
+    const transactions = planner.complete(),
+      derivedBindings = bindings.seal();
+    const prepared = preparations.seal(transactions, derivedBindings),
+      observations = verification.seal();
+    for (const review of await preparationCalldataReviews(prepared, transactions, context.runtime.hre.artifacts)) {
+      if (callReviews.has(review.transactionId)) throw Error('Duplicate calldata preparation intent');
+      callReviews.set(review.transactionId, review);
+    }
+    const calldata = parseCalldataReviews(transactions.map(tx => callReviews.get(tx.transactionId)), transactions);
+    if (input.expected?.calldata && canonicalJson(parseCalldataReviews(input.expected.calldata, transactions)) !== canonicalJson(calldata)) throw Error('Replayed calldata ABI intent differs');
+    const {inputsHash:knownHash,...base}=header;
+    const payload = deepFreeze({
+      ...base,
+      transactions,
+      derivedBindings,
+      operationBindings: operationIds.seal(),
+      transactionBindings: bindDeliveryTransactions(
+        transactions,
+        operationIds.seal()
+      ),
+      customBindings,
+      customInputClosure: session?.seal() ?? null,
+      deploymentBindings: prepared.map((p) => ({
+        stepId: p.stepId,
+        preparationHash: p.preparationHash,
+        transactionIds: p.mappings.map((m) => m.transactionId),
+        derivedKeys: p.derivedKeys,
+      })),
+      verificationBindings: executed
+        .filter((s) => s.kind === "check")
+        .map((s) => {
+          const checks = observations.filter((o) => o.stepId === s.id);
+          return {
+            stepId: s.id,
+            assertionIds: checks.map((o) => o.assertionId),
+            verificationHash: semanticHash(checks),
+          };
+        }),
+    });
+    if (input.expected && canonicalJson(input.expected.verification.map(parseVerificationObservation)) !== canonicalJson(observations))
+      throw new Error("Replayed verification evidence differs");
+    session?.closeReads();
+    const interval=await audit.capture({transactions,completedTransactions:input.completedTransactions??[]});
+    const stagedSnapshot=deepFreeze({payload,calldata,preparations:prepared,verification:observations,runtimeEvidence:{pendingUupsReuse:pendingObservations,forkAudit:interval.snapshot,references}});
+    const invariantHash=semanticHash(stagedSnapshot);
+    let state:'staged'|'bound'|'failed'|'closed'='staged';
+    const open=()=>{if(state!=='staged')throw new Error('Staged collection closed or already bound');};
+    const bind=(inputsHash:string):DeliveryCollection=>{
+      open(); state='failed';
+      const plan=sealDeliveryPlan({...payload,inputsHash});
+      if(expected&&plan.planHash!==expected.planHash)throw new Error('Replayed delivery plan differs from expected plan');
+      const forkAudit=interval.bind(plan.planHash);
+      const result=deepFreeze(canonicalData({plan,calldata,preparations:prepared,verification:observations,
+        runtimeEvidence:{pendingUupsReuse:pendingObservations,forkAudit,references}}) as unknown as DeliveryCollection);
+      if(collectionInvariantHash(result)!==invariantHash)throw new Error('Binding changed staged collection payload');
+      state='bound';return result;
+    };
+    const check=async()=>{
+      open();
+      try {
+        await verifyIdentities();await interval.assertUnchanged();
+        if(session&&canonicalJson(session.seal())!==canonicalJson(payload.customInputClosure))throw new Error('Custom input closure drift at collection completion');
+      }catch(error){state='failed';throw error;}
+    };
+    if(!staging){await check();return bind(knownHash);}
+    retained=true;
+    return Object.freeze({payload,invariantHash,snapshot:stagedSnapshot,assertUnchanged:check,bind,close(){state='closed';audit.close();}});
+
+  } finally {
+    if(!retained)audit.close();
+  }
+}
+
+/** Comparison only; this hash creates no collection/staging authority. */
+export function collectionInvariantHash(collection:DeliveryCollection):string {
+  const {inputsHash:_,planHash:__,...payload}=collection.plan;
+  const {planHash:___,evidenceHash:____,...forkAudit}=collection.runtimeEvidence.forkAudit;
+  return semanticHash({payload,calldata:collection.calldata,preparations:collection.preparations,verification:collection.verification,runtimeEvidence:{...collection.runtimeEvidence,forkAudit}});
+}

package/runtime/delivery/policy.ts

@@ -0,0 +1,9 @@
+// dist-runtime is a separate CommonJS package boundary. Resolve our built policy by
+// location rather than package self-reference, which is unavailable in a checkout.
+export const validateManifestPolicy: typeof import('gate-evm-tools/delivery-policy').validateManifestPolicy =
+  require('../../dist-cjs/delivery/policy.js').validateManifestPolicy;
+export const validateNetworkAlias: typeof import('gate-evm-tools/delivery-policy').validateNetworkAlias =
+  require('../../dist-cjs/delivery/policy.js').validateNetworkAlias;
+export const isSafeNetworkAlias: typeof import('gate-evm-tools/delivery-policy').isSafeNetworkAlias =
+  require('../../dist-cjs/delivery/policy.js').isSafeNetworkAlias;
+export type { ManifestEnvironment } from 'gate-evm-tools/delivery-policy';

package/runtime/delivery/preparation.ts

@@ -0,0 +1,240 @@
+/** Pure current-artifact consistency, including reuse. This does not attest compiler or OZ layout closure. */
+import { Interface, concat, getCreate2Address } from "ethers";
+import {
+  artifactIdentity,
+  TRANSPARENT_PROXY_ARTIFACT, PROXY_ADMIN_ARTIFACT, PROXY_ADMIN_INTERFACE, transparentAdminAddress,
+  type GateToolArtifact,
+  type GateToolPreparationPlanV1,
+  type GateToolPreparationRequestV1,
+  type GateToolDeploymentPlan,
+  type GateToolAddressPolicy,
+} from "gate-evm-tools/workflow";
+import { canonicalJson } from "../workflow/lib/canonicalData";
+import { canonicalCreate2Hashes } from "../workflow/lib/create2Hashes";
+import { strictData } from "./data";
+import { validateAbiArguments, validateTransactionValue } from "./abi";
+export const ERC1967_PROXY =
+  "@openzeppelin/contracts/proxy/ERC1967/ERC1967Proxy.sol:ERC1967Proxy";
+const factoryInterface = new Interface([
+  "function deploy(bytes32 salt,bytes initCode,bytes data,uint256 create2ForwardValue,uint256 callForwardValue) payable returns(address)",
+]);
+const upgradeInterface = new Interface([
+  "function upgradeToAndCall(address newImplementation,bytes data) payable",
+]);
+export type DeliveryArtifactReader = (
+  name: string,
+) => Promise<GateToolArtifact>;
+export function deliveryArtifact(raw: GateToolArtifact): GateToolArtifact {
+  const artifact = strictData(raw, "delivery artifact");
+  if (
+    artifact._format !== "hh-sol-artifact-1" ||
+    typeof artifact.bytecode !== "string" ||
+    !/^0x(?:[0-9a-fA-F]{2})*$/.test(artifact.bytecode)
+  )
+    throw new Error("Delivery requires actual EVM artifact bytecode");
+  new Interface(artifact.abi);
+  return artifact;
+}
+export function deliveryPreparationData(raw: unknown): unknown {
+  const value = strictData(raw);
+  if (
+    value &&
+    typeof value === "object" &&
+    Object.hasOwn(value, "constructorArgs")
+  ) {
+    const request = value as Record<string, unknown>;
+    for (const key of ["create2ForwardValue", "callForwardValue"])
+      if (Object.hasOwn(request, key)) validateTransactionValue(request[key]);
+  }
+  return value;
+}
+export async function validatePreparationSemantics(
+  request: GateToolPreparationRequestV1,
+  plan: GateToolPreparationPlanV1,
+  read: DeliveryArtifactReader,
+): Promise<void> {
+  strictData(request);
+  strictData(plan);
+  if ((request.scheme ?? "evm") !== "evm" || plan.scheme !== "evm")
+    throw new Error("Delivery preparation requires EVM");
+  if (request.kind === "create2-deploy") {
+    validateTransactionValue(request.create2ForwardValue ?? "0");
+    validateTransactionValue(request.callForwardValue ?? "0");
+    validateTransactionValue(
+      (
+        BigInt(request.create2ForwardValue ?? "0") +
+        BigInt(request.callForwardValue ?? "0")
+      ).toString(),
+    );
+  }
+  const artifact = deliveryArtifact(await read(request.contract));
+  if (
+    canonicalJson(artifactIdentity(artifact, "evm")) !==
+    canonicalJson(plan.artifact)
+  )
+    throw new Error("Actual artifact identity differs from preparation");
+  const deployments: GateToolDeploymentPlan[] = [],
+    transactions: GateToolPreparationPlanV1["transactions"] = [];
+  const role = (
+    name: GateToolDeploymentPlan["role"],
+    a: GateToolArtifact,
+    args: unknown[],
+    salt: string,
+    policy?: GateToolAddressPolicy,
+  ): string => {
+    if (a.bytecode === '0x') throw new Error('Deployment requires non-empty EVM bytecode');
+    validateAbiArguments(a.abi, null, args);
+    const constructorInput = new Interface(a.abi)
+        .encodeDeploy(args)
+        .toLowerCase(),
+      initCode = concat([a.bytecode, constructorInput]);
+    const hash = canonicalCreate2Hashes({ scheme: "evm", artifact: a, args });
+    if (hash.scheme !== "evm") throw new Error("Invalid CREATE2 scheme");
+    const address = getCreate2Address(
+      request.factory,
+      salt,
+      hash.initCodeHash,
+    ).toLowerCase();
+    if (
+      policy?.expectedAddress &&
+      policy.expectedAddress.toLowerCase() !== address
+    )
+      throw new Error("Actual CREATE2 address differs from expectedAddress");
+    if (
+      policy?.leadingZeroBytes !== undefined &&
+      (!Number.isSafeInteger(policy.leadingZeroBytes) ||
+        policy.leadingZeroBytes < 0 ||
+        policy.leadingZeroBytes > 20 ||
+        !address.slice(2).startsWith("00".repeat(policy.leadingZeroBytes)))
+    )
+      throw new Error("Actual CREATE2 address violates leadingZeroBytes");
+    const matches = plan.deployments.filter((d) => d.role === name);
+    if (matches.length !== 1) throw new Error("Actual CREATE2 roles differ");
+    const expected = {
+      role: name,
+      address,
+      salt: salt.toLowerCase(),
+      status: matches[0].status,
+      constructorInput,
+      initCodeHash: hash.initCodeHash,
+    };
+    if (canonicalJson(expected) !== canonicalJson(matches[0]))
+      throw new Error("Actual CREATE2 deployment differs from preparation");
+    deployments.push(expected);
+    if (expected.status === "required") {
+      const forward =
+          request.kind === "create2-deploy"
+            ? (request.create2ForwardValue ?? "0")
+            : "0",
+        callForward =
+          request.kind === "create2-deploy"
+            ? (request.callForwardValue ?? "0")
+            : "0";
+      validateTransactionValue(forward);
+      validateTransactionValue(callForward);
+      validateTransactionValue(
+        (BigInt(forward) + BigInt(callForward)).toString(),
+      );
+      const purpose =
+        name === "contract"
+          ? "deploy-contract"
+          : name === "implementation"
+            ? "deploy-implementation"
+            : "deploy-proxy";
+      transactions.push({
+        id: purpose,
+        purpose,
+        to: request.factory.toLowerCase(),
+        operation: 0,
+        value: (BigInt(forward) + BigInt(callForward)).toString(),
+        data: factoryInterface
+          .encodeFunctionData("deploy", [
+            salt,
+            initCode,
+            "0x",
+            forward,
+            callForward,
+          ])
+          .toLowerCase(),
+      });
+    }
+    return address;
+  };
+  if (request.kind === "create2-deploy")
+    role(
+      "contract",
+      artifact,
+      request.constructorArgs,
+      request.salt,
+      request.addressPolicy,
+    );
+  else {
+    const implementation = role(
+      "implementation",
+      artifact,
+      request.constructorArgs,
+      request.implementationSalt,
+      (request.kind === "uups-upgrade" || request.kind === "transparent-upgrade")
+        ? request.implementationAddressPolicy
+        : undefined,
+    );
+    if(request.kind === 'transparent-deploy' || request.kind === 'transparent-upgrade'){
+      if(request.call)validateAbiArguments(artifact.abi,request.call.method,request.call.args);
+      const data=request.call?new Interface(artifact.abi).encodeFunctionData(request.call.method,request.call.args):'0x';
+      await read(PROXY_ADMIN_ARTIFACT);
+      const proxy=request.kind==='transparent-deploy'
+        ?role('proxy',deliveryArtifact(await read(TRANSPARENT_PROXY_ARTIFACT)),[implementation,request.proxyAdminOwner,data],request.proxySalt,request.proxyAddressPolicy)
+        :request.proxy.toLowerCase();
+      const admin=transparentAdminAddress(proxy);
+      if(plan.proxyKind!=='transparent'||plan.proxyAdmin?.address!==admin||plan.proxyAdmin?.owner!==request.proxyAdminOwner.toLowerCase()
+        ||(request.kind==='transparent-upgrade'&&request.proxyAdmin.toLowerCase()!==admin))throw Error('Actual Transparent admin identity differs from preparation');
+      if(request.kind==='transparent-upgrade')transactions.push({id:'upgrade-proxy',purpose:'upgrade-proxy',to:admin,value:'0',operation:0,
+        data:PROXY_ADMIN_INTERFACE.encodeFunctionData('upgradeAndCall',[proxy,implementation,data]).toLowerCase()});
+      if(request.kind==='transparent-deploy'&&deployments.find(d=>d.role==='proxy')?.status==='reused'&&deployments.some(d=>d.status==='required'))throw Error('Invalid actual Transparent reuse roles');
+    } else {
+    const proxy =
+      request.kind === "uups-placeholder-deploy"
+        ? role(
+            "proxy",
+            deliveryArtifact(await read(ERC1967_PROXY)),
+            [request.placeholderImplementation, "0x"],
+            request.proxySalt,
+            request.proxyAddressPolicy,
+          )
+        : request.proxy.toLowerCase();
+    if (request.call)
+      validateAbiArguments(
+        artifact.abi,
+        request.call.method,
+        request.call.args,
+      );
+    const data = request.call
+      ? new Interface(artifact.abi).encodeFunctionData(
+          request.call.method,
+          request.call.args,
+        )
+      : "0x";
+    if (
+      request.kind === "uups-upgrade" ||
+      deployments.find((d) => d.role === "proxy")?.status === "required"
+    )
+      transactions.push({
+        id: "upgrade-proxy",
+        purpose: "upgrade-proxy",
+        to: proxy,
+        operation: 0,
+        value: "0",
+        data: upgradeInterface
+          .encodeFunctionData("upgradeToAndCall", [implementation, data])
+          .toLowerCase(),
+      });
+    else if (deployments.some((d) => d.status === "required"))
+      throw new Error("Invalid actual UUPS reuse roles");
+    }
+  }
+  if (
+    canonicalJson(deployments) !== canonicalJson(plan.deployments) ||
+    canonicalJson(transactions) !== canonicalJson(plan.transactions)
+  )
+    throw new Error("Actual CREATE2 calldata or roles differ from preparation");
+}

package/runtime/delivery/production-environment.ts

@@ -0,0 +1,7 @@
+/** Remove signing authority, retaining independent model/RPC API configuration. */
+export function productionChildEnvironment(input:NodeJS.ProcessEnv):NodeJS.ProcessEnv {
+ const out={...input};
+ // Also discard the retired alias if it remains in a caller's environment; it is never a signer input.
+ for(const key of Object.keys(out))if(/(^|_)(PRIVATE_KEY|WALLET_CREDENTIAL|MNEMONIC|SEED_PHRASE)$/.test(key)||key==='CUSTODY_API_BASE_URL'||/^GATEFLOW_(OPERATOR_TOKEN|PRODUCTION_|MAC_SECURE_SIGNER_)/.test(key)||/^GATE_(CUSTODY|SIGNER)_/.test(key))delete out[key];
+ return out;
+}