keyring-agent-core 0.2.0 → 0.2.2

package/dist/tools/builtin/wallet-action/SwapTokenTool.js

@@ -1,1258 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.SwapTokenTool = void 0;
-const BaseTool_1 = require("../../BaseTool");
-const web3_1 = require("../../../functions/web3");
-const MoralisService_1 = require("../../../services/MoralisService");
-const PantographService_1 = require("../../../services/PantographService");
-const swap_1 = require("../../../services/swap");
-const PoolService_1 = require("../../../services/PoolService");
-const abi_1 = require("../../../constants/abi");
-const amountSpec_1 = require("./amountSpec");
-const gasReserve_1 = require("./gasReserve");
-const chainResolver_1 = require("../../chainResolver");
-/**
- * Tool: open-swap-token-form
- *
- * A STANDALONE wallet-action tool (NOT a `BaseWalletActionTool`), built as the
- * mirror of {@link BuyTokenTool}: it does the quote + approval work itself and
- * ships a custom `SwapTokenConfirmTx` UI payload the FE executes directly. That's
- * why `swap_token` is intentionally NOT a member of `WalletActionType`.
- *
- * The defining difference from BUY: the SOURCE is a token the user ALREADY HOLDS.
- * Buy starts from a destination ("buy PEPE") and asks which wallet token to pay
- * with; swap starts from the user's own token ("swap USDC") and asks what to
- * receive. The source is therefore always balance-checked — we never quote a
- * swap the user can't fund.
- *
- *   - "swap usdc to usdt" → from = USDC (held), to = USDT.
- *   - "swap usdc"         → from = USDC (held); destination unknown ⇒ trending
- *                           picker so the user picks what to receive.
- *   - "swap"              → nothing named ⇒ source picker built from the wallet's
- *                           own holdings so the user picks what to swap FROM.
- *
- * Branches, picked deterministically from the args:
- *
- *  0. **Source picker** — the user named NO source (`from_symbol`/`from_address`
- *     empty). The tool fetches the wallet's native + ERC-20 holdings and emits
- *     `actionButtons` so the user picks which token to swap FROM. A click
- *     re-submits a prompt like `"swap USDC"` which routes back here.
- *
- *  1. **Destination picker (trending)** — the user named the source only. The
- *     tool fetches the chain's live trending list (minus the source token) and
- *     emits `actionButtons` so the user picks what to receive. A click submits a
- *     prompt like `"swap USDC to PEPE"` which routes back for the standard flow.
- *
- *  1.4 **Balance check** — the source token is named (amount optional). Runs
- *     before anything else so we never proceed with a token the user can't fund:
- *     if the wallet holds NONE of it, the tool offers the tokens the user DOES
- *     hold instead (source picker); if it holds SOME but less than the requested
- *     amount, it reports the shortfall and emits 25/50/75/100% buttons sized off
- *     the real balance. Skipped for the native source token.
- *
- *  1.5 **Amount picker** — source + dest known but no amount given. The tool
- *     reads the source balance and emits 25/50/75/100% buttons so the user sizes
- *     the swap in one tap (or types a custom amount).
- *
- *  1.75 **Confirm tx** — source + dest + a SOURCE amount are all known. The tool
- *     fetches a swap quote (estimated receive amount + the raw swap tx), checks
- *     allowance, and emits a `SwapTokenConfirmTx` payload bundling the estimate,
- *     the raw swap transaction, and the approve transaction (when one is needed).
- *     The FE executes approve (if any) then swap itself.
- *
- *  When none of the above produces a result (couldn't resolve a token, quote
- *  failed, …) the tool returns an error/_instructions object — it never opens a
- *  generic form.
- *
- * Amount disambiguation mirrors BuyTokenTool. The swap is EXACT_INPUT (deBridge),
- * so the amount that seeds the quote is the SOURCE amount:
- *   - "swap 10 USDC to USDT"  → from_amount = "10"
- *   - "swap USDC to 5 USDT"   → to_amount = "5" (converted to a source amount via
- *                                live USD prices, like BuyTokenTool's buy side).
- */
-class SwapTokenTool extends BaseTool_1.BaseTool {
-    name = 'open-swap-token-form';
-    kind = 'action';
-    category = 'wallet-action';
-    // The tool drives a concrete confirm/pick step — no generic LLM follow-ups.
-    noSuggestions = true;
-    moralis;
-    /** Trending tokens come from Pantograph (top-gainers), not Moralis. */
-    pantograph;
-    /** Branch-tracing on/off — shares AgentCore's `debug` flag (passed in). */
-    debug;
-    constructor(config, options) {
-        super();
-        if (config !== undefined) {
-            this.moralis = new MoralisService_1.MoralisService(config);
-            this.pantograph = new PantographService_1.PantographService({ baseUrl: config.pantographUrl });
-        }
-        this.debug = options?.debug ?? false;
-    }
-    /**
-     * Branch-tracing logger. Prints which branch the tool takes and the key
-     * values feeding that decision. Enabled by AgentCore's shared `debug` flag.
-     */
-    dbg(label, data) {
-        if (this.debug) {
-            if (data === undefined)
-                console.log(`[SwapTokenTool] ${label}`);
-            else
-                console.log(`[SwapTokenTool] ${label}`, JSON.stringify(data));
-        }
-    }
-    description = 'Open the SWAP TOKEN flow for ANY swap/exchange/convert intent where the user swaps a token they ' +
-        'ALREADY HOLD into another token — "swap USDC to USDT", "swap USDC", "đổi USDC sang ETH", "convert ' +
-        'DAI to USDC", "exchange 10 USDC for PEPE". The FROM token is the user\'s own holding (the source). ' +
-        'Handles both cases: (a) the user named the destination — "swap USDC to USDT": pass `from_symbol` ' +
-        '(the source, e.g. "USDC") and `to_symbol` (the destination, e.g. "USDT"). ' +
-        '(b) the user named only the source — "swap USDC": pass `from_symbol` and leave `to_symbol` blank; ' +
-        "the tool returns buttons of the chain's current trending tokens so the user picks what to receive. " +
-        'If the user named NO token at all — "swap" / "đổi token": leave both blank and the tool returns the ' +
-        "wallet's holdings so the user picks what to swap FROM. " +
-        'Amount: `from_amount` = source to SPEND; `to_amount` = destination to RECEIVE. Never both.';
-    parameters = [
-        { name: 'chain', type: 'string', description: 'Hex chain id. Defaults to connected chain.', required: false },
-        {
-            name: 'from_symbol',
-            type: 'string',
-            description: 'Symbol of the SOURCE token the user wants to swap FROM — a token they already hold (e.g. "USDC"). ' +
-                'Leave EMPTY only when the user named no token at all (e.g. "swap") — the tool then returns the ' +
-                "wallet's holdings to pick the source from.",
-            required: false,
-        },
-        {
-            name: 'from_address',
-            type: 'string',
-            description: 'Source token address (0x…), OR "native" for the chain\'s native coin. Leave empty when unknown — ' +
-                'the tool resolves it from from_symbol.',
-            required: false,
-        },
-        {
-            name: 'from_amount',
-            type: 'string',
-            description: 'Quantity of the SOURCE token (the one being swapped FROM / spent) the user wants to SPEND. ' +
-                'Set this when the amount sits next to the source token: "swap 10 USDC to USDT", "đổi 10 USDC sang ETH" ' +
-                '→ from_amount = the number next to USDC. May also be a PERCENT of the source balance ("swap 50% USDC ' +
-                'to USDT" → "50%"), the literal word "max" meaning the WHOLE balance, or a USD value ("swap $5 USDC ' +
-                'to USDT" → "5$"). NORMALIZE any "whole balance / everything / maximum" phrasing in ANY language ' +
-                '(e.g. "all", "max", "tất cả", "toàn bộ", "全部", "すべて", "전부", "todo", "tout") to the literal ' +
-                '"max"; pass plain/percent/USD numbers VERBATIM (the tool converts "%"/"$"/"max"). "max" is an AMOUNT, ' +
-                'never a token — still set from_symbol to the source token ("ETH" in "swap max ETH to USDC"). ' +
-                'Mutually exclusive with to_amount — set at most ONE of the two.',
-            required: false,
-        },
-        {
-            name: 'to_symbol',
-            type: 'string',
-            description: 'Symbol of the DESTINATION token the user wants to RECEIVE (e.g. "USDT"). Leave EMPTY when the user ' +
-                'did not name a destination (e.g. "swap USDC") — the tool then returns trending tokens to pick from.',
-            required: false,
-        },
-        {
-            name: 'to_address',
-            type: 'string',
-            description: 'Destination token address (0x…), OR "native" for the chain\'s native coin. Leave empty when unknown — ' +
-                'the tool resolves it from to_symbol.',
-            required: false,
-        },
-        {
-            name: 'to_amount',
-            type: 'string',
-            description: 'Quantity of the DESTINATION token (the one being received) the user wants to RECEIVE. ' +
-                'Set this when the amount sits next to the destination token: "swap USDC to 5 USDT" → to_amount = the ' +
-                'number next to USDT. May also be a USD value ("swap USDC to $5 USDT" → "5$"); pass the user\'s ' +
-                'expression VERBATIM (the tool converts "$"). Mutually exclusive with from_amount — set at most ONE.',
-            required: false,
-        },
-        {
-            name: 'limit',
-            type: 'number',
-            description: 'Only used when no destination is named: max number of trending tokens to show as buttons. Default 6. Clamped to [1, 10].',
-            required: false,
-        },
-        {
-            name: 'swap_from_prompt_template',
-            type: 'string',
-            description: 'A short "swap {token}" command IN THE USER\'S CURRENT LANGUAGE, used as the click-command for the ' +
-                'source picker (when the user named no token). Use the exact placeholder "{token}" (do not translate the ' +
-                'braces) for the source symbol; put the localized verb directly in the text. ' +
-                'English example: "swap {token}". Vietnamese example: "đổi {token}". Japanese example: "{token} をスワップ". ' +
-                'Always include {token}.',
-            required: true,
-        },
-        {
-            name: 'swap_to_prompt_template',
-            type: 'string',
-            description: 'A short "swap X to Y" command IN THE USER\'S CURRENT LANGUAGE, used as the click-command for the ' +
-                'destination (trending) picker and the percentage-spend buttons. Use these exact placeholders (do not ' +
-                'translate the braces): "{from}" = source token, "{to}" = destination token, "{from_amount}" = quantity ' +
-                'of the SOURCE token (place it next to {from}), "{to_amount}" = quantity of the DESTINATION token (place ' +
-                'it next to {to}). Put the localized verb and the "to" preposition directly in the text. ' +
-                'English example: "swap {from_amount} {from} to {to_amount} {to}". ' +
-                'Vietnamese example: "đổi {from_amount} {from} sang {to_amount} {to}". ' +
-                'Japanese example: "{from_amount} {from} を {to_amount} {to} にスワップ". ' +
-                'Always include {from} and {to}. Include both {from_amount} and {to_amount} too — the tool removes ' +
-                'whichever amount is unknown (only one side ever carries an amount).',
-            required: true,
-        },
-    ];
-    // -------------------------------------------------------------------------
-    // execute: lift `ui` / `actionButtons` from run() onto the ToolResult.
-    // -------------------------------------------------------------------------
-    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;
-            }
-            if (out && Array.isArray(out.actionButtons) && out.actionButtons.length > 0) {
-                result.actionButtons = out.actionButtons;
-            }
-            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 walletAddress = userContext?.walletAddress;
-        if (!walletAddress) {
-            return {
-                error: 'wallet_not_connected',
-                _instructions: 'The user is not connected. Ask them to connect their wallet before swapping. Do NOT proceed.',
-            };
-        }
-        // The wallet can only sign on the chain it's connected to. If the user named
-        // a chain that differs from their connected chain, ask them to switch first
-        // instead of building a swap they can't sign.
-        const mismatch = (0, chainResolver_1.detectChainMismatch)(args.chain, userContext);
-        if (mismatch) {
-            return {
-                error: 'wrong_chain',
-                _instructions: `The user asked to swap on ${mismatch.requestedLabel}, but their wallet is connected to ${mismatch.connectedLabel}. ` +
-                    `Tell them, in their language, that to swap on ${mismatch.requestedLabel} they must first switch their wallet's network to ${mismatch.requestedLabel}, ` +
-                    `or they can swap on ${mismatch.connectedLabel} (their current network) instead. Do NOT proceed. Do NOT mention tool names, UI, or forms.`,
-            };
-        }
-        const chainId = this.requireChain(args, userContext);
-        if (!chainId) {
-            return {
-                error: 'missing_chain',
-                _instructions: 'No chain is set. Pass the hex chain id explicitly (e.g. "0x1") or set userContext.chain before calling.',
-            };
-        }
-        return this.buildResult(args, userContext);
-    }
-    // -------------------------------------------------------------------------
-    // Main branch dispatch
-    // -------------------------------------------------------------------------
-    async buildResult(args, userContext) {
-        const fromSymbol = typeof args.from_symbol === 'string' ? args.from_symbol.trim() : '';
-        const fromRef = typeof args.from_address === 'string' ? args.from_address.trim() : '';
-        const toSymbol = typeof args.to_symbol === 'string' ? args.to_symbol.trim() : '';
-        const chain = this.requireChain(args, userContext) ?? undefined;
-        const walletAddress = userContext?.walletAddress ?? undefined;
-        this.dbg('buildResult:args', { args, chain, walletAddress, hasMoralis: !!this.moralis });
-        // ----- Branch 0: SOURCE PICKER — no source token named at all ----------
-        if (!fromSymbol && !fromRef) {
-            this.dbg('→ Branch 0: source picker (no source token named)');
-            return await this.buildSourcePicker(args, userContext);
-        }
-        // ----- Resolve SOURCE token (symbol/address → address + decimals) ------
-        const fromSide = await this.resolveSide(args.from_address, fromSymbol, chain, walletAddress, 'from');
-        const fromContract = fromSide.address;
-        const fromSym = fromSide.symbol ?? fromSymbol;
-        const fromDecimals = fromSide.decimals;
-        // ----- Resolve DEST token (if user gave one) ---------------------------
-        const toSide = await this.resolveSide(args.to_address, toSymbol, chain, walletAddress, 'to');
-        const toContract = toSide.address;
-        const toSym = toSide.symbol ?? toSymbol;
-        const toDecimals = toSide.decimals;
-        // Amounts may be plain ("10"), a percent of balance ("50%"), or a USD value
-        // ("5$"). From-side percent/usd resolve against the SOURCE token's
-        // balance/price; to-side usd resolves against the DEST token's price (percent
-        // on the to side is meaningless, so it's ignored).
-        const toAmount = await this.resolveToAmountSpec(args.to_amount, toContract, chain, toSym);
-        let fromAmount = fromContract
-            ? await this.resolveFromAmountSpec(args.from_amount, fromContract, chain, walletAddress, fromSym)
-            : this.normaliseAmount(args.from_amount);
-        // Whether the from amount was sized off the balance (percent / "max" / usd):
-        // such an amount is ≤ spendable by construction, so the balance check skips
-        // the over-balance comparison for it (a re-read spendable can drift a hair).
-        const fromSpec = (0, amountSpec_1.parseAmountSpec)(args.from_amount);
-        let amountSizedToBalance = !!fromSpec && fromSpec.kind !== 'token';
-        // Set to the to-side amount once we convert it into `fromAmount` (Branch 1.3)
-        // so downstream messaging can explain the conversion.
-        let derivedFromTo = null;
-        this.dbg('resolved sides', {
-            from: { fromContract, fromSym, fromDecimals },
-            to: { toContract, toSym, toDecimals },
-            fromAmount,
-            toAmount,
-        });
-        // Could not resolve the source token — surface it (never open a form).
-        if (!fromContract) {
-            this.dbg('→ source token not resolved');
-            return {
-                error: 'from_token_not_found',
-                _instructions: `Could not find the token "${fromSym || fromRef}" to swap from on this chain. ` +
-                    'Tell the user, in their language, that the token could not be found and ask them to check the name ' +
-                    'or provide its contract address. Do NOT invent an address. Do NOT mention tool names, UI, or forms.',
-            };
-        }
-        // ----- Branch 1: DEST PICKER (trending) — source known, dest missing ---
-        if (!toContract && this.moralis && userContext?.walletAddress) {
-            this.dbg('→ Branch 1: destination picker (dest token missing)');
-            return await this.buildToTrendingPicker({ args, userContext, fromSym, fromContract, fromAmount, toAmount });
-        }
-        if (!toContract) {
-            return {
-                error: 'to_token_missing',
-                _instructions: `Ask the user, in their language, which token they want to receive when swapping ${fromSym}. ` +
-                    'Do NOT invent a token. Do NOT mention tool names, UI, or forms.',
-            };
-        }
-        // ----- Branch 1.3: TO-SIDE AMOUNT → FROM AMOUNT ------------------------
-        // deBridge only supports EXACT_INPUT (spend X, receive ~Y). When the user
-        // sized the TO side instead ("swap USDC to 5 USDT") we have no source amount
-        // to seed the quote — derive one from the live USD price ratio
-        // (fromAmount ≈ toAmount × toPrice / fromPrice, +2% buffer for slippage/fees
-        // so they receive AT LEAST about the requested amount). The derived amount
-        // then flows through the SAME balance-check + confirm-tx path below.
-        if (toAmount && !fromAmount) {
-            this.dbg('Branch 1.3: deriving from amount from to amount', { toAmount, fromSym, toSym });
-            const derived = await this.deriveFromAmountFromTo({
-                chain,
-                toAmount,
-                toContract,
-                toSym,
-                fromContract,
-                fromSym,
-            });
-            if (!derived) {
-                this.dbg('→ Branch 1.3: price unavailable — needs from amount');
-                return {
-                    error: 'needs_from_amount',
-                    _instructions: `Could not work out how much ${fromSym ?? 'of the source token'} equals ${toAmount} ${toSym} right now. ` +
-                        `Tell the user, in their language, that the price couldn't be fetched at the moment, and ask how much ${fromSym ?? 'of the source token'} they want to swap instead. ` +
-                        'Do NOT invent an amount or a price. Do NOT mention tool names, UI, or forms.',
-                };
-            }
-            fromAmount = derived;
-            derivedFromTo = toAmount;
-            // A derived amount is a real cost that CAN exceed the balance — it must be
-            // checked (it was sized off the dest amount, not off the source balance).
-            amountSizedToBalance = false;
-            this.dbg('→ Branch 1.3: derived from amount', { fromAmount, derivedFromTo });
-        }
-        // ----- Branch 1.4: BALANCE CHECK — source token named ------------------
-        // Native is included: its spendable balance (held − gas reserve) is read by
-        // readFromBalance, so an amount that wouldn't leave room for gas is caught
-        // here just like an over-balance ERC-20 amount.
-        if (this.moralis && userContext?.walletAddress) {
-            this.dbg('Branch 1.4: checking source balance', { fromContract, fromSym, fromAmount });
-            const shortfall = await this.checkFromBalance({
-                args,
-                userContext,
-                chain,
-                fromContract,
-                fromSym,
-                fromAmount,
-                toAmount,
-                derivedFromTo,
-                amountSizedToBalance,
-            });
-            if (shortfall) {
-                this.dbg('→ Branch 1.4: balance shortfall — returning', {
-                    error: shortfall.error,
-                    hasButtons: Array.isArray(shortfall.actionButtons),
-                });
-                return shortfall;
-            }
-            this.dbg('Branch 1.4: balance OK — continuing');
-        }
-        // ----- Branch 1.5: AMOUNT PICKER — source + dest known, no amount ------
-        if (!fromAmount && !toAmount && this.moralis && userContext?.walletAddress) {
-            this.dbg('Branch 1.5: building amount picker');
-            const picker = await this.buildAmountPicker({
-                userContext,
-                chain,
-                fromContract,
-                fromSym,
-                toSym,
-                swapToTemplate: typeof args.swap_to_prompt_template === 'string' ? args.swap_to_prompt_template : '',
-            });
-            if (picker) {
-                this.dbg('→ Branch 1.5: amount picker returned');
-                return picker;
-            }
-            this.dbg('Branch 1.5: amount picker null — needs amount');
-        }
-        // ----- Branch 1.75: BUILD CONFIRM TX -----------------------------------
-        // Everything is known AND the spend is expressed as a source-token amount
-        // (EXACT_INPUT): estimate, build raw swap tx, check approval, ship the cube.
-        if (fromAmount && (fromDecimals !== undefined || fromContract === 'native')) {
-            this.dbg('Branch 1.75: building confirm tx');
-            const confirm = await this.buildConfirmTx({
-                userContext,
-                chain,
-                toContract,
-                toSym,
-                toDecimals,
-                fromContract,
-                fromSym,
-                fromDecimals,
-                fromAmount,
-            });
-            if (confirm && 'ui' in confirm) {
-                this.dbg('→ Branch 1.75: confirm tx returned');
-                return confirm;
-            }
-            // The swap provider returned a concrete reason — relay it to the user.
-            if (confirm && 'quoteError' in confirm) {
-                this.dbg('→ Branch 1.75: quote error from provider', { quoteError: confirm.quoteError });
-                return {
-                    error: 'quote_failed',
-                    quoteError: confirm.quoteError,
-                    _instructions: `Could not quote swapping ${fromSym ?? 'the source token'} to ${toSym}. The swap provider reported: "${confirm.quoteError}". ` +
-                        'Tell the user, in their language, exactly that reason (translate the wording, keep any numbers/limits verbatim) and suggest they adjust the amount or try again shortly. ' +
-                        'Do NOT invent numbers or a different reason. Do NOT mention tool names, UI, or forms.',
-                };
-            }
-            // null — couldn't even attempt a quote (bad chain, missing decimals, …).
-            this.dbg('Branch 1.75: confirm tx unavailable (null)');
-            return {
-                error: 'quote_failed',
-                _instructions: `Could not get a quote to swap ${fromSym ?? 'the source token'} to ${toSym} right now. ` +
-                    'Tell the user, in their language, that the swap could not be quoted at the moment and ask them to try ' +
-                    'again shortly or with a different amount. Do NOT invent numbers. Do NOT mention tool names, UI, or forms.',
-            };
-        }
-        // The only thing missing is a spendable amount (or it was given on the to
-        // side, which EXACT_INPUT can't seed off). Ask the user to size the spend.
-        this.dbg('→ needs from amount');
-        return {
-            error: 'needs_from_amount',
-            _instructions: `Ask the user, in their language, how much ${fromSym ?? 'of the source token'} they want to swap to ${toSym}. ` +
-                'Do NOT invent an amount. Do NOT mention tool names, UI, or forms.',
-        };
-    }
-    // -------------------------------------------------------------------------
-    // Token resolution (standalone — no BaseWalletActionTool dependency)
-    // -------------------------------------------------------------------------
-    normaliseAddress(value) {
-        if (typeof value !== 'string')
-            return null;
-        const v = value.trim();
-        return (0, web3_1.isAddressEVM)(v) ? v : null;
-    }
-    normaliseAmount(value) {
-        if (typeof value === 'number' && Number.isFinite(value) && value > 0)
-            return String(value);
-        if (typeof value !== 'string')
-            return null;
-        const v = value.trim();
-        if (!v)
-            return null;
-        const n = parseFloat(v);
-        return Number.isFinite(n) && n > 0 ? v : null;
-    }
-    requireChain(args, userContext) {
-        const fromArgs = typeof args.chain === 'string' && args.chain.trim() ? args.chain.trim() : null;
-        if (fromArgs)
-            return fromArgs;
-        return typeof userContext?.chain === 'string' && userContext.chain.trim() ? userContext.chain.trim() : null;
-    }
-    /**
-     * Resolve a token reference (symbol "USDC" or address "0x…") on a chain.
-     * Wallet balances first (most reliable), then Pantograph search. Decimals come
-     * from the API — never from the LLM.
-     */
-    async resolveContractAddress(key, chain, walletAddress) {
-        if (!this.moralis || !key)
-            return undefined;
-        const keyLower = key.trim().toLowerCase();
-        const keyIsAddress = (0, web3_1.isAddressEVM)(key.trim());
-        const matches = (t) => keyIsAddress ? (t.token_address ?? '').toLowerCase() === keyLower : (t.symbol ?? '').toLowerCase() === keyLower;
-        if (walletAddress) {
-            const balRes = await this.moralis.getWalletTokenBalances({ address: walletAddress, chain });
-            if (balRes.success && balRes.data?.result?.length) {
-                const match = balRes.data.result.find(matches);
-                if (match) {
-                    return {
-                        address: match.token_address,
-                        symbol: match.symbol,
-                        name: match.name,
-                        decimals: typeof match.decimals === 'number' ? match.decimals : undefined,
-                    };
-                }
-            }
-        }
-        const searchRes = await this.moralis.searchTokensByKey({ key, chain });
-        if (searchRes.success && searchRes.data?.length) {
-            const exact = searchRes.data.find(matches);
-            const candidate = exact ?? searchRes.data[0];
-            if (candidate?.token_address) {
-                return {
-                    address: candidate.token_address,
-                    symbol: candidate.symbol,
-                    name: candidate.name,
-                    decimals: typeof candidate.decimals === 'number' ? candidate.decimals : undefined,
-                };
-            }
-        }
-        return undefined;
-    }
-    /**
-     * Resolve one side of the swap (from or to). Honours the `"native"` sentinel
-     * the swap providers expect. Never errors — a side that can't be resolved
-     * just comes back with `address: null`.
-     */
-    async resolveSide(refArg, symbolArg, chain, walletAddress, label = 'side') {
-        const refStr = typeof refArg === 'string' ? refArg.trim() : '';
-        const symbolStr = typeof symbolArg === 'string' ? symbolArg.trim() : '';
-        if (refStr.toLowerCase() === 'native' || symbolStr.toLowerCase() === 'native') {
-            return { address: 'native', symbol: symbolStr || undefined };
-        }
-        const directAddress = this.normaliseAddress(refArg);
-        const symbolHint = symbolStr || undefined;
-        // The native coin surfaces as the zero address (in wallet balances, or when a
-        // user pastes it) — map it back to the 'native' sentinel so downstream native
-        // handling kicks in: gas-reserve deduction, approval skip, native-side quote.
-        const toNative = (addr) => (addr.toLowerCase() === PoolService_1.ZERO_ADDRESS ? 'native' : addr);
-        const key = directAddress ?? symbolHint ?? (refStr || undefined);
-        if (!key) {
-            this.dbg(`resolveSide:${label}`, { refStr, symbolStr, chain, resolved: 'none' });
-            return { address: null, symbol: symbolHint };
-        }
-        const lookup = await this.resolveContractAddress(key, chain, walletAddress);
-        this.dbg(`resolveSide:${label}`, { refStr, symbolStr, chain, key, lookup });
-        if (!lookup) {
-            // A concrete address with no enrichment — still usable.
-            if (directAddress)
-                return { address: toNative(directAddress), symbol: symbolHint };
-            return { address: null, symbol: symbolHint };
-        }
-        return { address: toNative(lookup.address), symbol: symbolHint ?? lookup.symbol, decimals: lookup.decimals };
-    }
-    // -------------------------------------------------------------------------
-    // Branch 1.75: build confirm tx (estimate + raw swap tx + approve)
-    // -------------------------------------------------------------------------
-    /**
-     * Source token + dest token + a source-token amount are known. Fetch a swap
-     * quote (estimated receive amount + raw swap tx), check approval, and return a
-     * `SwapTokenConfirmTx` UI payload the FE executes itself. Returns `null` when
-     * anything we need can't be produced (bad chain, quote failed, non-EVM tx).
-     */
-    async buildConfirmTx(input) {
-        const { userContext, chain, toContract, toSym, toDecimals, fromContract, fromSym, fromDecimals, fromAmount } = input;
-        const walletAddress = userContext?.walletAddress;
-        if (!walletAddress || !chain || !toContract)
-            return null;
-        const meta = (0, PoolService_1.getChainMeta)(chain);
-        const numericChainId = Number.parseInt(chain, 16);
-        if (!meta || !Number.isFinite(numericChainId))
-            return null;
-        // Native source token needs no decimals (chain meta) and never approves.
-        const fromIsNative = fromContract === 'native';
-        const fromDec = fromIsNative ? (meta.native.decimals ?? 18) : fromDecimals;
-        if (fromDec === undefined)
-            return null;
-        const rawAmount = this.toRawAmount(fromAmount, fromDec);
-        if (!rawAmount)
-            return null;
-        // Providers want a concrete address for the native side; both accept zero.
-        const srcTokenAddress = fromIsNative ? PoolService_1.ZERO_ADDRESS : fromContract;
-        const dstTokenAddress = toContract === 'native' ? PoolService_1.ZERO_ADDRESS : toContract;
-        let quote;
-        try {
-            const service = await swap_1.swapServiceFactory.getServiceByProvider('debridge');
-            quote = await service.getQuote({
-                srcChainId: numericChainId,
-                srcTokenAddress,
-                srcTokenAmount: rawAmount,
-                dstChainId: numericChainId,
-                dstTokenAddress,
-                recipientAddress: walletAddress,
-                senderAddress: walletAddress,
-                slippage: 'auto',
-                isCrossChain: false,
-            });
-        }
-        catch (err) {
-            // Network/throw — surface the message so the user sees the real reason.
-            return { quoteError: err instanceof Error ? err.message : String(err) };
-        }
-        // The provider returned a structured failure — forward its reason verbatim.
-        if (!quote.success) {
-            this.dbg('buildConfirmTx: quote failed', { error: quote.error, errorMessage: quote.errorMessage });
-            return { quoteError: this.extractQuoteError(quote) };
-        }
-        if (!quote.tx)
-            return { quoteError: 'No route available for this swap.' };
-        const tx = quote.tx;
-        if (!tx.to || typeof tx.data !== 'string')
-            return null; // non-EVM payload.
-        const swapTx = {
-            chainId: chain,
-            to: tx.to,
-            data: tx.data,
-            value: tx.value ?? '0',
-            from: walletAddress,
-        };
-        // Estimated receive amount of the dest token (provider-specific shape).
-        const estimatedOutRaw = this.extractOutRaw(quote);
-        const estimatedOut = estimatedOutRaw && toDecimals !== undefined
-            ? this.trimAmount(Number(estimatedOutRaw) / 10 ** toDecimals)
-            : undefined;
-        // Approval: native never approves; otherwise ask the provider.
-        let approveTx;
-        if (!fromIsNative) {
-            approveTx = await this.buildApproveTx({
-                chain,
-                walletAddress,
-                fromAddr: fromContract,
-                fromDec,
-                rawAmount,
-                quote,
-            });
-        }
-        const props = {
-            chain: { hexId: chain, name: meta.name },
-            fromToken: {
-                address: fromIsNative ? 'native' : fromContract,
-                symbol: fromSym,
-                decimals: fromDec,
-                amount: fromAmount,
-                rawAmount,
-            },
-            toToken: {
-                address: toContract,
-                symbol: toSym,
-                decimals: toDecimals,
-                amount: estimatedOut,
-                rawAmount: estimatedOutRaw,
-            },
-            estimatedOut,
-            estimatedOutRaw,
-            provider: quote.provider,
-            swapTx,
-            approveTx,
-        };
-        const ui = { component: 'SwapTokenConfirmTx', props };
-        const estPart = estimatedOut ? ` They will receive about ${estimatedOut} ${toSym}.` : '';
-        return {
-            ui: ui,
-            _instructions: `A confirmation panel has been opened for swapping ${fromAmount} ${fromSym ?? 'the source token'} to ${toSym}.${estPart} ` +
-                'Briefly tell the user, in their language, the amount they are swapping and the estimated amount they will receive, ' +
-                'and ask them to review and confirm to complete the swap. The estimate is approximate — say "about"/"estimated", never a guaranteed amount. ' +
-                'NEVER invent numbers not provided here. Do NOT mention tool names, UI, forms, or internal steps like approval.',
-        };
-    }
-    // -------------------------------------------------------------------------
-    // Branch 1.3: derive a from amount from a to-side amount via USD prices
-    // -------------------------------------------------------------------------
-    /**
-     * deBridge only quotes EXACT_INPUT, so a "swap to X of the dest token" request
-     * has no input amount to seed the quote. Convert the desired output into a
-     * source-token amount using each side's live USD price:
-     *
-     *   fromAmount ≈ (toAmount × toPriceUsd) / fromPriceUsd × (1 + buffer)
-     *
-     * The +2% buffer covers slippage + fees so the user receives AT LEAST roughly
-     * the requested amount (the confirm panel still shows the REAL estimate from
-     * the quote, not this derived figure). Returns `null` when either token's USD
-     * price can't be fetched — the caller then asks for a from amount instead.
-     */
-    async deriveFromAmountFromTo(input) {
-        const { chain, toAmount, toContract, fromContract } = input;
-        const [toPrice, fromPrice] = await Promise.all([
-            this.getUsdPrice(toContract, chain),
-            this.getUsdPrice(fromContract, chain),
-        ]);
-        this.dbg('deriveFromAmountFromTo: prices', { toPrice, fromPrice });
-        if (!toPrice || !fromPrice)
-            return null;
-        const toNum = Number(toAmount);
-        if (!Number.isFinite(toNum) || toNum <= 0)
-            return null;
-        const BUFFER = 1.02; // +2% headroom for slippage + provider/protocol fees.
-        const rawFrom = (toNum * toPrice) / fromPrice;
-        if (!Number.isFinite(rawFrom) || rawFrom <= 0)
-            return null;
-        return this.trimAmount(rawFrom * BUFFER);
-    }
-    /**
-     * Best-effort live USD price for one side of the swap, sourced from
-     * Pantograph (via `MoralisService.getTokenMetadata`). The native coin
-     * (`'native'`) is looked up with the zero address. Returns `null` when no
-     * positive price is available so the caller can degrade gracefully.
-     */
-    async getUsdPrice(tokenAddrOrNative, chain) {
-        if (!this.moralis)
-            return null;
-        const address = tokenAddrOrNative === 'native' ? PoolService_1.ZERO_ADDRESS : tokenAddrOrNative;
-        const res = await this.moralis.getTokenMetadata({ address, chain });
-        const price = res.success ? res.data?.usd_price : undefined;
-        return typeof price === 'number' && Number.isFinite(price) && price > 0 ? price : null;
-    }
-    // -------------------------------------------------------------------------
-    // Amount-spec resolution ("50%" / "5$" / plain) for the from / to sides
-    // -------------------------------------------------------------------------
-    /**
-     * Resolve the FROM-side amount, which may be plain ("10"), a PERCENT of the
-     * held source-token balance ("50%"), or a USD value ("5$"). Percent reads the
-     * wallet's source-token balance; usd divides by the source token's USD price.
-     * Returns a plain token amount string, or `null` when nothing usable was given
-     * / the balance or price needed for a percent/usd couldn't be fetched.
-     */
-    async resolveFromAmountSpec(rawAmount, fromAddr, chain, walletAddress, fromSym) {
-        const spec = (0, amountSpec_1.parseAmountSpec)(rawAmount);
-        if (!spec)
-            return null;
-        if (spec.kind === 'token')
-            return this.trimAmount(spec.value);
-        if (spec.kind === 'percent') {
-            if (!walletAddress)
-                return null;
-            const bal = await this.readFromBalance(walletAddress, fromAddr, chain);
-            this.dbg('resolveFromAmountSpec: percent', { percent: spec.percent, fromSym, bal: bal?.balanceNum });
-            if (!bal || !Number.isFinite(bal.balanceNum) || bal.balanceNum <= 0)
-                return null;
-            // 100% ("max"/"all") spends the EXACT spendable balance string, never a
-            // re-rounded number — `trimAmount` can round UP, which would then trip the
-            // balance check (a second gas-reserve read can land a hair lower). The
-            // exact string is the gas-aware spendable for native (readFromBalance) or
-            // the held balance for an ERC-20.
-            if (spec.percent >= 100)
-                return this.cleanAmountString(bal.balanceFormatted);
-            return this.trimAmount((bal.balanceNum * spec.percent) / 100);
-        }
-        // usd
-        const price = await this.getUsdPrice(fromAddr, chain);
-        this.dbg('resolveFromAmountSpec: usd', { usd: spec.usd, fromSym, price });
-        if (!price)
-            return null;
-        return this.trimAmount(spec.usd / price);
-    }
-    /**
-     * Resolve the TO-side amount, which may be plain ("5") or a USD value ("5$").
-     * USD divides by the DEST token's price to get how many dest tokens "$X worth"
-     * is — that token figure then flows through Branch 1.3 to derive the from
-     * amount. A PERCENT on the to side is meaningless, so it's ignored (returns
-     * null). Returns a plain token amount string or `null`.
-     */
-    async resolveToAmountSpec(rawAmount, toContract, chain, toSym) {
-        const spec = (0, amountSpec_1.parseAmountSpec)(rawAmount);
-        if (!spec)
-            return null;
-        if (spec.kind === 'token')
-            return this.trimAmount(spec.value);
-        if (spec.kind === 'percent')
-            return null; // not meaningful for the to side.
-        // usd → dest-token quantity via the dest price.
-        if (!toContract)
-            return null;
-        const price = await this.getUsdPrice(toContract, chain);
-        this.dbg('resolveToAmountSpec: usd', { usd: spec.usd, toSym, price });
-        if (!price)
-            return null;
-        return this.trimAmount(spec.usd / price);
-    }
-    /**
-     * Check whether the source token needs an allowance for this swap and, if so,
-     * return a ready-to-sign ERC-20 approve tx. deBridge only reports the spender
-     * (`tx.to`), so we encode the approve calldata ourselves; integrated providers
-     * (Relay) hand back the approve tx directly.
-     */
-    async buildApproveTx(input) {
-        const { chain, walletAddress, fromAddr, fromDec, rawAmount, quote } = input;
-        try {
-            const service = await swap_1.swapServiceFactory.getServiceByProvider('debridge');
-            const approval = await service.checkApproval({
-                chain,
-                userAddress: walletAddress,
-                tokenAddress: fromAddr,
-                amount: rawAmount,
-                tokenDecimals: fromDec,
-                quoteData: quote,
-            });
-            if (!approval.isNeeded)
-                return undefined;
-            // Integrated providers (Relay) hand back the approve tx directly.
-            const data = (approval.approvalData ?? {});
-            if (data.to && typeof data.data === 'string') {
-                return { chainId: chain, to: data.to, data: data.data, value: data.value ?? '0', from: walletAddress };
-            }
-            // deBridge: we only know the spender (the swap router). Encode approve().
-            const spender = approval.contractAddress;
-            if (!spender)
-                return undefined;
-            const approveData = (0, web3_1.encodeFunctionData)({
-                abi: abi_1.erc20Abi,
-                functionName: 'approve',
-                args: [spender, BigInt(rawAmount)],
-            });
-            return { chainId: chain, to: fromAddr, data: approveData, value: '0', from: walletAddress };
-        }
-        catch {
-            return undefined;
-        }
-    }
-    /** Human amount → smallest-unit decimal string (no float drift via BigInt). */
-    toRawAmount(human, decimals) {
-        const trimmed = human.trim();
-        if (!/^\d*\.?\d+$/.test(trimmed))
-            return null;
-        const [intPart, fracPartRaw = ''] = trimmed.split('.');
-        const fracPart = fracPartRaw.slice(0, decimals).padEnd(decimals, '0');
-        try {
-            const raw = BigInt(intPart || '0') * 10n ** BigInt(decimals) + BigInt(fracPart || '0');
-            return raw <= 0n ? null : raw.toString();
-        }
-        catch {
-            return null;
-        }
-    }
-    /**
-     * Pull a human-readable failure reason out of a failed quote. Adapters set
-     * `errorMessage` (string) and `error` (string or a provider object). deBridge
-     * also nests a reason in `raw.errorMessage` / `raw.error`. Falls back to a
-     * generic line so the caller always has something to show.
-     */
-    extractQuoteError(quote) {
-        if (quote.errorMessage && quote.errorMessage.trim())
-            return quote.errorMessage.trim();
-        const fromError = (e) => {
-            if (typeof e === 'string' && e.trim())
-                return e.trim();
-            if (e && typeof e === 'object') {
-                const o = e;
-                for (const v of [o.message, o.errorMessage, o.error]) {
-                    if (typeof v === 'string' && v.trim())
-                        return v.trim();
-                }
-            }
-            return undefined;
-        };
-        const raw = (quote.raw ?? {});
-        return (fromError(quote.error) ??
-            fromError(raw.errorMessage) ??
-            fromError(raw.error) ??
-            'The swap could not be quoted right now.');
-    }
-    /**
-     * Estimated receive amount in the dest token's smallest units. Shape differs
-     * per provider — deBridge same-chain: `raw.tokenOut.minAmount`; deBridge
-     * cross-chain: `raw.estimation.dstChainTokenOut.amount`; Relay:
-     * `raw.details.currencyOut.{amount|minimumAmount}`.
-     */
-    extractOutRaw(quote) {
-        const raw = (quote.raw ?? {});
-        const candidate = raw.tokenOut?.amount ??
-            raw.tokenOut?.minAmount ??
-            raw.details?.currencyOut?.amount ??
-            raw.details?.currencyOut?.minimumAmount ??
-            raw.estimation?.dstChainTokenOut?.recommendedAmount ??
-            raw.estimation?.dstChainTokenOut?.amount;
-        return candidate && /^\d+$/.test(candidate) ? candidate : undefined;
-    }
-    // -------------------------------------------------------------------------
-    // Branch 0: source picker (user named no token — pick from wallet holdings)
-    // -------------------------------------------------------------------------
-    async buildSourcePicker(args, userContext) {
-        if (!this.moralis || !userContext?.walletAddress) {
-            return {
-                error: 'source_unavailable',
-                _instructions: 'Cannot list the wallet holdings in this build. Tell the user briefly and ask them to name the token they want to swap from.',
-            };
-        }
-        const chain = this.requireChain(args, userContext) ?? undefined;
-        const walletAddress = userContext.walletAddress;
-        const balancesRes = await this.moralis.getWalletTokenBalances({
-            address: walletAddress,
-            chain,
-            excludeSpam: true,
-            excludeUnverifiedContracts: true,
-        });
-        const balances = balancesRes.success ? (balancesRes.data?.result ?? []) : [];
-        // Include native + ERC-20s the wallet actually holds — these are swappable.
-        const holdings = balances
-            .filter((t) => {
-            if (!t.symbol)
-                return false;
-            if (t.native_token)
-                return true;
-            return !!t.token_address;
-        })
-            .sort((a, b) => (b.usd_value ?? 0) - (a.usd_value ?? 0))
-            .slice(0, 8);
-        if (holdings.length === 0) {
-            return {
-                error: 'no_swap_holdings',
-                _instructions: 'The wallet holds no tokens to swap on this chain. Tell the user to top up first. Do NOT mention tool names, UI, or forms.',
-            };
-        }
-        // Click-prompt is re-submitted as a fresh user turn → phrase it in the
-        // user's language via the LLM-supplied "swap {token}" template.
-        const swapFromTemplate = typeof args.swap_from_prompt_template === 'string' ? args.swap_from_prompt_template : '';
-        const actionButtons = holdings.map((t) => {
-            const sym = t.symbol;
-            const name = t.name?.trim() || sym;
-            const amount = t.balance_formatted ? `${this.cleanAmountString(t.balance_formatted)} ` : '';
-            const usdLabel = typeof t.usd_value === 'number' && t.usd_value > 0 ? ` ($${t.usd_value.toFixed(2)})` : '';
-            const label = `${name}: ${amount}${sym}${usdLabel}`;
-            return { label, prompt: this.buildSwapFromPrompt(swapFromTemplate, sym) };
-        });
-        return {
-            actionButtons,
-            _instructions: `Reply briefly in the user's language: ask them to pick which token they want to swap from the options below. Do NOT list the tokens in text. Do NOT mention tool names, UI, or forms.`,
-        };
-    }
-    // -------------------------------------------------------------------------
-    // Branch 1: destination picker (source known, dest missing → trending)
-    // -------------------------------------------------------------------------
-    async buildToTrendingPicker(input) {
-        const { args, userContext, fromSym, fromContract } = input;
-        const chain = this.requireChain(args, userContext) ?? undefined;
-        const pantograph = this.pantograph;
-        const requestedLimit = typeof args.limit === 'number' && Number.isFinite(args.limit) ? Math.floor(args.limit) : 6;
-        const limit = Math.max(1, Math.min(10, requestedLimit));
-        const res = await pantograph.getTrendingTokens({ chain, limit: limit + 2 });
-        const list = res.success ? (res.data ?? []) : [];
-        // Exclude the source token itself (no self-swap) — match by address or symbol.
-        const fromLower = fromContract?.toLowerCase();
-        const fromSymLower = fromSym.toLowerCase();
-        const tokens = list
-            .filter((t) => {
-            if (!t.symbol)
-                return false;
-            if (fromLower && fromLower !== 'native' && t.tokenAddress && t.tokenAddress.toLowerCase() === fromLower) {
-                return false;
-            }
-            if (t.symbol.toLowerCase() === fromSymLower)
-                return false;
-            return true;
-        })
-            .slice(0, limit);
-        if (tokens.length === 0) {
-            return {
-                error: 'no_trending_tokens',
-                _instructions: `No trending tokens are available to swap ${fromSym} into on this chain right now. Tell the user briefly and suggest they name the token they want to receive directly. Do NOT mention tool names, UI, or forms.`,
-            };
-        }
-        // Prefer the caller's already-converted amounts (so "1$"/"50%" become a real
-        // token quantity in the click-prompt); fall back to re-parsing args.
-        const fromAmount = input.fromAmount ?? this.normaliseAmount(args.from_amount);
-        const toAmount = input.toAmount ?? this.normaliseAmount(args.to_amount);
-        const swapToTemplate = typeof args.swap_to_prompt_template === 'string' ? args.swap_to_prompt_template : '';
-        const actionButtons = tokens.map((t) => {
-            const sym = t.symbol;
-            // from_amount sits next to the source token ({from_amount}); otherwise an
-            // optional to_amount sits next to the dest token ({to_amount}). Only one
-            // side ever carries an amount.
-            const prompt = fromAmount
-                ? this.buildSwapToPrompt(swapToTemplate, fromSym, sym, fromAmount, null)
-                : this.buildSwapToPrompt(swapToTemplate, fromSym, sym, null, toAmount);
-            return { label: sym, prompt };
-        });
-        const lines = tokens.map((t, i) => {
-            const name = t.name?.trim() || t.symbol;
-            const sym = t.symbol;
-            const priceLabel = typeof t.usdPrice === 'number' && t.usdPrice > 0 ? `$${this.formatPrice(t.usdPrice)}` : 'N/A';
-            const change = t.pricePercentChange?.['24h'];
-            const hasChange = typeof change === 'number' && Number.isFinite(change);
-            const arrow = hasChange ? (change > 0 ? '▲' : change < 0 ? '▼' : '▪') : '';
-            const changeLabel = hasChange ? ` (${arrow} ${this.formatPercent(change)}%)` : '';
-            return `${i + 1}. ${name} (${sym})\n${priceLabel}${changeLabel}`;
-        });
-        const listText = lines.join('\n-----\n') + `\n---\nWhich token do you want to receive?`;
-        return {
-            actionButtons,
-            _instructions: `The user wants to swap ${fromSym} into another token. The trending tokens are on chain id "${chain ?? 'the connected chain'}" — use the human-readable chain name. ` +
-                `Reply in the user's language. Start with a one-line header like "📈 Here are tokens currently trending on <chain name> that you can swap ${fromSym} into", then output EXACTLY the following list, preserving the line breaks, ordering, prices, and percentages verbatim (translate only the wording, never the numbers). Do NOT add or remove tokens, and do NOT mention tool names, UI, or forms:\n\n${listText}`,
-        };
-    }
-    // -------------------------------------------------------------------------
-    // Branch 1.4: balance check (source token named — with or without an amount)
-    // -------------------------------------------------------------------------
-    /**
-     * Guard the swap flow against a source token the user can't fund. Returns:
-     *   - `null` when the user holds enough (or no amount yet, or balances can't be read).
-     *   - `no_from_balance` (+ source picker buttons) when the wallet holds none of it.
-     *   - `insufficient_from_balance` (+ percentage buttons) when it holds some but
-     *     less than the requested amount.
-     */
-    async checkFromBalance(input) {
-        const { args, userContext, chain, fromContract, fromAmount, derivedFromTo } = input;
-        const walletAddress = userContext.walletAddress;
-        const bal = await this.readFromBalance(walletAddress, fromContract, chain);
-        const fromSym = input.fromSym ?? bal?.symbol ?? 'the selected token';
-        // No holding at all: tell the user, then offer the tokens they DO hold.
-        if (!bal) {
-            this.dbg('checkFromBalance: NOT held → source picker fallback', { fromSym });
-            const picker = await this.buildSourcePicker(args, userContext);
-            if ('actionButtons' in picker) {
-                return {
-                    error: 'no_from_balance',
-                    actionButtons: picker.actionButtons,
-                    _instructions: `The user wanted to swap ${fromSym}, but their wallet holds no ${fromSym} on this chain. ` +
-                        `Tell them, in their language, that they don't have any ${fromSym}, then say they can instead choose one of the tokens they already hold (shown below) to swap from. ` +
-                        'Do NOT list the tokens in text, do NOT invent a balance, and do NOT mention tool names, UI, or forms.',
-                };
-            }
-            return picker;
-        }
-        // No amount yet — the holding exists, so let the amount picker take over.
-        if (!fromAmount)
-            return null;
-        // When the amount was SIZED OFF the balance (a percent / "max" / usd spec),
-        // it's already ≤ spendable by construction — skip the over-balance check.
-        // Re-checking would compare it against a freshly re-read spendable, which can
-        // drift a hair (the gas reserve is read from a separate RPC call), and a
-        // legitimate "max" would falsely trip as "insufficient". Only a plain
-        // user-typed amount ("swap 5 ETH") is genuinely checked against the balance.
-        if (input.amountSizedToBalance)
-            return null;
-        const wanted = Number(fromAmount);
-        if (!Number.isFinite(wanted) || wanted <= bal.balanceNum)
-            return null;
-        // Holds some but not enough: report the shortfall + percentage options.
-        const spendable = this.trimAmount(bal.balanceNum);
-        const actionButtons = this.percentSpendButtons({
-            balanceFormatted: bal.balanceFormatted,
-            balanceNum: bal.balanceNum,
-            fromSym,
-            toSym: typeof args.to_symbol === 'string' ? args.to_symbol.trim() : (bal.symbol ?? 'the destination token'),
-            swapToTemplate: typeof args.swap_to_prompt_template === 'string' ? args.swap_to_prompt_template : '',
-        });
-        // Frame the message by what the user actually said: a derived from amount
-        // came from "swap to X dest", so explain the conversion; otherwise they
-        // typed the from amount directly.
-        const needLine = derivedFromTo
-            ? `Receiving ${derivedFromTo} of the destination token needs about ${fromAmount} ${fromSym}, but they only have ${spendable} ${fromSym} on this chain — not enough. ` +
-                `Tell them, in their language, that this would cost about ${fromAmount} ${fromSym}, which is more than their balance of ${spendable} ${fromSym}, and ask them to swap a smaller amount — `
-            : `The user wants to swap ${fromAmount} ${fromSym}, but they only have ${spendable} ${fromSym} on this chain — not enough. ` +
-                `Tell them, in their language, that ${fromAmount} ${fromSym} exceeds their balance of ${spendable} ${fromSym}, and ask them to pick a smaller amount — `;
-        return {
-            error: 'insufficient_from_balance',
-            actionButtons,
-            _instructions: needLine +
-                'invite them to choose one of the options below (sized to their balance) or type the amount they want. ' +
-                'CRITICAL: clickable percentage buttons are rendered separately below your message — your text must NOT contain any "%", percentage values, or a list of amounts (no "25%", "50%", "75%", "100%"). ' +
-                'Do NOT invent numbers, and do NOT mention tool names, UI, buttons, or forms.',
-        };
-    }
-    /**
-     * Read the connected wallet's balance of the source token. Returns the held
-     * amount + on-chain symbol, or `null` when balances can't be fetched / the
-     * token isn't held (zero balance or not held at all).
-     *
-     * For the NATIVE source coin the returned balance is the SPENDABLE figure —
-     * the held balance minus a silently-estimated swap gas reserve (gasLimit
-     * 1_000_000 × gasPrice) — so the percent buttons, amount picker, and balance
-     * check all stay within what the user can actually swap while still covering
-     * gas. The reserve is never surfaced; callers only ever expose the spendable
-     * number. ERC-20 sources are returned at their raw held balance (gas is paid
-     * in the native coin, not the source token).
-     */
-    async readFromBalance(walletAddress, fromAddr, chain) {
-        if (!this.moralis)
-            return null;
-        const balancesRes = await this.moralis.getWalletTokenBalances({
-            address: walletAddress,
-            chain,
-            excludeSpam: true,
-            excludeUnverifiedContracts: true,
-        });
-        const balances = balancesRes.success ? (balancesRes.data?.result ?? []) : [];
-        this.dbg('readFromBalance', {
-            fromAddr,
-            chain,
-            ok: balancesRes.success,
-            count: balances.length,
-        });
-        const fromLower = fromAddr.toLowerCase();
-        const fromBal = balances.find((t) => fromLower === 'native' ? t.native_token === true : t.token_address?.toLowerCase() === fromLower);
-        if (!fromBal?.balance_formatted) {
-            this.dbg('readFromBalance: source token NOT held → null', { fromAddr });
-            return null;
-        }
-        const balanceNum = Number(fromBal.balance_formatted);
-        if (!Number.isFinite(balanceNum) || balanceNum <= 0) {
-            this.dbg('readFromBalance: zero/invalid balance → null', { fromAddr, balance: fromBal.balance_formatted });
-            return null;
-        }
-        // Native source: reduce to the spendable balance so we never quote/size a
-        // swap that would leave the user unable to pay gas.
-        if (fromLower === 'native' && chain) {
-            const reserve = await (0, gasReserve_1.estimateNativeGasReserveWei)(chain, 'swap');
-            const spendable = (0, gasReserve_1.spendableNative)(balanceNum, reserve, chain);
-            this.dbg('readFromBalance: native spendable', { balanceNum, spendable });
-            if (spendable <= 0) {
-                this.dbg('readFromBalance: native spendable ≤ 0 → null', { balanceNum });
-                return null;
-            }
-            const spendableStr = this.trimAmount(spendable);
-            return { balanceFormatted: spendableStr, balanceNum: spendable, symbol: fromBal.symbol };
-        }
-        this.dbg('readFromBalance: held', { fromAddr, balance: fromBal.balance_formatted, symbol: fromBal.symbol });
-        return { balanceFormatted: fromBal.balance_formatted, balanceNum, symbol: fromBal.symbol };
-    }
-    /**
-     * 25/50/75/100% quick-spend buttons sized off a held balance. 100% spends the
-     * EXACT held string; the partial fractions are float-trimmed. The amount rides
-     * in the prompt; the label is a bare percent.
-     */
-    percentSpendButtons(input) {
-        const { balanceFormatted, balanceNum, fromSym, toSym, swapToTemplate } = input;
-        const fractions = [0.25, 0.5, 0.75, 1];
-        return fractions.map((f) => {
-            const amount = f === 1 ? this.cleanAmountString(balanceFormatted) : this.trimAmount(balanceNum * f);
-            // The percentage amount is the SOURCE amount → it rides with the source
-            // token ({from_amount}), never with the destination token.
-            return {
-                label: `${Math.round(f * 100)}%`,
-                prompt: this.buildSwapToPrompt(swapToTemplate, fromSym, toSym, amount, null),
-            };
-        });
-    }
-    // -------------------------------------------------------------------------
-    // Branch 1.5: amount picker (source + dest known, no amount given)
-    // -------------------------------------------------------------------------
-    async buildAmountPicker(input) {
-        const { userContext, chain, fromContract, toSym, swapToTemplate } = input;
-        const walletAddress = userContext.walletAddress;
-        const bal = await this.readFromBalance(walletAddress, fromContract, chain);
-        const fromSym = input.fromSym ?? bal?.symbol;
-        if (!bal || !fromSym)
-            return null;
-        const actionButtons = this.percentSpendButtons({
-            balanceFormatted: bal.balanceFormatted,
-            balanceNum: bal.balanceNum,
-            fromSym,
-            toSym,
-            swapToTemplate,
-        });
-        const spendable = this.trimAmount(bal.balanceNum);
-        return {
-            actionButtons,
-            _instructions: `The user's spendable balance is ${spendable} ${fromSym}. Reply briefly in the user's language: tell them their spendable ${fromSym} balance and ask how much they want to swap to ${toSym}, inviting them to choose one of the options below or type the amount they want. CRITICAL: clickable percentage buttons are rendered separately below your message — your text must NOT contain any "%", percentage values, or a list of amounts (no "25%", "50%", "75%", "100%"). Just ask the question. Do NOT mention tool names, UI, buttons, or forms.`,
-        };
-    }
-    /**
-     * Trim IEEE-754 noise from a computed amount (≤8 significant digits) and
-     * ALWAYS return plain decimal notation — never exponential ("1.5e-7").
-     */
-    trimAmount(value) {
-        if (!Number.isFinite(value))
-            return '0';
-        return this.toPlainDecimal(parseFloat(value.toPrecision(8)));
-    }
-    /** Format a number as a plain decimal string, expanding any e-notation. */
-    toPlainDecimal(n) {
-        const s = String(n);
-        if (!/e/i.test(s))
-            return s;
-        const neg = n < 0;
-        const [mantissa, expPart] = Math.abs(n).toString().split('e');
-        const exp = Number(expPart);
-        const [intPart, fracPart = ''] = mantissa.split('.');
-        const digits = intPart + fracPart;
-        let out;
-        if (exp >= 0) {
-            const pointPos = intPart.length + exp;
-            out =
-                pointPos >= digits.length
-                    ? digits.padEnd(pointPos, '0')
-                    : `${digits.slice(0, pointPos)}.${digits.slice(pointPos)}`;
-        }
-        else {
-            out = `0.${'0'.repeat(-exp - intPart.length)}${digits}`;
-        }
-        if (out.includes('.'))
-            out = out.replace(/\.?0+$/, '');
-        return neg ? `-${out}` : out;
-    }
-    /**
-     * Sanitize an amount STRING from an external source (e.g. Moralis
-     * `balance_formatted`): expand e-notation to plain decimal; else pass through.
-     */
-    cleanAmountString(s) {
-        if (!/e/i.test(s))
-            return s;
-        const n = Number(s);
-        return Number.isFinite(n) ? this.toPlainDecimal(n) : s;
-    }
-    /**
-     * Build the source-picker click-prompt ("swap {token}") from the LLM-supplied,
-     * already-localized template. Falls back to English when the LLM omits one.
-     */
-    buildSwapFromPrompt(template, token) {
-        const tpl = template && template.includes('{token}') ? template : 'swap {token}';
-        return tpl
-            .replace(/\{token\}/g, token)
-            .replace(/\s+/g, ' ')
-            .trim();
-    }
-    /**
-     * Build the "swap X to Y" click-prompt from the LLM-supplied, already-localized
-     * template by substituting placeholders:
-     *   {from} → source token    {to} → destination token
-     *   {from_amount} → quantity swapped (next to {from})
-     *   {to_amount} → quantity received  (next to {to})
-     * The localized verb and "to" preposition live INSIDE the template, so we only
-     * substitute concrete values. Only one side ever carries an amount; the unused
-     * amount placeholder is replaced with '' (no preposition is attached to it, so
-     * nothing dangles). Falls back to an English template when the LLM omits one.
-     */
-    buildSwapToPrompt(template, from, to, fromAmount, toAmount) {
-        const tpl = template && template.includes('{from}') && template.includes('{to}')
-            ? template
-            : 'swap {from_amount} {from} to {to_amount} {to}';
-        return tpl
-            .replace(/\{from\}/g, from)
-            .replace(/\{to\}/g, to)
-            .replace(/\{from_amount\}/g, fromAmount ?? '')
-            .replace(/\{to_amount\}/g, toAmount ?? '')
-            .replace(/\s+/g, ' ')
-            .trim();
-    }
-    /**
-     * Format a 24h price-change percentage: ~6 significant digits, no trailing
-     * noise, and always plain decimal (never exponential for a tiny change).
-     */
-    formatPercent(value) {
-        if (!Number.isFinite(value))
-            return '0';
-        return this.toPlainDecimal(parseFloat(value.toPrecision(6)));
-    }
-    /** Compact price string: e.g. 0.00001234 → "0.00001234", 1234.5 → "1,234.50". */
-    formatPrice(price) {
-        if (price >= 1)
-            return price.toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 });
-        if (price >= 0.01)
-            return price.toFixed(4);
-        const str = price.toFixed(12);
-        const match = str.match(/^0\.0*([1-9]\d{0,3})/);
-        return match ? str.slice(0, (match[0].length || 0) + 0) : str;
-    }
-}
-exports.SwapTokenTool = SwapTokenTool;
-//# sourceMappingURL=SwapTokenTool.js.map