forgex-cli 1.0.0

package/dist/src/tx-tracker/detail-adapter.d.ts

@@ -0,0 +1,100 @@
+/**
+ * ForgeX CLI TxDetailAdapter -- 交易详情字段适配器
+ *
+ * 将 RPC 返回的原始交易数据 (ParsedTransactionDetail) 映射为
+ * CLI DataStore 的 TransactionRecord 结构。
+ *
+ * 核心职责:
+ * - 从 preBalances / postBalances 计算 SOL 变化量
+ * - 从 preTokenBalances / postTokenBalances 计算 Token 变化量
+ * - 计算成交价格 (pricePerToken = |solChange| / |tokenChange|)
+ * - 提取手续费
+ * - 根据交易记录更新持仓数据 (avgBuyPrice, realizedPnl 等)
+ *
+ * 设计参考: ARCH-DESIGN-v2.md Section 3.4
+ */
+import type { ParsedTransactionDetail } from '../adapters/rpc-adapter.js';
+import type { TransactionRecord, WalletHolding } from '../data-store/types.js';
+/** 追踪上下文 (由 TxTracker 传入) */
+export interface TrackingContext {
+    /** 代币合约地址 */
+    ca: string;
+    /** 钱包组 ID */
+    groupId: number;
+    /** 交易类型 */
+    txType: 'buy' | 'sell' | 'transfer_in' | 'transfer_out' | 'turnover';
+    /** 参与交易的钱包地址列表 */
+    wallets: string[];
+    /** 预期 SOL 金额 (用于验证，可选) */
+    expectedAmountSol?: number;
+    /** Jito Bundle ID (如有) */
+    jitoBundle?: string;
+}
+export declare class TxDetailAdapter {
+    /**
+     * 核心适配方法:
+     * 从 RPC 原始交易数据中提取并映射为 TransactionRecord。
+     *
+     * 解析流程:
+     * 1. 在 accountKeys 中找到目标钱包的索引
+     * 2. 通过索引比较 preBalances vs postBalances 计算 SOL 变化
+     * 3. 从 preTokenBalances / postTokenBalances 中筛选目标代币和钱包，计算 Token 变化
+     * 4. 计算成交价格: |SOL变化 - fee| / |Token变化|
+     * 5. 组装 TransactionRecord
+     *
+     * @param txHash 交易签名
+     * @param detail RPC 返回的解析后交易详情
+     * @param context 追踪上下文
+     * @returns TransactionRecord
+     */
+    adaptToTransactionRecord(txHash: string, detail: ParsedTransactionDetail, context: TrackingContext): TransactionRecord;
+    /**
+     * 根据交易记录更新持仓数据。
+     *
+     * 更新逻辑:
+     * - buy:  增加 tokenBalance, totalBought, totalCostSol; 重算 avgBuyPrice
+     * - sell: 减少 tokenBalance, 增加 totalSold, totalRevenueSol; 计算 realizedPnl
+     * - transfer_in:  增加 tokenBalance (不影响成本)
+     * - transfer_out: 减少 tokenBalance (不影响成本)
+     * - turnover: 不更新持仓 (换手不改变净持仓)
+     *
+     * @param currentHolding 当前持仓数据
+     * @param tx 交易记录
+     * @returns 更新后的持仓数据 (新对象，不修改原对象)
+     */
+    updateHoldingFromTx(currentHolding: WalletHolding, tx: TransactionRecord): WalletHolding;
+    /**
+     * 为指定钱包创建空的初始持仓
+     */
+    createEmptyHolding(walletAddress: string): WalletHolding;
+    /**
+     * 在 accountKeys 中找到目标钱包的索引。
+     * 优先匹配第一个钱包地址（主钱包）。
+     */
+    private findWalletIndex;
+    /**
+     * 解析实际使用的钱包地址。
+     * 如果在 accountKeys 中找到了匹配的钱包，返回该地址；
+     * 否则返回 context.wallets[0] 作为兜底。
+     */
+    private resolveWalletAddress;
+    /**
+     * 计算 Token 余额变化量。
+     *
+     * 从 preTokenBalances 和 postTokenBalances 中筛选:
+     * - mint === 目标代币合约地址
+     * - owner 属于参与交易的钱包之一
+     *
+     * 然后计算 post - pre 得到变化量。
+     *
+     * 注意: preTokenBalances/postTokenBalances 中的 owner 字段可能不存在，
+     * 此时通过 accountIndex 映射 accountKeys 来确定 owner。
+     */
+    private calculateTokenChange;
+    /**
+     * 从 tokenBalances 数组中，汇总指定代币和钱包的余额。
+     * 支持通过 owner 字段直接匹配，或通过 accountIndex -> accountKeys 间接匹配。
+     */
+    private sumTokenBalance;
+}
+//# sourceMappingURL=detail-adapter.d.ts.map

