@whiterresearch/litvmswap-aggregator 1.0.4

package/dist/client.js

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LitVMAggregator = void 0;
+const viem_1 = require("viem");
+const index_js_1 = require("./constants/index.js");
+const quoter_js_1 = require("./quoter/quoter.js");
+const swapBuilder_js_1 = require("./swap/swapBuilder.js");
+const index_js_2 = require("./abi/index.js");
+/**
+ * Main SDK Client for LitecoinVM (LitVM) DEX Aggregator
+ *
+ * @example
+ * ```ts
+ * import { LitVMAggregator } from '@whiterresearch/litvmswap-aggregator';
+ *
+ * const aggregator = new LitVMAggregator();
+ *
+ * // 1. Get best quote across LitVM liquidity pools
+ * const quote = await aggregator.getQuote({
+ *   tokenIn: 'zkLTC',
+ *   tokenOut: 'ZKUSDC',
+ *   amountIn: '1.0',
+ *   slippageTolerancePercent: 0.5,
+ * });
+ *
+ * // 2. Build ready-to-execute swap transaction
+ * const tx = aggregator.buildSwapTx({
+ *   quote,
+ *   userAddress: '0x1234...',
+ * });
+ * ```
+ */
+class LitVMAggregator {
+    quoter;
+    publicClient;
+    defaultFeeConfig;
+    constructor(config) {
+        this.publicClient =
+            config?.publicClient ??
+                (0, viem_1.createPublicClient)({
+                    chain: index_js_1.LitVMChain,
+                    transport: (0, viem_1.http)(config?.rpcUrl ?? index_js_1.LitVMChain.rpcUrls.default.http[0]),
+                });
+        this.quoter = new quoter_js_1.LitVMQuoter(this.publicClient);
+        this.defaultFeeConfig = config?.defaultFeeConfig;
+    }
+    /**
+     * Fetches best quote and generates execution program across LitVM pools
+     */
+    async getQuote(params) {
+        return this.quoter.getQuote(params);
+    }
+    /**
+     * Prepares a ready-to-sign transaction object (to, data, value, chainId)
+     */
+    buildSwapTx(params) {
+        const feeConfig = params.feeConfig ?? this.defaultFeeConfig;
+        return swapBuilder_js_1.LitVMSwapBuilder.buildSwapTransaction({
+            ...params,
+            feeConfig,
+        });
+    }
+    /**
+     * Checks ERC20 token allowance for a given spender (defaults to Aggregator Entrypoint)
+     */
+    async checkAllowance(params) {
+        const spender = params.spenderAddress ?? index_js_1.LITVM_ADDRESSES.aggregatorEntrypoint;
+        const allowance = await this.publicClient.readContract({
+            address: params.tokenAddress,
+            abi: index_js_2.ERC20ABI,
+            functionName: 'allowance',
+            args: [params.ownerAddress, spender],
+        });
+        return allowance;
+    }
+    /**
+     * Checks if an ERC20 token needs approval for a swap
+     */
+    async needsApproval(params) {
+        if (params.tokenAddress === viem_1.zeroAddress)
+            return false;
+        const currentAllowance = await this.checkAllowance(params);
+        return currentAllowance < params.amount;
+    }
+    /**
+     * Generates ERC20 approval transaction data
+     */
+    buildApproveTx(params) {
+        return swapBuilder_js_1.LitVMSwapBuilder.buildApproveTransaction(params.tokenAddress, params.spenderAddress ?? index_js_1.LITVM_ADDRESSES.aggregatorEntrypoint, params.amount);
+    }
+    /**
+     * Resolves token metadata from address or symbol
+     */
+    async getToken(addressOrSymbol) {
+        return this.quoter.resolveToken(addressOrSymbol);
+    }
+    /**
+     * Returns list of verified tokens on LitecoinVM
+     */
+    getKnownTokens() {
+        return Object.values(index_js_1.KNOWN_TOKENS);
+    }
+    /**
+     * Directly executes a swap using a Viem WalletClient
+     */
+    async executeSwapWithWallet(params) {
+        const tx = this.buildSwapTx({
+            quote: params.quote,
+            userAddress: params.userAddress,
+            receiverAddress: params.receiverAddress,
+            feeConfig: params.feeConfig,
+        });
+        const hash = await params.walletClient.sendTransaction({
+            account: params.userAddress,
+            to: tx.to,
+            data: tx.data,
+            value: tx.value,
+            chain: index_js_1.LitVMChain,
+        });
+        return hash;
+    }
+}
+exports.LitVMAggregator = LitVMAggregator;

