gate-evm-tools 1.0.27 → 1.0.31

package/runtime/delivery/safe-prepare.ts

@@ -0,0 +1,101 @@
+/** Final execution preparation only. Pure exports never import this RPC operation. */
+import { Interface, keccak256 } from "ethers";
+import { deepFreeze, exactObject } from "../workflow/lib/canonicalData";
+import { strictData } from "./data";
+import { uint256 } from "./observations";
+import { rpcQuantity, type EoaRpc, type EoaFinality } from "./eoa-observation";
+import {
+  SAFE_ADAPTER,
+  freezeSafeEnvelope,
+  safeAddress,
+  type SafeEnvelope,
+} from "./safe";
+import { SAFE_RUNTIME_HASHES } from "./safe-manifest";
+import type { DeliveryPlan } from "./plan";
+export interface SafeTarget {
+  adapter: "safe-1.4.1-call-only/v1";
+  multiSendCallOnly: string;
+  safeTxGas: string;
+  submitterPolicy: { kind: "any" };
+}
+export function parseSafeTarget(raw: unknown): SafeTarget {
+  const v = exactObject(
+    strictData(raw),
+    ["adapter", "multiSendCallOnly", "safeTxGas", "submitterPolicy"],
+    "Safe target profile"
+  );
+  if (v.adapter !== SAFE_ADAPTER.id)
+    throw Error("Unsupported Safe target adapter");
+  safeAddress(v.multiSendCallOnly);
+  uint256(v.safeTxGas, "Safe target gas");
+  exactObject(v.submitterPolicy, ["kind"], "Safe target submitter");
+  if ((v.submitterPolicy as any).kind !== "any")
+    throw Error("Unsupported Safe submitter policy");
+  return deepFreeze(v as unknown as SafeTarget);
+}
+export async function prepareSafeEnvelope(
+  plan: DeliveryPlan,
+  start: number,
+  raw: unknown,
+  provider: EoaRpc,
+  finality: EoaFinality
+): Promise<SafeEnvelope> {
+  const profile = parseSafeTarget(raw),
+    first = plan.transactions[start];
+  if (!first || first.route !== "external")
+    throw Error("Current external Safe segment required");
+  let count = 1;
+  while (
+    start + count < plan.transactions.length &&
+    plan.transactions[start + count].route === "external" &&
+    plan.transactions[start + count].executor === first.executor
+  )
+    count++;
+  const request = provider.request.bind(provider);
+  if (rpcQuantity(await request("eth_chainId", [])) !== plan.chainId)
+    throw Error("Safe preparation chain mismatch");
+  const block: any = await request("eth_getBlockByNumber", ["latest", false]);
+  if (!block?.hash || !block?.number)
+    throw Error("Safe preparation block unavailable");
+  const at = { blockHash: block.hash, requireCanonical: true };
+  const slot = await request("eth_getStorageAt", [first.executor, "0x0", at]);
+  if (typeof slot !== "string" || !/^0x[0-9a-fA-F]{64}$/.test(slot))
+    throw Error("Missing Safe singleton slot");
+  const singleton = safeAddress("0x" + slot.slice(-40).toLowerCase());
+  for (const [a, name] of [
+    [first.executor, "SafeProxy"],
+    [singleton, "Safe"],
+    [profile.multiSendCallOnly, "MultiSendCallOnly"],
+  ] as [string, keyof typeof SAFE_RUNTIME_HASHES][]) {
+    const code = await request("eth_getCode", [a, at]);
+    if (
+      typeof code !== "string" ||
+      !/^0x(?:[a-fA-F0-9]{2})+$/.test(code) ||
+      keccak256(code) !== SAFE_RUNTIME_HASHES[name]
+    )
+      throw Error(`Unsupported Safe preparation ${name} identity`);
+  }
+  const iface = new Interface(["function nonce() view returns(uint256)"]);
+  const rawNonce = await request("eth_call", [
+    { to: first.executor, data: iface.encodeFunctionData("nonce") },
+    at,
+  ]);
+  if (typeof rawNonce !== "string") throw Error("Missing Safe nonce");
+  const nonce = iface.decodeFunctionResult("nonce", rawNonce)[0].toString();
+  if (iface.encodeFunctionResult("nonce", [nonce]) !== rawNonce.toLowerCase())
+    throw Error("Noncanonical Safe nonce");
+  const end: any = await request("eth_getBlockByNumber", [block.number, false]);
+  if (end?.hash !== block.hash) throw Error("Safe preparation anchor changed");
+  return freezeSafeEnvelope(plan, {
+    adapter: profile.adapter,
+    start,
+    count,
+    safe: first.executor,
+    singleton,
+    multiSend: profile.multiSendCallOnly,
+    nonce,
+    safeTxGas: profile.safeTxGas,
+    submitter: profile.submitterPolicy,
+    finality,
+  });
+}

