agentwallet-sdk 4.0.5 → 5.0.1

package/dist/swap/router/types.d.ts

@@ -0,0 +1,120 @@
+export type SwapStrategy = 'best-net-output' | 'fastest' | 'lowest-gas' | 'mev-protected';
+/** Unified quote format returned by every provider */
+export interface AggregatorQuote {
+    /** Provider name (e.g. '1inch', '0x', 'paraswap', 'cowswap', 'lifi', 'uniswap', 'jupiter') */
+    provider: string;
+    /** Input token symbol or address */
+    fromToken: string;
+    /** Output token symbol or address */
+    toToken: string;
+    /** Input amount in smallest unit (e.g. wei, lamports) */
+    fromAmount: bigint;
+    /** Expected output amount in smallest unit */
+    toAmount: bigint;
+    /** Gas estimate in wei (0 for Solana/gasless) */
+    gasEstimate: bigint;
+    /** Gas cost in USD */
+    gasEstimateUsd: number;
+    /** Provider platform fee in basis points */
+    platformFee: number;
+    /** toAmount adjusted for gas cost — used for ranking */
+    netOutput: bigint;
+    /** Price impact as percentage (e.g. 0.3 = 0.3%) */
+    priceImpact: number;
+    /** DEX route path (e.g. ['Uniswap V3', 'Curve']) */
+    route: string[];
+    /** Estimated execution time in milliseconds */
+    estimatedTimeMs: number;
+    /** Whether this quote is MEV-protected (CowSwap, 1inch Fusion) */
+    mevProtected: boolean;
+    /** Ready-to-submit transaction data (if provided by aggregator) */
+    txData?: {
+        to: string;
+        data: string;
+        value: bigint;
+        gasLimit: bigint;
+    };
+    /** Token decimals for the output token (needed for USD normalization) */
+    toTokenDecimals?: number;
+    /** USD price of one unit of the output token */
+    toTokenPriceUsd?: number;
+    /** Raw provider response for debugging */
+    metadata?: Record<string, unknown>;
+}
+/** Receipt from waitForTransaction */
+export interface TransactionReceipt {
+    status: 'success' | 'reverted';
+    blockNumber?: number;
+    gasUsed?: bigint;
+    [key: string]: unknown;
+}
+/** Result after executing a swap */
+export interface AggregatorSwapResult {
+    /** Transaction hash (EVM) or signature (Solana) */
+    txHash: string;
+    /** Quote that was executed */
+    quote: AggregatorQuote;
+    /** Chain the swap was executed on */
+    chain: string;
+    /** Receipt (populated when waitForReceipt: true) */
+    receipt?: TransactionReceipt;
+    /** Whether the transaction succeeded (populated when waitForReceipt: true) */
+    success?: boolean;
+}
+/** Parameters for requesting a quote */
+export interface QuoteParams {
+    /** Token symbol or address (e.g. 'USDC' or '0x833589...') */
+    fromToken: string;
+    /** Token symbol or address */
+    toToken: string;
+    /** Human-readable amount (e.g. '100' for 100 USDC) */
+    amount: string;
+    /** Chain name: 'ethereum', 'base', 'arbitrum', 'optimism', 'polygon', 'solana', etc. */
+    chain: string;
+    /** Sender address (required by some providers for accurate quotes) */
+    fromAddress?: string;
+    /** Slippage tolerance in bps (default: 50 = 0.5%) */
+    slippageBps?: number;
+}
+/** Provider interface — each aggregator implements this */
+export interface ISwapProvider {
+    /** Provider identifier */
+    readonly name: string;
+    /** Chains this provider supports (lowercase) */
+    readonly supportedChains: string[];
+    /** Fetch a quote; returns null if unsupported or on error */
+    getQuote(params: QuoteParams, timeoutMs: number): Promise<AggregatorQuote | null>;
+}
+/** SmartSwapRouter configuration */
+export interface SmartSwapConfig {
+    /** Providers to query (default: all available for chain) */
+    providers?: string[];
+    /** Ranking strategy (default: 'best-net-output') */
+    strategy?: SwapStrategy;
+    /** Per-provider timeout in ms (default: 5000) */
+    timeoutMs?: number;
+    /** Default slippage in bps (default: 50) */
+    slippageBps?: number;
+    /** Providers to exclude */
+    excludeProviders?: string[];
+    /** API keys for providers that require them */
+    apiKeys?: {
+        oneInch?: string;
+        zerox?: string;
+    };
+    /** Quote cache TTL in ms (default: 3000, set to 0 to disable) */
+    cacheTtlMs?: number;
+    /** Max consecutive failures before a provider is marked unhealthy (default: 3) */
+    healthMaxFailures?: number;
+    /** Cooldown in ms before retrying an unhealthy provider (default: 60000) */
+    healthCooldownMs?: number;
+    /** [MAX-ADDED] RSI engine config — opt-in self-improvement (default: disabled) */
+    rsi?: import('./rsi/types.js').RSIConfig;
+    /** [MAX-ADDED] Wallet goals for RSI optimization */
+    goals?: import('./rsi/types.js').WalletGoals;
+}
+/** Chain name → chain ID mapping for EVM chains */
+export declare const CHAIN_IDS: Record<string, number>;
+/** Reverse mapping: chain ID → name */
+export declare const CHAIN_NAMES: Record<number, string>;
+//# sourceMappingURL=types.d.ts.map

