@whiterresearch/litvmswap-aggregator 1.0.4

package/README.md

@@ -0,0 +1,208 @@
+# litvmswap-aggregator
+
+The official TypeScript/JavaScript SDK for building on the **LitecoinVM (LitVM)** DEX Aggregator.
+
+Enables builders, bots, and frontends to find optimal liquidity routes across all LitecoinVM decentralized exchanges (Uniswap V2, Uniswap V3, Algebra, Curve) and execute atomic swaps in a single transaction.
+
+---
+
+## ⚡ Quickstart
+
+### 1. Installation
+
+```bash
+npm install @whiterresearch/litvmswap-aggregator viem
+# or
+yarn add @whiterresearch/litvmswap-aggregator viem
+# or
+pnpm add @whiterresearch/litvmswap-aggregator viem
+```
+
+---
+
+### 2. Fetch a Swap Quote
+
+Query the best route and expected output across all LitVM liquidity pools:
+
+```typescript
+import { LitVMAggregator } from '@whiterresearch/litvmswap-aggregator';
+
+const aggregator = new LitVMAggregator();
+
+const quote = await aggregator.getQuote({
+  tokenIn: 'zkLTC',    // Native token symbol or address
+  tokenOut: 'ZKUSDC',  // Target token symbol or address
+  amountIn: '1.0',     // Formatted amount (1.0 zkLTC)
+  slippageTolerancePercent: 0.5, // 0.5% max slippage
+});
+
+console.log(`Expected Output: ${quote.expectedAmountOutFormatted} ${quote.tokenOut.symbol}`);
+console.log(`Minimum Output:  ${quote.minAmountOutFormatted} ${quote.tokenOut.symbol}`);
+console.log(`Route Pool:      ${quote.route.dexName} (${quote.route.poolAddress})`);
+```
+
+---
+
+### 3. Build & Execute Swap Transaction
+
+Prepare a transaction payload ready to be signed with **Viem**, **Wagmi**, or **Ethers.js**:
+
+```typescript
+// 1. Build ready-to-sign swap transaction
+const swapTx = aggregator.buildSwapTx({
+  quote,
+  userAddress: '0xYourWalletAddress...',
+});
+
+// swapTx contains:
+// - to: Contract address (AGGFlowRouter / AGGFlowEntrypoint)
+// - data: Calldata hex string
+// - value: Native token amount in wei (0n if selling ERC-20)
+// - chainId: 4441
+
+// 2. Send transaction with Viem / Wagmi
+const hash = await walletClient.sendTransaction({
+  account: userAddress,
+  to: swapTx.to,
+  data: swapTx.data,
+  value: swapTx.value,
+});
+```
+
+---
+
+### 4. Handling ERC-20 Approvals
+
+When selling an ERC-20 token, check allowance and approve if required:
+
+```typescript
+if (!quote.tokenIn.isNative) {
+  const needsApproval = await aggregator.needsApproval({
+    tokenAddress: quote.tokenIn.address,
+    ownerAddress: userAddress,
+    amount: quote.amountIn,
+  });
+
+  if (needsApproval) {
+    const approveTx = aggregator.buildApproveTx({
+      tokenAddress: quote.tokenIn.address,
+    });
+
+    await walletClient.sendTransaction({
+      account: userAddress,
+      to: approveTx.to,
+      data: approveTx.data,
+      value: 0n,
+    });
+  }
+}
+```
+
+---
+
+### 5. Monetization: Partner & Referrer Fees
+
+Builders can earn a custom fee on every swap executed through their app, bot, or interface:
+
+```typescript
+const swapTx = aggregator.buildSwapTx({
+  quote,
+  userAddress: userAddress,
+  feeConfig: {
+    feeCollectorAddress: '0xYourRevenueWallet...',
+    feeBps: 10n, // 10 bps = 0.1% of swap amount goes directly to you
+    isInTokenFee: true, // Fee collected in input token
+  },
+});
+```
+
+---
+
+## 🌐 LitecoinVM Network Configuration
+
+| Parameter | Value |
+| :--- | :--- |
+| **Network Name** | LitecoinVM (LitVM) |
+| **Chain ID** | `4441` |
+| **RPC Endpoint** | `https://liteforge.rpc.caldera.xyz/http` |
+| **Secondary RPC** | `https://liteforge.rpc.caldera.xyz/infra-partner-http` |
+| **Block Explorer** | `https://explorer.LitVM.network` |
+| **Native Currency**| `zkLTC` (18 decimals) |
+
+---
+
+## 🔀 How a swap is routed
+
+```
+your app → AGGFlowPointsWrapper → AGGFlowEntrypoint → AGGFlowRouter → pools
+            records Lit Diamonds   enforces the fee     executes
+            + NFT staking boost
+```
+
+`buildSwapTx` targets the **wrapper** by default. Two consequences worth
+knowing:
+
+- **The protocol fee is enforced on-chain.** It must go to the DexFeeVault and be
+  at least `MIN_PROTOCOL_FEE_BPS` (15 = 0.15%). A swap with a lower fee, or one
+  pointing the fee elsewhere, reverts. The SDK applies the minimum for you when
+  `feeConfig.feeBps` is omitted or below it.
+- **Skipping the wrapper costs your users their points.** Lit Diamonds and the NFT
+  staking multiplier are recorded by the wrapper, not the entrypoint.
+
+`useDirectRouter: true` bypasses both — no protocol fee, no points. It was
+previously the default whenever no `feeConfig` was passed, so integrators hit it
+by accident; it is now explicit.
+
+---
+
+## 🏛️ Deployed Contracts (LitecoinVM Chain ID: 4441)
+
+| Contract | Address |
+| :--- | :--- |
+| **AGGFlowPointsWrapper** — send swaps here | `0xF664B56933f3cF0d7d69982b5A8eC9101b80059D` |
+| **AGGFlowEntrypoint (fee enforcement)** | `0x5E19EB2A6BA30892CCe33f93D7Fb24D498512266` |
+| **AGGFlowRouter (aggregator core)** | `0x0624E93350bFfc5B3570589FCae68e2CaBe6c620` |
+| ~~Legacy entrypoint (no fee enforcement)~~ | ~~`0xF69E64804000d28aA695eB5c594B996100fb3B49`~~ |
+| **Wrapped Native (wzkLTC / WETH)** | `0x315374AA9b5536037Cc1Efeea2439CCC0913A77e` |
+| **OurV2 Factory** | `0x4680BCe1632824d30D2F53656dD610736c3e312e` |
+| **Inky UniswapV2 Factory** | `0x458C5d5B75ccBA22651D2C5b61cB1EA1e0b0f95D` |
+| **UniswapV3 Factory** | `0xde6763a041f8fc94ca2ee5933736f78f6d1a11c5` |
+| **UniswapV3 Router** | `0x60F8A7642F0aeC06cE628224E743326B23Fe5208` |
+| **DEX Fee Vault** | `0xF2DF37067a8Af0e9ae617c96C887B2FdA8eA3f10` |
+
+---
+
+## 🪙 Pre-Configured Tokens
+
+| Symbol | Name | Address |
+| :--- | :--- | :--- |
+| `zkLTC` | Native Litecoin | `0x0000000000000000000000000000000000000000` |
+| `wzkLTC` | Wrapped zkLTC | `0x315374AA9b5536037Cc1Efeea2439CCC0913A77e` |
+| `ZKUSDC` | ZK USD Coin | `0xdf69970B2fE416339187aA41D39882e864984CE9` |
+| `ZKUSDT` | ZK Tether USD | `0xa338b743Ec494ebB8345f4B6F27ffC902b7EF5Aa` |
+| `LETH` | LitVM Ethereum | `0xDF474006aa807598B616500d146FfF661d644138` |
+| `ZKBTC` | ZK Bitcoin | `0xca4914407868bc37ccbE324cA149DD475d39A2Bf` |
+| `LitVMSwap` | LitVMSwap Token | `0xCa4c7EdB398684cB4C5B3fD0cc6ced30b5a5f4d3` |
+| `LXRP` | LitVM XRP | `0xfdf5cD6452EDC340e67cd16db6A9D74aaa4f81a3` |
+| `brBNB` | Bridged BNB | `0x58B6CD7891cd0A682226E25607b958a6479195A6` |
+
+---
+
+## 📚 API Reference
+
+### `LitVMAggregator`
+* `constructor(config?: LitVMAggregatorConfig)`
+* `getQuote(params: QuoteParams): Promise<QuoteResult>`
+* `buildSwapTx(params: BuildSwapTxParams): PreparedTransaction`
+* `checkAllowance(params: { tokenAddress, ownerAddress, spenderAddress? }): Promise<bigint>`
+* `needsApproval(params: { tokenAddress, ownerAddress, amount, spenderAddress? }): Promise<boolean>`
+* `buildApproveTx(params: { tokenAddress, spenderAddress?, amount? }): PreparedTransaction`
+* `getToken(addressOrSymbol: string): Promise<TokenInfo>`
+* `getKnownTokens(): TokenInfo[]`
+* `executeSwapWithWallet(params): Promise<Hex>`
+
+---
+
+## 📄 License
+MIT
+