package/runtime/delivery/safe.ts

@@ -0,0 +1,344 @@
+/** Pure, finite official Safe 1.4.1 CALL adapter. No provider, signer or file access. */
+import { Interface, TypedDataEncoder, solidityPacked } from "ethers";
+import {
+  canonicalJson,
+  deepFreeze,
+  exactObject,
+  semanticHash,
+} from "../workflow/lib/canonicalData";
+import { immutableDeliveryPlan } from "./export";
+import { strictData } from "./data";
+import { uint256 } from "./observations";
+import type { EoaFinality } from "./eoa-observation";
+import type { DeliveryPlan } from "./plan";
+import { SAFE_RUNTIME_HASHES } from "./safe-manifest";
+export const SAFE_ADAPTER = deepFreeze({
+  id: "safe-1.4.1-call-only/v1",
+  version: "1.4.1",
+  runtime: SAFE_RUNTIME_HASHES,
+  collector: "geth-1.15.11-prestate-opcodes/v1",
+  refund: "zero",
+  maxCalldataBytes: 262144,
+});
+export const SAFE_DEFINITION_HASH = semanticHash(SAFE_ADAPTER);
+export const SAFE_TYPES = {
+  SafeTx: [
+    { name: "to", type: "address" },
+    { name: "value", type: "uint256" },
+    { name: "data", type: "bytes" },
+    { name: "operation", type: "uint8" },
+    { name: "safeTxGas", type: "uint256" },
+    { name: "baseGas", type: "uint256" },
+    { name: "gasPrice", type: "uint256" },
+    { name: "gasToken", type: "address" },
+    { name: "refundReceiver", type: "address" },
+    { name: "nonce", type: "uint256" },
+  ],
+};
+export const SAFE_INTERFACE = new Interface([
+  "function execTransaction(address to,uint256 value,bytes data,uint8 operation,uint256 safeTxGas,uint256 baseGas,uint256 gasPrice,address gasToken,address refundReceiver,bytes signatures) returns (bool)",
+  "event ExecutionSuccess(bytes32 indexed txHash,uint256 payment)",
+  "event ExecutionFailure(bytes32 indexed txHash,uint256 payment)",
+]);
+const multi = new Interface(["function multiSend(bytes transactions)"]);
+export const ZERO_ADDRESS = "0x" + "00".repeat(20);
+export function safeAddress(v: unknown): string {
+  if (
+    typeof v !== "string" ||
+    !/^0x[0-9a-f]{40}$/.test(v) ||
+    v === ZERO_ADDRESS
+  )
+    throw Error("Invalid canonical Safe address");
+  return v;
+}
+export function safeBytes(v: unknown): string {
+  if (
+    typeof v !== "string" ||
+    !/^0x(?:[0-9a-f]{2})*$/.test(v) ||
+    v.length > 2 + SAFE_ADAPTER.maxCalldataBytes * 2
+  )
+    throw Error("Invalid or oversized Safe bytes");
+  return v;
+}
+export function safeFinality(v: unknown): EoaFinality {
+  const f = v as EoaFinality;
+  exactObject(
+    f,
+    f?.kind === "rpc_finalized" ? ["kind"] : ["kind", "depth"],
+    "Safe finality"
+  );
+  if (
+    f.kind !== "rpc_finalized" &&
+    (f.kind !== "confirmations" || BigInt(uint256(f.depth, "depth")) < 1n)
+  )
+    throw Error("Invalid Safe finality");
+  return f;
+}
+export interface SafeBinding {
+  adapter: string;
+  start: number;
+  count: number;
+  safe: string;
+  singleton: string;
+  multiSend: string;
+  nonce: string;
+  safeTxGas: string;
+  submitter: { kind: "any" } | { kind: "address"; address: string };
+  finality: EoaFinality;
+}
+export interface SafeEnvelope extends SafeBinding {
+  schema: "gate-safe-envelope";
+  version: 1;
+  definitionHash: string;
+  executionId: string;
+  planHash: string;
+  chainId: string;
+  transactionIds: string[];
+  to: string;
+  value: string;
+  data: string;
+  operation: 0 | 1;
+  baseGas: string;
+  gasPrice: string;
+  gasToken: string;
+  refundReceiver: string;
+  expectedSafeTxHash: string;
+  envelopeId: string;
+}
+const bindingKeys = [
+  "adapter",
+  "start",
+  "count",
+  "safe",
+  "singleton",
+  "multiSend",
+  "nonce",
+  "safeTxGas",
+  "submitter",
+  "finality",
+];
+export type SafeCall = {
+  to: string;
+  value: string;
+  data: string;
+  operation: 0;
+};
+export function decodeSafeCalls(raw: unknown): SafeCall[] {
+  const data = safeBytes(raw).slice(2);
+  const result: SafeCall[] = [];
+  let cursor = 0;
+  while (cursor < data.length) {
+    if (data.length - cursor < 170) throw Error("Truncated Safe packed call");
+    const operation = data.slice(cursor, cursor + 2);
+    if (operation !== "00") throw Error("Only CALL inner operations supported");
+    const to = safeAddress("0x" + data.slice(cursor + 2, cursor + 42)),
+      value = BigInt("0x" + data.slice(cursor + 42, cursor + 106)).toString(),
+      length = BigInt("0x" + data.slice(cursor + 106, cursor + 170));
+    cursor += 170;
+    if (length > BigInt((data.length - cursor) / 2))
+      throw Error("Truncated Safe packed data length");
+    const end = cursor + Number(length) * 2;
+    result.push({
+      to,
+      value,
+      data: "0x" + data.slice(cursor, end),
+      operation: 0,
+    });
+    cursor = end;
+  }
+  if (!result.length) throw Error("Empty Safe batch");
+  return result;
+}
+export function freezeSafeEnvelope(
+  rawPlan: unknown,
+  raw: unknown
+): SafeEnvelope {
+  const plan = immutableDeliveryPlan(rawPlan),
+    b = exactObject(
+      strictData(raw),
+      bindingKeys,
+      "Safe binding"
+    ) as unknown as SafeBinding;
+  if (b.adapter !== SAFE_ADAPTER.id) throw Error("Unsupported Safe adapter");
+  for (const a of [b.safe, b.singleton, b.multiSend]) safeAddress(a);
+  if (new Set([b.safe, b.singleton, b.multiSend]).size !== 3)
+    throw Error("Safe asset addresses must differ");
+  uint256(b.nonce, "Safe nonce");
+  uint256(b.safeTxGas, "safeTxGas");
+  safeFinality(b.finality);
+  exactObject(
+    b.submitter,
+    b.submitter?.kind === "any" ? ["kind"] : ["kind", "address"],
+    "Safe submitter"
+  );
+  if (b.submitter.kind === "address") safeAddress(b.submitter.address);
+  else if (b.submitter.kind !== "any") throw Error("Invalid Safe submitter");
+  if (
+    !Number.isSafeInteger(b.start) ||
+    !Number.isSafeInteger(b.count) ||
+    b.start < 0 ||
+    b.count < 1 ||
+    b.start + b.count > plan.transactions.length
+  )
+    throw Error("Invalid Safe transaction range");
+  const txs = plan.transactions.slice(b.start, b.start + b.count);
+  if (
+    txs.some(
+      (t) =>
+        t.executor !== b.safe ||
+        t.route !== "external" ||
+        t.operation !== 0 ||
+        [b.safe, b.singleton, b.multiSend].includes(t.to)
+    )
+  )
+    throw Error(
+      "Safe range crosses executor/segment barrier or unsupported nesting"
+    );
+  const calls = txs.map(({ to, value, data }) => ({
+    to,
+    value,
+    data,
+    operation: 0 as const,
+  }));
+  let to = txs[0].to,
+    value = txs[0].value,
+    data = txs[0].data,
+    operation: 0 | 1 = 0;
+  if (b.count > 1) {
+    to = b.multiSend;
+    value = "0";
+    operation = 1;
+    data = multi.encodeFunctionData("multiSend", [
+      "0x" +
+        calls
+          .map((c) =>
+            solidityPacked(
+              ["uint8", "address", "uint256", "uint256", "bytes"],
+              [0, c.to, c.value, BigInt((c.data.length - 2) / 2), c.data]
+            ).slice(2)
+          )
+          .join(""),
+    ]);
+  }
+  safeBytes(data);
+  const body = {
+    ...b,
+    schema: "gate-safe-envelope" as const,
+    version: 1 as const,
+    definitionHash: SAFE_DEFINITION_HASH,
+    executionId: plan.executionId,
+    planHash: plan.planHash,
+    chainId: plan.chainId,
+    transactionIds: txs.map((t) => t.transactionId),
+    to,
+    value,
+    data,
+    operation,
+    baseGas: "0",
+    gasPrice: "0",
+    gasToken: ZERO_ADDRESS,
+    refundReceiver: ZERO_ADDRESS,
+  };
+  const expectedSafeTxHash = TypedDataEncoder.hash(
+    { chainId: plan.chainId, verifyingContract: b.safe },
+    SAFE_TYPES,
+    body
+  );
+  const hashed = { ...body, expectedSafeTxHash };
+  return deepFreeze({ ...hashed, envelopeId: semanticHash(hashed) });
+}
+export function parseSafeEnvelope(
+  raw: unknown,
+  plan: DeliveryPlan
+): SafeEnvelope {
+  const v = strictData(raw) as SafeEnvelope;
+  const e = freezeSafeEnvelope(
+    plan,
+    Object.fromEntries(bindingKeys.map((k) => [k, (v as any)[k]]))
+  );
+  if (canonicalJson(v) !== canonicalJson(e))
+    throw Error("Frozen Safe envelope mismatch");
+  return e;
+}
+const execKeys = [
+  "to",
+  "value",
+  "data",
+  "operation",
+  "safeTxGas",
+  "baseGas",
+  "gasPrice",
+  "gasToken",
+  "refundReceiver",
+];
+export function encodeSafeExec(
+  e: Pick<
+    SafeEnvelope,
+    | "to"
+    | "value"
+    | "data"
+    | "operation"
+    | "safeTxGas"
+    | "baseGas"
+    | "gasPrice"
+    | "gasToken"
+    | "refundReceiver"
+  >,
+  signatures: string
+): string {
+  return SAFE_INTERFACE.encodeFunctionData("execTransaction", [
+    ...execKeys.map((k) => (e as any)[k]),
+    safeBytes(signatures),
+  ]);
+}
+export function verifySafeExec(
+  plan: DeliveryPlan,
+  raw: unknown,
+  input: unknown
+) {
+  const e = parseSafeEnvelope(raw, plan),
+    data = safeBytes(input);
+  const decoded = SAFE_INTERFACE.decodeFunctionData("execTransaction", data);
+  if (
+    SAFE_INTERFACE.encodeFunctionData(
+      "execTransaction",
+      decoded
+    ).toLowerCase() !== data
+  )
+    throw Error("Noncanonical Safe calldata");
+  if (encodeSafeExec(e, decoded[9]) !== data)
+    throw Error("Actual Safe envelope mismatch");
+  let calls: SafeCall[];
+  if (e.operation === 0)
+    calls = [{ to: e.to, value: e.value, data: e.data, operation: 0 }];
+  else {
+    const packed = multi.decodeFunctionData("multiSend", e.data);
+    if (multi.encodeFunctionData("multiSend", packed) !== e.data)
+      throw Error("Noncanonical MultiSend calldata");
+    calls = decodeSafeCalls(packed[0]);
+  }
+  const expected = plan.transactions
+    .slice(e.start, e.start + e.count)
+    .map(({ to, value, data }) => ({ to, value, data, operation: 0 }));
+  if (canonicalJson(calls) !== canonicalJson(expected))
+    throw Error("Safe calls differ from full frozen range");
+  return { envelope: e, calls, signatures: decoded[9] as string };
+}
+export function renderSafeExport(rawPlan: unknown, raw: unknown) {
+  const plan = immutableDeliveryPlan(rawPlan),
+    envelope = parseSafeEnvelope(raw, plan),
+    model = deepFreeze({
+      schema: "gate-safe-export",
+      version: 1,
+      status: "artifact-delivered",
+      plan,
+      envelope,
+      unsignedExecTransaction: encodeSafeExec(envelope, "0x"),
+    });
+  const json = canonicalJson(model);
+  return deepFreeze({
+    model,
+    json,
+    markdown: `# Safe calldata\n\nFrozen Safe envelope. Signatures must be collected externally.\n\n\`\`\`json\n${json}\n\`\`\`\n`,
+  });
+}

