gate-evm-tools 1.0.25 → 1.0.27

package/runtime/config/networks.ts

@@ -0,0 +1,296 @@
+import type { HardhatUserConfig, HttpNetworkUserConfig, NetworkUserConfig } from "hardhat/types";
+import { resolveEvmRpcUrl, resolveZkSyncRpcUrl } from "./rpc";
+
+export interface TemplateNetworkOptions {
+  accounts: HttpNetworkUserConfig["accounts"];
+  env?: NodeJS.ProcessEnv;
+  overrides?: NonNullable<HardhatUserConfig["networks"]>;
+}
+
+/** Creates fresh network objects; caller-owned compiler configuration is never touched. */
+export function createTemplateNetworks({ accounts, env = process.env, overrides = {} }: TemplateNetworkOptions): NonNullable<HardhatUserConfig["networks"]> {
+  const hardhatForking = env.HARDHAT_FORK_RPC_URL
+    ? { url: env.HARDHAT_FORK_RPC_URL }
+    : undefined;
+  const hardhatForkChainId = env.HARDHAT_FORK_CHAIN_ID?.trim();
+  if (
+    hardhatForkChainId
+    && (
+      !/^[1-9][0-9]*$/.test(hardhatForkChainId)
+      || !Number.isSafeInteger(Number(hardhatForkChainId))
+    )
+  ) {
+    throw new Error("HARDHAT_FORK_CHAIN_ID must be a positive safe integer");
+  }
+
+  interface RemoteNetworkOptions {
+    route: string;
+    publicFallback: string;
+    useBaseRpc: boolean;
+    chainId: number;
+    ethNetwork?: string;
+    zksync?: boolean;
+    rpcUrl?: string;
+  }
+
+  const remoteNetwork = ({
+    route,
+    publicFallback,
+    useBaseRpc,
+    rpcUrl,
+    ...network
+  }: RemoteNetworkOptions) => ({
+    ...network,
+    url: rpcUrl || resolveEvmRpcUrl({ route, publicFallback, useBaseRpc }, env.BASE_RPC_URI),
+    accounts,
+  });
+
+  const zkSyncForkRpcUrl = env.GATE_ZKSYNC_FORK_RPC_URL?.trim();
+  if (zkSyncForkRpcUrl) {
+    let parsed: URL;
+    try {
+      parsed = new URL(zkSyncForkRpcUrl);
+    } catch {
+      throw new Error("GATE_ZKSYNC_FORK_RPC_URL is invalid");
+    }
+    if (
+      parsed.protocol !== "http:"
+      || parsed.hostname !== "127.0.0.1"
+      || !parsed.port
+      || parsed.username
+      || parsed.password
+      || parsed.search
+      || parsed.hash
+    ) {
+      throw new Error("GATE_ZKSYNC_FORK_RPC_URL must be loopback-only");
+    }
+  }
+
+  const networks = {
+    hardhat: {
+      allowUnlimitedContractSize: false,
+      chainId: hardhatForkChainId ? Number(hardhatForkChainId) : 1,
+      ...(hardhatForking ? { forking: hardhatForking } : {}),
+    },
+    localhost: {
+      url: "http://127.0.0.1:8545",
+      accounts,
+    },
+    zkFork: {
+      url: zkSyncForkRpcUrl || "http://127.0.0.1:8011",
+      accounts: [],
+      ethNetwork: "mainnet",
+      zksync: true,
+      chainId: hardhatForkChainId ? Number(hardhatForkChainId) : 324,
+    } as any,
+    ethDev: remoteNetwork({
+      route: "eth",
+      publicFallback: "https://ethereum-rpc.publicnode.com",
+      useBaseRpc: true,
+      chainId: 1,
+    }),
+    ethProd: remoteNetwork({
+      route: "eth",
+      publicFallback: "https://ethereum-rpc.publicnode.com",
+      useBaseRpc: true,
+      chainId: 1,
+    }),
+    opDev: remoteNetwork({
+      route: "optimism",
+      publicFallback: "https://optimism-rpc.publicnode.com",
+      useBaseRpc: true,
+      chainId: 10,
+    }),
+    opProd: remoteNetwork({
+      route: "optimism",
+      publicFallback: "https://optimism-rpc.publicnode.com",
+      useBaseRpc: true,
+      chainId: 10,
+    }),
+    bscDev: remoteNetwork({
+      route: "bsc",
+      publicFallback: "https://bsc.drpc.org",
+      useBaseRpc: true,
+      chainId: 56,
+    }),
+    bscProd: remoteNetwork({
+      route: "bsc",
+      publicFallback: "https://bsc.drpc.org",
+      useBaseRpc: true,
+      chainId: 56,
+    }),
+    wldDev: remoteNetwork({
+      route: "world",
+      publicFallback: "https://480.rpc.thirdweb.com",
+      useBaseRpc: true,
+      chainId: 480,
+    }),
+    wldProd: remoteNetwork({
+      route: "world",
+      publicFallback: "https://480.rpc.thirdweb.com",
+      useBaseRpc: true,
+      chainId: 480,
+    }),
+    polygonDev: remoteNetwork({
+      route: "polygon",
+      publicFallback: "https://polygon.drpc.org",
+      useBaseRpc: true,
+      chainId: 137,
+    }),
+    polygonProd: remoteNetwork({
+      route: "polygon",
+      publicFallback: "https://polygon.drpc.org",
+      useBaseRpc: true,
+      chainId: 137,
+    }),
+    ftmDev: remoteNetwork({
+      route: "fantom",
+      publicFallback: "https://fantom-json-rpc.stakely.io",
+      useBaseRpc: false,
+      chainId: 250,
+    }),
+    ftmProd: remoteNetwork({
+      route: "fantom",
+      publicFallback: "https://fantom-json-rpc.stakely.io",
+      useBaseRpc: false,
+      chainId: 250,
+    }),
+    sepolia: remoteNetwork({
+      route: "eth",
+      publicFallback: "https://ethereum-sepolia-rpc.publicnode.com",
+      useBaseRpc: false,
+      chainId: 11155111,
+    }),
+    zkDev: remoteNetwork({
+      route: "zksync",
+      publicFallback: "https://mainnet.era.zksync.io",
+      useBaseRpc: false,
+      rpcUrl: resolveZkSyncRpcUrl("https://mainnet.era.zksync.io", env.ZKSYNC_RPC_URL),
+      ethNetwork: "mainnet",
+      zksync: true,
+      chainId: 324,
+    }) as any,
+    zkProd: remoteNetwork({
+      route: "zksync",
+      publicFallback: "https://mainnet.era.zksync.io",
+      useBaseRpc: false,
+      rpcUrl: resolveZkSyncRpcUrl("https://mainnet.era.zksync.io", env.ZKSYNC_RPC_URL),
+      ethNetwork: "mainnet",
+      zksync: true,
+      chainId: 324,
+    }) as any,
+    lineaDev: remoteNetwork({
+      route: "linea",
+      publicFallback: "https://linea.drpc.org",
+      useBaseRpc: true,
+      chainId: 59144,
+    }),
+    lineaProd: remoteNetwork({
+      route: "linea",
+      publicFallback: "https://linea.drpc.org",
+      useBaseRpc: true,
+      chainId: 59144,
+    }),
+    baseDev: remoteNetwork({
+      route: "base",
+      publicFallback: "https://base.drpc.org",
+      useBaseRpc: true,
+      chainId: 8453,
+    }),
+    baseProd: remoteNetwork({
+      route: "base",
+      publicFallback: "https://base.drpc.org",
+      useBaseRpc: true,
+      chainId: 8453,
+    }),
+    arbDev: remoteNetwork({
+      route: "arbitrum",
+      publicFallback: "https://public-arb-mainnet.fastnode.io",
+      useBaseRpc: true,
+      chainId: 42161,
+    }),
+    arbProd: remoteNetwork({
+      route: "arbitrum",
+      publicFallback: "https://public-arb-mainnet.fastnode.io",
+      useBaseRpc: true,
+      chainId: 42161,
+    }),
+    blastDev: remoteNetwork({
+      route: "blast",
+      publicFallback: "https://blast.drpc.org",
+      useBaseRpc: true,
+      chainId: 81457,
+    }),
+    blastProd: remoteNetwork({
+      route: "blast",
+      publicFallback: "https://blast.drpc.org",
+      useBaseRpc: true,
+      chainId: 81457,
+    }),
+    avaxDev: remoteNetwork({
+      route: "avaxc",
+      publicFallback: "https://api.avax.network/ext/bc/C/rpc",
+      useBaseRpc: true,
+      chainId: 43114,
+    }),
+    avaxProd: remoteNetwork({
+      route: "avaxc",
+      publicFallback: "https://api.avax.network/ext/bc/C/rpc",
+      useBaseRpc: true,
+      chainId: 43114,
+    }),
+    gtDev: remoteNetwork({
+      route: "gatelayer",
+      publicFallback: "https://gatelayer-mainnet.gatenode.cc",
+      useBaseRpc: true,
+      chainId: 10088,
+    }),
+    gtProd: remoteNetwork({
+      route: "gatelayer",
+      publicFallback: "https://gatelayer-mainnet.gatenode.cc",
+      useBaseRpc: true,
+      chainId: 10088,
+    }),
+    eniDev: remoteNetwork({
+      route: "eni",
+      publicFallback: "https://rpc.eniac.network",
+      useBaseRpc: true,
+      chainId: 173,
+    }),
+    eniProd: remoteNetwork({
+      route: "eni",
+      publicFallback: "https://rpc.eniac.network",
+      useBaseRpc: true,
+      chainId: 173,
+    }),
+    beraDev: remoteNetwork({
+      route: "bera",
+      publicFallback: "https://rpc.berachain.com",
+      useBaseRpc: true,
+      chainId: 80094,
+    }),
+    beraProd: remoteNetwork({
+      route: "bera",
+      publicFallback: "https://rpc.berachain.com",
+      useBaseRpc: true,
+      chainId: 80094,
+    }),
+    sonicDev: remoteNetwork({
+      route: "sonic",
+      publicFallback: "https://rpc.soniclabs.com",
+      useBaseRpc: true,
+      chainId: 146,
+    }),
+    sonicProd: remoteNetwork({
+      route: "sonic",
+      publicFallback: "https://rpc.soniclabs.com",
+      useBaseRpc: true,
+      chainId: 146,
+    }),
+  };
+  const result: NonNullable<HardhatUserConfig["networks"]> = networks;
+  for (const [name, override] of Object.entries(overrides)) {
+    if (override !== undefined) result[name] = { ...result[name], ...override } as NetworkUserConfig;
+  }
+  return result;
+}

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