package/dist/abi/AGGFlowEntrypoint.d.ts

@@ -0,0 +1,190 @@
+export declare const AGGFlowEntrypointABI: readonly [{
+    readonly type: "constructor";
+    readonly inputs: readonly [{
+        readonly name: "_owner";
+        readonly type: "address";
+    }, {
+        readonly name: "_AGGFlowRouter";
+        readonly type: "address";
+    }];
+    readonly stateMutability: "nonpayable";
+}, {
+    readonly type: "event";
+    readonly name: "AGGFlowSwap";
+    readonly inputs: readonly [{
+        readonly name: "user";
+        readonly type: "address";
+        readonly indexed: true;
+    }, {
+        readonly name: "referrer";
+        readonly type: "address";
+        readonly indexed: true;
+    }, {
+        readonly name: "tokenIn";
+        readonly type: "address";
+        readonly indexed: false;
+    }, {
+        readonly name: "tokenOut";
+        readonly type: "address";
+        readonly indexed: false;
+    }, {
+        readonly name: "isFeeInInput";
+        readonly type: "bool";
+        readonly indexed: false;
+    }, {
+        readonly name: "amountIn";
+        readonly type: "uint256";
+        readonly indexed: false;
+    }, {
+        readonly name: "amountOut";
+        readonly type: "uint256";
+        readonly indexed: false;
+    }, {
+        readonly name: "referrerFeeBps";
+        readonly type: "uint256";
+        readonly indexed: false;
+    }, {
+        readonly name: "totalFeeBps";
+        readonly type: "uint256";
+        readonly indexed: false;
+    }];
+    readonly anonymous: false;
+}, {
+    readonly type: "event";
+    readonly name: "FeeCollected";
+    readonly inputs: readonly [{
+        readonly name: "feeCollector";
+        readonly type: "address";
+        readonly indexed: false;
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+        readonly indexed: false;
+    }, {
+        readonly name: "referrer";
+        readonly type: "address";
+        readonly indexed: false;
+    }, {
+        readonly name: "referrerAmount";
+        readonly type: "uint256";
+        readonly indexed: false;
+    }, {
+        readonly name: "user";
+        readonly type: "address";
+        readonly indexed: false;
+    }, {
+        readonly name: "token";
+        readonly type: "address";
+        readonly indexed: false;
+    }];
+    readonly anonymous: false;
+}, {
+    readonly type: "function";
+    readonly name: "getRouter";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "executeSwap";
+    readonly inputs: readonly [{
+        readonly name: "swapIntent";
+        readonly type: "tuple";
+        readonly components: readonly [{
+            readonly name: "tokenUserBuys";
+            readonly type: "address";
+        }, {
+            readonly name: "minAmountUserBuys";
+            readonly type: "uint256";
+        }, {
+            readonly name: "tokenUserSells";
+            readonly type: "address";
+        }, {
+            readonly name: "amountUserSells";
+            readonly type: "uint256";
+        }];
+    }, {
+        readonly name: "feeCollection";
+        readonly type: "tuple";
+        readonly components: readonly [{
+            readonly name: "feeCollectorAddress";
+            readonly type: "address";
+        }, {
+            readonly name: "feeBps";
+            readonly type: "uint256";
+        }, {
+            readonly name: "referrerAddress";
+            readonly type: "address";
+        }, {
+            readonly name: "referrerFeeBps";
+            readonly type: "uint256";
+        }, {
+            readonly name: "isInTokenFee";
+            readonly type: "bool";
+        }];
+    }, {
+        readonly name: "program";
+        readonly type: "bytes";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "amountOut";
+        readonly type: "uint256";
+    }];
+    readonly stateMutability: "payable";
+}, {
+    readonly type: "function";
+    readonly name: "executeSwapWithReceiver";
+    readonly inputs: readonly [{
+        readonly name: "swapIntent";
+        readonly type: "tuple";
+        readonly components: readonly [{
+            readonly name: "tokenUserBuys";
+            readonly type: "address";
+        }, {
+            readonly name: "minAmountUserBuys";
+            readonly type: "uint256";
+        }, {
+            readonly name: "tokenUserSells";
+            readonly type: "address";
+        }, {
+            readonly name: "amountUserSells";
+            readonly type: "uint256";
+        }];
+    }, {
+        readonly name: "feeCollection";
+        readonly type: "tuple";
+        readonly components: readonly [{
+            readonly name: "feeCollectorAddress";
+            readonly type: "address";
+        }, {
+            readonly name: "feeBps";
+            readonly type: "uint256";
+        }, {
+            readonly name: "referrerAddress";
+            readonly type: "address";
+        }, {
+            readonly name: "referrerFeeBps";
+            readonly type: "uint256";
+        }, {
+            readonly name: "isInTokenFee";
+            readonly type: "bool";
+        }];
+    }, {
+        readonly name: "program";
+        readonly type: "bytes";
+    }, {
+        readonly name: "receiver";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "amountOut";
+        readonly type: "uint256";
+    }];
+    readonly stateMutability: "payable";
+}, {
+    readonly type: "receive";
+    readonly stateMutability: "payable";
+}];

