@wowok/wowok 2.3.6 → 2.3.7

package/dist/esm/networks-DhrBVvu6.d.mts

@@ -0,0 +1,140 @@
+//#region src/w/local/evm/networks.d.ts
+/**
+ * EVM 多链网络配置与注册表
+ *
+ * 设计目标：
+ * - 一份配置覆盖一条链的所有参数（chainId、rpcUrls、explorer、确认数、gas 策略、超时等）
+ * - 通过 EvmNetworkRegistry 单例集中管理，支持按 chainId / name 查找
+ * - 智能维护：备用 RPC 故障转移、chainId 缓存、健康检查
+ * - 与 BridgeConfig 协同：bridge 初始化时把 EvmChainConfig 注册进来，
+ *   EvmAccount 调用时即可自动找到对应网络的 RPC，无需重复传参
+ * - 预留 L2 扩展：每条 L2 都是独立的 EvmNetworkConfig
+ */
+/**
+ * 单条 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 主网默认配置
+ *
+ * NOTE: rpcUrls 使用公共 RPC 仅作占位，生产环境建议通过
+ * `EvmNetworkRegistry.Instance().register(...)` 覆盖为付费 RPC（Alchemy/Infura/自建节点）。
+ */
+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;
+  /** 按 chainId 索引 */
+  private byChainId;
+  /** 按小写 name 索引 */
+  private byName;
+  /** 默认网络 chainId */
+  private defaultChainId;
+  /** chainId 缓存（RPC 返回的真实 chainId，避免重复查询） */
+  private chainIdCache;
+  /** RPC 故障转移状态：url → 下次重试时间 */
+  private unhealthyRpc;
+  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（跳过被标记为不可用的）
+   */
+  pickHealthyRpc(cfg: EvmNetworkConfig): string;
+  /** 标记 RPC 不可用（一段时间后自动恢复） */
+  markUnhealthy(url: string, retryAfterMs?: number): void;
+  /** 标记 RPC 恢复健康 */
+  markHealthy(url: string): void;
+  /** 健康检查（ping RPC 节点） */
+  ping(url: string, timeoutMs?: number): Promise<boolean>;
+  /** 通过 RPC 查询 chainId（带缓存） */
+  queryChainIdFromRpc(rpcUrl: string): Promise<number>;
+  /** 清空 chainId 缓存（切换节点后调用） */
+  clearChainIdCache(): void;
+  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 };