agentwallet-sdk 3.0.0 → 3.1.1

package/dist/settlement/verifier.js

@@ -0,0 +1,354 @@
+// SettlementVerifier — On-chain settlement verification for agent transactions
+//
+// Verifies that bridge transfers, x402 payments, and regular transactions actually
+// settled on-chain. Uses Alchemy RPC for supported chains, public RPCs as fallback.
+//
+// Supported verification types:
+//   - EVM transaction receipts (any EVM chain)
+//   - Solana transaction confirmation
+//   - CCTP bridge transfers end-to-end (source burn + attestation + dest mint)
+//   - x402 ERC20 payment verification (payee + amount from event logs)
+import { SETTLEMENT_ALCHEMY_NETWORKS, SETTLEMENT_PUBLIC_RPCS, CIRCLE_ATTESTATION_API, ERC20_TRANSFER_TOPIC, SOLANA_RPC_URL, } from './types.js';
+export class SettlementVerifier {
+    constructor(config = {}) {
+        this.alchemyApiKey = config.alchemyApiKey;
+    }
+    // ─── EVM Transaction Verification ───
+    /**
+     * Verify that an EVM transaction settled on-chain.
+     *
+     * Uses Alchemy RPC if apiKey is configured and chain is supported,
+     * otherwise falls back to public RPCs.
+     *
+     * @param params.chain - SDK chain name (e.g. 'base', 'arbitrum')
+     * @param params.txHash - Transaction hash to verify
+     * @param params.confirmations - Minimum confirmations required (default: 1)
+     */
+    async verifyEvmTransaction(params) {
+        const requiredConfirmations = params.confirmations ?? 1;
+        const rpcUrl = this._getRpcUrl(params.chain);
+        try {
+            // Get receipt
+            const receiptResp = await this._evmRpc(rpcUrl, 'eth_getTransactionReceipt', [params.txHash]);
+            const receipt = receiptResp.result;
+            if (!receipt) {
+                // Not mined yet — check if it's in the mempool
+                return {
+                    status: 'pending',
+                    txHash: params.txHash,
+                    blockNumber: 0n,
+                    confirmations: 0,
+                };
+            }
+            // Get current block number to compute confirmations
+            const blockResp = await this._evmRpc(rpcUrl, 'eth_blockNumber', []);
+            const currentBlock = BigInt(blockResp.result);
+            const txBlock = BigInt(receipt.blockNumber);
+            const confirmationCount = Number(currentBlock - txBlock) + 1;
+            const success = receipt.status === '0x1';
+            if (!success) {
+                return {
+                    status: 'failed',
+                    txHash: params.txHash,
+                    blockNumber: txBlock,
+                    confirmations: confirmationCount,
+                    gasUsed: BigInt(receipt.gasUsed),
+                    success: false,
+                    error: 'Transaction reverted (status=0)',
+                };
+            }
+            if (confirmationCount < requiredConfirmations) {
+                return {
+                    status: 'pending',
+                    txHash: params.txHash,
+                    blockNumber: txBlock,
+                    confirmations: confirmationCount,
+                    gasUsed: BigInt(receipt.gasUsed),
+                    success: true,
+                };
+            }
+            return {
+                status: 'confirmed',
+                txHash: params.txHash,
+                blockNumber: txBlock,
+                confirmations: confirmationCount,
+                gasUsed: BigInt(receipt.gasUsed),
+                success: true,
+            };
+        }
+        catch (err) {
+            return {
+                status: 'not_found',
+                txHash: params.txHash,
+                blockNumber: 0n,
+                confirmations: 0,
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+    // ─── Solana Transaction Verification ───
+    /**
+     * Verify that a Solana transaction settled on-chain.
+     *
+     * @param params.signature - Solana transaction signature (base58)
+     * @param params.commitment - Commitment level: 'confirmed' or 'finalized' (default: 'confirmed')
+     */
+    async verifySolanaTransaction(params) {
+        const commitment = params.commitment ?? 'confirmed';
+        try {
+            const resp = await this._solanaRpc('getTransaction', [
+                params.signature,
+                { encoding: 'json', commitment, maxSupportedTransactionVersion: 0 },
+            ]);
+            const tx = resp.result;
+            if (!tx) {
+                return {
+                    status: 'not_found',
+                    txHash: params.signature,
+                    blockNumber: 0n,
+                    confirmations: 0,
+                    error: 'Transaction not found or not yet confirmed',
+                };
+            }
+            const success = tx.meta.err === null;
+            // Get current slot for confirmation count approximation
+            const slotResp = await this._solanaRpc('getSlot', [{ commitment }]);
+            const currentSlot = slotResp.result;
+            const confirmations = currentSlot - tx.slot;
+            return {
+                status: success ? 'confirmed' : 'failed',
+                txHash: params.signature,
+                blockNumber: BigInt(tx.slot),
+                confirmations,
+                success,
+                error: !success ? `Solana transaction error: ${JSON.stringify(tx.meta.err)}` : undefined,
+            };
+        }
+        catch (err) {
+            return {
+                status: 'not_found',
+                txHash: params.signature,
+                blockNumber: 0n,
+                confirmations: 0,
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+    // ─── CCTP Bridge Settlement ───
+    /**
+     * Verify a CCTP bridge transfer settled end-to-end:
+     *   1. Verifies source chain burn tx succeeded
+     *   2. Checks Circle attestation API for the message hash
+     *   3. Attempts to find destination mint tx (if attestation is complete)
+     *
+     * @param params.sourceTxHash - Burn tx hash on source chain
+     * @param params.sourceChain - Source chain name (e.g. 'solana', 'base')
+     * @param params.destinationChain - Destination chain name
+     * @param params.expectedAmount - Expected USDC amount in base units (6 decimals)
+     */
+    async verifyBridgeSettlement(params) {
+        // Step 1: verify source tx
+        let sourceTx;
+        if (params.sourceChain === 'solana') {
+            sourceTx = await this.verifySolanaTransaction({ signature: params.sourceTxHash });
+        }
+        else {
+            sourceTx = await this.verifyEvmTransaction({
+                chain: params.sourceChain,
+                txHash: params.sourceTxHash,
+                confirmations: params.sourceChain === 'ethereum' ? 65 : 1, // Ethereum needs more for CCTP
+            });
+        }
+        if (sourceTx.status === 'failed') {
+            return {
+                status: 'source_failed',
+                sourceTx,
+                error: 'Source chain burn transaction failed or reverted',
+            };
+        }
+        if (sourceTx.status === 'pending' || sourceTx.status === 'not_found') {
+            return {
+                status: 'source_pending',
+                sourceTx,
+            };
+        }
+        // Step 2: check Circle attestation API
+        let attestationStatus;
+        try {
+            attestationStatus = await this._checkCircleAttestation(params.sourceTxHash);
+        }
+        catch {
+            attestationStatus = 'error';
+        }
+        if (attestationStatus === 'pending_confirmations') {
+            return {
+                status: 'source_confirmed_awaiting_attestation',
+                sourceTx,
+                attestationStatus,
+            };
+        }
+        if (attestationStatus === 'complete') {
+            // Step 3: Try to find the destination mint tx
+            // For now, we report attestation complete and let the caller poll for mint
+            // A full implementation would index destination chain events
+            return {
+                status: 'attestation_complete_awaiting_mint',
+                sourceTx,
+                attestationStatus,
+            };
+        }
+        // If we can verify source + attestation but not destination, return partial
+        return {
+            status: 'error',
+            sourceTx,
+            attestationStatus,
+            error: 'Could not determine attestation status',
+        };
+    }
+    // ─── x402 Payment Verification ───
+    /**
+     * Verify an x402 payment settled on-chain by inspecting ERC20 Transfer event logs.
+     *
+     * Checks that the tx:
+     *   - Succeeded (status=1)
+     *   - Emitted an ERC20 Transfer event to expectedPayee
+     *   - The transferred amount matches expectedAmount
+     *
+     * @param params.chain - EVM chain name
+     * @param params.txHash - Transaction hash
+     * @param params.expectedPayee - Address that should have received the payment
+     * @param params.expectedAmount - Amount in USDC base units (6 decimals)
+     */
+    async verifyX402Payment(params) {
+        const rpcUrl = this._getRpcUrl(params.chain);
+        try {
+            const receiptResp = await this._evmRpc(rpcUrl, 'eth_getTransactionReceipt', [params.txHash]);
+            const receipt = receiptResp.result;
+            if (!receipt) {
+                return {
+                    status: 'pending',
+                    txHash: params.txHash,
+                    payeeVerified: false,
+                    amountVerified: false,
+                };
+            }
+            if (receipt.status !== '0x1') {
+                return {
+                    status: 'failed',
+                    txHash: params.txHash,
+                    payeeVerified: false,
+                    amountVerified: false,
+                    error: 'Transaction reverted',
+                };
+            }
+            // Find ERC20 Transfer events — topic[0] = Transfer sig, topic[2] = to address
+            const expectedPayeeHex = params.expectedPayee.toLowerCase().replace('0x', '').padStart(64, '0');
+            const transferLog = receipt.logs.find((log) => {
+                return (log.topics[0]?.toLowerCase() === ERC20_TRANSFER_TOPIC &&
+                    log.topics[2]?.toLowerCase() === `0x${expectedPayeeHex}`);
+            });
+            if (!transferLog) {
+                return {
+                    status: 'confirmed',
+                    txHash: params.txHash,
+                    payeeVerified: false,
+                    amountVerified: false,
+                    error: `No ERC20 Transfer found to payee ${params.expectedPayee}`,
+                };
+            }
+            // Decode amount from log.data (ABI-encoded uint256)
+            const actualAmount = BigInt(transferLog.data);
+            const amountVerified = actualAmount === params.expectedAmount;
+            const actualPayee = `0x${transferLog.topics[2]?.slice(-40)}`;
+            const tokenAddress = transferLog.address;
+            return {
+                status: 'confirmed',
+                txHash: params.txHash,
+                payeeVerified: true,
+                amountVerified,
+                actualAmount,
+                actualPayee,
+                tokenAddress,
+                error: amountVerified
+                    ? undefined
+                    : `Amount mismatch: expected ${params.expectedAmount}, got ${actualAmount}`,
+            };
+        }
+        catch (err) {
+            return {
+                status: 'not_found',
+                txHash: params.txHash,
+                payeeVerified: false,
+                amountVerified: false,
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+    // ─── Internal Helpers ───
+    /** Get the RPC URL for a chain, preferring Alchemy over public RPCs */
+    _getRpcUrl(chain) {
+        if (this.alchemyApiKey && chain in SETTLEMENT_ALCHEMY_NETWORKS) {
+            const slug = SETTLEMENT_ALCHEMY_NETWORKS[chain];
+            return `https://${slug}.g.alchemy.com/v2/${this.alchemyApiKey}`;
+        }
+        const publicRpc = SETTLEMENT_PUBLIC_RPCS[chain];
+        if (!publicRpc) {
+            throw new Error(`No RPC URL available for chain "${chain}"`);
+        }
+        return publicRpc;
+    }
+    /** Make an EVM JSON-RPC call */
+    async _evmRpc(url, method, params) {
+        const resp = await fetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }),
+        });
+        if (!resp.ok) {
+            throw new Error(`EVM RPC error: HTTP ${resp.status}`);
+        }
+        const json = (await resp.json());
+        if (json.error)
+            throw new Error(`EVM RPC error: ${json.error.message}`);
+        return json;
+    }
+    /** Make a Solana JSON-RPC call */
+    async _solanaRpc(method, params) {
+        const resp = await fetch(SOLANA_RPC_URL, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }),
+        });
+        if (!resp.ok) {
+            throw new Error(`Solana RPC error: HTTP ${resp.status}`);
+        }
+        const json = (await resp.json());
+        if (json.error)
+            throw new Error(`Solana RPC error: ${json.error.message}`);
+        return json;
+    }
+    /** Check Circle attestation API for a CCTP burn message */
+    async _checkCircleAttestation(burnTxHash) {
+        // Circle attestation API: GET /attestations/{messageHash}
+        // For CCTP, the messageHash is derived from the MessageSent event in the burn tx.
+        // Since we don't have the full event parsing here, we query by tx hash pattern.
+        // In production, callers should provide the message hash from the burn tx receipt.
+        const url = `${CIRCLE_ATTESTATION_API}/${burnTxHash}`;
+        const resp = await fetch(url, {
+            headers: { Accept: 'application/json' },
+        });
+        if (resp.status === 404) {
+            return 'pending_confirmations';
+        }
+        if (!resp.ok) {
+            return 'error';
+        }
+        const json = (await resp.json());
+        if (json.status === 'complete')
+            return 'complete';
+        if (json.status === 'pending_confirmations')
+            return 'pending_confirmations';
+        return 'error';
+    }
+}
+//# sourceMappingURL=verifier.js.map

package/dist/settlement/verifier.js.map

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

package/dist/solver/adapter.d.ts

@@ -0,0 +1,47 @@
+/**
+ * CowSolverAdapter — Main entry point for the CowSwap solver integration.
+ *
+ * ⚠️  IMPORTANT: Shadow competition is FREE and requires no registration or KYC.
+ *     Production solver requires CowSwap DAO bonding pool approval and KYC.
+ *     This adapter defaults to 'shadow' mode — never assume production credentials.
+ *
+ * Flow:
+ *   1. CowSwap broadcasts an auction batch to all registered solvers.
+ *   2. We call processAuction() — must return within ~30 seconds.
+ *   3. We detect CoW (Coincidence of Wants) first — zero DEX fees.
+ *   4. Remaining orders are routed through SmartSwapRouter (7 DEXes in parallel).
+ *   5. We call submitSolution() with the best settlement we can construct.
+ *   6. If we win, we earn the surplus above user limit prices.
+ */
+import type { SmartSwapRouter } from '../swap/router/router.js';
+import type { CowAuctionBatch, SolverConfig, SolverSolution, SolverStats, SolutionSubmissionResult } from './types.js';
+export declare class CowSolverAdapter {
+    private config;
+    private analyzer;
+    private builder;
+    private stats;
+    /** CowSwap competition API endpoints */
+    private readonly ENDPOINTS;
+    constructor(config: SolverConfig, router?: SmartSwapRouter);
+    /**
+     * Process an auction batch and return our best settlement solution.
+     *
+     * Called when CowSwap sends us an auction. Must respond within 30 seconds.
+     * Returns null if we have nothing viable to submit.
+     */
+    processAuction(batch: CowAuctionBatch): Promise<SolverSolution | null>;
+    /**
+     * Submit a solution to CowSwap.
+     *
+     * In shadow mode, the solution is evaluated but never executed on-chain —
+     * useful for measuring competitiveness before applying for the production
+     * bonding pool.
+     */
+    submitSolution(solution: SolverSolution): Promise<SolutionSubmissionResult>;
+    /** Get current solver performance statistics */
+    getStats(): SolverStats;
+    /** Get the CowSwap API base URL for the configured environment */
+    getApiUrl(): string;
+    private getChainId;
+}
+//# sourceMappingURL=adapter.d.ts.map

package/dist/solver/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../src/solver/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,KAAK,EACV,eAAe,EACf,YAAY,EACZ,cAAc,EACd,WAAW,EACX,wBAAwB,EACzB,MAAM,YAAY,CAAC;AAIpB,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAyB;IACvC,OAAO,CAAC,QAAQ,CAAkB;IAClC,OAAO,CAAC,OAAO,CAAkB;IACjC,OAAO,CAAC,KAAK,CAAc;IAE3B,wCAAwC;IACxC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAIxB;gBAEU,MAAM,EAAE,YAAY,EAAE,MAAM,CAAC,EAAE,eAAe;IAyB1D;;;;;OAKG;IACG,cAAc,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAmD5E;;;;;;OAMG;IACG,cAAc,CAClB,QAAQ,EAAE,cAAc,GACvB,OAAO,CAAC,wBAAwB,CAAC;IAgDpC,gDAAgD;IAChD,QAAQ,IAAI,WAAW;IAIvB,kEAAkE;IAClE,SAAS,IAAI,MAAM;IAInB,OAAO,CAAC,UAAU;CASnB"}

package/dist/solver/adapter.js

@@ -0,0 +1,138 @@
+import { AuctionAnalyzer } from './analyzer.js';
+import { SolutionBuilder } from './builder.js';
+export class CowSolverAdapter {
+    constructor(config, router) {
+        /** CowSwap competition API endpoints */
+        this.ENDPOINTS = {
+            shadow: 'https://api.cow.fi/mainnet/api/v1/solver_competition',
+            staging: 'https://barn.api.cow.fi/mainnet/api/v1/solver_competition',
+            mainnet: 'https://api.cow.fi/mainnet/api/v1/solver_competition',
+        };
+        this.config = {
+            environment: 'shadow',
+            solverName: 'AgentWallet',
+            maxGasGwei: 50,
+            minSurplusUsd: 0.5,
+            responseTimeoutMs: 20000,
+            submissionUrl: '',
+            ...config,
+        };
+        this.analyzer = new AuctionAnalyzer(router);
+        this.builder = new SolutionBuilder();
+        this.stats = {
+            auctionsProcessed: 0,
+            auctionsWon: 0,
+            auctionsLost: 0,
+            totalSurplusGenerated: '0',
+            winRate: 0,
+            avgResponseTimeMs: 0,
+            lastAuctionAt: undefined,
+        };
+    }
+    /**
+     * Process an auction batch and return our best settlement solution.
+     *
+     * Called when CowSwap sends us an auction. Must respond within 30 seconds.
+     * Returns null if we have nothing viable to submit.
+     */
+    async processAuction(batch) {
+        const startTime = Date.now();
+        this.stats.auctionsProcessed++;
+        this.stats.lastAuctionAt = startTime;
+        const orders = Object.values(batch.instance.orders);
+        if (orders.length === 0)
+            return null;
+        // Step 1: Find Coincidence of Wants — best outcome for users, no DEX fees
+        const cowMatches = this.analyzer.findCoincidenceOfWants(orders);
+        // Step 2: Route remaining orders through SmartSwapRouter
+        const matchedOrderIds = new Set(cowMatches.flatMap((m) => [m.orderA.uid, m.orderB.uid]));
+        const remainingOrders = orders.filter((o) => !matchedOrderIds.has(o.uid));
+        const analysisPromises = remainingOrders.map((order) => this.analyzer
+            .analyzeOrder(order, this.getChainId())
+            .then((result) => result ? { order, route: result.bestRoute } : { order, route: null }));
+        const routes = await Promise.all(analysisPromises);
+        // Step 3: Only keep orders we can actually fill
+        const viableRoutes = routes.filter((r) => r.route !== null);
+        // Step 4: Nothing to submit?
+        if (viableRoutes.length === 0 && cowMatches.length === 0)
+            return null;
+        // Step 5: Assemble the solution
+        const solution = this.builder.buildSolution({
+            auctionId: batch.id,
+            orders,
+            routes: viableRoutes,
+            cowMatches,
+        });
+        // Step 6: Update timing stats
+        const elapsed = Date.now() - startTime;
+        this.stats.avgResponseTimeMs =
+            (this.stats.avgResponseTimeMs * (this.stats.auctionsProcessed - 1) +
+                elapsed) /
+                this.stats.auctionsProcessed;
+        return solution;
+    }
+    /**
+     * Submit a solution to CowSwap.
+     *
+     * In shadow mode, the solution is evaluated but never executed on-chain —
+     * useful for measuring competitiveness before applying for the production
+     * bonding pool.
+     */
+    async submitSolution(solution) {
+        const endpoint = this.config.submissionUrl ||
+            this.ENDPOINTS[this.config.environment];
+        try {
+            const response = await fetch(`${endpoint}/solutions`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    auctionId: solution.auctionId,
+                    trades: solution.trades,
+                    interactions: solution.interactions,
+                    prices: solution.prices,
+                }),
+            });
+            if (!response.ok) {
+                const text = await response.text();
+                return {
+                    success: false,
+                    auctionId: solution.auctionId,
+                    error: text,
+                };
+            }
+            const result = (await response.json());
+            return {
+                success: true,
+                auctionId: solution.auctionId,
+                solutionId: result.id,
+                won: result.winner === this.config.solverName,
+                surplus: result.surplus,
+            };
+        }
+        catch (err) {
+            return {
+                success: false,
+                auctionId: solution.auctionId,
+                error: err instanceof Error ? err.message : 'Unknown error',
+            };
+        }
+    }
+    /** Get current solver performance statistics */
+    getStats() {
+        return { ...this.stats };
+    }
+    /** Get the CowSwap API base URL for the configured environment */
+    getApiUrl() {
+        return this.ENDPOINTS[this.config.environment];
+    }
+    getChainId() {
+        const map = {
+            ethereum: 1,
+            base: 8453,
+            arbitrum: 42161,
+            gnosis: 100,
+        };
+        return map[this.config.chain] ?? 1;
+    }
+}
+//# sourceMappingURL=adapter.js.map