package/runtime/delivery/same-fork-baseline.ts

@@ -0,0 +1,16 @@
+import { hashPreparationRequest, normalizePreparationPlan, normalizePreparationRequest, type GateToolPreparationPlanV1, type GateToolPreparationRequestV1 } from 'gate-evm-tools/workflow';
+import { semanticHash } from '../workflow/lib/canonicalData';
+
+export interface SameForkInitialPreparation { request: GateToolPreparationRequestV1; plan: GateToolPreparationPlanV1; }
+/** Stable initial preparation and full prior layout commitment. Auxiliary compiler randomness is excluded. */
+export function sameForkBaselineDigest(initial: SameForkInitialPreparation, oldLayoutHash: string): string {
+  const request = normalizePreparationRequest(initial.request), plan = normalizePreparationPlan(initial.plan);
+  if (request.kind !== 'uups-placeholder-deploy' || plan.kind !== request.kind || plan.requestHash !== hashPreparationRequest(request)
+    || plan.target !== request.target || !/^[a-f0-9]{64}$/.test(oldLayoutHash)) throw new Error('Invalid same-fork initial preparation');
+  return semanticHash({kind:'same-fork',request,plan,oldLayoutHash});
+}
+export function matchesSameForkInitial(initial: SameForkInitialPreparation, target: string, chainId: string, proxy: string, implementation?: string): boolean {
+  return initial.request.kind === 'uups-placeholder-deploy' && initial.request.target === target && initial.plan.target === target && initial.plan.chainId === chainId
+    && initial.plan.deployments.some(d => d.role === 'proxy' && d.address.toLowerCase() === proxy.toLowerCase())
+    && (implementation === undefined || initial.plan.deployments.some(d => d.role === 'implementation' && d.address.toLowerCase() === implementation.toLowerCase()));
+}

