gate-evm-tools 1.0.26 → 1.0.28

package/runtime/config/openzeppelin.ts

@@ -0,0 +1,173 @@
+import fs from "fs";
+import path from "path";
+import YAML from "yaml";
+import { parseForkSnapshotJson } from "../workflow/lib/forkSnapshot";
+
+export type DeploymentEnvironment = "local" | "development" | "production";
+
+export interface OpenZeppelinTargetConfig {
+  environment: DeploymentEnvironment;
+  openzeppelin?: { manifestDir?: unknown };
+}
+
+const TARGET_ENVIRONMENTS = new Set<DeploymentEnvironment>([
+  "local",
+  "development",
+  "production",
+]);
+const SAFE_MANIFEST_DIR = /^\.openzeppelin(?:\.[a-z0-9][a-z0-9-]*)?$/;
+
+const assertConfinedManifestDirectory = (root: string, manifestDir: string): void => {
+  const rootPath = fs.realpathSync(root);
+  const candidatePath = path.resolve(root, manifestDir);
+  if (path.dirname(candidatePath) !== path.resolve(root)) {
+    throw new Error(`OpenZeppelin manifest directory escapes the project: ${manifestDir}`);
+  }
+  if (!fs.existsSync(candidatePath)) return;
+
+  const realCandidate = fs.realpathSync(candidatePath);
+  const relative = path.relative(rootPath, realCandidate);
+  if (relative === "" || relative.startsWith(`..${path.sep}`) || relative === ".." || path.isAbsolute(relative)) {
+    throw new Error(`OpenZeppelin manifest symlink resolves outside the project: ${manifestDir}`);
+  }
+};
+
+export function resolveOpenZeppelinManifestDir(
+  root: string,
+  network: string,
+  target: OpenZeppelinTargetConfig,
+): string {
+  if (!TARGET_ENVIRONMENTS.has(target?.environment)) {
+    throw new Error(`Network ${network} must declare a valid deployment environment`);
+  }
+  const manifestDir = target.openzeppelin?.manifestDir;
+  if (typeof manifestDir !== "string" || !SAFE_MANIFEST_DIR.test(manifestDir)) {
+    throw new Error(`Network ${network} must declare one safe OpenZeppelin manifest directory segment`);
+  }
+  if (target.environment === "production" && manifestDir !== ".openzeppelin") {
+    throw new Error(`Production network ${network} must use exactly .openzeppelin`);
+  }
+  if (target.environment !== "production" && manifestDir === ".openzeppelin") {
+    throw new Error(`Non-production network ${network} must not use .openzeppelin`);
+  }
+  assertConfinedManifestDirectory(root, manifestDir);
+  return manifestDir;
+}
+
+export function loadOpenZeppelinManifestDir(root: string, network: string): string {
+  const configPath = path.join(root, "config.yaml");
+  const config = YAML.parse(fs.readFileSync(configPath, "utf8"), { merge: true }) as unknown;
+  if (!config || typeof config !== "object" || Array.isArray(config)) {
+    throw new Error("config.yaml must define network keys at the top level");
+  }
+  const target = (config as Record<string, unknown>)[network];
+  if (!target || typeof target !== "object" || Array.isArray(target) || network.startsWith("_")) {
+    throw new Error(`Missing config.yaml entry for network "${network}"`);
+  }
+  return resolveOpenZeppelinManifestDir(
+    root,
+    network,
+    target as OpenZeppelinTargetConfig,
+  );
+}
+
+export function resolveEffectiveManifestTarget(input: {
+  network: string;
+  mode?: string;
+  target?: string;
+  env?: NodeJS.ProcessEnv;
+}): string {
+  const network = input.network.trim();
+  const target = input.target?.trim();
+  const env = input.env ?? process.env;
+  if (!network) throw new Error("Hardhat network is required to resolve the OpenZeppelin manifest");
+  if (input.mode === "simulate" && network === "hardhat" && !target) {
+    throw new Error("Target is required for a Hardhat fork simulation");
+  }
+  if (network === "zkFork" && !target) {
+    throw new Error("Target is required for a zkSync fork simulation");
+  }
+  if (target && network !== "hardhat" && target !== network) {
+    if (network !== "zkFork") {
+      throw new Error(`Manifest target ${target} conflicts with Hardhat network ${network}`);
+    }
+    const snapshot = parseForkSnapshotJson(
+      env.GATE_SIMULATION_FORK_SNAPSHOT_JSON,
+      target,
+    );
+    if (snapshot.runner.kind !== "anvil-zksync") {
+      throw new Error("zkFork manifest target requires an anvil-zksync fork snapshot");
+    }
+    let rpcUrl: URL;
+    try {
+      rpcUrl = new URL(env.GATE_ZKSYNC_FORK_RPC_URL || "");
+    } catch {
+      throw new Error("zkFork manifest target requires a valid loopback RPC URL");
+    }
+    if (
+      rpcUrl.protocol !== "http:"
+      || rpcUrl.hostname !== "127.0.0.1"
+      || !rpcUrl.port
+      || rpcUrl.username
+      || rpcUrl.password
+      || rpcUrl.search
+      || rpcUrl.hash
+    ) {
+      throw new Error("zkFork manifest target requires a loopback-only RPC URL");
+    }
+  }
+  return target || network;
+}
+
+export function openZeppelinProcessEnvironment(input: {
+  root: string;
+  network: string;
+  mode?: string;
+  target?: string;
+  env?: NodeJS.ProcessEnv;
+}): NodeJS.ProcessEnv {
+  const env = input.env ?? process.env;
+  const target = resolveEffectiveManifestTarget({ ...input, env });
+  const manifestDir = loadOpenZeppelinManifestDir(input.root, target);
+  if (env.GATE_WORKFLOW_TARGET && env.GATE_WORKFLOW_TARGET !== target) {
+    throw new Error(`GATE_WORKFLOW_TARGET conflict: expected ${target}, received ${env.GATE_WORKFLOW_TARGET}`);
+  }
+  if (env.MANIFEST_DEFAULT_DIR && env.MANIFEST_DEFAULT_DIR !== manifestDir) {
+    throw new Error(`MANIFEST_DEFAULT_DIR conflict: expected ${manifestDir}, received ${env.MANIFEST_DEFAULT_DIR}`);
+  }
+  return {
+    ...env,
+    GATE_WORKFLOW_TARGET: target,
+    MANIFEST_DEFAULT_DIR: manifestDir,
+  };
+}
+
+const argvValue = (argv: string[], name: string): string | undefined => {
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index];
+    if (value === name) return argv[index + 1];
+    if (value.startsWith(`${name}=`)) return value.slice(name.length + 1);
+  }
+  return undefined;
+};
+
+export function configureOpenZeppelinManifestEnvironment(input: {
+  root: string;
+  target?: string;
+  argv?: string[];
+  env?: NodeJS.ProcessEnv;
+}): string {
+  const env = input.env ?? process.env;
+  const network = argvValue(input.argv ?? process.argv, "--network")?.trim()
+    || input.target?.trim()
+    || "hardhat";
+  const next = openZeppelinProcessEnvironment({
+    root: input.root,
+    network,
+    target: input.target,
+    env,
+  });
+  env.GATE_WORKFLOW_TARGET = next.GATE_WORKFLOW_TARGET;
+  env.MANIFEST_DEFAULT_DIR = next.MANIFEST_DEFAULT_DIR;
+  return next.MANIFEST_DEFAULT_DIR!;
+}