package/dist/abi/AGGFlowEntrypoint.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AGGFlowEntrypointABI = void 0;
+exports.AGGFlowEntrypointABI = [
+    {
+        type: "constructor",
+        inputs: [
+            { name: "_owner", type: "address" },
+            { name: "_AGGFlowRouter", type: "address" }
+        ],
+        stateMutability: "nonpayable"
+    },
+    {
+        type: "event",
+        name: "AGGFlowSwap",
+        inputs: [
+            { name: "user", type: "address", indexed: true },
+            { name: "referrer", type: "address", indexed: true },
+            { name: "tokenIn", type: "address", indexed: false },
+            { name: "tokenOut", type: "address", indexed: false },
+            { name: "isFeeInInput", type: "bool", indexed: false },
+            { name: "amountIn", type: "uint256", indexed: false },
+            { name: "amountOut", type: "uint256", indexed: false },
+            { name: "referrerFeeBps", type: "uint256", indexed: false },
+            { name: "totalFeeBps", type: "uint256", indexed: false }
+        ],
+        anonymous: false
+    },
+    {
+        type: "event",
+        name: "FeeCollected",
+        inputs: [
+            { name: "feeCollector", type: "address", indexed: false },
+            { name: "amount", type: "uint256", indexed: false },
+            { name: "referrer", type: "address", indexed: false },
+            { name: "referrerAmount", type: "uint256", indexed: false },
+            { name: "user", type: "address", indexed: false },
+            { name: "token", type: "address", indexed: false }
+        ],
+        anonymous: false
+    },
+    {
+        type: "function",
+        name: "getRouter",
+        inputs: [],
+        outputs: [{ name: "", type: "address" }],
+        stateMutability: "view"
+    },
+    {
+        type: "function",
+        name: "executeSwap",
+        inputs: [
+            {
+                name: "swapIntent",
+                type: "tuple",
+                components: [
+                    { name: "tokenUserBuys", type: "address" },
+                    { name: "minAmountUserBuys", type: "uint256" },
+                    { name: "tokenUserSells", type: "address" },
+                    { name: "amountUserSells", type: "uint256" }
+                ]
+            },
+            {
+                name: "feeCollection",
+                type: "tuple",
+                components: [
+                    { name: "feeCollectorAddress", type: "address" },
+                    { name: "feeBps", type: "uint256" },
+                    { name: "referrerAddress", type: "address" },
+                    { name: "referrerFeeBps", type: "uint256" },
+                    { name: "isInTokenFee", type: "bool" }
+                ]
+            },
+            { name: "program", type: "bytes" }
+        ],
+        outputs: [{ name: "amountOut", type: "uint256" }],
+        stateMutability: "payable"
+    },
+    {
+        type: "function",
+        name: "executeSwapWithReceiver",
+        inputs: [
+            {
+                name: "swapIntent",
+                type: "tuple",
+                components: [
+                    { name: "tokenUserBuys", type: "address" },
+                    { name: "minAmountUserBuys", type: "uint256" },
+                    { name: "tokenUserSells", type: "address" },
+                    { name: "amountUserSells", type: "uint256" }
+                ]
+            },
+            {
+                name: "feeCollection",
+                type: "tuple",
+                components: [
+                    { name: "feeCollectorAddress", type: "address" },
+                    { name: "feeBps", type: "uint256" },
+                    { name: "referrerAddress", type: "address" },
+                    { name: "referrerFeeBps", type: "uint256" },
+                    { name: "isInTokenFee", type: "bool" }
+                ]
+            },
+            { name: "program", type: "bytes" },
+            { name: "receiver", type: "address" }
+        ],
+        outputs: [{ name: "amountOut", type: "uint256" }],
+        stateMutability: "payable"
+    },
+    {
+        type: "receive",
+        stateMutability: "payable"
+    }
+];