package/dist/src/tx-tracker/detail-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detail-adapter.d.ts","sourceRoot":"","sources":["../../../src/tx-tracker/detail-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AAC1E,OAAO,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAM/E,6BAA6B;AAC7B,MAAM,WAAW,eAAe;IAC9B,aAAa;IACb,EAAE,EAAE,MAAM,CAAC;IACX,aAAa;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW;IACX,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,aAAa,GAAG,cAAc,GAAG,UAAU,CAAC;IACrE,kBAAkB;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,0BAA0B;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,0BAA0B;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AA6BD,qBAAa,eAAe;IAC1B;;;;;;;;;;;;;;;OAeG;IACH,wBAAwB,CACtB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,uBAAuB,EAC/B,OAAO,EAAE,eAAe,GACvB,iBAAiB;IA8CpB;;;;;;;;;;;;;OAaG;IACH,mBAAmB,CAAC,cAAc,EAAE,aAAa,EAAE,EAAE,EAAE,iBAAiB,GAAG,aAAa;IA0DxF;;OAEG;IACH,kBAAkB,CAAC,aAAa,EAAE,MAAM,GAAG,aAAa;IAkBxD;;;OAGG;IACH,OAAO,CAAC,eAAe;IASvB;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IAO5B;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,oBAAoB;IAY5B;;;OAGG;IACH,OAAO,CAAC,eAAe;CA6BxB"}

package/dist/src/tx-tracker/detail-adapter.js

