@whiterresearch/litvmswap-aggregator

v1.0.4

Published

19 days ago

Official TypeScript/JavaScript SDK for the LitecoinVM (LitVM) DEX Aggregator

0High
0Medium
0Low

whiterresearch

litvm litecoinvm dex aggregator sdk defi swap uniswap ethereum

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

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:

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:

// 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:

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:

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

🔀 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)

🪙 Pre-Configured Tokens

📚 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