@whiterresearch/litvmswap-aggregator 1.0.4

package/dist/abi/ERC20.d.ts

@@ -0,0 +1,127 @@
+export declare const ERC20ABI: readonly [{
+    readonly type: "function";
+    readonly name: "name";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "string";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "symbol";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "string";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "decimals";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint8";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "totalSupply";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "balanceOf";
+    readonly inputs: readonly [{
+        readonly name: "account";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "allowance";
+    readonly inputs: readonly [{
+        readonly name: "owner";
+        readonly type: "address";
+    }, {
+        readonly name: "spender";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "approve";
+    readonly inputs: readonly [{
+        readonly name: "spender";
+        readonly type: "address";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bool";
+    }];
+    readonly stateMutability: "nonpayable";
+}, {
+    readonly type: "function";
+    readonly name: "transfer";
+    readonly inputs: readonly [{
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bool";
+    }];
+    readonly stateMutability: "nonpayable";
+}, {
+    readonly type: "function";
+    readonly name: "transferFrom";
+    readonly inputs: readonly [{
+        readonly name: "from";
+        readonly type: "address";
+    }, {
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bool";
+    }];
+    readonly stateMutability: "nonpayable";
+}, {
+    readonly type: "function";
+    readonly name: "deposit";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [];
+    readonly stateMutability: "payable";
+}, {
+    readonly type: "function";
+    readonly name: "withdraw";
+    readonly inputs: readonly [{
+        readonly name: "wad";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
+}];

package/dist/abi/ERC20.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ERC20ABI = void 0;
+exports.ERC20ABI = [
+    {
+        type: "function",
+        name: "name",
+        inputs: [],
+        outputs: [{ name: "", type: "string" }],
+        stateMutability: "view"
+    },
+    {
+        type: "function",
+        name: "symbol",
+        inputs: [],
+        outputs: [{ name: "", type: "string" }],
+        stateMutability: "view"
+    },
+    {
+        type: "function",
+        name: "decimals",
+        inputs: [],
+        outputs: [{ name: "", type: "uint8" }],
+        stateMutability: "view"
+    },
+    {
+        type: "function",
+        name: "totalSupply",
+        inputs: [],
+        outputs: [{ name: "", type: "uint256" }],
+        stateMutability: "view"
+    },
+    {
+        type: "function",
+        name: "balanceOf",
+        inputs: [{ name: "account", type: "address" }],
+        outputs: [{ name: "", type: "uint256" }],
+        stateMutability: "view"
+    },
+    {
+        type: "function",
+        name: "allowance",
+        inputs: [
+            { name: "owner", type: "address" },
+            { name: "spender", type: "address" }
+        ],
+        outputs: [{ name: "", type: "uint256" }],
+        stateMutability: "view"
+    },
+    {
+        type: "function",
+        name: "approve",
+        inputs: [
+            { name: "spender", type: "address" },
+            { name: "amount", type: "uint256" }
+        ],
+        outputs: [{ name: "", type: "bool" }],
+        stateMutability: "nonpayable"
+    },
+    {
+        type: "function",
+        name: "transfer",
+        inputs: [
+            { name: "to", type: "address" },
+            { name: "amount", type: "uint256" }
+        ],
+        outputs: [{ name: "", type: "bool" }],
+        stateMutability: "nonpayable"
+    },
+    {
+        type: "function",
+        name: "transferFrom",
+        inputs: [
+            { name: "from", type: "address" },
+            { name: "to", type: "address" },
+            { name: "amount", type: "uint256" }
+        ],
+        outputs: [{ name: "", type: "bool" }],
+        stateMutability: "nonpayable"
+    },
+    // WETH deposit & withdraw
+    {
+        type: "function",
+        name: "deposit",
+        inputs: [],
+        outputs: [],
+        stateMutability: "payable"
+    },
+    {
+        type: "function",
+        name: "withdraw",
+        inputs: [{ name: "wad", type: "uint256" }],
+        outputs: [],
+        stateMutability: "nonpayable"
+    }
+];

package/dist/abi/UniswapV2Pair.d.ts

@@ -0,0 +1,77 @@
+export declare const UniswapV2PairABI: readonly [{
+    readonly type: "function";
+    readonly name: "token0";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "token1";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "getReserves";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "reserve0";
+        readonly type: "uint112";
+    }, {
+        readonly name: "reserve1";
+        readonly type: "uint112";
+    }, {
+        readonly name: "blockTimestampLast";
+        readonly type: "uint32";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "swap";
+    readonly inputs: readonly [{
+        readonly name: "amount0Out";
+        readonly type: "uint256";
+    }, {
+        readonly name: "amount1Out";
+        readonly type: "uint256";
+    }, {
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "data";
+        readonly type: "bytes";
+    }];
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
+}];
+export declare const UniswapV2FactoryABI: readonly [{
+    readonly type: "function";
+    readonly name: "getPair";
+    readonly inputs: readonly [{
+        readonly name: "tokenA";
+        readonly type: "address";
+    }, {
+        readonly name: "tokenB";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "pair";
+        readonly type: "address";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "allPairsLength";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+    readonly stateMutability: "view";
+}];

package/dist/abi/UniswapV2Pair.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UniswapV2FactoryABI = exports.UniswapV2PairABI = void 0;
+exports.UniswapV2PairABI = [
+    {
+        type: "function",
+        name: "token0",
+        inputs: [],
+        outputs: [{ name: "", type: "address" }],
+        stateMutability: "view"
+    },
+    {
+        type: "function",
+        name: "token1",
+        inputs: [],
+        outputs: [{ name: "", type: "address" }],
+        stateMutability: "view"
+    },
+    {
+        type: "function",
+        name: "getReserves",
+        inputs: [],
+        outputs: [
+            { name: "reserve0", type: "uint112" },
+            { name: "reserve1", type: "uint112" },
+            { name: "blockTimestampLast", type: "uint32" }
+        ],
+        stateMutability: "view"
+    },
+    {
+        type: "function",
+        name: "swap",
+        inputs: [
+            { name: "amount0Out", type: "uint256" },
+            { name: "amount1Out", type: "uint256" },
+            { name: "to", type: "address" },
+            { name: "data", type: "bytes" }
+        ],
+        outputs: [],
+        stateMutability: "nonpayable"
+    }
+];
+exports.UniswapV2FactoryABI = [
+    {
+        type: "function",
+        name: "getPair",
+        inputs: [
+            { name: "tokenA", type: "address" },
+            { name: "tokenB", type: "address" }
+        ],
+        outputs: [{ name: "pair", type: "address" }],
+        stateMutability: "view"
+    },
+    {
+        type: "function",
+        name: "allPairsLength",
+        inputs: [],
+        outputs: [{ name: "", type: "uint256" }],
+        stateMutability: "view"
+    }
+];

package/dist/abi/index.d.ts

@@ -0,0 +1,4 @@
+export * from './AGGFlowEntrypoint.js';
+export * from './AGGFlowRouter.js';
+export * from './ERC20.js';
+export * from './UniswapV2Pair.js';

package/dist/abi/index.js

@@ -0,0 +1,20 @@
+"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 });
+__exportStar(require("./AGGFlowEntrypoint.js"), exports);
+__exportStar(require("./AGGFlowRouter.js"), exports);
+__exportStar(require("./ERC20.js"), exports);
+__exportStar(require("./UniswapV2Pair.js"), exports);

package/dist/builder/opcodes.d.ts

@@ -0,0 +1,21 @@
+export declare const OPCODES: {
+    readonly PROCESS_ROUTER_ERC20: 1;
+    readonly PROCESS_USER_ERC20: 2;
+    readonly PROCESS_NATIVE: 3;
+    readonly PROCESS_ONE_POOL: 4;
+    readonly APPLY_PERMIT: 5;
+};
+export declare const POOL_TYPES: {
+    readonly UNIV2: 0;
+    readonly UNIV3: 1;
+    readonly WRAP: 2;
+    readonly AGG: 3;
+    readonly CRYSTAL: 4;
+    readonly CURVE: 5;
+    readonly PALINDROME_FI: 6;
+    readonly LIQUIDITY_BOOK: 7;
+};
+export declare const WRAP_FLAGS: {
+    readonly WRAP: 1;
+    readonly UNWRAP: 0;
+};

package/dist/builder/opcodes.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WRAP_FLAGS = exports.POOL_TYPES = exports.OPCODES = void 0;
+exports.OPCODES = {
+    PROCESS_ROUTER_ERC20: 0x01,
+    PROCESS_USER_ERC20: 0x02,
+    PROCESS_NATIVE: 0x03,
+    PROCESS_ONE_POOL: 0x04,
+    APPLY_PERMIT: 0x05,
+};
+exports.POOL_TYPES = {
+    UNIV2: 0x00,
+    UNIV3: 0x01,
+    WRAP: 0x02,
+    AGG: 0x03,
+    CRYSTAL: 0x04,
+    CURVE: 0x05,
+    PALINDROME_FI: 0x06,
+    LIQUIDITY_BOOK: 0x07,
+};
+exports.WRAP_FLAGS = {
+    WRAP: 0x01, // Wrap native -> WETH
+    UNWRAP: 0x00, // Unwrap WETH -> native
+};

package/dist/builder/programBuilder.d.ts

@@ -0,0 +1,12 @@
+import type { Address, Hex } from 'viem';
+import type { RouteLeg } from '../types/index.js';
+import type { TokenInfo } from '../constants/index.js';
+/**
+ * Converts a hex address (0x...) into an array of 20 bytes
+ */
+export declare function addressToBytes(address: Address | string): number[];
+/**
+ * Encodes the bytecode program for AGGFlowRouter.executeRoute
+ * Compatible with LitecoinVM (Chain 4441)
+ */
+export declare function buildAggregatorProgram(fromToken: TokenInfo, toToken: TokenInfo, route: RouteLeg, wethAddress: Address): Hex;

package/dist/builder/programBuilder.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addressToBytes = addressToBytes;
+exports.buildAggregatorProgram = buildAggregatorProgram;
+const opcodes_js_1 = require("./opcodes.js");
+/**
+ * Converts a hex address (0x...) into an array of 20 bytes
+ */
+function addressToBytes(address) {
+    const clean = address.toLowerCase().replace('0x', '').padStart(40, '0');
+    const bytes = [];
+    for (let i = 0; i < 40; i += 2) {
+        bytes.push(parseInt(clean.slice(i, i + 2), 16));
+    }
+    return bytes;
+}
+/**
+ * Encodes the bytecode program for AGGFlowRouter.executeRoute
+ * Compatible with LitecoinVM (Chain 4441)
+ */
+function buildAggregatorProgram(fromToken, toToken, route, wethAddress) {
+    if (!route?.poolAddress) {
+        throw new Error('Invalid route: poolAddress is required');
+    }
+    const isNativeIn = !!fromToken.isNative;
+    const isNativeOut = !!toToken.isNative;
+    const tokenInSwap = isNativeIn ? wethAddress : fromToken.address;
+    const tokenOutSwap = isNativeOut ? wethAddress : toToken.address;
+    const bytes = [];
+    // 1. Process Input Opcode
+    if (isNativeIn) {
+        // Opcode 0x03: PROCESS_NATIVE
+        bytes.push(opcodes_js_1.OPCODES.PROCESS_NATIVE);
+        bytes.push(0x01); // 1 pool leg
+        bytes.push(0xff, 0xff); // 100% share (65535)
+        bytes.push(opcodes_js_1.POOL_TYPES.WRAP); // PT_WRAP
+        bytes.push(opcodes_js_1.WRAP_FLAGS.WRAP); // Flag: 1 = wrap deposit
+    }
+    else {
+        // Opcode 0x02: PROCESS_USER_ERC20
+        bytes.push(opcodes_js_1.OPCODES.PROCESS_USER_ERC20);
+        bytes.push(...addressToBytes(fromToken.address));
+        bytes.push(0x01); // 1 pool leg
+        bytes.push(0xff, 0xff); // 100% share
+        addSwapLeg(bytes, route, tokenInSwap, tokenOutSwap);
+    }
+    // 2. If Native Input, now swap the wrapped WETH token
+    if (isNativeIn) {
+        // Opcode 0x01: PROCESS_ROUTER_ERC20
+        bytes.push(opcodes_js_1.OPCODES.PROCESS_ROUTER_ERC20);
+        bytes.push(...addressToBytes(wethAddress));
+        bytes.push(0x01); // 1 pool leg
+        bytes.push(0xff, 0xff); // 100% share
+        addSwapLeg(bytes, route, tokenInSwap, tokenOutSwap);
+    }
+    // 3. If Native Output, unwrap WETH -> native
+    if (isNativeOut) {
+        // Opcode 0x01: PROCESS_ROUTER_ERC20
+        bytes.push(opcodes_js_1.OPCODES.PROCESS_ROUTER_ERC20);
+        bytes.push(...addressToBytes(wethAddress));
+        bytes.push(0x01); // 1 leg
+        bytes.push(0xff, 0xff); // 100% share
+        bytes.push(opcodes_js_1.POOL_TYPES.WRAP); // PT_WRAP
+        bytes.push(opcodes_js_1.WRAP_FLAGS.UNWRAP); // Flag: 0 = unwrap withdraw
+    }
+    const hexString = ('0x' + bytes.map((b) => b.toString(16).padStart(2, '0')).join(''));
+    return hexString;
+}
+/**
+ * Appends the swap configuration bytes based on pool type (V2, V3, Curve)
+ */
+function addSwapLeg(bytes, route, tokenIn, tokenOut) {
+    const isV2 = route.poolType === 'v2';
+    const isCurve = route.poolType === 'curve';
+    const zeroForOne = tokenIn.toLowerCase() < tokenOut.toLowerCase();
+    if (isV2) {
+        // PT_UNIV2 = 0x00
+        bytes.push(opcodes_js_1.POOL_TYPES.UNIV2);
+        bytes.push(...addressToBytes(route.poolAddress));
+        bytes.push(zeroForOne ? 0 : 1);
+        // fee in 24 bits (e.g. 3000 fee = 0.3%)
+        const fee = Number(route.fee || 3000);
+        bytes.push((fee >> 16) & 0xff, (fee >> 8) & 0xff, fee & 0xff);
+    }
+    else if (isCurve) {
+        // PT_CURVE = 0x05
+        bytes.push(opcodes_js_1.POOL_TYPES.CURVE);
+        bytes.push(...addressToBytes(route.poolAddress));
+        bytes.push(route.curvePoolType ?? 0);
+        bytes.push(route.curveIndices?.from ?? 0);
+        bytes.push(route.curveIndices?.to ?? 1);
+    }
+    else {
+        // PT_UNIV3 = 0x01 (Uniswap V3, Inky V3, Algebra)
+        bytes.push(opcodes_js_1.POOL_TYPES.UNIV3);
+        bytes.push(...addressToBytes(route.poolAddress));
+        bytes.push(zeroForOne ? 1 : 0);
+    }
+}

package/dist/client.d.ts

@@ -0,0 +1,90 @@
+import { type Address, type PublicClient, type WalletClient, type Hex } from 'viem';
+import { type TokenInfo } from './constants/index.js';
+import { LitVMQuoter } from './quoter/quoter.js';
+import type { QuoteParams, QuoteResult, BuildSwapTxParams, PreparedTransaction, FeeConfig } from './types/index.js';
+export interface LitVMAggregatorConfig {
+    rpcUrl?: string;
+    publicClient?: PublicClient;
+    defaultFeeConfig?: FeeConfig;
+}
+/**
+ * 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...',
+ * });
+ * ```
+ */
+export declare class LitVMAggregator {
+    readonly quoter: LitVMQuoter;
+    readonly publicClient: PublicClient;
+    private defaultFeeConfig?;
+    constructor(config?: LitVMAggregatorConfig);
+    /**
+     * Fetches best quote and generates execution program across LitVM pools
+     */
+    getQuote(params: QuoteParams): Promise<QuoteResult>;
+    /**
+     * Prepares a ready-to-sign transaction object (to, data, value, chainId)
+     */
+    buildSwapTx(params: BuildSwapTxParams): PreparedTransaction;
+    /**
+     * Checks ERC20 token allowance for a given spender (defaults to Aggregator Entrypoint)
+     */
+    checkAllowance(params: {
+        tokenAddress: Address;
+        ownerAddress: Address;
+        spenderAddress?: Address;
+    }): Promise<bigint>;
+    /**
+     * Checks if an ERC20 token needs approval for a swap
+     */
+    needsApproval(params: {
+        tokenAddress: Address;
+        ownerAddress: Address;
+        amount: bigint;
+        spenderAddress?: Address;
+    }): Promise<boolean>;
+    /**
+     * Generates ERC20 approval transaction data
+     */
+    buildApproveTx(params: {
+        tokenAddress: Address;
+        spenderAddress?: Address;
+        amount?: bigint;
+    }): PreparedTransaction;
+    /**
+     * Resolves token metadata from address or symbol
+     */
+    getToken(addressOrSymbol: string): Promise<TokenInfo>;
+    /**
+     * Returns list of verified tokens on LitecoinVM
+     */
+    getKnownTokens(): TokenInfo[];
+    /**
+     * Directly executes a swap using a Viem WalletClient
+     */
+    executeSwapWithWallet(params: {
+        walletClient: WalletClient;
+        quote: QuoteResult;
+        userAddress: Address;
+        receiverAddress?: Address;
+        feeConfig?: FeeConfig;
+    }): Promise<Hex>;
+}