package/dist/constants/index.d.ts

@@ -0,0 +1,67 @@
+import type { Chain } from 'viem';
+export declare const LITECOIN_VM_CHAIN_ID = 4441;
+/**
+ * Viem Chain definition for LitecoinVM (LitVM)
+ */
+export declare const LitVMChain: Chain;
+/**
+ * Core contract addresses for the Aggregator & Liquidity Pools on LitecoinVM
+ */
+export declare const LITVM_ADDRESSES: {
+    chainId: number;
+    aggregatorEntrypoint: "0xF664B56933f3cF0d7d69982b5A8eC9101b80059D";
+    /** The wrapper, named explicitly. Same address as aggregatorEntrypoint. */
+    pointsWrapper: "0xF664B56933f3cF0d7d69982b5A8eC9101b80059D";
+    /**
+     * The fee-enforcing entrypoint the wrapper forwards to. It requires the
+     * protocol fee to go to the DexFeeVault and to be at least MIN_PROTOCOL_FEE_BPS;
+     * a swap that does not will revert. Exposed for inspection — route through
+     * `aggregatorEntrypoint` so points are still recorded.
+     */
+    feeEnforcingEntrypoint: "0x5E19EB2A6BA30892CCe33f93D7Fb24D498512266";
+    /**
+     * Superseded. The original entrypoint, which took feeCollector and feeBps
+     * straight from calldata and enforced neither, so any caller could pay the
+     * protocol nothing. The wrapper no longer routes here. Kept only so an
+     * integrator pinning this address can see why their swaps changed.
+     * @deprecated use `aggregatorEntrypoint`
+     */
+    legacyEntrypointNoFeeEnforcement: "0xF69E64804000d28aA695eB5c594B996100fb3B49";
+    aggregatorRouter: "0x0624E93350bFfc5B3570589FCae68e2CaBe6c620";
+    platformFeeCollector: "0xF2DF37067a8Af0e9ae617c96C887B2FdA8eA3f10";
+    wrappedNative: "0x315374AA9b5536037Cc1Efeea2439CCC0913A77e";
+    weth: "0x315374AA9b5536037Cc1Efeea2439CCC0913A77e";
+    ourV2Factory: "0x4680BCe1632824d30D2F53656dD610736c3e312e";
+    ourV2Router: "0xF456737D17C2Bbb348fd4F7D1b000D62A46FB3b5";
+    inkyV2Factory: "0x458C5d5B75ccBA22651D2C5b61cB1EA1e0b0f95D";
+    v3Factory: "0xde6763a041f8fc94ca2ee5933736f78f6d1a11c5";
+    v3Router: "0x60F8A7642F0aeC06cE628224E743326B23Fe5208";
+    v3PositionManager: "0x1089f046B597f259BeFDC15Bf9C90E33616BA366";
+};
+/**
+ * Sentinel address for native LTC/ETH
+ */
+/**
+ * Minimum protocol fee, in basis points, enforced on-chain by the entrypoint.
+ * A swap routed through the entrypoint with a lower fee, or with the fee pointed
+ * anywhere other than the DexFeeVault, reverts.
+ */
+export declare const MIN_PROTOCOL_FEE_BPS = 15n;
+export declare const NATIVE_TOKEN_ADDRESS: "0x0000000000000000000000000000000000000000";
+export declare const NATIVE_TOKEN_ALT_ADDRESS: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE";
+export interface TokenInfo {
+    address: `0x${string}`;
+    symbol: string;
+    name: string;
+    decimals: number;
+    isNative?: boolean;
+    logoURI?: string;
+}
+/**
+ * Native zkLTC definition
+ */
+export declare const NATIVE_TOKEN: TokenInfo;
+/**
+ * Standard tokens deployed on LitecoinVM (Chain ID 4441)
+ */
+export declare const KNOWN_TOKENS: Record<string, TokenInfo>;

