@whiterresearch/litvmswap-aggregator 1.0.4

package/dist/swap/swapBuilder.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LitVMSwapBuilder = void 0;
+const viem_1 = require("viem");
+const index_js_1 = require("../constants/index.js");
+const index_js_2 = require("../abi/index.js");
+class LitVMSwapBuilder {
+    /**
+     * Prepares a ready-to-sign transaction for executing a swap
+     */
+    static buildSwapTransaction(params) {
+        const { quote, userAddress, receiverAddress, feeConfig } = params;
+        const receiver = receiverAddress ?? userAddress;
+        // 1. Handle Wrap / Unwrap directly
+        if (quote.route.poolType === 'wrap') {
+            const isWrap = quote.tokenIn.isNative;
+            const wethAddr = index_js_1.LITVM_ADDRESSES.weth;
+            if (isWrap) {
+                // Native -> wzkLTC (Deposit)
+                const data = (0, viem_1.encodeFunctionData)({
+                    abi: index_js_2.ERC20ABI,
+                    functionName: 'deposit',
+                });
+                return {
+                    to: wethAddr,
+                    data,
+                    value: quote.amountIn,
+                    chainId: index_js_1.LITECOIN_VM_CHAIN_ID,
+                    description: `Wrap ${quote.amountInFormatted} ${quote.tokenIn.symbol} to ${quote.tokenOut.symbol}`,
+                };
+            }
+            else {
+                // wzkLTC -> Native (Withdraw)
+                const data = (0, viem_1.encodeFunctionData)({
+                    abi: index_js_2.ERC20ABI,
+                    functionName: 'withdraw',
+                    args: [quote.amountIn],
+                });
+                return {
+                    to: wethAddr,
+                    data,
+                    value: 0n,
+                    chainId: index_js_1.LITECOIN_VM_CHAIN_ID,
+                    description: `Unwrap ${quote.amountInFormatted} ${quote.tokenIn.symbol} to ${quote.tokenOut.symbol}`,
+                };
+            }
+        }
+        // 2. Route through the entrypoint unless the caller explicitly opts out.
+        //
+        // This used to be conditional on a feeConfig being supplied, so the DEFAULT
+        // was a direct router call paying no protocol fee and earning the user no
+        // Lit Diamonds. Integrators got that by accident. The fee path is now the
+        // default and the bypass is explicit.
+        if (!params.useDirectRouter) {
+            // The points wrapper, not the bare entrypoint: it records Lit Diamonds and
+            // the NFT staking multiplier before forwarding to the fee-enforcing
+            // entrypoint. Calling past it silently drops points the user earned.
+            const entrypointAddress = index_js_1.LITVM_ADDRESSES.aggregatorEntrypoint;
+            const swapIntent = {
+                tokenUserBuys: quote.tokenOut.isNative ? viem_1.zeroAddress : quote.tokenOut.address,
+                minAmountUserBuys: quote.minAmountOut,
+                tokenUserSells: quote.tokenIn.isNative ? viem_1.zeroAddress : quote.tokenIn.address,
+                amountUserSells: quote.amountIn,
+            };
+            // The entrypoint enforces both of these on-chain: the fee must go to the
+            // DexFeeVault and must be at least MIN_PROTOCOL_FEE_BPS. Defaulting feeBps
+            // to 0n, as this did, produced transactions that revert with FeeBelowMinimum.
+            const requestedFeeBps = feeConfig?.feeBps !== undefined ? BigInt(feeConfig.feeBps) : index_js_1.MIN_PROTOCOL_FEE_BPS;
+            const feeCollection = {
+                feeCollectorAddress: feeConfig?.feeCollectorAddress ?? index_js_1.LITVM_ADDRESSES.platformFeeCollector,
+                feeBps: requestedFeeBps < index_js_1.MIN_PROTOCOL_FEE_BPS ? index_js_1.MIN_PROTOCOL_FEE_BPS : requestedFeeBps,
+                referrerAddress: feeConfig?.referrerAddress ?? viem_1.zeroAddress,
+                referrerFeeBps: feeConfig?.referrerFeeBps ? BigInt(feeConfig.referrerFeeBps) : 0n,
+                isInTokenFee: feeConfig?.isInTokenFee ?? true,
+            };
+            const isDiffReceiver = receiver.toLowerCase() !== userAddress.toLowerCase();
+            const data = isDiffReceiver
+                ? (0, viem_1.encodeFunctionData)({
+                    abi: index_js_2.AGGFlowEntrypointABI,
+                    functionName: 'executeSwapWithReceiver',
+                    args: [swapIntent, feeCollection, quote.program, receiver],
+                })
+                : (0, viem_1.encodeFunctionData)({
+                    abi: index_js_2.AGGFlowEntrypointABI,
+                    functionName: 'executeSwap',
+                    args: [swapIntent, feeCollection, quote.program],
+                });
+            return {
+                to: entrypointAddress,
+                data,
+                value: quote.tokenIn.isNative ? quote.amountIn : 0n,
+                chainId: index_js_1.LITECOIN_VM_CHAIN_ID,
+                description: `Swap ${quote.amountInFormatted} ${quote.tokenIn.symbol} for ${quote.tokenOut.symbol} via AGGFlowPointsWrapper`,
+            };
+        }
+        // 3. Explicit bypass: straight to AGGFlowRouter.
+        //    No protocol fee, and no Lit Diamonds for the user. Reached only when the
+        //    caller sets useDirectRouter: true.
+        const routerAddress = index_js_1.LITVM_ADDRESSES.aggregatorRouter;
+        const tokenIn = quote.tokenIn.isNative ? viem_1.zeroAddress : quote.tokenIn.address;
+        const tokenOut = quote.tokenOut.isNative ? viem_1.zeroAddress : quote.tokenOut.address;
+        const data = (0, viem_1.encodeFunctionData)({
+            abi: index_js_2.AGGFlowRouterABI,
+            functionName: 'executeRoute',
+            args: [tokenIn, quote.amountIn, tokenOut, quote.minAmountOut, quote.program],
+        });
+        return {
+            to: routerAddress,
+            data,
+            value: quote.tokenIn.isNative ? quote.amountIn : 0n,
+            chainId: index_js_1.LITECOIN_VM_CHAIN_ID,
+            description: `Swap ${quote.amountInFormatted} ${quote.tokenIn.symbol} for ${quote.tokenOut.symbol} via AGGFlowRouter (no protocol fee, no points)`,
+        };
+    }
+    /**
+     * 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, spender = index_js_1.LITVM_ADDRESSES.aggregatorEntrypoint, amount = viem_1.maxUint256) {
+        const data = (0, viem_1.encodeFunctionData)({
+            abi: index_js_2.ERC20ABI,
+            functionName: 'approve',
+            args: [spender, amount],
+        });
+        return {
+            to: tokenAddress,
+            data,
+            value: 0n,
+            chainId: index_js_1.LITECOIN_VM_CHAIN_ID,
+            description: `Approve ${spender} to spend token`,
+        };
+    }
+}
+exports.LitVMSwapBuilder = LitVMSwapBuilder;

package/dist/types/index.d.ts

@@ -0,0 +1,80 @@
+import type { Address, Hex } from 'viem';
+import type { TokenInfo } from '../constants/index.js';
+export type PoolType = 'v2' | 'v3' | 'curve' | 'wrap';
+export interface RouteLeg {
+    dexName: string;
+    poolType: PoolType;
+    poolAddress: Address;
+    tokenIn: Address;
+    tokenOut: Address;
+    fee?: number;
+    curvePoolType?: number;
+    curveIndices?: {
+        from: number;
+        to: number;
+    };
+}
+export interface QuoteParams {
+    tokenIn: Address | string;
+    tokenOut: Address | string;
+    amountIn: bigint | string;
+    slippageTolerancePercent?: number;
+}
+export interface QuoteResult {
+    tokenIn: TokenInfo;
+    tokenOut: TokenInfo;
+    amountIn: bigint;
+    amountInFormatted: string;
+    expectedAmountOut: bigint;
+    expectedAmountOutFormatted: string;
+    minAmountOut: bigint;
+    minAmountOutFormatted: string;
+    priceImpactPercent: number;
+    executionPrice: number;
+    route: RouteLeg;
+    program: Hex;
+}
+export interface FeeConfig {
+    feeCollectorAddress?: Address;
+    feeBps?: bigint | number;
+    referrerAddress?: Address;
+    referrerFeeBps?: bigint | number;
+    isInTokenFee?: boolean;
+}
+export interface BuildSwapTxParams {
+    quote: QuoteResult;
+    userAddress: Address;
+    receiverAddress?: Address;
+    feeConfig?: FeeConfig;
+    /** @deprecated Swaps route through the entrypoint by default. Use `useDirectRouter` to opt out. */
+    useEntrypoint?: boolean;
+    /**
+     * Bypass the entrypoint and call AGGFlowRouter directly.
+     *
+     * This pays NO protocol fee and earns the user NO Lit Diamonds or NFT staking
+     * multiplier. It used to be the default whenever no feeConfig was supplied,
+     * which meant an integrator got it by accident rather than by choice. It is
+     * now opt-in, and deliberately verbose.
+     */
+    useDirectRouter?: boolean;
+}
+export interface PreparedTransaction {
+    to: Address;
+    data: Hex;
+    value: bigint;
+    chainId: number;
+    description: string;
+}
+export interface SwapIntent {
+    tokenUserBuys: Address;
+    minAmountUserBuys: bigint;
+    tokenUserSells: Address;
+    amountUserSells: bigint;
+}
+export interface FeeCollection {
+    feeCollectorAddress: Address;
+    feeBps: bigint;
+    referrerAddress: Address;
+    referrerFeeBps: bigint;
+    isInTokenFee: boolean;
+}