package/dist/swap/router/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/swap/router/types.ts"],"names":[],"mappings":"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"}

package/dist/swap/router/types.js

@@ -0,0 +1,16 @@
+// [MAX-ADDED] SmartSwapRouter types — multi-DEX meta-aggregation for agentwallet-sdk
+// Separate from the existing Uniswap-specific SwapQuote in ../types.ts
+/** Chain name → chain ID mapping for EVM chains */
+export const CHAIN_IDS = {
+    ethereum: 1,
+    base: 8453,
+    arbitrum: 42161,
+    optimism: 10,
+    polygon: 137,
+    avalanche: 43114,
+    bnb: 56,
+    gnosis: 100,
+};
+/** Reverse mapping: chain ID → name */
+export const CHAIN_NAMES = Object.fromEntries(Object.entries(CHAIN_IDS).map(([k, v]) => [v, k]));
+//# sourceMappingURL=types.js.map

package/dist/swap/router/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/swap/router/types.ts"],"names":[],"mappings":"AAAA,qFAAqF;AACrF,uEAAuE;AA4HvE,mDAAmD;AACnD,MAAM,CAAC,MAAM,SAAS,GAA2B;IAC/C,QAAQ,EAAE,CAAC;IACX,IAAI,EAAE,IAAI;IACV,QAAQ,EAAE,KAAK;IACf,QAAQ,EAAE,EAAE;IACZ,OAAO,EAAE,GAAG;IACZ,SAAS,EAAE,KAAK;IAChB,GAAG,EAAE,EAAE;IACP,MAAM,EAAE,GAAG;CACZ,CAAC;AAEF,uCAAuC;AACvC,MAAM,CAAC,MAAM,WAAW,GAA2B,MAAM,CAAC,WAAW,CACnE,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAClD,CAAC"}

package/dist/swap/types.d.ts

@@ -1,17 +1,51 @@
+import type { Address, Hash } from 'viem';
+/** Uniswap V3 fee tier options */
+export type UniswapFeeTier = 100 | 500 | 3000 | 10000;
+export interface SwapQuote {
+    tokenIn: Address;
+    tokenOut: Address;
+    amountInRaw: bigint;
+    amountInNet: bigint;
+    feeAmount: bigint;
+    amountOut: bigint;
+    amountOutMinimum: bigint;
+    poolFeeTier: UniswapFeeTier;
+    effectiveRate: number;
+    gasEstimate: bigint;
+}
+export interface SwapOptions {
+    slippageBps?: number;
+    feeTiers?: UniswapFeeTier[];
+    deadlineSecs?: number;
+    feeWallet?: Address;
+}
+export interface SwapResult {
+    txHash: Hash;
+    feeTxHash?: Hash;
+    quote: SwapQuote;
+    approvalRequired: boolean;
+    approvalTxHash?: Hash;
+}
+export interface SwapModuleConfig {
+    routerAddress: Address;
+    quoterAddress: Address;
+    feeBps: number;
+    feeWallet: Address;
+}
 /** Well-known Base Mainnet token addresses */
 export declare const BASE_TOKENS: {
-    USDC: string;
-    WETH: string;
-    cbETH: string;
-    WNATIVE: string;
+    USDC: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+    WETH: "0x4200000000000000000000000000000000000006";
+    cbETH: "0x2Ae3F1Ec7F1F5012CFEab0185bfc7aa3cf0DEc22";
+    WNATIVE: "0x4200000000000000000000000000000000000006";
 };
 /** Uniswap V3 contract addresses on Base Mainnet (chain 8453) */
 export declare const UNISWAP_V3_BASE: {
-    ROUTER: string;
-    QUOTER_V2: string;
+    ROUTER: "0x2626664c2603336E57B271c5C0b26F421741e481";
+    QUOTER_V2: "0x3d4e44Eb1374240CE5F1B871ab261CD16335B76a";
 };
 /** Protocol fee in bps — 0.875% */