package/dist/constants/index.js

@@ -0,0 +1,168 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KNOWN_TOKENS = exports.NATIVE_TOKEN = exports.NATIVE_TOKEN_ALT_ADDRESS = exports.NATIVE_TOKEN_ADDRESS = exports.MIN_PROTOCOL_FEE_BPS = exports.LITVM_ADDRESSES = exports.LitVMChain = exports.LITECOIN_VM_CHAIN_ID = void 0;
+exports.LITECOIN_VM_CHAIN_ID = 4441;
+/**
+ * Viem Chain definition for LitecoinVM (LitVM)
+ */
+exports.LitVMChain = {
+    id: exports.LITECOIN_VM_CHAIN_ID,
+    name: 'LitecoinVM',
+    nativeCurrency: {
+        name: 'zkLTC',
+        symbol: 'zkLTC',
+        decimals: 18,
+    },
+    rpcUrls: {
+        default: {
+            http: [
+                'https://liteforge.rpc.caldera.xyz/http',
+                'https://liteforge.rpc.caldera.xyz/infra-partner-http',
+            ],
+        },
+        public: {
+            http: [
+                'https://liteforge.rpc.caldera.xyz/http',
+                'https://liteforge.rpc.caldera.xyz/infra-partner-http',
+            ],
+        },
+    },
+    blockExplorers: {
+        default: {
+            name: 'LitVM Explorer',
+            url: 'https://explorer.LitVM.network',
+        },
+    },
+    testnet: true,
+};
+/**
+ * Core contract addresses for the Aggregator & Liquidity Pools on LitecoinVM
+ */
+exports.LITVM_ADDRESSES = {
+    chainId: exports.LITECOIN_VM_CHAIN_ID,
+    // ── Aggregator contracts ──────────────────────────────────────────────
+    // Swaps should go to `aggregatorEntrypoint` — the AGGFlowPointsWrapper. It
+    // records Lit Diamonds and applies the NFT staking multiplier, then forwards
+    // to the fee-enforcing entrypoint. Calling anything below it skips the points
+    // a user has earned.
+    aggregatorEntrypoint: '0xF664B56933f3cF0d7d69982b5A8eC9101b80059D',
+    /** The wrapper, named explicitly. Same address as aggregatorEntrypoint. */
+    pointsWrapper: '0xF664B56933f3cF0d7d69982b5A8eC9101b80059D',
+    /**
+     * The fee-enforcing entrypoint the wrapper forwards to. It requires the
+     * protocol fee to go to the DexFeeVault and to be at least MIN_PROTOCOL_FEE_BPS;
+     * a swap that does not will revert. Exposed for inspection — route through
+     * `aggregatorEntrypoint` so points are still recorded.
+     */
+    feeEnforcingEntrypoint: '0x5E19EB2A6BA30892CCe33f93D7Fb24D498512266',
+    /**
+     * Superseded. The original entrypoint, which took feeCollector and feeBps
+     * straight from calldata and enforced neither, so any caller could pay the
+     * protocol nothing. The wrapper no longer routes here. Kept only so an
+     * integrator pinning this address can see why their swaps changed.
+     * @deprecated use `aggregatorEntrypoint`
+     */
+    legacyEntrypointNoFeeEnforcement: '0xF69E64804000d28aA695eB5c594B996100fb3B49',
+    aggregatorRouter: '0x0624E93350bFfc5B3570589FCae68e2CaBe6c620',
+    platformFeeCollector: '0xF2DF37067a8Af0e9ae617c96C887B2FdA8eA3f10',
+    // Wrapped Native (wzkLTC / WETH)
+    wrappedNative: '0x315374AA9b5536037Cc1Efeea2439CCC0913A77e',
+    weth: '0x315374AA9b5536037Cc1Efeea2439CCC0913A77e',
+    // Uniswap V2 Compatible DEXes
+    ourV2Factory: '0x4680BCe1632824d30D2F53656dD610736c3e312e',
+    ourV2Router: '0xF456737D17C2Bbb348fd4F7D1b000D62A46FB3b5',
+    inkyV2Factory: '0x458C5d5B75ccBA22651D2C5b61cB1EA1e0b0f95D',
+    // Uniswap V3 Compatible DEXes
+    v3Factory: '0xde6763a041f8fc94ca2ee5933736f78f6d1a11c5',
+    v3Router: '0x60F8A7642F0aeC06cE628224E743326B23Fe5208',
+    v3PositionManager: '0x1089f046B597f259BeFDC15Bf9C90E33616BA366',
+};
+/**
+ * Sentinel address for native LTC/ETH
+ */
+/**
+ * Minimum protocol fee, in basis points, enforced on-chain by the entrypoint.
+ * A swap routed through the entrypoint with a lower fee, or with the fee pointed
+ * anywhere other than the DexFeeVault, reverts.
+ */
+exports.MIN_PROTOCOL_FEE_BPS = 15n; // 0.15%
+exports.NATIVE_TOKEN_ADDRESS = '0x0000000000000000000000000000000000000000';
+exports.NATIVE_TOKEN_ALT_ADDRESS = '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE';
+/**
+ * Native zkLTC definition
+ */
+exports.NATIVE_TOKEN = {
+    address: exports.NATIVE_TOKEN_ADDRESS,
+    symbol: 'zkLTC',
+    name: 'Litecoin (zkLTC)',
+    decimals: 18,
+    isNative: true,
+    logoURI: 'https://assets.coingecko.com/coins/images/2/standard/litecoin.png',
+};
+/**
+ * Standard tokens deployed on LitecoinVM (Chain ID 4441)
+ */
+exports.KNOWN_TOKENS = {
+    NATIVE: exports.NATIVE_TOKEN,
+    WZKLTC: {
+        address: '0x315374AA9b5536037Cc1Efeea2439CCC0913A77e',
+        symbol: 'wzkLTC',
+        name: 'Wrapped zkLTC',
+        decimals: 18,
+        isNative: false,
+        logoURI: 'https://assets.coingecko.com/coins/images/2/standard/litecoin.png',
+    },
+    ZKUSDC: {
+        address: '0xdf69970B2fE416339187aA41D39882e864984CE9',
+        symbol: 'ZKUSDC',
+        name: 'ZK USD Coin',
+        decimals: 18,
+        isNative: false,
+        logoURI: 'https://assets.coingecko.com/coins/images/53776/standard/usdc.jpg',
+    },
+    ZKUSDT: {
+        address: '0xa338b743Ec494ebB8345f4B6F27ffC902b7EF5Aa',
+        symbol: 'ZKUSDT',
+        name: 'ZK Tether USD',
+        decimals: 18,
+        isNative: false,
+        logoURI: 'https://assets.coingecko.com/coins/images/53705/standard/usdt0.jpg',
+    },
+    LETH: {
+        address: '0xDF474006aa807598B616500d146FfF661d644138',
+        symbol: 'LETH',
+        name: 'LitVM Ethereum',
+        decimals: 18,
+        isNative: false,
+        logoURI: 'https://assets.coingecko.com/coins/images/279/standard/ethereum.png',
+    },
+    ZKBTC: {
+        address: '0xca4914407868bc37ccbE324cA149DD475d39A2Bf',
+        symbol: 'ZKBTC',
+        name: 'ZK Bitcoin',
+        decimals: 18,
+        isNative: false,
+        logoURI: 'https://assets.coingecko.com/coins/images/1/standard/bitcoin.png',
+    },
+    LITVMSWAP: {
+        address: '0xCa4c7EdB398684cB4C5B3fD0cc6ced30b5a5f4d3',
+        symbol: 'LitVMSwap',
+        name: 'LitVMSwap Token',
+        decimals: 18,
+        isNative: false,
+    },
+    LXRP: {
+        address: '0xfdf5cD6452EDC340e67cd16db6A9D74aaa4f81a3',
+        symbol: 'LXRP',
+        name: 'LitVM XRP',
+        decimals: 18,
+        isNative: false,
+    },
+    BRBNB: {
+        address: '0x58B6CD7891cd0A682226E25607b958a6479195A6',
+        symbol: 'brBNB',
+        name: 'Bridged BNB',
+        decimals: 18,
+        isNative: false,
+    },
+};

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { LitVMAggregator, type LitVMAggregatorConfig } from './client.js';
+export { LitVMQuoter } from './quoter/quoter.js';
+export { LitVMSwapBuilder } from './swap/swapBuilder.js';
+export { buildAggregatorProgram, addressToBytes } from './builder/programBuilder.js';
+export { OPCODES, POOL_TYPES, WRAP_FLAGS } from './builder/opcodes.js';
+export { LITECOIN_VM_CHAIN_ID, LitVMChain, LITVM_ADDRESSES, MIN_PROTOCOL_FEE_BPS, NATIVE_TOKEN_ADDRESS, NATIVE_TOKEN_ALT_ADDRESS, NATIVE_TOKEN, KNOWN_TOKENS, type TokenInfo, } from './constants/index.js';
+export type { PoolType, RouteLeg, QuoteParams, QuoteResult, FeeConfig, BuildSwapTxParams, PreparedTransaction, SwapIntent, FeeCollection, } from './types/index.js';
+export { toBigIntAmount, formatTokenAmount, calculateMinAmountOut, calculatePriceImpact, } from './utils/format.js';
+export * from './abi/index.js';

