@wowok/wowok 2.3.6 → 2.3.8

package/dist/esm/networks-CEYOA-1U.d.mts

@@ -0,0 +1,219 @@
+//#region src/w/local/evm/networks.d.ts
+/**
+ * 单条 EVM 链的完整网络配置
+ *
+ * 一条链 = 一个 EvmNetworkConfig。
+ * ETH 主网、未来 Arbitrum/Optimism/Base 等 L2 或 EVM 兼容链各自一份配置。
+ * 本 SDK 不支持测试网（如 Sepolia / Holesky）；如需测试请使用主网或 L2。
+ */
+interface EvmNetworkConfig {
+  /** 网络别名（小写），如 "mainnet" / "arbitrum" / "optimism" / "base" */
+  name: string;
+  /** EVM chainId（用于交易签名） */
+  chainId: number;
+  /** RPC URL 列表（顺序尝试，第一个为主，其余备用故障转移） */
+  rpcUrls: string[];
+  /** 区块浏览器 URL（可选，用于查询交易） */
+  explorerUrl?: string;
+  /** 交易确认所需区块数（默认 1；L2 通常 1 即可） */
+  confirmations?: number;
+  /** 是否强制使用 Legacy 交易（某些 L2 或 EVM 兼容链不支持 EIP-1559） */
+  useLegacy?: boolean;
+  /** gas limit 估算倍数（默认 1.2，留余量） */
+  gasLimitMultiplier?: number;
+  /** maxPriorityFeePerGas 下限（wei，防止估算为 0） */
+  minPriorityFee?: bigint;
+  /** 单次 RPC 请求超时（ms） */
+  rpcTimeoutMs?: number;
+  /** 等待交易确认总超时（ms） */
+  txConfirmTimeoutMs?: number;
+  /** 轮询交易回执间隔（ms） */
+  pollIntervalMs?: number;
+}
+/**
+ * ETH 主网默认配置
+ *
+ * 默认配置 10 个免费公共 RPC，按顺序尝试，主 RPC 失败自动故障转移到备用。
+ * 公共 RPC 易触发 429 限流，建议通过 `EvmNetworkRegistry.Instance().addRpc(...)`
+ * 或 `setRpcs(...)` 追加 / 替换为付费 RPC（Alchemy/Infura/自建节点）以提升稳定性。
+ *
+ * 健康状态过期：被标记为不可用的 RPC 在 5 分钟后自动重新加入轮询池
+ * （见 `EvmNetworkRegistry.DEFAULT_UNHEALTHY_RETRY_MS`）。
+ */
+declare const ETH_MAINNET: EvmNetworkConfig;
+/**
+ * L2 / EVM 兼容链预留配置模板（当前不启用，仅占位）
+ * 启用时取消注释并注册到 Registry。
+ *
+ * 说明：本 SDK 不支持 EVM 测试网（如 Sepolia / Holesky）。
+ * 未来扩展方向为 Arbitrum / Optimism / Base 等 L2 主网。
+ */
+/**
+ * EVM 网络注册表
+ *
+ * 使用方式：
+ *   const registry = EvmNetworkRegistry.Instance();
+ *   registry.register(ETH_MAINNET);
+ *   registry.setDefault("mainnet");
+ *   const net = await registry.resolve("mainnet");  // 或 1（chainId）
+ *   const net = await registry.resolve();  // 默认网络
+ *
+ * 智能维护：
+ * - RPC 故障转移：主 RPC 失败自动切换备用
+ * - chainId 缓存：避免重复 RPC 调用
+ * - 健康检查：ping RPC 确认可用性
+ */
+declare class EvmNetworkRegistry {
+  private static _instance;
+  /**
+   * 默认 RPC 不可用重试窗口：5 分钟。
+   *
+   * 公共 RPC 429 限流通常在分钟级别恢复，5 分钟保证既不会被永久剔除，
+   * 也不会反复重试坏节点。可通过 `markUnhealthy(url, customMs)` 覆盖。
+   */
+  static readonly DEFAULT_UNHEALTHY_RETRY_MS: number;
+  /** 按 chainId 索引 */
+  private byChainId;
+  /** 按小写 name 索引 */
+  private byName;
+  /** 默认网络 chainId */
+  private defaultChainId;
+  /** chainId 缓存（RPC 返回的真实 chainId，避免重复查询） */
+  private chainIdCache;
+  /** RPC 故障转移状态：url → 下次重试时间 */
+  unhealthyRpc: Map<string, number>;
+  /**
+   * RPC 失败计数器：url → 累计失败次数。
+   *
+   * 用于"垃圾 RPC 反复复位"问题：失败次数越多，恢复时间越长，排序越靠后。
+   * 成功调用一次清零（见 markHealthy）。
+   *
+   * 恢复时间策略（指数退避）：
+   *   1 次 = 5 分钟
+   *   2 次 = 15 分钟
+   *   3 次 = 30 分钟
+   *   4+ 次 = 60 分钟（上限）
+   */
+  unhealthyCounter: Map<string, number>;
+  /** Persistence: evm_network_rpcs table in account.db (shared with evm-account) */
+  private _persistStore;
+  private constructor();
+  static Instance(): EvmNetworkRegistry;
+  /** 注册或覆盖一条网络配置 */
+  register(config: EvmNetworkConfig): void;
+  /** 注销一条网络 */
+  unregister(chainIdOrName: number | string): void;
+  /** 设置默认网络 */
+  setDefault(chainIdOrName: number | string): void;
+  /** 直接获取配置（不触发 RPC） */
+  get(chainIdOrName?: number | string): EvmNetworkConfig | undefined;
+  /** 列出所有已注册网络 */
+  list(): EvmNetworkConfig[];
+  /** 获取默认网络（必须存在） */
+  getDefault(): EvmNetworkConfig;
+  /**
+   * 解析网络配置：
+   * 1. 若传入 chainId/name 直接命中注册表，返回
+   * 2. 若传入 rpcUrl，从缓存查 chainId 或现场查询
+   *
+   * @param network chainId | name | rpcUrl | undefined（用默认）
+   */
+  resolve(network?: number | string): Promise<EvmNetworkConfig>;
+  /**
+   * 选出当前可用的 RPC URL（跳过被标记为不可用的）
+   *
+   * 改进：按"健康度"排序，失败次数少的优先。
+   * 即使所有 RPC 都"过期可重试"，也会优先选择历史记录好的。
+   */
+  pickHealthyRpc(cfg: EvmNetworkConfig): string;
+  /**
+   * 标记 RPC 不可用。
+   *
+   * 改进：使用指数退避，失败次数越多，恢复时间越长。
+   * 这样"垃圾 RPC"反复失败后会被自动降级，不会反复复位影响体验。
+   *
+   * 恢复时间策略：
+   *   1 次 = 5 分钟
+   *   2 次 = 15 分钟
+   *   3 次 = 30 分钟
+   *   4+ 次 = 60 分钟（上限）
+   */
+  markUnhealthy(url: string, retryAfterMs?: number): void;
+  /** 标记 RPC 恢复健康（成功调用一次后清零计数） */
+  markHealthy(url: string): void;
+  /** 查询某个 RPC 当前是否被标记为不可用 */
+  isUnhealthy(url: string): boolean;
+  /** 查询某条链上所有 RPC 的健康状态（用于 AI / 用户管理 RPC） */
+  listRpcStatus(chainIdOrName?: number | string): Array<{
+    url: string;
+    healthy: boolean;
+    retryInMs?: number;
+    failCount: number;
+  }>;
+  /**
+   * 给指定链追加一个 RPC（去重，已存在则忽略）
+   *
+   * 用于 AI / 用户动态管理 RPC 端点：
+   *   registry.addRpc("mainnet", "https://my-private-rpc.example.com")
+   */
+  addRpc(chainIdOrName: number | string, rpcUrl: string): boolean;
+  /**
+   * 从指定链移除一个 RPC
+   *
+   * 注意：不应移除链上最后一个 RPC，否则将无法发起任何请求。
+   */
+  removeRpc(chainIdOrName: number | string, rpcUrl: string): boolean;
+  /**
+   * 完全替换指定链的 RPC 列表
+   *
+   * 用于 AI / 用户批量替换 RPC（如全部切换到付费节点）。
+   * 必须至少传入一个 RPC。
+   */
+  setRpcs(chainIdOrName: number | string, rpcUrls: string[]): boolean;
+  /** 健康检查（ping RPC 节点） */
+  ping(url: string, timeoutMs?: number): Promise<boolean>;
+  /** 通过 RPC 查询 chainId（带缓存） */
+  queryChainIdFromRpc(rpcUrl: string): Promise<number>;
+  /** 清空 chainId 缓存（切换节点后调用） */
+  clearChainIdCache(): void;
+  /**
+   * Lazy init: use SQLiteAccountStorage with table "evm_network_rpcs" in account.db.
+   * Same database file as evm-account.ts, but isolated table.
+   * Data format: single JSON row — { "<chainId>": ["url1", "url2", ...], ... }
+   */
+  private _getPersistStore;
+  /** Save all chains' RPC URLs as a single JSON blob */
+  private _saveAllRpcs;
+  /** Load all chains' RPC overrides from account.db, applied on top of defaults */
+  private _loadAllRpcs;
+  /**
+   * Batch add RPC URLs to a chain. Duplicates are silently ignored.
+   * Returns the number of URLs actually added.
+   */
+  addRpcs(chainIdOrName: number | string, rpcUrls: string[]): number;
+  /**
+   * Batch remove RPC URLs from a chain.
+   * At least one RPC must remain. Silently skips URLs not found.
+   * Returns the number of URLs actually removed.
+   */
+  removeRpcs(chainIdOrName: number | string, rpcUrls: string[]): number;
+  private buildTempConfig;
+}
+/**
+ * BridgeConfig 中的 EvmChainConfig 与 Registry 的 EvmNetworkConfig 字段不完全相同：
+ * - EvmChainConfig 含 bridge 合约地址（bridge 专用）
+ * - EvmNetworkConfig 含 gas/explorer/超时等通用参数（账户操作通用）
+ *
+ * 这里提供一个桥接函数：把 BridgeConfig 中的 Evm 链注册到 Registry，
+ * 这样后续 EvmAccount 操作时通过 chainId 即可自动找到对应 RPC。
+ */
+declare function registerBridgeEvmNetworks(params: {
+  /** EVM 链配置（含 chainId、rpcUrl、bridge 合约地址） */evmChain: {
+    chainId: number;
+    rpcUrl: string;
+  }; /** 网络别名（可选，默认用 "chain-<chainId>"） */
+  name?: string; /** 是否设为默认网络 */
+  setAsDefault?: boolean;
+}): EvmNetworkConfig;
+//#endregion
+export { registerBridgeEvmNetworks as i, EvmNetworkConfig as n, EvmNetworkRegistry as r, ETH_MAINNET as t };