package/runtime/config/rpc.ts

@@ -0,0 +1,27 @@
+export interface EvmRpcOptions {
+  route: string;
+  publicFallback: string;
+  useBaseRpc: boolean;
+}
+
+const trimSlashes = (value: string): string => value.replace(/^\/+|\/+$/g, "");
+
+export const resolveEvmRpcUrl = (
+  options: EvmRpcOptions,
+  baseRpcUri: string | undefined = process.env.BASE_RPC_URI,
+): string => {
+  const fallback = options.publicFallback.trim();
+  const base = baseRpcUri?.trim();
+  if (!options.useBaseRpc || !base) return fallback;
+
+  const normalizedBase = base.replace(/\/+$/g, "");
+  const normalizedRoute = trimSlashes(options.route.trim());
+  return normalizedRoute
+    ? `${normalizedBase}/${normalizedRoute}/`
+    : `${normalizedBase}/`;
+};
+
+export const resolveZkSyncRpcUrl = (
+  publicFallback: string,
+  explicitRpcUrl: string | undefined = process.env.ZKSYNC_RPC_URL,
+): string => explicitRpcUrl?.trim() || publicFallback.trim();

package/runtime/config/zksyncSolcPath.ts

@@ -0,0 +1,59 @@
+import fs from "fs";
+import os from "os";
+import path from "path";
+
+let adapterTail: Promise<void> = Promise.resolve();
+
+const runSerialized = async <T>(run: () => Promise<T>): Promise<T> => {
+  const previous = adapterTail;
+  let release: () => void = () => undefined;
+  adapterTail = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  await previous;
+  try {
+    return await run();
+  } finally {
+    release();
+  }
+};
+
+const restorePath = (previousPath: string | undefined): void => {
+  if (previousPath === undefined) {
+    delete process.env.PATH;
+    return;
+  }
+  process.env.PATH = previousPath;
+};
+
+export async function withZkSyncSolcOnPath<T>(
+  solcPath: string,
+  run: () => Promise<T>,
+): Promise<T> {
+  return runSerialized(async () => {
+    const resolvedSolcPath = fs.realpathSync(solcPath);
+    if (!fs.statSync(resolvedSolcPath).isFile()) {
+      throw new Error(`Hardhat solc path is not a file: ${solcPath}`);
+    }
+
+    const adapterDirectory = fs.mkdtempSync(path.join(os.tmpdir(), "gate-zksolc-path-"));
+    const executableName = process.platform === "win32" ? "solc.exe" : "solc";
+    const mappedSolcPath = path.join(adapterDirectory, executableName);
+    const previousPath = process.env.PATH;
+    try {
+      if (process.platform === "win32") {
+        fs.copyFileSync(resolvedSolcPath, mappedSolcPath);
+        fs.chmodSync(mappedSolcPath, 0o755);
+      } else {
+        fs.symlinkSync(resolvedSolcPath, mappedSolcPath);
+      }
+      process.env.PATH = previousPath
+        ? `${adapterDirectory}${path.delimiter}${previousPath}`
+        : adapterDirectory;
+      return await run();
+    } finally {
+      restorePath(previousPath);
+      fs.rmSync(adapterDirectory, { recursive: true, force: true });
+    }
+  });
+}