package/dist/types/index.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/utils/format.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Parses user input string or bigint to Wei BigInt
+ */
+export declare function toBigIntAmount(amount: string | bigint | number, decimals: number): bigint;
+/**
+ * Formats a BigInt amount into human readable string
+ */
+export declare function formatTokenAmount(amount: bigint, decimals: number, precision?: number): string;
+/**
+ * Calculates minimum amount out given a slippage tolerance percentage
+ * @param amountOut Expected amount out
+ * @param slippagePercent Slippage tolerance (e.g. 0.5 for 0.5%)
+ */
+export declare function calculateMinAmountOut(amountOut: bigint, slippagePercent: number): bigint;
+/**
+ * Calculates price impact percentage
+ */
+export declare function calculatePriceImpact(amountIn: bigint, amountOut: bigint, reserveIn: bigint, reserveOut: bigint): number;

package/dist/utils/format.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toBigIntAmount = toBigIntAmount;
+exports.formatTokenAmount = formatTokenAmount;
+exports.calculateMinAmountOut = calculateMinAmountOut;
+exports.calculatePriceImpact = calculatePriceImpact;
+const viem_1 = require("viem");
+/**
+ * Parses user input string or bigint to Wei BigInt
+ */
+function toBigIntAmount(amount, decimals) {
+    if (typeof amount === 'bigint') {
+        return amount;
+    }
+    const str = typeof amount === 'number' ? amount.toString() : amount.trim();
+    return (0, viem_1.parseUnits)(str, decimals);
+}
+/**
+ * Formats a BigInt amount into human readable string
+ */
+function formatTokenAmount(amount, decimals, precision = 6) {
+    const formatted = (0, viem_1.formatUnits)(amount, decimals);
+    const parts = formatted.split('.');
+    if (parts.length === 1)
+        return parts[0];
+    const truncated = parts[1].slice(0, precision);
+    return `${parts[0]}.${truncated}`;
+}
+/**
+ * Calculates minimum amount out given a slippage tolerance percentage
+ * @param amountOut Expected amount out
+ * @param slippagePercent Slippage tolerance (e.g. 0.5 for 0.5%)
+ */
+function calculateMinAmountOut(amountOut, slippagePercent) {
+    const basisPoints = BigInt(Math.floor(slippagePercent * 100));
+    const minAmount = (amountOut * (10000n - basisPoints)) / 10000n;
+    return minAmount > 0n ? minAmount : 0n;
+}
+/**
+ * Calculates price impact percentage
+ */
+function calculatePriceImpact(amountIn, amountOut, reserveIn, reserveOut) {
+    if (reserveIn === 0n || reserveOut === 0n)
+        return 0;
+    // Mid price = reserveOut / reserveIn
+    // Execution price = amountOut / amountIn
+    const midPrice = Number(reserveOut) / Number(reserveIn);
+    const execPrice = Number(amountOut) / Number(amountIn);
+    const impact = ((midPrice - execPrice) / midPrice) * 100;
+    return Math.max(0, parseFloat(impact.toFixed(2)));
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@whiterresearch/litvmswap-aggregator",
+  "version": "1.0.4",
+  "description": "Official TypeScript/JavaScript SDK for the LitecoinVM (LitVM) DEX Aggregator",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./constants": {
+      "types": "./dist/constants/index.d.ts",
+      "default": "./dist/constants/index.js"
+    },
+    "./abi": {
+      "types": "./dist/abi/index.d.ts",
+      "default": "./dist/abi/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "tsc",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "litvm",
+    "litecoinvm",
+    "dex",
+    "aggregator",
+    "sdk",
+    "defi",
+    "swap",
+    "uniswap",
+    "ethereum"
+  ],
+  "author": "LitVM Ecosystem",
+  "license": "MIT",
+  "dependencies": {
+    "viem": "^2.21.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.9.3"
+  },
+  "homepage": "https://litvmswap.com",
+  "publishConfig": {
+    "access": "public"
+  }
+}