package/dist/index.js

@@ -0,0 +1,51 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calculatePriceImpact = exports.calculateMinAmountOut = exports.formatTokenAmount = exports.toBigIntAmount = exports.KNOWN_TOKENS = exports.NATIVE_TOKEN = exports.NATIVE_TOKEN_ALT_ADDRESS = exports.NATIVE_TOKEN_ADDRESS = exports.MIN_PROTOCOL_FEE_BPS = exports.LITVM_ADDRESSES = exports.LitVMChain = exports.LITECOIN_VM_CHAIN_ID = exports.WRAP_FLAGS = exports.POOL_TYPES = exports.OPCODES = exports.addressToBytes = exports.buildAggregatorProgram = exports.LitVMSwapBuilder = exports.LitVMQuoter = exports.LitVMAggregator = void 0;
+// Main Client
+var client_js_1 = require("./client.js");
+Object.defineProperty(exports, "LitVMAggregator", { enumerable: true, get: function () { return client_js_1.LitVMAggregator; } });
+// Quoter & Router
+var quoter_js_1 = require("./quoter/quoter.js");
+Object.defineProperty(exports, "LitVMQuoter", { enumerable: true, get: function () { return quoter_js_1.LitVMQuoter; } });
+// Swap & Program Builders
+var swapBuilder_js_1 = require("./swap/swapBuilder.js");
+Object.defineProperty(exports, "LitVMSwapBuilder", { enumerable: true, get: function () { return swapBuilder_js_1.LitVMSwapBuilder; } });
+var programBuilder_js_1 = require("./builder/programBuilder.js");
+Object.defineProperty(exports, "buildAggregatorProgram", { enumerable: true, get: function () { return programBuilder_js_1.buildAggregatorProgram; } });
+Object.defineProperty(exports, "addressToBytes", { enumerable: true, get: function () { return programBuilder_js_1.addressToBytes; } });
+var opcodes_js_1 = require("./builder/opcodes.js");
+Object.defineProperty(exports, "OPCODES", { enumerable: true, get: function () { return opcodes_js_1.OPCODES; } });
+Object.defineProperty(exports, "POOL_TYPES", { enumerable: true, get: function () { return opcodes_js_1.POOL_TYPES; } });
+Object.defineProperty(exports, "WRAP_FLAGS", { enumerable: true, get: function () { return opcodes_js_1.WRAP_FLAGS; } });
+// Constants & Chain Details
+var index_js_1 = require("./constants/index.js");
+Object.defineProperty(exports, "LITECOIN_VM_CHAIN_ID", { enumerable: true, get: function () { return index_js_1.LITECOIN_VM_CHAIN_ID; } });
+Object.defineProperty(exports, "LitVMChain", { enumerable: true, get: function () { return index_js_1.LitVMChain; } });
+Object.defineProperty(exports, "LITVM_ADDRESSES", { enumerable: true, get: function () { return index_js_1.LITVM_ADDRESSES; } });
+Object.defineProperty(exports, "MIN_PROTOCOL_FEE_BPS", { enumerable: true, get: function () { return index_js_1.MIN_PROTOCOL_FEE_BPS; } });
+Object.defineProperty(exports, "NATIVE_TOKEN_ADDRESS", { enumerable: true, get: function () { return index_js_1.NATIVE_TOKEN_ADDRESS; } });
+Object.defineProperty(exports, "NATIVE_TOKEN_ALT_ADDRESS", { enumerable: true, get: function () { return index_js_1.NATIVE_TOKEN_ALT_ADDRESS; } });
+Object.defineProperty(exports, "NATIVE_TOKEN", { enumerable: true, get: function () { return index_js_1.NATIVE_TOKEN; } });
+Object.defineProperty(exports, "KNOWN_TOKENS", { enumerable: true, get: function () { return index_js_1.KNOWN_TOKENS; } });
+// Math & Format Utilities
+var format_js_1 = require("./utils/format.js");
+Object.defineProperty(exports, "toBigIntAmount", { enumerable: true, get: function () { return format_js_1.toBigIntAmount; } });
+Object.defineProperty(exports, "formatTokenAmount", { enumerable: true, get: function () { return format_js_1.formatTokenAmount; } });
+Object.defineProperty(exports, "calculateMinAmountOut", { enumerable: true, get: function () { return format_js_1.calculateMinAmountOut; } });
+Object.defineProperty(exports, "calculatePriceImpact", { enumerable: true, get: function () { return format_js_1.calculatePriceImpact; } });
+// ABIs
+__exportStar(require("./abi/index.js"), exports);