-export declare const PROTOCOL_FEE_BPS = 770;
+export declare const PROTOCOL_FEE_BPS = 875;
 /** Default slippage in bps — 0.5% */
 export declare const DEFAULT_SLIPPAGE_BPS = 50;
 //# sourceMappingURL=types.d.ts.map

package/dist/swap/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/swap/types.ts"],"names":[],"mappings":"AACA,8CAA8C;AAC9C,eAAO,MAAM,WAAW;;;;;CAKvB,CAAC;AACF,iEAAiE;AACjE,eAAO,MAAM,eAAe;;;CAG3B,CAAC;AACF,mCAAmC;AACnC,eAAO,MAAM,gBAAgB,MAAM,CAAC;AACpC,qCAAqC;AACrC,eAAO,MAAM,oBAAoB,KAAK,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/swap/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAE1C,kCAAkC;AAClC,MAAM,MAAM,cAAc,GAAG,GAAG,GAAG,GAAG,GAAG,IAAI,GAAG,KAAK,CAAC;AAEtD,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,cAAc,CAAC;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,cAAc,EAAE,CAAC;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,IAAI,CAAC;IACb,SAAS,CAAC,EAAE,IAAI,CAAC;IACjB,KAAK,EAAE,SAAS,CAAC;IACjB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,cAAc,CAAC,EAAE,IAAI,CAAC;CACvB;AAED,MAAM,WAAW,gBAAgB;IAC/B,aAAa,EAAE,OAAO,CAAC;IACvB,aAAa,EAAE,OAAO,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,8CAA8C;AAC9C,eAAO,MAAM,WAAW;;;;;CAKvB,CAAC;AAEF,iEAAiE;AACjE,eAAO,MAAM,eAAe;;;CAG3B,CAAC;AAEF,mCAAmC;AACnC,eAAO,MAAM,gBAAgB,MAAM,CAAC;AACpC,qCAAqC;AACrC,eAAO,MAAM,oBAAoB,KAAK,CAAC"}

package/dist/swap/types.js