package/runtime/delivery/setup.ts

@@ -0,0 +1,172 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { createRequire } from 'node:module';
+import { spawnSync } from 'node:child_process';
+import YAML from 'yaml';
+import { object } from './protocol';
+import { coreMarker, projectRoot, readFile, confinedFile, stat, integratedConfig, readProjectNetworkSnapshots, projectSourcesDirectory } from './project';
+import { configDocument, validateDeliveryTarget, type DeliveryTarget } from './config';
+export { readProjectNetworkSnapshots } from './project';
+export { loadDeliveryTarget } from './config';
+export { configureDeliveryEnvironment } from './manifest';
+export type { DeliveryTarget, DeliveryTargetConfig } from './config';
+
+const TOOLCHAIN: Record<string, string> = { hardhat: '2.26.3', ethers: '6.15.0', '@nomicfoundation/hardhat-ethers': '3.1.0', typescript: '5.9.3', 'ts-node': '10.9.2' };
+const DEPENDENCIES: Record<string, string> = { 'gate-evm-tools': '1.0.29', '@openzeppelin/hardhat-upgrades': '3.9.1', '@openzeppelin/upgrades-core': '1.44.2', '@openzeppelin/contracts': '5.4.0' };
+export interface DeliverySetupOptions {
+  workspaceRoot: string;
+  projectRoot: string;
+  targets: DeliveryTarget[];
+  /** An explicit local built tarball for unpublished delivery APIs. Never installed implicitly. */
+  toolPackage?: string;
+}
+export interface DeliveryInspection {
+  status: 'dependencies_pending' | 'setup_pending' | 'ready';
+  projectRoot: string;
+  dependencies: Array<{ name: string; required: string; reason: string }>;
+  changes: string[];
+  networks: Array<{ network: string; chainId: number; rpcConfigured: boolean }>;
+}
+function dependencyTreeProblem(root: string): string | undefined {
+  const result = spawnSync(process.platform === 'win32' ? 'npm.cmd' : 'npm',
+    ['ls', '--all', '--long', '--json', '--depth=Infinity', '--link=false', '--global=false', '--workspaces=false', '--include=dev', '--include=optional', '--include=peer'],
+    { cwd: root, encoding: 'utf8', timeout: 30000, maxBuffer: 16 * 1024 * 1024 });
+  if (result.error || result.status !== 0) return 'local dependency graph is incomplete or invalid; install project dependencies explicitly';
+  try {
+    const visit = (entry: { path?: string; dependencies?: Record<string, unknown> }, top = false): void => {
+      if (entry.path && !top) {
+        const actual = fs.realpathSync(entry.path);
+        if (!actual.startsWith(path.join(root, 'node_modules') + path.sep)) throw new Error('dependency resolves outside project node_modules');
+      }
+      for (const dependency of Object.values(entry.dependencies ?? {})) visit(dependency as typeof entry);
+    };
+    visit(JSON.parse(result.stdout), true);
+    return undefined;
+  } catch { return 'dependency graph contains a missing or nonlocal package'; }
+}
+function businessUsesUpgradeable(root: string): boolean {
+  const contracts = projectSourcesDirectory(root);
+  const visit = (dir: string): boolean => {
+    if (!stat(dir)) return false;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isSymbolicLink()) throw new Error('Business source symlinks cannot be inspected safely');
+      const file = path.join(dir, entry.name);
+      if (entry.isDirectory() ? visit(file) : entry.isFile() && entry.name.endsWith('.sol') && /["']@openzeppelin\/contracts-upgradeable\//.test(fs.readFileSync(file, 'utf8'))) return true;
+    }
+    return false;
+  };
+  return visit(contracts);
+}
+function preflight(input: DeliverySetupOptions): { result: DeliveryInspection; writes: Map<string, string>; before: Map<string, string | undefined> } {
+  const [major,minor]=process.versions.node.split('.').map(Number);if(major<22||(major===22&&minor<13))throw Error('Delivery requires Node >=22.13.0');
+  object(input, 'setup options', ['workspaceRoot', 'projectRoot', 'targets', 'toolPackage']);
+  if (!Array.isArray(input.targets) || !input.targets.length) throw new Error('Selected delivery targets are required');
+  const targets = input.targets.map(validateDeliveryTarget);
+  if (new Set(targets.map(target => target.network)).size !== targets.length) throw new Error('Duplicate selected target');
+  const root = projectRoot(input.workspaceRoot, input.projectRoot);
+  coreMarker(root);
+  const before = new Map<string, string | undefined>();
+  for (const file of ['.gate-template.json', 'package.json', 'hardhat.config.ts', 'config.yaml', 'contractInfo.json']) before.set(file, readFile(root, file));
+  const pkg = object(JSON.parse(before.get('package.json') ?? 'null'), 'package.json');
+  const declarations: Record<string, unknown> = {};
+  for (const section of ['dependencies', 'devDependencies']) {
+    const entries = pkg[section] === undefined ? {} : object(pkg[section], section);
+    for (const [name, value] of Object.entries(entries)) {
+      if (name in declarations && declarations[name] !== value) throw new Error(`Dependency declaration conflict: ${name}`);
+      declarations[name] = value;
+    }
+  }
+  const required = { ...DEPENDENCIES };
+  if (input.toolPackage !== undefined) {
+    if (!path.isAbsolute(input.toolPackage) || !input.toolPackage.endsWith('.tgz') || !stat(input.toolPackage)?.isFile() || stat(input.toolPackage)?.isSymbolicLink()) throw new Error('toolPackage must be an explicit absolute local tarball path');
+    required['gate-evm-tools'] = `file:${input.toolPackage}`;
+  }
+  if (businessUsesUpgradeable(root)) required['@openzeppelin/contracts-upgradeable'] = '5.4.0';
+  for (const [name, version] of Object.entries({ ...TOOLCHAIN, ...required })) {
+    const declared = declarations[name];
+    // Preserve an existing explicit local tarball declaration when rerunning after installation.
+    const localTool = name === 'gate-evm-tools' && input.toolPackage === undefined && typeof declared === 'string' && /^file:.*\.tgz$/.test(declared);
+    if ((name in TOOLCHAIN && declared === undefined) || (declared !== undefined && declared !== version && !localTool)) throw new Error(`Dependency declaration conflict for ${name}: expected ${version}`);
+  }
+  const networks = readProjectNetworkSnapshots(root, targets.map(target => target.network));
+  const source = before.get('hardhat.config.ts')!;
+  const withPlugin = integratedConfig(source); // Check integration conflicts even when dependencies are missing.
+  const doc = configDocument(root);
+  let changedYaml = before.get('config.yaml') === undefined;
+  const merge = (keys: string[], expected: unknown): void => {
+    const actual = doc.getIn(keys, true);
+    if (actual === undefined) { doc.setIn(keys, expected); changedYaml = true; return; }
+    if (expected && typeof expected === 'object' && !Array.isArray(expected)) {
+      if (!YAML.isMap(actual)) throw new Error(`Config conflict at ${keys.join('.')}`);
+      for (const [key, value] of Object.entries(expected)) merge([...keys, key], value);
+    } else if (!YAML.isScalar(actual) || actual.value !== expected) throw new Error(`Config conflict at ${keys.join('.')}`);
+  };
+  for (const { network, ...target } of targets) {
+    confinedFile(root, target.openzeppelin!.manifestDir, 'directory');
+    merge([network], target);
+  }
+  if (before.get('contractInfo.json') !== undefined) object(JSON.parse(before.get('contractInfo.json')!), 'contractInfo.json');
+  const dependencies: DeliveryInspection['dependencies'] = [];
+  const projectRequire = createRequire(path.join(root, 'package.json'));
+  for (const [name, requested] of Object.entries({ ...TOOLCHAIN, ...required })) {
+    const metadata = confinedFile(root, `node_modules/${name}/package.json`);
+    if (!stat(metadata)) { dependencies.push({ name, required: requested, reason: 'not installed locally' }); continue; }
+    const installed = JSON.parse(fs.readFileSync(metadata, 'utf8'));
+    const expected = name === 'gate-evm-tools' ? DEPENDENCIES[name] : requested;
+    if (installed.name !== name || installed.version !== expected) throw new Error(`Installed dependency conflict for ${name}: expected ${expected}`);
+    if (name !== 'gate-evm-tools') {
+      const entry = name === '@openzeppelin/contracts' ? `${name}/proxy/ERC1967/ERC1967Proxy.sol`
+        : name === '@openzeppelin/contracts-upgradeable' ? `${name}/package.json` : name;
+      try {
+        const resolved = fs.realpathSync(projectRequire.resolve(entry));
+        if (!stat(resolved)?.isFile() || !resolved.startsWith(path.join(root, 'node_modules') + path.sep)) throw new Error('nonlocal entry');
+      } catch {
+        dependencies.push({ name, required: requested, reason: 'required entry point is missing or nonlocal' });
+      }
+    }
+    if (name === 'gate-evm-tools') {
+      try {
+        for (const entry of ['delivery-setup', 'delivery-protocol', 'delivery-hardhat', 'delivery-policy']) {
+          const resolved = projectRequire.resolve(`gate-evm-tools/${entry}`);
+          if (!resolved.startsWith(path.join(root, 'node_modules') + path.sep)) throw new Error('nonlocal API');
+        }
+      } catch { dependencies.push({ name, required: requested, reason: 'installed package lacks delivery API exports; install a built delivery package' }); }
+    }
+  }
+  if (!dependencies.length) {
+    const reason = dependencyTreeProblem(root);
+    if (reason) dependencies.push({ name: 'dependency-tree', required: 'complete local dependency graph', reason });
+  }
+  const writes = new Map<string, string>();
+  const missing = Object.entries(required).filter(([name]) => declarations[name] === undefined);
+  if (missing.length) {
+    const dev = { ...(pkg.devDependencies as Record<string, unknown> ?? {}) };
+    for (const [name, version] of missing) dev[name] = version;
+    writes.set('package.json', JSON.stringify({ ...pkg, devDependencies: dev }, null, 2) + '\n');
+  }
+  if (changedYaml) writes.set('config.yaml', doc.toString());
+  if (before.get('contractInfo.json') === undefined) writes.set('contractInfo.json', '{}\n');
+  if (!dependencies.length && source !== withPlugin) writes.set('hardhat.config.ts', withPlugin);
+  return { before, writes, result: { status: dependencies.length ? 'dependencies_pending' : writes.size ? 'setup_pending' : 'ready', projectRoot: root, dependencies, changes: [...writes.keys()],
+    networks: networks.map(({ network, chainId, url }) => ({ network, chainId, rpcConfigured: Boolean(url) })) } };
+}
+/** Read-only, never imports the project's config/HRE or contacts an RPC. */
+export function inspectDeliveryProject(options: DeliverySetupOptions): DeliveryInspection { return preflight(options).result; }
+/** Stage declarations/config; caller explicitly installs dependencies then reruns to enable the plugin. */
+export function setupDeliveryProject(options: DeliverySetupOptions): DeliveryInspection {
+  const { result, writes, before } = preflight(options);
+  const root = projectRoot(options.workspaceRoot, options.projectRoot);
+  // Recheck every output before the first write, including concurrent human edits.
+  for (const [file, content] of before) if (readFile(root, file) !== content) throw new Error(`Concurrent setup conflict: ${file}`);
+  for (const [file, contents] of writes) {
+    const destination = confinedFile(root, file);
+    const temporary = confinedFile(root, `.gate-delivery-${crypto.randomUUID()}.tmp`);
+    try {
+      fs.writeFileSync(temporary, contents, { flag: 'wx' });
+      if (readFile(root, file) !== before.get(file)) throw new Error(`Concurrent setup conflict: ${file}`);
+      fs.renameSync(temporary, destination);
+    } finally { if (stat(temporary)) fs.unlinkSync(temporary); }
+  }
+  return { ...result, status: result.dependencies.length ? 'dependencies_pending' : 'ready' };
+}