package/dist/quoter/quoter.d.ts

@@ -0,0 +1,19 @@
+import { type PublicClient } from 'viem';
+import { type TokenInfo } from '../constants/index.js';
+import type { QuoteParams, QuoteResult } from '../types/index.js';
+export declare class LitVMQuoter {
+    private client;
+    constructor(customClient?: PublicClient);
+    /**
+     * Resolves token metadata from address or symbol
+     */
+    resolveToken(addressOrSymbol: string): Promise<TokenInfo>;
+    /**
+     * Fetches best quote and generates execution program across LitVM pools
+     */
+    getQuote(params: QuoteParams): Promise<QuoteResult>;
+    /**
+     * Helper: Quotes a Uniswap V2 pair
+     */
+    private quoteV2Pool;
+}

package/dist/quoter/quoter.js

@@ -0,0 +1,206 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LitVMQuoter = void 0;
+const viem_1 = require("viem");
+const index_js_1 = require("../constants/index.js");
+const index_js_2 = require("../abi/index.js");
+const programBuilder_js_1 = require("../builder/programBuilder.js");
+const format_js_1 = require("../utils/format.js");
+class LitVMQuoter {
+    client;
+    constructor(customClient) {
+        this.client =
+            customClient ??
+                (0, viem_1.createPublicClient)({
+                    chain: index_js_1.LitVMChain,
+                    transport: (0, viem_1.http)(index_js_1.LitVMChain.rpcUrls.default.http[0]),
+                });
+    }
+    /**
+     * Resolves token metadata from address or symbol
+     */
+    async resolveToken(addressOrSymbol) {
+        const query = addressOrSymbol.trim();
+        // Check known native tokens
+        if (query === viem_1.zeroAddress ||
+            query.toLowerCase() === index_js_1.NATIVE_TOKEN_ALT_ADDRESS.toLowerCase() ||
+            query.toUpperCase() === 'ETH' ||
+            query.toUpperCase() === 'LTC' ||
+            query.toUpperCase() === 'ZKLTC') {
+            return index_js_1.NATIVE_TOKEN;
+        }
+        // Check predefined list
+        const found = Object.values(index_js_1.KNOWN_TOKENS).find((t) => t.address.toLowerCase() === query.toLowerCase() ||
+            t.symbol.toUpperCase() === query.toUpperCase());
+        if (found)
+            return found;
+        // Fetch ERC-20 on-chain details
+        const tokenAddr = query;
+        const [decimals, symbol, name] = await Promise.all([
+            this.client.readContract({
+                address: tokenAddr,
+                abi: index_js_2.ERC20ABI,
+                functionName: 'decimals',
+            }),
+            this.client.readContract({
+                address: tokenAddr,
+                abi: index_js_2.ERC20ABI,
+                functionName: 'symbol',
+            }),
+            this.client.readContract({
+                address: tokenAddr,
+                abi: index_js_2.ERC20ABI,
+                functionName: 'name',
+            }),
+        ]);
+        return {
+            address: tokenAddr,
+            symbol,
+            name,
+            decimals: Number(decimals),
+            isNative: false,
+        };
+    }
+    /**
+     * Fetches best quote and generates execution program across LitVM pools
+     */
+    async getQuote(params) {
+        const fromToken = await this.resolveToken(params.tokenIn);
+        const toToken = await this.resolveToken(params.tokenOut);
+        if (fromToken.address.toLowerCase() === toToken.address.toLowerCase() && fromToken.isNative === toToken.isNative) {
+            throw new Error('Cannot swap a token to itself');
+        }
+        const amountIn = (0, format_js_1.toBigIntAmount)(params.amountIn, fromToken.decimals);
+        if (amountIn <= 0n) {
+            throw new Error('Amount in must be greater than 0');
+        }
+        const slippage = params.slippageTolerancePercent ?? 0.5;
+        // Handle Wrap / Unwrap directly
+        const isWrap = fromToken.isNative && toToken.address.toLowerCase() === index_js_1.LITVM_ADDRESSES.weth.toLowerCase();
+        const isUnwrap = fromToken.address.toLowerCase() === index_js_1.LITVM_ADDRESSES.weth.toLowerCase() && toToken.isNative;
+        if (isWrap || isUnwrap) {
+            const amountOut = amountIn; // 1:1 wrap/unwrap
+            const route = {
+                dexName: isWrap ? 'NativeWrap' : 'NativeUnwrap',
+                poolType: 'wrap',
+                poolAddress: index_js_1.LITVM_ADDRESSES.weth,
+                tokenIn: fromToken.address,
+                tokenOut: toToken.address,
+            };
+            return {
+                tokenIn: fromToken,
+                tokenOut: toToken,
+                amountIn,
+                amountInFormatted: (0, format_js_1.formatTokenAmount)(amountIn, fromToken.decimals),
+                expectedAmountOut: amountOut,
+                expectedAmountOutFormatted: (0, format_js_1.formatTokenAmount)(amountOut, toToken.decimals),
+                minAmountOut: amountOut,
+                minAmountOutFormatted: (0, format_js_1.formatTokenAmount)(amountOut, toToken.decimals),
+                priceImpactPercent: 0,
+                executionPrice: 1,
+                route,
+                program: '0x',
+            };
+        }
+        // Resolve intermediate ERC20 addresses (if native, route via wzkLTC)
+        const tokenInAddr = fromToken.isNative ? index_js_1.LITVM_ADDRESSES.weth : fromToken.address;
+        const tokenOutAddr = toToken.isNative ? index_js_1.LITVM_ADDRESSES.weth : toToken.address;
+        const candidates = [];
+        // 1. Query OurV2 Factory
+        const ourV2Candidate = await this.quoteV2Pool(index_js_1.LITVM_ADDRESSES.ourV2Factory, 'OurV2', tokenInAddr, tokenOutAddr, amountIn, 3000 // 0.3% fee
+        );
+        if (ourV2Candidate)
+            candidates.push(ourV2Candidate);
+        // 2. Query InkyV2 Factory
+        const inkyV2Candidate = await this.quoteV2Pool(index_js_1.LITVM_ADDRESSES.inkyV2Factory, 'InkyV2', tokenInAddr, tokenOutAddr, amountIn, 3000);
+        if (inkyV2Candidate)
+            candidates.push(inkyV2Candidate);
+        if (candidates.length === 0) {
+            throw new Error(`No active liquidity pools found between ${fromToken.symbol} and ${toToken.symbol} on LitecoinVM`);
+        }
+        // Select candidate with the best amountOut
+        const best = candidates.reduce((a, b) => (a.amountOut > b.amountOut ? a : b));
+        const route = {
+            dexName: best.dexName,
+            poolType: best.poolType,
+            poolAddress: best.poolAddress,
+            tokenIn: fromToken.address,
+            tokenOut: toToken.address,
+            fee: best.fee,
+        };
+        // Compile bytecode program for AGGFlow
+        const program = (0, programBuilder_js_1.buildAggregatorProgram)(fromToken, toToken, route, index_js_1.LITVM_ADDRESSES.weth);
+        const minAmountOut = (0, format_js_1.calculateMinAmountOut)(best.amountOut, slippage);
+        const priceImpact = best.reserveIn && best.reserveOut
+            ? (0, format_js_1.calculatePriceImpact)(amountIn, best.amountOut, best.reserveIn, best.reserveOut)
+            : 0;
+        const inUnits = Number((0, format_js_1.formatTokenAmount)(amountIn, fromToken.decimals, 6));
+        const outUnits = Number((0, format_js_1.formatTokenAmount)(best.amountOut, toToken.decimals, 6));
+        const executionPrice = inUnits > 0 ? outUnits / inUnits : 0;
+        return {
+            tokenIn: fromToken,
+            tokenOut: toToken,
+            amountIn,
+            amountInFormatted: (0, format_js_1.formatTokenAmount)(amountIn, fromToken.decimals),
+            expectedAmountOut: best.amountOut,
+            expectedAmountOutFormatted: (0, format_js_1.formatTokenAmount)(best.amountOut, toToken.decimals),
+            minAmountOut,
+            minAmountOutFormatted: (0, format_js_1.formatTokenAmount)(minAmountOut, toToken.decimals),
+            priceImpactPercent: priceImpact,
+            executionPrice,
+            route,
+            program,
+        };
+    }
+    /**
+     * Helper: Quotes a Uniswap V2 pair
+     */
+    async quoteV2Pool(factory, dexName, tokenA, tokenB, amountIn, fee) {
+        try {
+            const pair = await this.client.readContract({
+                address: factory,
+                abi: index_js_2.UniswapV2FactoryABI,
+                functionName: 'getPair',
+                args: [tokenA, tokenB],
+            });
+            if (!pair || pair === viem_1.zeroAddress)
+                return null;
+            const [reserves, token0] = await Promise.all([
+                this.client.readContract({
+                    address: pair,
+                    abi: index_js_2.UniswapV2PairABI,
+                    functionName: 'getReserves',
+                }),
+                this.client.readContract({
+                    address: pair,
+                    abi: index_js_2.UniswapV2PairABI,
+                    functionName: 'token0',
+                }),
+            ]);
+            const isToken0 = tokenA.toLowerCase() === token0.toLowerCase();
+            const reserveIn = isToken0 ? BigInt(reserves[0]) : BigInt(reserves[1]);
+            const reserveOut = isToken0 ? BigInt(reserves[1]) : BigInt(reserves[0]);
+            if (reserveIn === 0n || reserveOut === 0n)
+                return null;
+            // Constant-product AMM with fee in ppm (parts per million: 1,000,000)
+            // e.g. 3000 fee = 0.3%
+            const amountInWithFee = amountIn * BigInt(1_000_000 - fee);
+            const numerator = amountInWithFee * reserveOut;
+            const denominator = reserveIn * 1000000n + amountInWithFee;
+            const amountOut = numerator / denominator;
+            return {
+                dexName,
+                poolType: 'v2',
+                poolAddress: pair,
+                amountOut,
+                fee,
+                reserveIn,
+                reserveOut,
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+}
+exports.LitVMQuoter = LitVMQuoter;

package/dist/swap/swapBuilder.d.ts

@@ -0,0 +1,15 @@
+import { type Address } from 'viem';
+import type { BuildSwapTxParams, PreparedTransaction } from '../types/index.js';
+export declare class LitVMSwapBuilder {
+    /**
+     * Prepares a ready-to-sign transaction for executing a swap
+     */
+    static buildSwapTransaction(params: BuildSwapTxParams): PreparedTransaction;
+    /**
+     * Prepares an ERC-20 approval transaction
+     * @param tokenAddress The ERC-20 token contract
+     * @param spender The contract to approve (Defaults to AGGFlowEntrypoint)
+     * @param amount Optional amount to approve (defaults to max uint256)
+     */
+    static buildApproveTransaction(tokenAddress: Address, spender?: Address, amount?: bigint): PreparedTransaction;
+}