package/dist/abi/AGGFlowRouter.d.ts

@@ -0,0 +1,69 @@
+export declare const AGGFlowRouterABI: readonly [{
+    readonly type: "constructor";
+    readonly inputs: readonly [{
+        readonly name: "_weth";
+        readonly type: "address";
+    }];
+    readonly stateMutability: "nonpayable";
+}, {
+    readonly type: "event";
+    readonly name: "Route";
+    readonly inputs: readonly [{
+        readonly name: "user";
+        readonly type: "address";
+        readonly indexed: true;
+    }, {
+        readonly name: "tokenIn";
+        readonly type: "address";
+        readonly indexed: false;
+    }, {
+        readonly name: "tokenOut";
+        readonly type: "address";
+        readonly indexed: false;
+    }, {
+        readonly name: "amountIn";
+        readonly type: "uint256";
+        readonly indexed: false;
+    }, {
+        readonly name: "amountOut";
+        readonly type: "uint256";
+        readonly indexed: false;
+    }];
+    readonly anonymous: false;
+}, {
+    readonly type: "function";
+    readonly name: "WETH";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+    }];
+    readonly stateMutability: "view";
+}, {
+    readonly type: "function";
+    readonly name: "executeRoute";
+    readonly inputs: readonly [{
+        readonly name: "tokenIn";
+        readonly type: "address";
+    }, {
+        readonly name: "amountIn";
+        readonly type: "uint256";
+    }, {
+        readonly name: "tokenOut";
+        readonly type: "address";
+    }, {
+        readonly name: "minAmountOut";
+        readonly type: "uint256";
+    }, {
+        readonly name: "program";
+        readonly type: "bytes";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "amountOut";
+        readonly type: "uint256";
+    }];
+    readonly stateMutability: "payable";
+}, {
+    readonly type: "receive";
+    readonly stateMutability: "payable";
+}];