@@ -1,4 +1,3 @@
-// @ts-nocheck
 /** Well-known Base Mainnet token addresses */
 export const BASE_TOKENS = {
     USDC: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
@@ -12,8 +11,7 @@ export const UNISWAP_V3_BASE = {
     QUOTER_V2: '0x3d4e44Eb1374240CE5F1B871ab261CD16335B76a',
 };
 /** Protocol fee in bps — 0.875% */
-export const PROTOCOL_FEE_BPS = 770;
+export const PROTOCOL_FEE_BPS = 875;
 /** Default slippage in bps — 0.5% */
 export const DEFAULT_SLIPPAGE_BPS = 50;
-//# sourceMappingURL=types.js.map
 //# sourceMappingURL=types.js.map

package/dist/swap/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/swap/types.ts"],"names":[],"mappings":"AAAA,cAAc;AACd,8CAA8C;AAC9C,MAAM,CAAC,MAAM,WAAW,GAAG;IACvB,IAAI,EAAE,4CAA4C;IAClD,IAAI,EAAE,4CAA4C;IAClD,KAAK,EAAE,4CAA4C;IACnD,OAAO,EAAE,4CAA4C;CACxD,CAAC;AACF,iEAAiE;AACjE,MAAM,CAAC,MAAM,eAAe,GAAG;IAC3B,MAAM,EAAE,4CAA4C;IACpD,SAAS,EAAE,4CAA4C;CAC1D,CAAC;AACF,mCAAmC;AACnC,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAC;AACpC,qCAAqC;AACrC,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,CAAC;AACvC,iCAAiC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/swap/types.ts"],"names":[],"mappings":"AAwCA,8CAA8C;AAC9C,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,IAAI,EAAE,4CAAqD;IAC3D,IAAI,EAAE,4CAAqD;IAC3D,KAAK,EAAE,4CAAqD;IAC5D,OAAO,EAAE,4CAAqD;CAC/D,CAAC;AAEF,iEAAiE;AACjE,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,MAAM,EAAE,4CAAqD;IAC7D,SAAS,EAAE,4CAAqD;CACjE,CAAC;AAEF,mCAAmC;AACnC,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAC;AACpC,qCAAqC;AACrC,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,CAAC"}

package/dist/tax/engine.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Tax / P&L Engine — Core Engine
+ *
+ * ⚠️ DISCLAIMER: This module is for informational purposes only.
+ * Tax laws are complex, jurisdiction-specific, and change frequently.
+ * Always consult a qualified tax professional before filing. This is NOT tax advice.
+ *
+ * Key rules modeled (US-centric):
+ * - Every token swap = taxable disposal of fromToken + acquisition of toToken
+ * - Short-term gain: held < 365 days → taxed as ordinary income
+ * - Long-term gain: held ≥ 365 days → preferential capital gains rates
+ * - Yield received = ordinary income (full rate)
+ * - Gas fees = reduce net gain (treated as selling expense)
+ * - Wash sale rule: NOT applicable to crypto as of 2024 (no legislation yet)
+ * - Fiat on-ramp = establishes cost basis, NOT a taxable event
+ * - Bridge (cross-chain move) = generally NOT taxable (same owner, same asset)
+ */
+import type { TaxEngineConfig, TaxEvent, TaxLot, RealizedGain, TaxSummary } from './types.js';
+export declare class TaxEngine {
+    private config;
+    private lotManager;
+    private events;
+    private gains;
+    constructor(config?: TaxEngineConfig);
+    /**
+     * Record a swap — the most common taxable event in DeFi.
+     *
+     * A swap creates two sub-events:
+     * 1. Disposal of fromToken (taxable — creates realized gain/loss)
+     * 2. Acquisition of toToken (establishes new cost basis)
+     *
+     * Returns the RealizedGain record, or null if no lots were tracked
+     * (zero cost basis scenario — gain equals full proceeds).
+     */
+    recordSwap(params: {
+        txHash: string;
+        chain: string;
+        timestamp: number;
+        fromToken: string;
+        fromTokenAddress: string;
+        fromAmount: bigint;
+        fromValueUsd: number;
+        toToken: string;
+        toTokenAddress: string;
+        toAmount: bigint;
+        toValueUsd: number;
+        gasPaidUsd?: number;
+    }): RealizedGain | null;
+    /**
+     * Record yield received from a DeFi protocol (taxable as ordinary income).
+     *
+     * Yield is treated as income at the fair market value when received.
+     * The cost basis of the new lot = market value at receipt.
+     */
+    recordYieldReceived(params: {
+        txHash?: string;
+        chain: string;
+        timestamp: number;
+        token: string;
+        tokenAddress: string;
+        amount: bigint;
+        valueUsd: number;
+        protocol: string;
+    }): void;
+    /**
+     * Record a fiat on-ramp (buying crypto with fiat currency).
+     *
+     * This is NOT a taxable event — it establishes the cost basis for future disposals.
+     * The cost basis = amount paid in fiat (USD).
+     */
+    recordFiatOnRamp(params: {
+        txHash?: string;
+        chain: string;
+        timestamp: number;
+        token: string;
+        tokenAddress: string;
+        amount: bigint;
+        paidUsd: number;
+    }): void;
+    /**
+     * Generate an annual tax summary.
+     *
+     * ⚠️ For informational purposes only. Consult a tax professional.
+     */
+    getSummary(year?: number): TaxSummary;
+    /**
+     * Export to CSV format compatible with TurboTax, Koinly, CoinTracker, and similar tools.
+     *
+     * ⚠️ For informational purposes only. Consult a tax professional.
+     * All USD values are formatted to 2 decimal places to prevent CSV parsing issues.
+     */
+    exportCSV(year?: number): string;
+    /**
+     * Export to JSON (for programmatic use, custom reporting, CPA handoff).
+     *
+     * ⚠️ For informational purposes only. Consult a tax professional.
+     */
+    exportJSON(year?: number): {
+        summary: TaxSummary;
+        gains: RealizedGain[];
+        events: TaxEvent[];
+    };
+    /**
+     * Export full engine state for persistence across sessions.
+     */
+    exportState(): {
+        lots: Record<string, TaxLot[]>;
+        events: TaxEvent[];
+        gains: RealizedGain[];
+    };
+    /**
+     * Load state from a previous session (e.g., from database or JSON file).
+     * After loading, new swaps will correctly build on existing lot inventory.
+     */
+    loadState(state: {
+        lots: Record<string, TaxLot[]>;
+        events: TaxEvent[];
+        gains: RealizedGain[];
+    }): void;
+    /**
+     * Determine if a disposal is short-term or long-term.
+     *
+     * Uses the acquisition timestamp of the earliest lot consumed (conservative
+     * for FIFO; oldest lot determines the holding period of the bulk of the disposal).
+     *
+     * Rule: held ≥ 365 days = long-term; held < 365 days = short-term.
+     * If no lots were tracked, defaults to short-term (conservative).
+     */
+    private determineGainType;
+}
+//# sourceMappingURL=engine.d.ts.map

package/dist/tax/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/tax/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,QAAQ,EACR,MAAM,EACN,YAAY,EACZ,UAAU,EAEX,MAAM,YAAY,CAAC;AAMpB,qBAAa,SAAS;IACpB,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,KAAK,CAAsB;gBAEvB,MAAM,GAAE,eAAoB;IAWxC;;;;;;;;;OASG;IACH,UAAU,CAAC,MAAM,EAAE;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,gBAAgB,EAAE,MAAM,CAAC;QACzB,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,MAAM,CAAC;QACrB,OAAO,EAAE,MAAM,CAAC;QAChB,cAAc,EAAE,MAAM,CAAC;QACvB,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,GAAG,YAAY,GAAG,IAAI;IA4EvB;;;;;OAKG;IACH,mBAAmB,CAAC,MAAM,EAAE;QAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,EAAE,MAAM,CAAC;QACd,YAAY,EAAE,MAAM,CAAC;QACrB,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;KAClB,GAAG,IAAI;IAiCR;;;;;OAKG;IACH,gBAAgB,CAAC,MAAM,EAAE;QACvB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,EAAE,MAAM,CAAC;QACd,YAAY,EAAE,MAAM,CAAC;QACrB,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;KACjB,GAAG,IAAI;IAgCR;;;;OAIG;IACH,UAAU,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,UAAU;IAwCrC;;;;;OAKG;IACH,SAAS,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM;IAoChC;;;;OAIG;IACH,UAAU,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG;QACzB,OAAO,EAAE,UAAU,CAAC;QACpB,KAAK,EAAE,YAAY,EAAE,CAAC;QACtB,MAAM,EAAE,QAAQ,EAAE,CAAC;KACpB;IAiBD;;OAEG;IACH,WAAW,IAAI;QACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;QAC/B,MAAM,EAAE,QAAQ,EAAE,CAAC;QACnB,KAAK,EAAE,YAAY,EAAE,CAAC;KACvB;IAQD;;;OAGG;IACH,SAAS,CAAC,KAAK,EAAE;QACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;QAC/B,MAAM,EAAE,QAAQ,EAAE,CAAC;QACnB,KAAK,EAAE,YAAY,EAAE,CAAC;KACvB,GAAG,IAAI;IAQR;;;;;;;;OAQG;IACH,OAAO,CAAC,iBAAiB;CAiB1B"}