@@ -0,0 +1,215 @@
+/**
+ * ForgeX CLI TxDetailAdapter -- 交易详情字段适配器
+ *
+ * 将 RPC 返回的原始交易数据 (ParsedTransactionDetail) 映射为
+ * CLI DataStore 的 TransactionRecord 结构。
+ *
+ * 核心职责:
+ * - 从 preBalances / postBalances 计算 SOL 变化量
+ * - 从 preTokenBalances / postTokenBalances 计算 Token 变化量
+ * - 计算成交价格 (pricePerToken = |solChange| / |tokenChange|)
+ * - 提取手续费
+ * - 根据交易记录更新持仓数据 (avgBuyPrice, realizedPnl 等)
+ *
+ * 设计参考: ARCH-DESIGN-v2.md Section 3.4
+ */
+// ============================================================
+// TxDetailAdapter 实现
+// ============================================================
+export class TxDetailAdapter {
+    /**
+     * 核心适配方法:
+     * 从 RPC 原始交易数据中提取并映射为 TransactionRecord。
+     *
+     * 解析流程:
+     * 1. 在 accountKeys 中找到目标钱包的索引
+     * 2. 通过索引比较 preBalances vs postBalances 计算 SOL 变化
+     * 3. 从 preTokenBalances / postTokenBalances 中筛选目标代币和钱包，计算 Token 变化
+     * 4. 计算成交价格: |SOL变化 - fee| / |Token变化|
+     * 5. 组装 TransactionRecord
+     *
+     * @param txHash 交易签名
+     * @param detail RPC 返回的解析后交易详情
+     * @param context 追踪上下文
+     * @returns TransactionRecord
+     */
+    adaptToTransactionRecord(txHash, detail, context) {
+        const { accountKeys, preBalances, postBalances, preTokenBalances, postTokenBalances, fee, err, slot, blockTime } = detail;
+        // 1. 找到目标钱包在 accountKeys 中的索引
+        const walletIndex = this.findWalletIndex(accountKeys, context.wallets);
+        // 2. 计算 SOL 变化 (lamports -> SOL)
+        const solChangeLamports = walletIndex >= 0 ? (postBalances[walletIndex] ?? 0) - (preBalances[walletIndex] ?? 0) : 0;
+        const solChange = solChangeLamports / 1e9;
+        // 3. 计算 Token 变化
+        const tokenChange = this.calculateTokenChange(preTokenBalances, postTokenBalances, context.ca, context.wallets, accountKeys);
+        // 4. 计算成交价格
+        // 对于 buy: 花费 SOL 获取 Token，solChange 为负，tokenChange 为正
+        // 对于 sell: 花费 Token 获取 SOL，solChange 为正，tokenChange 为负
+        // 价格 = |净 SOL 变化(扣除 fee)| / |Token 变化|
+        const feeInSol = (fee || 0) / 1e9;
+        const netSolChange = Math.abs(solChange) - feeInSol;
+        const pricePerToken = tokenChange !== 0 ? Math.max(0, netSolChange) / Math.abs(tokenChange) : 0;
+        // 5. 组装记录
+        return {
+            txHash,
+            txType: context.txType,
+            walletAddress: this.resolveWalletAddress(accountKeys, context.wallets, walletIndex),
+            tokenCA: context.ca,
+            amountSol: solChange,
+            amountToken: tokenChange,
+            pricePerToken,
+            fee: feeInSol,
+            slot,
+            blockTime: blockTime || Math.floor(Date.now() / 1000),
+            status: err ? 'failed' : 'confirmed',
+            jitoBundle: context.jitoBundle,
+        };
+    }
+    /**
+     * 根据交易记录更新持仓数据。
+     *
+     * 更新逻辑:
+     * - buy:  增加 tokenBalance, totalBought, totalCostSol; 重算 avgBuyPrice
+     * - sell: 减少 tokenBalance, 增加 totalSold, totalRevenueSol; 计算 realizedPnl
+     * - transfer_in:  增加 tokenBalance (不影响成本)
+     * - transfer_out: 减少 tokenBalance (不影响成本)
+     * - turnover: 不更新持仓 (换手不改变净持仓)
+     *
+     * @param currentHolding 当前持仓数据
+     * @param tx 交易记录
+     * @returns 更新后的持仓数据 (新对象，不修改原对象)
+     */
+    updateHoldingFromTx(currentHolding, tx) {
+        const updated = { ...currentHolding };
+        switch (tx.txType) {
+            case 'buy': {
+                const boughtTokens = Math.abs(tx.amountToken);
+                const costSol = Math.abs(tx.amountSol);
+                updated.totalBought += boughtTokens;
+                updated.totalCostSol += costSol;
+                updated.tokenBalance += boughtTokens;
+                // 重算平均买入价 (加权平均)
+                if (updated.totalBought > 0) {
+                    updated.avgBuyPrice = updated.totalCostSol / updated.totalBought;
+                }
+                break;
+            }
+            case 'sell': {
+                const soldTokens = Math.abs(tx.amountToken);
+                const revenueSol = Math.abs(tx.amountSol);
+                updated.totalSold += soldTokens;
+                updated.totalRevenueSol += revenueSol;
+                updated.tokenBalance = Math.max(0, updated.tokenBalance - soldTokens);
+                // 计算本次卖出的已实现盈亏
+                // realizedPnl += 卖出收入 - 卖出数量 * 平均买入成本
+                const soldCost = soldTokens * updated.avgBuyPrice;
+                updated.realizedPnl += revenueSol - soldCost;
+                break;
+            }
+            case 'transfer_in': {
+                // 转入: 增加余额，不影响成本数据
+                const transferredIn = Math.abs(tx.amountToken);
+                updated.tokenBalance += transferredIn;
+                break;
+            }
+            case 'transfer_out': {
+                // 转出: 减少余额，不影响成本数据
+                const transferredOut = Math.abs(tx.amountToken);
+                updated.tokenBalance = Math.max(0, updated.tokenBalance - transferredOut);
+                break;
+            }
+            case 'turnover': {
+                // 换手: 不改变净持仓
+                // 换手交易本质上是一买一卖的对冲操作，net 持仓不变
+                break;
+            }
+        }
+        return updated;
+    }
+    /**
+     * 为指定钱包创建空的初始持仓
+     */
+    createEmptyHolding(walletAddress) {
+        return {
+            walletAddress,
+            tokenBalance: 0,
+            avgBuyPrice: 0,
+            totalBought: 0,
+            totalSold: 0,
+            totalCostSol: 0,
+            totalRevenueSol: 0,
+            realizedPnl: 0,
+            unrealizedPnl: 0,
+        };
+    }
+    // ============================================================
+    // 私有方法
+    // ============================================================
+    /**
+     * 在 accountKeys 中找到目标钱包的索引。
+     * 优先匹配第一个钱包地址（主钱包）。
+     */
+    findWalletIndex(accountKeys, wallets) {
+        // 先尝试精确匹配第一个钱包（主钱包）
+        for (const wallet of wallets) {
+            const idx = accountKeys.indexOf(wallet);
+            if (idx >= 0)
+                return idx;
+        }
+        return -1;
+    }
+    /**
+     * 解析实际使用的钱包地址。
+     * 如果在 accountKeys 中找到了匹配的钱包，返回该地址；
+     * 否则返回 context.wallets[0] 作为兜底。
+     */
+    resolveWalletAddress(accountKeys, wallets, walletIndex) {
+        if (walletIndex >= 0 && walletIndex < accountKeys.length) {
+            return accountKeys[walletIndex];
+        }
+        return wallets[0] || '';
+    }
+    /**
+     * 计算 Token 余额变化量。
+     *
+     * 从 preTokenBalances 和 postTokenBalances 中筛选:
+     * - mint === 目标代币合约地址
+     * - owner 属于参与交易的钱包之一
+     *
+     * 然后计算 post - pre 得到变化量。
+     *
+     * 注意: preTokenBalances/postTokenBalances 中的 owner 字段可能不存在，
+     * 此时通过 accountIndex 映射 accountKeys 来确定 owner。
+     */
+    calculateTokenChange(preTokenBalances, postTokenBalances, tokenMint, walletAddresses, accountKeys) {
+        const preBalance = this.sumTokenBalance(preTokenBalances, tokenMint, walletAddresses, accountKeys);
+        const postBalance = this.sumTokenBalance(postTokenBalances, tokenMint, walletAddresses, accountKeys);
+        return postBalance - preBalance;
+    }
+    /**
+     * 从 tokenBalances 数组中，汇总指定代币和钱包的余额。
+     * 支持通过 owner 字段直接匹配，或通过 accountIndex -> accountKeys 间接匹配。
+     */
+    sumTokenBalance(tokenBalances, tokenMint, walletAddresses, accountKeys) {
+        if (!Array.isArray(tokenBalances))
+            return 0;
+        let total = 0;
+        for (const entry of tokenBalances) {
+            // 只关心目标代币
+            if (entry.mint !== tokenMint)
+                continue;
+            // 确定 owner: 优先使用 entry.owner，否则通过 accountIndex 查找
+            const owner = entry.owner || (entry.accountIndex >= 0 ? accountKeys[entry.accountIndex] : undefined);
+            if (!owner)
+                continue;
+            // 检查 owner 是否属于参与交易的钱包
+            if (!walletAddresses.includes(owner))
+                continue;
+            // 取 uiAmount
+            const uiAmount = entry.uiTokenAmount?.uiAmount ?? 0;
+            total += uiAmount;
+        }
+        return total;
+    }
+}
+//# sourceMappingURL=detail-adapter.js.map