package/dist/solver/adapter.js.map

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

package/dist/solver/analyzer.d.ts

@@ -0,0 +1,48 @@
+/**
+ * AuctionAnalyzer — Core intelligence for CowSwap solver.
+ *
+ * Given an auction batch, finds the best execution route for each order
+ * by leveraging SmartSwapRouter (7 DEX aggregators queried in parallel).
+ *
+ * Also detects Coincidence of Wants (CoW): orders that can settle directly
+ * without any DEX, saving gas and maximising user surplus.
+ */
+import type { SmartSwapRouter } from '../swap/router/router.js';
+import type { AggregatorQuote } from '../swap/router/types.js';
+import type { CowOrder } from './types.js';
+export declare class AuctionAnalyzer {
+    private router?;
+    constructor(router?: SmartSwapRouter | undefined);
+    /**
+     * Analyse a single order — find the best execution route.
+     * Returns null if no router is configured or no viable quotes exist.
+     *
+     * NOTE: analyzeOrder is intentionally graceful — it never throws.
+     * A missing router or empty quote list simply returns null.
+     */
+    analyzeOrder(order: CowOrder, chainId: number): Promise<{
+        order: CowOrder;
+        bestRoute: AggregatorQuote | null;
+        /** Surplus vs the order's limit price in buy-token units */
+        surplusBuyToken: bigint;
+        /** Surplus in USD (simplified) */
+        surplusUsd: number;
+        viable: boolean;
+    } | null>;
+    /**
+     * Find Coincidence of Wants (CoW) — orders that can trade directly.
+     *
+     * If user A wants to sell ETH for USDC and user B wants to sell USDC for
+     * ETH, they can settle directly with ZERO DEX fees. This is CowSwap's core
+     * innovation and is the primary edge for any competitive solver.
+     */
+    findCoincidenceOfWants(orders: CowOrder[]): Array<{
+        orderA: CowOrder;
+        orderB: CowOrder;
+        matchedAmount: bigint;
+        estimatedGasSaved: bigint;
+    }>;
+    private calculateCoWMatch;
+    private chainIdToName;
+}
+//# sourceMappingURL=analyzer.d.ts.map

