keyring-agent-core 0.1.0

package/dist/tools/builtin/pool/PreviewAddLiquidityTool.js

@@ -0,0 +1,380 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PreviewAddLiquidityTool = void 0;
+const BaseTool_1 = require("../../BaseTool");
+const PoolService_1 = require("../../../services/PoolService");
+const pool_1 = require("../../../functions/pool");
+const PantographService_1 = require("../../../services/PantographService");
+const web3_1 = require("../../../functions/web3");
+const abi_1 = require("../../../constants/abi");
+/**
+ * Tool: preview-add-liquidity
+ *
+ * Called when the user has filled the AddLiquidityForm with:
+ *   - native amount (in wei)
+ *   - minPrice + maxPrice (token1 per token0, decimal-adjusted — the same unit
+ *     as `pool.currentPrice` returned by open-add-liquidity-form)
+ *
+ * The tool converts those prices into ticks (rounded to tickSpacing), fetches
+ * deBridge swap quotes for both legs, encodes the gateway.mint calldata, and
+ * returns:
+ *   - a UI payload (`ConfirmAddLiquidityTx`) the FE renders as a confirmation
+ *     panel showing expected token0/token1 amounts and the unsigned tx,
+ *   - the unsigned tx itself in `props.unsignedTx`, which the FE will pass to
+ *     a wallet-side execute function (e.g. wagmi.sendTransactionAsync).
+ *
+ * The user reviews the panel and either confirms (FE signs + broadcasts) or
+ * cancels. Native-only input — no approvals needed.
+ */
+class PreviewAddLiquidityTool extends BaseTool_1.BaseTool {
+    name = 'preview-add-liquidity';
+    kind = 'action';
+    category = 'pool-action';
+    description = 'Preview the add-liquidity transaction once the user has filled the AddLiquidityForm with a native amount ' +
+        'and a price range (min/max price in token1 per token0). The tool converts prices → ticks (rounded to ' +
+        'tickSpacing), fetches deBridge swap quotes for both legs, encodes the gateway.mint call, and returns an ' +
+        'unsigned tx the FE will sign. Do NOT call this until the user has filled both prices and an amount.';
+    parameters = [
+        {
+            name: 'poolAddress',
+            type: 'string',
+            description: 'V3 pool contract address (returned by open-add-liquidity-form in props.pool.address).',
+            required: true,
+        },
+        {
+            name: 'chain',
+            type: 'string',
+            description: 'Hex chain ID: "0x1" Ethereum, "0xa" Optimism, "0x38" BSC, "0x89" Polygon, "0x2105" Base, ' +
+                '"0xa4b1" Arbitrum, "0xa86a" Avalanche, "0xe708" Linea .Must match the pool\'s chain. Defaults to connected chain.',
+            required: true,
+        },
+        {
+            name: 'minPrice',
+            type: 'number',
+            description: 'Lower bound of the position price range, in token1-per-token0 units (decimal-adjusted — the SAME unit ' +
+                'as pool.currentPrice from open-add-liquidity-form). Example: if currentPrice is 1800 (USDC per WETH), ' +
+                'minPrice 900 means "the position is in-range while WETH ≥ 900 USDC". Must be > 0 and < maxPrice.',
+            required: true,
+        },
+        {
+            name: 'maxPrice',
+            type: 'number',
+            description: 'Upper bound of the position price range, in the same units as minPrice. Must be > minPrice. ' +
+                'Pass a very large number (or props.priceBounds.max) for a "full range upper" position.',
+            required: true,
+        },
+        {
+            name: 'nativeAmount',
+            type: 'number',
+            description: 'Native amount the user wants to spend, as a human-readable decimal number ' +
+                '(e.g. 0.1 for 0.1 ETH). The tool converts to wei internally.',
+            required: true,
+        },
+        {
+            name: 'slippageBps',
+            type: 'number',
+            description: 'Slippage tolerance in basis points (100 = 1%). Optional — defaults to 100.',
+            required: false,
+        },
+    ];
+    pool;
+    defaultSlippageBps;
+    mintMinPercent;
+    pantograph;
+    constructor(config) {
+        super();
+        this.pool = new PoolService_1.PoolService(config?.pool);
+        this.defaultSlippageBps = config?.defaultSlippageBps ?? 'auto';
+        this.mintMinPercent = config?.mintMinPercent ?? 80;
+        this.pantograph = new PantographService_1.PantographService();
+    }
+    /** Forward `ui` from run() into the ToolResult envelope. */
+    async execute(args, userContext) {
+        const callId = `call_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+        const start = Date.now();
+        try {
+            const out = (await this.run(args, userContext));
+            const result = {
+                toolName: this.name,
+                callId,
+                success: true,
+                data: out,
+                duration: Date.now() - start,
+            };
+            if (out && typeof out === 'object' && out.ui) {
+                result.ui = out.ui;
+            }
+            return result;
+        }
+        catch (err) {
+            return {
+                toolName: this.name,
+                callId,
+                success: false,
+                error: err instanceof Error ? err.message : String(err),
+                duration: Date.now() - start,
+            };
+        }
+    }
+    async run(args, userContext) {
+        const poolAddress = typeof args.poolAddress === 'string' ? args.poolAddress.trim() : '';
+        const chain = typeof args.chain === 'string' && args.chain.trim() ? args.chain.trim() : userContext?.chain || '';
+        const minPrice = Number(args.minPrice);
+        const maxPrice = Number(args.maxPrice);
+        const nativeAmountHuman = typeof args.nativeAmount === 'number' && Number.isFinite(args.nativeAmount) ? args.nativeAmount : NaN;
+        const slippageBps = typeof args.slippageBps === 'number' && Number.isFinite(args.slippageBps) && String(args.slippageBps) !== 'auto'
+            ? Math.floor(args.slippageBps) / 100
+            : String(this.defaultSlippageBps);
+        if (!poolAddress ||
+            !chain ||
+            !Number.isFinite(nativeAmountHuman) ||
+            !Number.isFinite(minPrice) ||
+            !Number.isFinite(maxPrice)) {
+            return {
+                error: 'missing_inputs',
+                _instructions: 'poolAddress, chain, minPrice, maxPrice, nativeAmount are all required.',
+            };
+        }
+        if (minPrice <= 0 || maxPrice <= 0 || minPrice >= maxPrice) {
+            return {
+                error: 'invalid_price_range',
+                _instructions: 'minPrice and maxPrice must both be > 0 and minPrice must be strictly less than maxPrice.',
+            };
+        }
+        if (nativeAmountHuman <= 0) {
+            return { error: 'invalid_native_amount', _instructions: 'nativeAmount must be > 0.' };
+        }
+        const meta = (0, PoolService_1.getChainMeta)(chain);
+        if (!meta)
+            return { error: 'unsupported_chain', chain };
+        const gateway = await this.pool.getGatewayAddress(chain);
+        if (!gateway)
+            return { error: 'no_gateway_configured', chain };
+        const walletAddress = userContext?.walletAddress;
+        if (!walletAddress)
+            return { error: 'wallet_not_connected' };
+        // Convert human-readable native amount to wei bigint
+        const native = (0, PoolService_1.getNativeTokenInfo)(chain);
+        const nativeAmount = BigInt(Math.floor(nativeAmountHuman * 10 ** native.decimals));
+        if (nativeAmount <= 0n) {
+            return { error: 'invalid_native_amount', _instructions: 'nativeAmount must be > 0.' };
+        }
+        // ---- Read pool to get tickSpacing + token decimals ----
+        const onchain = await this.pool.readPoolOnchain(chain, poolAddress);
+        const [token0Decimals, token1Decimals] = await Promise.all([
+            this.pool.readErc20Decimals(chain, onchain.token0),
+            this.pool.readErc20Decimals(chain, onchain.token1),
+        ]);
+        // ---- Convert prices → ticks → align to tickSpacing ----
+        // Floor the lower tick (round down → wider range), ceil the upper tick
+        // (round up → wider range). Both are clamped to V3's protocol bounds.
+        const rawTickLower = (0, PoolService_1.priceToTick)(minPrice, token0Decimals, token1Decimals);
+        const rawTickUpper = (0, PoolService_1.priceToTick)(maxPrice, token0Decimals, token1Decimals);
+        const tickLower = (0, PoolService_1.clampTick)((0, PoolService_1.roundTickToSpacing)(rawTickLower, onchain.tickSpacing, 'down'));
+        const tickUpper = (0, PoolService_1.clampTick)((0, PoolService_1.roundTickToSpacing)(rawTickUpper, onchain.tickSpacing, 'up'));
+        if (tickLower >= tickUpper || tickLower < pool_1.MIN_TICK || tickUpper > pool_1.MAX_TICK) {
+            return {
+                error: 'invalid_range_after_alignment',
+                _instructions: 'After aligning to tickSpacing the range collapsed. Ask the user for a wider price range.',
+                rawTickLower,
+                rawTickUpper,
+                tickLower,
+                tickUpper,
+            };
+        }
+        // Re-derive the actual range prices from the aligned ticks so the FE
+        // can display what was really used (may differ slightly from user input).
+        const resolvedRange = {
+            tickLower,
+            tickUpper,
+            minPrice: (0, PoolService_1.tickToPrice)(tickLower, token0Decimals, token1Decimals),
+            maxPrice: (0, PoolService_1.tickToPrice)(tickUpper, token0Decimals, token1Decimals),
+        };
+        // ---- Re-check balance ----
+        const [balanceWei, gasReserveWei, nativePriceUsd] = await Promise.all([
+            this.pool.getNativeBalance(chain, walletAddress),
+            this.pool.estimateGasReserveWei(chain),
+            this.pool.getNativePriceUsd(chain),
+        ]);
+        const required = nativeAmount + gasReserveWei;
+        if (balanceWei < required) {
+            return {
+                error: 'insufficient_balance',
+                _instructions: 'User does not have enough native coin (amount + gas reserve). ' +
+                    'Tell them the shortfall in their language.',
+                balanceWei: balanceWei.toString(),
+                requiredWei: required.toString(),
+                gasReserveWei: gasReserveWei.toString(),
+            };
+        }
+        // ---- Split native amount across the two pool tokens ----
+        const split = this.pool.splitNativeAmountForRange({
+            nativeAmountWei: nativeAmount,
+            pool: onchain,
+            tickLower,
+            tickUpper,
+            token0Decimals,
+            token1Decimals,
+        });
+        // ---- Build swap legs (skip when native == pool token) ----
+        const t0IsNative = onchain.token0.toLowerCase() === PoolService_1.ZERO_ADDRESS;
+        const t1IsNative = onchain.token1.toLowerCase() === PoolService_1.ZERO_ADDRESS;
+        const legs = [];
+        if (t0IsNative || split.amountInFor0Wei === 0n) {
+            legs.push({
+                tokenIn: PoolService_1.ZERO_ADDRESS,
+                tokenOut: onchain.token0,
+                amountIn: split.amountInFor0Wei,
+                tx: { to: PoolService_1.ZERO_ADDRESS, data: '0x', value: '0' },
+                minAmountOut: t0IsNative ? split.amountInFor0Wei : 0n,
+            });
+        }
+        else {
+            const swap = await this.pool.fetchSwapLeg({
+                senderAddress: walletAddress,
+                chainId: chain,
+                tokenIn: PoolService_1.ZERO_ADDRESS,
+                tokenInAmount: split.amountInFor0Wei.toString(),
+                tokenOut: onchain.token0,
+                tokenOutRecipient: gateway,
+                slippage: typeof slippageBps === 'number' ? slippageBps : 'auto',
+            });
+            legs.push({
+                tokenIn: PoolService_1.ZERO_ADDRESS,
+                tokenOut: onchain.token0,
+                amountIn: split.amountInFor0Wei,
+                tx: { to: swap.to, data: swap.data, value: swap.value },
+                minAmountOut: BigInt(swap.minAmountOut || '0'),
+            });
+        }
+        if (t1IsNative || split.amountInFor1Wei === 0n) {
+            legs.push({
+                tokenIn: PoolService_1.ZERO_ADDRESS,
+                tokenOut: onchain.token1,
+                amountIn: split.amountInFor1Wei,
+                tx: { to: PoolService_1.ZERO_ADDRESS, data: '0x', value: '0' },
+                minAmountOut: t1IsNative ? split.amountInFor1Wei : 0n,
+            });
+        }
+        else {
+            const swap = await this.pool.fetchSwapLeg({
+                senderAddress: walletAddress,
+                chainId: chain,
+                tokenIn: PoolService_1.ZERO_ADDRESS,
+                tokenInAmount: split.amountInFor1Wei.toString(),
+                tokenOut: onchain.token1,
+                tokenOutRecipient: gateway,
+                slippage: typeof slippageBps === 'number' ? slippageBps : 'auto',
+            });
+            legs.push({
+                tokenIn: PoolService_1.ZERO_ADDRESS,
+                tokenOut: onchain.token1,
+                amountIn: split.amountInFor1Wei,
+                tx: { to: swap.to, data: swap.data, value: swap.value },
+                minAmountOut: BigInt(swap.minAmountOut || '0'),
+            });
+        }
+        // ---- amount0Min/amount1Min: floor at mintMinPercent of swap minOut ----
+        const floorMin = (n) => (n * BigInt(this.mintMinPercent)) / 100n;
+        const amount0Min = floorMin(legs[0].minAmountOut);
+        const amount1Min = floorMin(legs[1].minAmountOut);
+        const paymentInfo = legs.map((l) => ({
+            tokenIn: l.tokenIn,
+            tokenInAmount: BigInt(l.amountIn),
+            tokenOut: l.tokenOut,
+            tokenOutAmount: BigInt(l.minAmountOut),
+        }));
+        const exchangesInfo = legs.map((l) => ({
+            to: l.tx.to,
+            data: l.tx.data,
+            value: BigInt(l.tx.value || '0'),
+        }));
+        console.log('🚀 ~ PreviewAddLiquidityTool ~ run ~ paymentInfo:', paymentInfo);
+        console.log('🚀 ~ PreviewAddLiquidityTool ~ run ~ exchangesInfo:', exchangesInfo);
+        console.log('🚀 ~ PreviewAddLiquidityTool ~ run ~ args:', {
+            args: [
+                paymentInfo,
+                exchangesInfo,
+                {
+                    fee: Number(onchain.fee),
+                    amount0Min: BigInt(amount0Min),
+                    amount1Min: BigInt(amount1Min),
+                    tickLower,
+                    tickUpper,
+                },
+            ],
+        });
+        const calldata = (0, web3_1.encodeFunctionData)({
+            abi: abi_1.GatewayAbi,
+            functionName: 'mint',
+            args: [
+                paymentInfo,
+                exchangesInfo,
+                {
+                    fee: Number(onchain.fee),
+                    amount0Min: BigInt(amount0Min),
+                    amount1Min: BigInt(amount1Min),
+                    tickLower,
+                    tickUpper,
+                },
+            ],
+        });
+        const humanAmountIn = nativeAmountHuman;
+        const unsignedTx = {
+            chainId: chain,
+            to: gateway,
+            data: calldata,
+            value: nativeAmount.toString(),
+            from: walletAddress,
+        };
+        const txSummary = {
+            nativeIn: humanAmountIn,
+            nativeInUsd: nativePriceUsd != null ? humanAmountIn * nativePriceUsd : null,
+            ratio: { token0Percent: split.ratio0, token1Percent: split.ratio1 },
+            expectedToken0: Number(legs[0].minAmountOut) / 10 ** token0Decimals,
+            expectedToken1: Number(legs[1].minAmountOut) / 10 ** token1Decimals,
+            amount0Min: amount0Min.toString(),
+            amount1Min: amount1Min.toString(),
+            slippageBps,
+        };
+        const dataTokens = await this.pantograph.getTokensMetadata([onchain.token0, onchain.token1], chain);
+        const token0Info = dataTokens[onchain.token0];
+        const token1Info = dataTokens[onchain.token1];
+        const props = {
+            chain: { hexId: chain, name: meta.name },
+            unsignedTx,
+            summary: txSummary,
+            pool: {
+                ...onchain,
+                feePercent: onchain.fee / 10_000,
+                token0: {
+                    address: onchain.token0,
+                    symbol: token0Info.symbol,
+                    name: token0Info.name,
+                    decimals: token0Info.decimals,
+                    logo: token0Info.icon_image,
+                },
+                token1: {
+                    address: onchain.token1,
+                    symbol: token1Info.symbol,
+                    name: token1Info.name,
+                    decimals: token1Info.decimals,
+                    logo: token1Info.icon_image,
+                },
+            },
+            range: resolvedRange,
+            gatewayAddress: gateway,
+        };
+        const ui = { component: 'ConfirmAddLiquidityTx', props };
+        return {
+            ui,
+            summary: `Ready to add ${humanAmountIn} ${native.symbol} to pool ${onchain.token0}/${onchain.token1} ` +
+                `${onchain.fee / 10_000}% on ${meta.name}, range [${resolvedRange.minPrice}, ${resolvedRange.maxPrice}].`,
+            _instructions: 'A confirmation panel has been opened on the FE; the user will sign and broadcast the unsigned tx with their wallet. ' +
+                'Briefly tell them (in their language) what is about to happen — the native amount, the auto-split ratio between the two pool tokens, ' +
+                'and the chosen price range. Do NOT mention internal tool/component names.',
+        };
+    }
+}
+exports.PreviewAddLiquidityTool = PreviewAddLiquidityTool;
+//# sourceMappingURL=PreviewAddLiquidityTool.js.map

package/dist/tools/builtin/pool/PreviewAddLiquidityTool.js.map

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

package/dist/tools/builtin/pool/TopPoolsTool.d.ts

@@ -0,0 +1,68 @@
+import { BaseTool } from '../../BaseTool';
+import type { ToolParameter, UserContext } from '../../../types';
+import { type UniswapServiceConfig, type UniswapProtocolVersion } from '../../../services/UniswapService';
+export type TopPoolsToolConfig = UniswapServiceConfig;
+/**
+ * Tool: get-top-pools
+ *
+ * Wraps Uniswap's ExploreStats endpoint
+ * (`uniswap.explore.v1.ExploreStatsService/ExploreStats`) to surface the
+ * top liquidity pools for a given EVM chain. Returns pools ranked by TVL by
+ * default; sorting can be switched to volume or transaction count.
+ */
+export declare class TopPoolsTool extends BaseTool {
+    name: string;
+    description: string;
+    category: string;
+    parameters: ToolParameter[];
+    private service;
+    constructor(config?: TopPoolsToolConfig);
+    protected run(args: Record<string, unknown>, userContext?: UserContext): Promise<{
+        error: string;
+        _instructions?: undefined;
+        chain?: undefined;
+        protocolVersion?: undefined;
+        sortBy?: undefined;
+        count?: undefined;
+        pools?: undefined;
+    } | {
+        _instructions: string;
+        chain: string;
+        protocolVersion: UniswapProtocolVersion;
+        sortBy: "tvl" | "volume1Day" | "volume1Week" | "volume30Day" | "txCount" | "apr";
+        count: number;
+        pools: {
+            apr: number | undefined;
+            address: string;
+            chain: string | undefined;
+            protocolVersion: UniswapProtocolVersion | undefined;
+            feeTierBps: number | undefined;
+            feeTierPercent: number | undefined;
+            tvlUsd: number | undefined;
+            volume1DayUsd: number | undefined;
+            volume1WeekUsd: number | undefined;
+            volume30DayUsd: number | undefined;
+            txCount: number | undefined;
+            token0: {
+                address: string | undefined;
+                symbol: string | undefined;
+                name: string | undefined;
+                decimals: number | undefined;
+                priceUsd: number | undefined;
+            } | undefined;
+            token1: {
+                address: string | undefined;
+                symbol: string | undefined;
+                name: string | undefined;
+                decimals: number | undefined;
+                priceUsd: number | undefined;
+            } | undefined;
+        }[];
+        error?: undefined;
+    }>;
+    private parseProtocolVersion;
+    private parseSortKey;
+    /** Trim the upstream payload to the fields a downstream LLM actually needs. */
+    private formatPool;
+}
+//# sourceMappingURL=TopPoolsTool.d.ts.map

package/dist/tools/builtin/pool/TopPoolsTool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TopPoolsTool.d.ts","sourceRoot":"","sources":["../../../../src/tools/builtin/pool/TopPoolsTool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AACjE,OAAO,EAEL,KAAK,oBAAoB,EAEzB,KAAK,sBAAsB,EAC5B,MAAM,kCAAkC,CAAC;AAE1C,MAAM,MAAM,kBAAkB,GAAG,oBAAoB,CAAC;AAOtD;;;;;;;GAOG;AACH,qBAAa,YAAa,SAAQ,QAAQ;IACxC,IAAI,SAAmB;IACvB,WAAW,SAOsE;IACjF,QAAQ,SAAqB;IAC7B,UAAU,EAAE,aAAa,EAAE,CA6CzB;IAEF,OAAO,CAAC,OAAO,CAAiB;gBAEpB,MAAM,CAAC,EAAE,kBAAkB;cAKvB,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,CAAC,EAAE,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAuC5E,OAAO,CAAC,oBAAoB;IAU5B,OAAO,CAAC,YAAY;IAUpB,+EAA+E;IAC/E,OAAO,CAAC,UAAU;CAiCnB"}

package/dist/tools/builtin/pool/TopPoolsTool.js

@@ -0,0 +1,158 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TopPoolsTool = void 0;
+const BaseTool_1 = require("../../BaseTool");
+const UniswapService_1 = require("../../../services/UniswapService");
+const SUPPORTED_SORT_KEYS = ['tvl', 'volume1Day', 'volume1Week', 'volume30Day', 'txCount', 'apr'];
+const SUPPORTED_VERSIONS = ['V2', 'V3', 'V4'];
+/**
+ * Tool: get-top-pools
+ *
+ * Wraps Uniswap's ExploreStats endpoint
+ * (`uniswap.explore.v1.ExploreStatsService/ExploreStats`) to surface the
+ * top liquidity pools for a given EVM chain. Returns pools ranked by TVL by
+ * default; sorting can be switched to volume or transaction count.
+ */
+class TopPoolsTool extends BaseTool_1.BaseTool {
+    name = 'get-top-pools';
+    description = 'List the top Uniswap liquidity pools on a given EVM chain, ranked by TVL by default. ' +
+        "Returns each pool's address, fee tier, protocol version, both tokens (symbol, name, address, decimals), " +
+        'TVL, transaction count, and rolling volume buckets (1d / 1w / 30d). ' +
+        'Use this tool for questions like: "top pools on Ethereum", "biggest Uniswap V3 pools on Base", ' +
+        '"which pool has the most liquidity for USDC", "show pools with highest 24h volume on Arbitrum". ' +
+        'Source: https://app.uniswap.org/explore (ExploreStats gateway). ' +
+        'Supports: Ethereum, Optimism, BSC, Polygon, Base, Arbitrum, Avalanche, Linea';
+    category = 'blockchain-data';
+    parameters = [
+        {
+            name: 'chain',
+            type: 'string',
+            description: 'Hex chain ID: "0x1" Ethereum, "0xa" Optimism, "0x38" BSC, "0x89" Polygon, "0x2105" Base, ' +
+                '"0xa4b1" Arbitrum, "0xa86a" Avalanche, "0xe708" Linea. Defaults to connected chain.',
+            required: true,
+        },
+        {
+            name: 'protocolVersion',
+            type: 'string',
+            description: 'Uniswap protocol version to filter by: "V2", "V3", or "V4". ' +
+                'Default is "V3" (the dataset with the richest stats). ' +
+                'Use "V4" only when the user explicitly asks for V4 pools.',
+            required: false,
+            default: 'V3',
+        },
+        {
+            name: 'sortBy',
+            type: 'string',
+            description: 'Ranking metric: "tvl" (total value locked, default), "volume1Day", "volume1Week", ' +
+                '"volume30Day", "txCount", or "apr" (estimated annualized fee yield). ' +
+                'Pools are returned in descending order by this metric.',
+            required: false,
+            default: 'tvl',
+        },
+        {
+            name: 'limit',
+            type: 'number',
+            description: 'Maximum number of pools to return after sorting. Defaults to 10.',
+            required: false,
+            default: 10,
+        },
+        {
+            name: 'multichain',
+            type: 'boolean',
+            description: "When true, request Uniswap's multichain aggregated view instead of a single chain. " +
+                'Defaults to false. Most queries should leave this off.',
+            required: false,
+            default: false,
+        },
+    ];
+    service;
+    constructor(config) {
+        super();
+        this.service = new UniswapService_1.UniswapService(config);
+    }
+    async run(args, userContext) {
+        const chain = typeof args.chain === 'string' && args.chain.trim() ? args.chain.trim() : userContext?.chain || '0x1';
+        const protocolVersion = this.parseProtocolVersion(args.protocolVersion);
+        const sortBy = this.parseSortKey(args.sortBy);
+        const limit = typeof args.limit === 'number' && Number.isFinite(args.limit) && args.limit > 0
+            ? Math.min(Math.floor(args.limit), 50)
+            : 10;
+        const multichain = args.multichain === true;
+        const result = await this.service.getTopPools({
+            chain,
+            protocolVersion,
+            sortBy,
+            limit,
+            multichain,
+        });
+        if (!result.success) {
+            return { error: result.error || 'Failed to fetch top pools' };
+        }
+        const pools = (result.data ?? []).map((p) => this.formatPool(p));
+        return {
+            _instructions: 'Present the pools as a ranked list. For each pool show: rank, pair (token0/token1 symbols), apr(in %), ' +
+                'fee tier (in %), TVL in USD, 24h volume, 24h fee revenue, and protocol version. ' +
+                'Format numbers human-readably (e.g. $12.5M, 0.05%). Mention the chain and the sort metric ' +
+                'in the intro line. If a value is null, omit it. Do NOT mention tool or API names.',
+            chain,
+            protocolVersion,
+            sortBy,
+            count: pools.length,
+            pools,
+        };
+    }
+    parseProtocolVersion(value) {
+        if (typeof value === 'string') {
+            const upper = value.trim().toUpperCase();
+            if (SUPPORTED_VERSIONS.includes(upper)) {
+                return upper;
+            }
+        }
+        return 'V3';
+    }
+    parseSortKey(value) {
+        if (typeof value === 'string') {
+            const trimmed = value.trim();
+            if (SUPPORTED_SORT_KEYS.includes(trimmed)) {
+                return trimmed;
+            }
+        }
+        return 'tvl';
+    }
+    /** Trim the upstream payload to the fields a downstream LLM actually needs. */
+    formatPool(p) {
+        return {
+            apr: p.apr,
+            address: p.id,
+            chain: p.chain,
+            protocolVersion: p.protocolVersion,
+            feeTierBps: p.feeTier,
+            feeTierPercent: typeof p.feeTier === 'number' ? p.feeTier / 10_000 : undefined,
+            tvlUsd: p.totalLiquidity?.value,
+            volume1DayUsd: p.volume1Day?.value,
+            volume1WeekUsd: p.volume1Week?.value,
+            volume30DayUsd: p.volume30Day?.value,
+            txCount: p.txCount,
+            token0: p.token0
+                ? {
+                    address: p.token0.address,
+                    symbol: p.token0.symbol,
+                    name: p.token0.name,
+                    decimals: p.token0.decimals,
+                    priceUsd: p.token0.price?.value,
+                }
+                : undefined,
+            token1: p.token1
+                ? {
+                    address: p.token1.address,
+                    symbol: p.token1.symbol,
+                    name: p.token1.name,
+                    decimals: p.token1.decimals,
+                    priceUsd: p.token1.price?.value,
+                }
+                : undefined,
+        };
+    }
+}
+exports.TopPoolsTool = TopPoolsTool;
+//# sourceMappingURL=TopPoolsTool.js.map

package/dist/tools/builtin/pool/TopPoolsTool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TopPoolsTool.js","sourceRoot":"","sources":["../../../../src/tools/builtin/pool/TopPoolsTool.ts"],"names":[],"mappings":";;;AAAA,6CAA0C;AAE1C,qEAK0C;AAI1C,MAAM,mBAAmB,GAAG,CAAC,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,SAAS,EAAE,KAAK,CAAU,CAAC;AAG3G,MAAM,kBAAkB,GAA6B,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;AAExE;;;;;;;GAOG;AACH,MAAa,YAAa,SAAQ,mBAAQ;IACxC,IAAI,GAAG,eAAe,CAAC;IACvB,WAAW,GACT,uFAAuF;QACvF,0GAA0G;QAC1G,sEAAsE;QACtE,iGAAiG;QACjG,kGAAkG;QAClG,kEAAkE;QAClE,8EAA8E,CAAC;IACjF,QAAQ,GAAG,iBAAiB,CAAC;IAC7B,UAAU,GAAoB;QAC5B;YACE,IAAI,EAAE,OAAO;YACb,IAAI,EAAE,QAAQ;YACd,WAAW,EACT,2FAA2F;gBAC3F,qFAAqF;YACvF,QAAQ,EAAE,IAAI;SACf;QACD;YACE,IAAI,EAAE,iBAAiB;YACvB,IAAI,EAAE,QAAQ;YACd,WAAW,EACT,8DAA8D;gBAC9D,wDAAwD;gBACxD,2DAA2D;YAC7D,QAAQ,EAAE,KAAK;YACf,OAAO,EAAE,IAAI;SACd;QACD;YACE,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,QAAQ;YACd,WAAW,EACT,oFAAoF;gBACpF,uEAAuE;gBACvE,wDAAwD;YAC1D,QAAQ,EAAE,KAAK;YACf,OAAO,EAAE,KAAK;SACf;QACD;YACE,IAAI,EAAE,OAAO;YACb,IAAI,EAAE,QAAQ;YACd,WAAW,EAAE,kEAAkE;YAC/E,QAAQ,EAAE,KAAK;YACf,OAAO,EAAE,EAAE;SACZ;QACD;YACE,IAAI,EAAE,YAAY;YAClB,IAAI,EAAE,SAAS;YACf,WAAW,EACT,qFAAqF;gBACrF,wDAAwD;YAC1D,QAAQ,EAAE,KAAK;YACf,OAAO,EAAE,KAAK;SACf;KACF,CAAC;IAEM,OAAO,CAAiB;IAEhC,YAAY,MAA2B;QACrC,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,OAAO,GAAG,IAAI,+BAAc,CAAC,MAAM,CAAC,CAAC;IAC5C,CAAC;IAES,KAAK,CAAC,GAAG,CAAC,IAA6B,EAAE,WAAyB;QAC1E,MAAM,KAAK,GAAG,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,KAAK,IAAI,KAAK,CAAC;QAEpH,MAAM,eAAe,GAAG,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;QACxE,MAAM,MAAM,GAAG,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC9C,MAAM,KAAK,GACT,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,KAAK,GAAG,CAAC;YAC7E,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC;YACtC,CAAC,CAAC,EAAE,CAAC;QACT,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,KAAK,IAAI,CAAC;QAE5C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC;YAC5C,KAAK;YACL,eAAe;YACf,MAAM;YACN,KAAK;YACL,UAAU;SACX,CAAC,CAAC;QAEH,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,2BAA2B,EAAE,CAAC;QAChE,CAAC;QAED,MAAM,KAAK,GAAG,CAAC,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;QAEjE,OAAO;YACL,aAAa,EACX,yGAAyG;gBACzG,kFAAkF;gBAClF,4FAA4F;gBAC5F,mFAAmF;YACrF,KAAK;YACL,eAAe;YACf,MAAM;YACN,KAAK,EAAE,KAAK,CAAC,MAAM;YACnB,KAAK;SACN,CAAC;IACJ,CAAC;IAEO,oBAAoB,CAAC,KAAc;QACzC,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;YACzC,IAAK,kBAA+B,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;gBACrD,OAAO,KAA+B,CAAC;YACzC,CAAC;QACH,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAEO,YAAY,CAAC,KAAc;QACjC,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;YAC7B,IAAK,mBAAyC,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;gBACjE,OAAO,OAAkB,CAAC;YAC5B,CAAC;QACH,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,+EAA+E;IACvE,UAAU,CAAC,CAAmB;QACpC,OAAO;YACL,GAAG,EAAE,CAAC,CAAC,GAAG;YACV,OAAO,EAAE,CAAC,CAAC,EAAE;YACb,KAAK,EAAE,CAAC,CAAC,KAAK;YACd,eAAe,EAAE,CAAC,CAAC,eAAe;YAClC,UAAU,EAAE,CAAC,CAAC,OAAO;YACrB,cAAc,EAAE,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,GAAG,MAAM,CAAC,CAAC,CAAC,SAAS;YAC9E,MAAM,EAAE,CAAC,CAAC,cAAc,EAAE,KAAK;YAC/B,aAAa,EAAE,CAAC,CAAC,UAAU,EAAE,KAAK;YAClC,cAAc,EAAE,CAAC,CAAC,WAAW,EAAE,KAAK;YACpC,cAAc,EAAE,CAAC,CAAC,WAAW,EAAE,KAAK;YACpC,OAAO,EAAE,CAAC,CAAC,OAAO;YAClB,MAAM,EAAE,CAAC,CAAC,MAAM;gBACd,CAAC,CAAC;oBACE,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO;oBACzB,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM;oBACvB,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI;oBACnB,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,QAAQ;oBAC3B,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK;iBAChC;gBACH,CAAC,CAAC,SAAS;YACb,MAAM,EAAE,CAAC,CAAC,MAAM;gBACd,CAAC,CAAC;oBACE,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO;oBACzB,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM;oBACvB,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI;oBACnB,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,QAAQ;oBAC3B,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK;iBAChC;gBACH,CAAC,CAAC,SAAS;SACd,CAAC;IACJ,CAAC;CACF;AA9JD,oCA8JC"}

package/dist/tools/builtin/pool/index.d.ts

@@ -0,0 +1,15 @@
+export { TopPoolsTool } from './TopPoolsTool';
+export type { TopPoolsToolConfig } from './TopPoolsTool';
+export { PoolDetailTool } from './PoolDetailTool';
+export type { PoolDetailToolConfig } from './PoolDetailTool';
+export { PoolSearchTool } from './PoolSearchTool';
+export type { PoolSearchToolConfig } from './PoolSearchTool';
+export { PoolByAddressTool } from './PoolByAddressTool';
+export type { PoolByAddressToolConfig } from './PoolByAddressTool';
+export { OpenAddLiquidityFormTool } from './OpenAddLiquidityFormTool';
+export type { OpenAddLiquidityFormToolConfig } from './OpenAddLiquidityFormTool';
+export { PreviewAddLiquidityTool } from './PreviewAddLiquidityTool';
+export type { PreviewAddLiquidityToolConfig } from './PreviewAddLiquidityTool';
+export { EstimatePoolYieldTool } from './EstimatePoolYieldTool';
+export type { EstimatePoolYieldToolConfig } from './EstimatePoolYieldTool';
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/builtin/pool/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/tools/builtin/pool/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,YAAY,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,YAAY,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,YAAY,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAC7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,YAAY,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AACnE,OAAO,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AACtE,YAAY,EAAE,8BAA8B,EAAE,MAAM,4BAA4B,CAAC;AACjF,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACpE,YAAY,EAAE,6BAA6B,EAAE,MAAM,2BAA2B,CAAC;AAC/E,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,YAAY,EAAE,2BAA2B,EAAE,MAAM,yBAAyB,CAAC"}