gate-evm-tools 1.0.26 → 1.0.28

package/runtime/workflow/lib/deployments.ts

@@ -0,0 +1,276 @@
+import fs from "fs";
+import path from "path";
+import { isAddress } from "ethers";
+import type { WorkflowConfig } from "./config";
+import { readJsonFile, writeJsonFile } from "./config";
+
+export type ContractInfo = Record<string, Record<string, string>>;
+
+export interface ResolvedDeployment {
+  key: string;
+  address: string;
+}
+
+const contractInfoPath = (root: string): string => {
+  return path.join(root, "contractInfo.json");
+};
+
+const sleepSync = (milliseconds: number): void => {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
+};
+
+const errorCode = (error: unknown): string | undefined => {
+  return error && typeof error === "object" && "code" in error
+    ? String((error as { code?: unknown }).code)
+    : undefined;
+};
+
+const lockOwnerIsAlive = (lockPath: string): boolean | undefined => {
+  let ownerPid: number;
+  try {
+    ownerPid = Number.parseInt(fs.readFileSync(lockPath, "utf8").split("-", 1)[0], 10);
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") return false;
+    return undefined;
+  }
+  if (!Number.isSafeInteger(ownerPid) || ownerPid <= 0) return undefined;
+
+  try {
+    process.kill(ownerPid, 0);
+    return true;
+  } catch (error) {
+    if (errorCode(error) === "ESRCH") return false;
+    return true;
+  }
+};
+
+export const withContractInfoLock = <T>(root: string, operation: () => T): T => {
+  const filePath = contractInfoPath(root);
+  const lockPath = `${filePath}.lock`;
+  const token = `${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+  const startedAt = Date.now();
+  const timeoutMs = 10_000;
+  const staleMs = 30_000;
+  let lockFile: number | undefined;
+
+  fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+  while (lockFile === undefined) {
+    try {
+      const candidate = fs.openSync(lockPath, "wx");
+      try {
+        fs.writeFileSync(candidate, `${token}\n`);
+        lockFile = candidate;
+      } catch (error) {
+        fs.closeSync(candidate);
+        fs.unlinkSync(lockPath);
+        throw error;
+      }
+    } catch (error) {
+      if (errorCode(error) !== "EEXIST") throw error;
+
+      try {
+        const ownerAlive = lockOwnerIsAlive(lockPath);
+        const lockAgeMs = Date.now() - fs.statSync(lockPath).mtimeMs;
+        if (
+          ownerAlive === false ||
+          (ownerAlive === undefined && lockAgeMs > staleMs)
+        ) {
+          fs.unlinkSync(lockPath);
+          continue;
+        }
+      } catch (statError) {
+        if (errorCode(statError) === "ENOENT") continue;
+        throw statError;
+      }
+
+      if (Date.now() - startedAt >= timeoutMs) {
+        throw new Error(`Timed out waiting for contractInfo lock: ${lockPath}`);
+      }
+      sleepSync(25);
+    }
+  }
+
+  let operationFailed = false;
+  try {
+    return operation();
+  } catch (error) {
+    operationFailed = true;
+    throw error;
+  } finally {
+    try {
+      fs.closeSync(lockFile);
+      if (fs.readFileSync(lockPath, "utf8").trim() === token) {
+        fs.unlinkSync(lockPath);
+      }
+    } catch (error) {
+      if (!operationFailed && errorCode(error) !== "ENOENT") throw error;
+    }
+  }
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> => {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+};
+
+export const validateContractInfo = (value: unknown): ContractInfo => {
+  if (!isRecord(value)) {
+    throw new Error("contractInfo.json must contain an object keyed by network");
+  }
+
+  const contractInfo: ContractInfo = {};
+  for (const [targetId, targetValue] of Object.entries(value)) {
+    if (!isRecord(targetValue)) {
+      throw new Error(`contractInfo.json network ${targetId} must contain an object`);
+    }
+
+    const entries: Record<string, string> = {};
+    const instanceIds = new Set<string>();
+    for (const [name, address] of Object.entries(targetValue)) {
+      const keyParts = name.split(":");
+      if (
+        keyParts.length > 2 ||
+        keyParts.some((part) => !part.trim() || part !== part.trim())
+      ) {
+        throw new Error(
+          `contractInfo.json key ${targetId}.${name} must use Contract or saveAs:Contract format`,
+        );
+      }
+      const instanceId = keyParts[0];
+      if (instanceIds.has(instanceId)) {
+        throw new Error(
+          `contractInfo.json network ${targetId} defines deployment instance ${instanceId} more than once`,
+        );
+      }
+      instanceIds.add(instanceId);
+
+      if (typeof address !== "string" || !isAddress(address)) {
+        throw new Error(
+          `contractInfo.json entry ${targetId}.${name} must be an address string with a valid EVM address`,
+        );
+      }
+      entries[name] = address;
+    }
+    contractInfo[targetId] = entries;
+  }
+  return contractInfo;
+};
+
+export const cloneContractInfo = (contractInfo: ContractInfo): ContractInfo => {
+  return Object.fromEntries(
+    Object.entries(contractInfo).map(([targetId, entries]) => [
+      targetId,
+      { ...entries },
+    ]),
+  );
+};
+
+export const actualContractName = (contractName: string): string => {
+  const trimmed = contractName.trim();
+  if (!trimmed) {
+    throw new Error("Actual contract name must not be empty");
+  }
+  const separator = trimmed.lastIndexOf(":");
+  const actual = separator >= 0 ? trimmed.slice(separator + 1).trim() : trimmed;
+  if (!actual) {
+    throw new Error(`Invalid fully qualified contract name: ${contractName}`);
+  }
+  return actual;
+};
+
+export const deploymentInstanceId = (instanceId: string): string => {
+  const normalizedInstanceId = instanceId.trim();
+  if (!normalizedInstanceId) {
+    throw new Error("Deployment saveAs must not be empty");
+  }
+  if (normalizedInstanceId.includes(":")) {
+    throw new Error(`Deployment saveAs "${normalizedInstanceId}" must not contain ":"`);
+  }
+  return normalizedInstanceId;
+};
+
+export const contractInfoKey = (instanceId: string, contractName: string): string => {
+  const normalizedInstanceId = deploymentInstanceId(instanceId);
+  const actual = actualContractName(contractName);
+  return normalizedInstanceId === actual
+    ? actual
+    : `${normalizedInstanceId}:${actual}`;
+};
+
+export const loadContractInfo = (root: string, _config: WorkflowConfig): ContractInfo => {
+  const filePath = contractInfoPath(root);
+  if (!fs.existsSync(filePath)) return {};
+  return validateContractInfo(readJsonFile<unknown>(filePath));
+};
+
+export const saveContractInfo = (root: string, contractInfo: ContractInfo): void => {
+  writeJsonFile(contractInfoPath(root), validateContractInfo(contractInfo));
+};
+
+export const planDeploymentAddress = (
+  contractInfo: ContractInfo,
+  targetId: string,
+  instanceId: string,
+  contractName: string,
+  address: string,
+): { key: string; contractInfo: ContractInfo } => {
+  const key = contractInfoKey(instanceId, contractName);
+  const normalizedInstanceId = deploymentInstanceId(instanceId);
+  const planned = cloneContractInfo(contractInfo);
+  const targetEntries = { ...(planned[targetId] || {}) };
+  for (const existingKey of Object.keys(targetEntries)) {
+    if (
+      existingKey === normalizedInstanceId ||
+      existingKey.startsWith(`${normalizedInstanceId}:`)
+    ) {
+      delete targetEntries[existingKey];
+    }
+  }
+  targetEntries[key] = address;
+  planned[targetId] = targetEntries;
+  return { key, contractInfo: planned };
+};
+
+export const resolveDeployment = (
+  contractInfo: ContractInfo,
+  targetId: string,
+  name: string,
+): ResolvedDeployment | undefined => {
+  const entries = contractInfo[targetId] || {};
+  const exactAddress = entries[name];
+  if (exactAddress) {
+    return { key: name, address: exactAddress };
+  }
+
+  const aliases = Object.entries(entries).filter(([key]) => key.startsWith(`${name}:`));
+  if (aliases.length > 1) {
+    throw new Error(
+      `Ambiguous contractInfo deployment ${targetId}.${name}; matches ${aliases.map(([key]) => key).join(", ")}`,
+    );
+  }
+  if (aliases.length === 1) {
+    return { key: aliases[0][0], address: aliases[0][1] };
+  }
+  return undefined;
+};
+
+export const findDeploymentAddress = (
+  root: string,
+  config: WorkflowConfig,
+  targetId: string,
+  name: string,
+): string | undefined => {
+  return resolveDeployment(loadContractInfo(root, config), targetId, name)?.address;
+};
+
+export const getDeploymentAddress = (
+  root: string,
+  config: WorkflowConfig,
+  targetId: string,
+  name: string,
+): string => {
+  const deployment = resolveDeployment(loadContractInfo(root, config), targetId, name);
+  if (!deployment) {
+    throw new Error(`Missing contractInfo address: ${targetId}.${name}`);
+  }
+  return deployment.address;
+};

package/runtime/workflow/lib/erc1967.ts

@@ -0,0 +1,57 @@
+import type { Provider } from "ethers";
+import { getAddress, isAddress } from "ethers";
+
+export const ERC1967_IMPLEMENTATION_SLOT =
+  "0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc";
+
+export const ERC1967_ADMIN_SLOT =
+  "0xb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d6103";
+
+const getERC1967Address = async (
+  provider: Pick<Provider, "getStorage">,
+  proxyAddress: string,
+  slot: string,
+  label: string,
+  blockTag?: number,
+): Promise<string | undefined> => {
+  if (!isAddress(proxyAddress)) {
+    throw new Error("Invalid proxy candidate address: " + proxyAddress);
+  }
+  const storage = await provider.getStorage(proxyAddress, slot, blockTag);
+  if (!/^0x[0-9a-fA-F]{64}$/.test(storage)) {
+    throw new Error(`Invalid ERC1967 ${label} slot value for ${proxyAddress}`);
+  }
+  const storedAddress = "0x" + storage.slice(-40);
+  if (storedAddress.toLowerCase() === "0x" + "00".repeat(20)) {
+    return undefined;
+  }
+  return getAddress(storedAddress);
+};
+
+export const getERC1967Implementation = async (
+  provider: Pick<Provider, "getStorage">,
+  proxyAddress: string,
+  blockTag?: number,
+): Promise<string | undefined> => {
+  return getERC1967Address(
+    provider,
+    proxyAddress,
+    ERC1967_IMPLEMENTATION_SLOT,
+    "implementation",
+    blockTag,
+  );
+};
+
+export const getERC1967Admin = async (
+  provider: Pick<Provider, "getStorage">,
+  proxyAddress: string,
+  blockTag?: number,
+): Promise<string | undefined> => {
+  return getERC1967Address(
+    provider,
+    proxyAddress,
+    ERC1967_ADMIN_SLOT,
+    "admin",
+    blockTag,
+  );
+};

package/runtime/workflow/lib/errors.ts

@@ -0,0 +1,95 @@
+export type WorkflowErrorType =
+  | "transient"
+  | "check_failed"
+  | "parameter_error"
+  | "config_error"
+  | "contract_error"
+  | "execution_reverted"
+  | "unknown";
+
+export interface WorkflowErrorClassification {
+  errorType: WorkflowErrorType;
+  retryable: boolean;
+}
+
+const messageOf = (error: unknown): string => {
+  return error instanceof Error ? error.message : String(error);
+};
+
+const matchesAny = (message: string, patterns: RegExp[]): boolean => {
+  return patterns.some((pattern) => pattern.test(message));
+};
+
+export const classifyWorkflowError = (error: unknown): WorkflowErrorClassification => {
+  const message = messageOf(error);
+
+  if (matchesAny(message, [
+    /timeout/i,
+    /timed out/i,
+    /rate limit/i,
+    /too many requests/i,
+    /\b429\b/,
+    /\b503\b/,
+    /ECONNRESET/i,
+    /ETIMEDOUT/i,
+    /EAI_AGAIN/i,
+    /header not found/i,
+    /missing trie node/i,
+    /could not detect network/i,
+    /network error/i,
+    /connection/i,
+  ])) {
+    return { errorType: "transient", retryable: true };
+  }
+
+  if (matchesAny(message, [
+    /Check failed/i,
+  ])) {
+    return { errorType: "check_failed", retryable: false };
+  }
+
+  if (matchesAny(message, [
+    /Missing parameters/i,
+    /Reference not found/i,
+    /must resolve to an array/i,
+    /Invalid admin address/i,
+    /requires saveAs/i,
+    /Duplicate deploy saveAs/i,
+  ])) {
+    return { errorType: "parameter_error", retryable: false };
+  }
+
+  if (matchesAny(message, [
+    /Missing config\.yaml/i,
+    /Missing hardhat\.config\.ts network/i,
+    /cannot be forked/i,
+    /no factory address/i,
+    /no salt/i,
+    /simulation callers?/i,
+    /releaseTargetNetworks/i,
+    /release-target simulation/i,
+  ])) {
+    return { errorType: "config_error", retryable: false };
+  }
+
+  if (matchesAny(message, [
+    /Contract does not expose method/i,
+    /missing upgradeToAndCall/i,
+    /missing newImplementation/i,
+    /Unsupported step kind/i,
+  ])) {
+    return { errorType: "contract_error", retryable: false };
+  }
+
+  if (matchesAny(message, [
+    /revert/i,
+    /reverted/i,
+    /CALL_EXCEPTION/i,
+    /transaction failed/i,
+    /gate-tool validate failed/i,
+  ])) {
+    return { errorType: "execution_reverted", retryable: false };
+  }
+
+  return { errorType: "unknown", retryable: false };
+};

package/runtime/workflow/lib/executionId.ts

@@ -0,0 +1,35 @@
+const EXECUTION_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,199}$/;
+const MAX_EXECUTION_ID_LENGTH = 200;
+
+interface BuildExecutionIdOptions {
+  now?: Date;
+  random?: number;
+}
+
+export const validateExecutionId = (
+  value: unknown,
+  label = "executionId",
+): string => {
+  if (typeof value !== "string" || !EXECUTION_ID_PATTERN.test(value)) {
+    throw new Error(
+      `${label} must match the canonical execution ID rule: `
+      + "1-200 letters, numbers, underscores, or hyphens, beginning with a letter or number",
+    );
+  }
+  return value;
+};
+
+export const buildExecutionId = (
+  targetId: string,
+  options: BuildExecutionIdOptions = {},
+): string => {
+  const timestamp = (options.now || new Date()).toISOString().replace(/\D/g, "");
+  const random = options.random ?? Math.random();
+  const nonce = random.toString(36).slice(2).padEnd(8, "0").slice(0, 8);
+  const prefix = `exec-${timestamp}-${nonce}`;
+  const targetBudget = MAX_EXECUTION_ID_LENGTH - prefix.length - 1;
+  const targetSlug = targetId
+    .replace(/[^A-Za-z0-9_-]/g, "-")
+    .slice(0, targetBudget);
+  return validateExecutionId(`${prefix}-${targetSlug}`);
+};