package/dist/src/tx-tracker/detail-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"detail-adapter.js","sourceRoot":"","sources":["../../../src/tx-tracker/detail-adapter.ts"],"names":[],"mappings":"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"}

package/dist/src/tx-tracker/index.d.ts

@@ -0,0 +1,142 @@
+/**
+ * ForgeX CLI TxTracker -- 交易追踪系统
+ *
+ * 在每次交易发起后:
+ * 1. 通过 RPC 或 Jito API 轮询检查交易状态
+ * 2. 确认后获取完整交易详情
+ * 3. 通过 TxDetailAdapter 将链上原始数据映射为 CLI 数据结构
+ * 4. 自动写入 DataStore (交易记录、持仓、余额)
+ *
+ * 支持:
+ * - 普通交易追踪 (trackTransaction)
+ * - Jito Bundle 追踪 (trackBundle)
+ * - 批量交易追踪 (trackBatch)
+ * - 进度回调 (onProgress)
+ * - 可配置的轮询间隔和超时
+ *
+ * 设计参考: ARCH-DESIGN-v2.md Section 3.2 ~ 3.6
+ */
+import { RpcAdapter } from '../adapters/rpc-adapter.js';
+import { JitoAdapter } from '../adapters/jito-adapter.js';
+import { DataStore } from '../data-store/index.js';
+import type { TrackingContext } from './detail-adapter.js';
+import type { TransactionRecord } from '../data-store/types.js';
+export { TxDetailAdapter } from './detail-adapter.js';
+export type { TrackingContext } from './detail-adapter.js';
+/** 追踪选项 */
+export interface TrackingOptions {
+    /** 轮询间隔 (ms), 默认 2000 */
+    pollIntervalMs?: number;
+    /** 超时时间 (ms), 默认 60000 */
+    timeoutMs?: number;
+    /** 最大重试次数 (RPC 请求失败时), 默认 3 */
+    maxRetries?: number;
+    /** 进度回调 */
+    onProgress?: (status: string, txHash: string) => void;
+}
+/** 单笔交易追踪结果 */
+export interface TrackingResult {
+    /** 交易签名 */
+    txHash: string;
+    /** 最终状态 */
+    status: 'confirmed' | 'failed' | 'timeout';
+    /** 成功时的交易记录 */
+    record?: TransactionRecord;
+    /** 失败原因 */
+    error?: string;
+}
+export declare class TxTracker {
+    private rpc;
+    private jito;
+    private store;
+    private adapter;
+    constructor(rpc?: RpcAdapter, jito?: JitoAdapter, store?: DataStore);
+    /**
+     * 追踪单笔普通交易。
+     *
+     * 流程:
+     * 1. 轮询 RPC 直到交易确认 / 失败 / 超时
+     * 2. 确认后获取交易详情
+     * 3. 通过 TxDetailAdapter 适配为 TransactionRecord
+     * 4. 写入 DataStore (交易记录 + 持仓 + 余额)
+     *
+     * @param txHash 交易签名
+     * @param context 追踪上下文
+     * @param options 追踪选项 (可选)
+     * @returns 追踪结果
+     */
+    trackTransaction(txHash: string, context: TrackingContext, options?: TrackingOptions): Promise<TrackingResult>;
+    /**
+     * 追踪 Jito Bundle。
+     *
+     * 流程:
+     * 1. 通过 JitoAdapter 等待 Bundle 确认
+     * 2. Bundle 确认后，逐个获取内部交易详情
+     * 3. 适配并写入 DataStore
+     *
+     * @param bundleId Jito Bundle ID
+     * @param txHashes Bundle 中包含的交易签名列表
+     * @param context 追踪上下文
+     * @param options 追踪选项 (可选)
+     * @returns 每笔交易的追踪结果
+     */
+    trackBundle(bundleId: string, txHashes: string[], context: TrackingContext, options?: TrackingOptions): Promise<TrackingResult[]>;
+    /**
+     * 批量追踪多笔独立交易。
+     * 并发追踪所有交易，每笔交易独立处理。
+     *
+     * @param entries 交易列表 (txHash + context)
+     * @param options 追踪选项 (可选)
+     * @returns 每笔交易的追踪结果
+     */
+    trackBatch(entries: Array<{
+        txHash: string;
+        context: TrackingContext;
+    }>, options?: TrackingOptions): Promise<TrackingResult[]>;
+    /**
+     * 轮询 RPC 直到交易确认、失败或超时。
+     *
+     * 策略:
+     * - 每隔 pollIntervalMs 查询一次交易状态
+     * - confirmed / finalized -> 返回 'confirmed'
+     * - failed -> 返回 'failed'
+     * - not_found -> 继续等待
+     * - RPC 请求错误 -> 计入重试次数，超限后抛出
+     * - 超时 -> 返回 'timeout'
+     */
+    private pollUntilConfirmed;
+    /**
+     * 带重试的交易详情获取。
+     * 交易刚确认时，详情可能还没有被索引，需要多次尝试。
+     */
+    private fetchDetailWithRetry;
+    /**
+     * 处理已确认的单笔交易: 获取详情 -> 适配 -> 持久化
+     */
+    private processConfirmedTransaction;
+    /**
+     * 将交易记录写入 DataStore
+     */
+    private persistTransaction;
+    /**
+     * 根据交易记录更新持仓数据
+     */
+    private updateHoldingFromRecord;
+    /**
+     * 根据交易记录更新余额快照
+     */
+    private updateBalanceFromRecord;
+    /** 创建 pending (超时) 状态的交易记录 */
+    private createPendingRecord;
+    /** 创建 failed 状态的交易记录 */
+    private createFailedRecord;
+    /** 创建已确认但无详情的交易记录 */
+    private createConfirmedPartialRecord;
+    /** 合并用户选项和默认选项 */
+    private resolveOptions;
+}
+/** 获取 TxTracker 全局单例 */
+export declare function getTxTracker(): TxTracker;
+/** 重置单例 (用于测试或配置变更) */
+export declare function resetTxTracker(): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/tx-tracker/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/tx-tracker/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,UAAU,EAAiB,MAAM,4BAA4B,CAAC;AACvE,OAAO,EAAE,WAAW,EAAoC,MAAM,6BAA6B,CAAC;AAC5F,OAAO,EAAE,SAAS,EAAgB,MAAM,wBAAwB,CAAC;AAEjE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EAAE,iBAAiB,EAAiB,MAAM,wBAAwB,CAAC;AAG/E,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,YAAY,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAM3D,WAAW;AACX,MAAM,WAAW,eAAe;IAC9B,yBAAyB;IACzB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,0BAA0B;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+BAA+B;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW;IACX,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CACvD;AAED,eAAe;AACf,MAAM,WAAW,cAAc;IAC7B,WAAW;IACX,MAAM,EAAE,MAAM,CAAC;IACf,WAAW;IACX,MAAM,EAAE,WAAW,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC3C,eAAe;IACf,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,WAAW;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAwBD,qBAAa,SAAS;IACpB,OAAO,CAAC,GAAG,CAAa;IACxB,OAAO,CAAC,IAAI,CAAc;IAC1B,OAAO,CAAC,KAAK,CAAY;IACzB,OAAO,CAAC,OAAO,CAAkB;gBAErB,GAAG,CAAC,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,EAAE,SAAS;IAWnE;;;;;;;;;;;;;OAaG;IACG,gBAAgB,CACpB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,eAAe,EACxB,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,cAAc,CAAC;IAwE1B;;;;;;;;;;;;;OAaG;IACG,WAAW,CACf,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAAE,EAClB,OAAO,EAAE,eAAe,EACxB,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,cAAc,EAAE,CAAC;IAiE5B;;;;;;;OAOG;IACG,UAAU,CACd,OAAO,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,eAAe,CAAA;KAAE,CAAC,EAC5D,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,cAAc,EAAE,CAAC;IAqB5B;;;;;;;;;;OAUG;YACW,kBAAkB;IAuChC;;;OAGG;YACW,oBAAoB;IAwBlC;;OAEG;YACW,2BAA2B;IAwCzC;;OAEG;YACW,kBAAkB;IAQhC;;OAEG;YACW,uBAAuB;IAqBrC;;OAEG;YACW,uBAAuB;IA0BrC,8BAA8B;IAC9B,OAAO,CAAC,mBAAmB;IAiB3B,wBAAwB;IACxB,OAAO,CAAC,kBAAkB;IAiB1B,qBAAqB;IACrB,OAAO,CAAC,4BAA4B;IAqBpC,kBAAkB;IAClB,OAAO,CAAC,cAAc;CAQvB;AAQD,wBAAwB;AACxB,wBAAgB,YAAY,IAAI,SAAS,CAKxC;AAED,uBAAuB;AACvB,wBAAgB,cAAc,IAAI,IAAI,CAErC"}