package/runtime/hardhat-types.d.ts

@@ -0,0 +1,2 @@
+import '@nomicfoundation/hardhat-ethers';
+import '@openzeppelin/hardhat-upgrades';

package/runtime/migrate.ts

@@ -0,0 +1,154 @@
+import { satisfies, validRange } from 'semver';
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { createRequire } from 'node:module';
+
+interface Entry { sha256: string; replacement: string }
+interface Change { path: string; status: 'current' | 'remove' | 'update' | 'conflict'; reason?: string }
+const commands: Record<string, string> = {
+  cli: 'run', checkCode: 'checkcode', checkCodePlan: 'checkcode-plan',
+  checkCodeFinalize: 'checkcode-finalize', staticValidate: 'static-validate',
+  create2Hashes: 'create2-hashes', releaseFinalize: 'release-finalize',
+  importState: 'import-state', reconcileExternal: 'reconcile-external',
+  commitContractInfo: 'commit-contract-info',
+};
+
+/** Plan first; preserve custom files/state. Only known sources/shims are removable. */
+export function migrateTemplate(projectRoot: string, apply = false) {
+  const root = fs.realpathSync(projectRoot);
+  const baseline: { templateVersion: string; files: Record<string, Entry> } = JSON.parse(
+    fs.readFileSync(path.join(__dirname, 'template-migration.json'), 'utf8'),
+  );
+  const plan: Change[] = [];
+  const edits = new Map<string, string>();
+  const originals = new Map<string, string>();
+  const conflict = (relative: string, reason: string) => plan.push({ path: relative, status: 'conflict', reason });
+  const unsafe = (relative: string) => {
+    const file = path.resolve(root, relative);
+    if (!file.startsWith(root + path.sep)) return true;
+    return relative.split('/').some((_, i, parts) => {
+      try { return fs.lstatSync(path.join(root, ...parts.slice(0, i + 1))).isSymbolicLink(); }
+      catch (error) { if ((error as NodeJS.ErrnoException).code === 'ENOENT') return false; throw error; }
+    });
+  };
+
+  for (const [relative, entry] of Object.entries(baseline.files)) {
+    const file = path.join(root, relative);
+    if (unsafe(relative)) { conflict(relative, 'Symlinked or unconfined runtime path'); continue; }
+    if (!fs.existsSync(file)) { plan.push({ path: relative, status: 'current' }); continue; }
+    if (!fs.statSync(file).isFile()) { conflict(relative, 'Runtime path must be a regular file'); continue; }
+    const source = fs.readFileSync(file, 'utf8');
+    if (source !== entry.replacement && createHash('sha256').update(source).digest('hex') !== entry.sha256) {
+      conflict(relative, 'Customized runtime file requires manual merge'); continue;
+    }
+    originals.set(relative, source);
+    plan.push({ path: relative, status: 'remove' });
+  }
+
+  const packagePath = path.join(root, 'package.json');
+  if (unsafe('package.json') || !fs.existsSync(packagePath)) conflict('package.json', 'Project package.json must exist and be a regular local file');
+  else {
+    const source = fs.readFileSync(packagePath, 'utf8');
+    const pkg = JSON.parse(source);
+    try {
+      if (!(pkg.devDependencies?.['gate-evm-tools'] ?? pkg.dependencies?.['gate-evm-tools'])) throw new Error('gate-evm-tools is not declared');
+      const projectRequire = createRequire(packagePath);
+      const installedRoot = path.resolve(path.dirname(projectRequire.resolve('gate-evm-tools/runtime/cli')), '../..');
+      const installed = JSON.parse(fs.readFileSync(path.join(installedRoot, 'package.json'), 'utf8'));
+      const declared = pkg.devDependencies?.['gate-evm-tools'] ?? pkg.dependencies?.['gate-evm-tools'];
+      if (typeof declared !== 'string' || (!declared.startsWith('file:') && (!validRange(declared) || !satisfies(installed.version, declared)))) throw new Error('Install a version satisfying the declared dependency range first');
+      const lockPath = path.join(root, 'package-lock.json');
+      if (fs.existsSync(lockPath)) {
+        const lock = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
+        const locked = lock.packages?.['node_modules/gate-evm-tools'] ?? lock.dependencies?.['gate-evm-tools'];
+        if (locked?.version !== installed.version) throw new Error('Lockfile version differs from installation');
+      }
+      for (const entry of Object.values(baseline.files)) {
+        const specifier = entry.replacement.match(/export \* from "([^"]+)"/)?.[1];
+        if (!specifier || !fs.statSync(projectRequire.resolve(specifier)).isFile()) throw new Error('Missing packaged runtime export');
+      }
+    } catch {
+      conflict('package.json', 'Install the approved GateTool package and existing lockfile with all runtime exports before removing scripts');
+    }
+    let changed = false;
+    for (const [name, command] of Object.entries(pkg.scripts ?? {})) {
+      if (typeof command !== 'string') continue;
+      const match = command.match(/^ts-node scripts\/workflow\/([A-Za-z0-9]+)\.ts(?=\s|$)/);
+      if (match && commands[match[1]!]) {
+        pkg.scripts[name] = command.replace(match[0], `gate-workflow ${commands[match[1]!]}`);
+        changed = true;
+      }
+    }
+    const next = changed ? JSON.stringify(pkg, null, source.match(/\n(\s+)"/)?.[1] ?? 2) + '\n' : source;
+    if (next.includes('scripts/workflow') || next.includes('scripts\\\\workflow')) conflict('package.json', 'Unrecognized workflow command/reference; update manually');
+    else if (changed) { originals.set('package.json', source); edits.set('package.json', next); plan.push({ path: 'package.json', status: 'update' }); }
+  }
+
+  const moduleTarget = (file: string, specifier: string): string | undefined => {
+    if (!specifier.startsWith('.')) return undefined;
+    const absolute = path.resolve(path.dirname(file), specifier).replace(/\.(?:ts|js)$/, '') + '.ts';
+    const relative = path.relative(root, absolute).split(path.sep).join('/');
+    return baseline.files[relative]?.replacement.match(/export \* from "([^"]+)"/)?.[1];
+  };
+  const ignored = new Set(['node_modules', '.git', '.gateflow', '.codex', 'dist', 'build', 'out', 'results', 'runtime-bindings', 'calldata', 'tx-requests']);
+  const visit = (directory: string) => {
+    for (const item of fs.readdirSync(directory, { withFileTypes: true })) {
+      if (ignored.has(item.name) || /^(?:artifacts|cache|typechain|\.openzeppelin|\.gate-workflow-backup)/.test(item.name)) continue;
+      const file = path.join(directory, item.name);
+      const relative = path.relative(root, file).split(path.sep).join('/');
+      if (baseline.files[relative] || relative === 'package.json') continue;
+      if (item.isSymbolicLink()) { conflict(relative, 'Cannot inspect symlink for legacy runtime references'); continue; }
+      if (item.isDirectory()) { visit(file); continue; }
+      if (relative.startsWith('scripts/workflow/')) { conflict(relative, 'Unrecognized custom workflow file'); continue; }
+      if (!item.isFile() || !/\.(?:[cm]?[jt]sx?|json|ya?ml|sh|toml)$/.test(item.name) || item.name.endsWith('.lock.json') || /(?:package-lock|yarn.lock|pnpm-lock)/.test(item.name)) continue;
+      const source = fs.readFileSync(file, 'utf8');
+      let next = source;
+      if (/\.[cm]?[jt]sx?$/.test(item.name)) {
+        // Only static module specifiers are rewritten; filesystem paths/commands require review.
+        next = source.replace(/(\bfrom\s*|\b(?:require|import)\s*\(\s*|\bimport\s*)(["'])(\.[^"'\n]+)\2/g,
+          (all, prefix: string, quote: string, specifier: string) => {
+            const target = moduleTarget(file, specifier);
+            return target ? `${prefix}${quote}${target}${quote}` : all;
+          });
+      }
+      const unresolvedModule = [...next.matchAll(/["'](\.[^"'\n]+)["']/g)].some(match => moduleTarget(file, match[1]!) !== undefined);
+      if (unresolvedModule || /scripts[\\/]workflow|scripts[\\/]config[\\/](?:rpc|openzeppelin|zksyncSolcPath)/.test(next)) {
+        conflict(relative, 'Unresolved runtime path/reference; update manually before removal'); continue;
+      }
+      if (next !== source) { originals.set(relative, source); edits.set(relative, next); plan.push({ path: relative, status: 'update' }); }
+    }
+  };
+  visit(root);
+  const conflicts = plan.filter(item => item.status === 'conflict');
+  if (apply && conflicts.length) throw new Error('Runtime migration requires manual merge: ' + conflicts.map(item => `${item.path}: ${item.reason}`).join('; '));
+  let backup: string | undefined;
+  if (apply && originals.size > 0) {
+    // Recheck every input before creating the backup or applying changes.
+    for (const [relative, source] of originals) {
+      if (unsafe(relative) || fs.readFileSync(path.join(root, relative), 'utf8') !== source) throw new Error(`Migration input changed: ${relative}`);
+    }
+    backup = fs.mkdtempSync(path.join(root, '.gate-workflow-backup-'));
+    for (const [relative, source] of originals) {
+      const saved = path.join(backup, relative);
+      fs.mkdirSync(path.dirname(saved), { recursive: true });
+      fs.writeFileSync(saved, source);
+    }
+    try {
+      // Rewrite consumers first, then remove the now-unreferenced known files.
+      for (const [relative, source] of edits) fs.writeFileSync(path.join(root, relative), source);
+      for (const item of plan.filter(item => item.status === 'remove')) fs.unlinkSync(path.join(root, item.path));
+    } catch (error) {
+      for (const [relative, source] of originals) fs.writeFileSync(path.join(root, relative), source);
+      throw error;
+    }
+    const prune = (directory: string) => {
+      if (!fs.existsSync(directory) || fs.lstatSync(directory).isSymbolicLink()) return;
+      for (const item of fs.readdirSync(directory, { withFileTypes: true })) if (item.isDirectory()) prune(path.join(directory, item.name));
+      if (fs.readdirSync(directory).length === 0) fs.rmdirSync(directory);
+    };
+    prune(path.join(root, 'scripts/workflow'));
+    prune(path.join(root, 'scripts/config'));
+  }
+  return { applied: apply, baselineVersion: baseline.templateVersion, backup, plan };
+}

package/runtime/projectHardhat.ts

@@ -0,0 +1,10 @@
+import path from 'node:path';
+import { createRequire } from 'node:module';
+// Runtime modules must use the selected project's HRE, not a package/global HRE.
+const projectRequire = createRequire(path.join(process.cwd(), 'package.json'));
+projectRequire('hardhat/register');
+const hre: typeof import('hardhat') = projectRequire('hardhat');
+export default hre;
+export const { ethers, artifacts, network, config, upgrades } = hre;
+
+export const run = hre.run.bind(hre);