package/dist/solver/analyzer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../../src/solver/analyzer.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,qBAAa,eAAe;IACd,OAAO,CAAC,MAAM,CAAC;gBAAP,MAAM,CAAC,6BAAiB;IAE5C;;;;;;OAMG;IACG,YAAY,CAChB,KAAK,EAAE,QAAQ,EACf,OAAO,EAAE,MAAM,GACd,OAAO,CAAC;QACT,KAAK,EAAE,QAAQ,CAAC;QAChB,SAAS,EAAE,eAAe,GAAG,IAAI,CAAC;QAClC,4DAA4D;QAC5D,eAAe,EAAE,MAAM,CAAC;QACxB,kCAAkC;QAClC,UAAU,EAAE,MAAM,CAAC;QACnB,MAAM,EAAE,OAAO,CAAC;KACjB,GAAG,IAAI,CAAC;IAqCT;;;;;;OAMG;IACH,sBAAsB,CAAC,MAAM,EAAE,QAAQ,EAAE,GAAG,KAAK,CAAC;QAChD,MAAM,EAAE,QAAQ,CAAC;QACjB,MAAM,EAAE,QAAQ,CAAC;QACjB,aAAa,EAAE,MAAM,CAAC;QACtB,iBAAiB,EAAE,MAAM,CAAC;KAC3B,CAAC;IA+BF,OAAO,CAAC,iBAAiB;IAOzB,OAAO,CAAC,aAAa;CAStB"}