package/dist/abi/AGGFlowRouter.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AGGFlowRouterABI = void 0;
+exports.AGGFlowRouterABI = [
+    {
+        type: "constructor",
+        inputs: [{ name: "_weth", type: "address" }],
+        stateMutability: "nonpayable"
+    },
+    {
+        type: "event",
+        name: "Route",
+        inputs: [
+            { name: "user", type: "address", indexed: true },
+            { name: "tokenIn", type: "address", indexed: false },
+            { name: "tokenOut", type: "address", indexed: false },
+            { name: "amountIn", type: "uint256", indexed: false },
+            { name: "amountOut", type: "uint256", indexed: false }
+        ],
+        anonymous: false
+    },
+    {
+        type: "function",
+        name: "WETH",
+        inputs: [],
+        outputs: [{ name: "", type: "address" }],
+        stateMutability: "view"
+    },
+    {
+        type: "function",
+        name: "executeRoute",
+        inputs: [
+            { name: "tokenIn", type: "address" },
+            { name: "amountIn", type: "uint256" },
+            { name: "tokenOut", type: "address" },
+            { name: "minAmountOut", type: "uint256" },
+            { name: "program", type: "bytes" }
+        ],
+        outputs: [{ name: "amountOut", type: "uint256" }],
+        stateMutability: "payable"
+    },
+    {
+        type: "receive",
+        stateMutability: "payable"
+    }
+];