Skip to content

SNAKexchange - Developer Guide

This document is intended for developers who want to build applications, services, or tools that integrate with the SNAKexchange protocol on the Xian Network.

Understanding the Architecture

SNAKexchange operates using two main contracts:

  1. Router (con_dex_v2): This is the contract your application will almost always interact with. It provides a clear and safe API for swapping tokens and managing liquidity. It acts as an intermediary, abstracting away the complexities of direct pair interactions.

  2. Factory/Pairs (con_pairs): This is the core contract. It creates new pairs and contains the fundamental logic for liquidity pools. While you can interact with it directly for some data queries, most actions (like swaps) should go through the router.

The Standard Interaction Flow (e.g., a Swap)

  1. Approval: The user's wallet must first approve the con_dex_v2 (Router) contract to spend the specific token they wish to trade. This is done by calling the approve method on the token's own contract, not on a SNAKexchange contract.

  2. Router Call: The user's application calls a function on the con_dex_v2 contract, such as swapExactTokensForTokens. The parameters will include the amount of token to spend, the minimum amount of token they are willing to receive (to protect against slippage), and the path of the trade.

  3. Token Transfer: The Router contract, now having an allowance, uses the token's transfer_from function to pull the approved amount of tokens from the user's wallet and sends them to the relevant pair contract within con_pairs.

  4. Core Logic Execution: The Router then calls the swap function on the pair contract. The pair contract executes the trade, calculates the output amount based on its reserves, and sends the output tokens from its own reserves to the final recipient address.

Integrating with SNAKexchange

Querying Data

Your application will often need to query the state of the DEX to display prices, calculate potential trades, etc.

  • Getting Pair Reserves: To calculate a trade's price, you first need the reserves of the corresponding liquidity pool. You can get this by calling getReserves(pair) on the con_pairs contract.

  • Finding a Pair Address: You can find the numerical ID of a pair by calling pairFor(tokenA, tokenB) on the con_pairs contract. Remember that token addresses must be passed in lexicographical (alphabetical) order.

  • Calculating Output Amounts: The con_dex_v2 contract provides helper functions to calculate trade outcomes without executing a trade (doesn't work for fee tokens):

    • getAmountOut(amountIn, reserveIn, reserveOut): Calculates the output amount for a single pair swap.
    • getAmountsOut(amountIn, src, path): Calculates the output amounts for a multi-hop trade. The path is a list of pair IDs that the trade will route through and the src is input token.

Executing Swaps

When executing a swap, always use the functions on the con_dex_v2 router.

  • path: For multi-token swaps, you must provide a path. This is an array of pair IDs. For a swap from Token A -> Token B -> Token C, the path would be [pairID_A_B, pairID_B_C].

  • amountOutMin: This is a critical security parameter. It defines the minimum amount of output tokens the user is willing to accept. If the trade would result in fewer tokens due to price movement (slippage), the transaction will revert, protecting the user.

  • deadline: This is a timestamp after which the transaction will revert. It protects users from having their transactions stuck in the mempool for a long time, where they could be executed at a much later, unfavorable price.

Managing Liquidity

  • addLiquidity: This function on the router handles the complexity of adding liquidity. It calculates the optimal ratio of tokens to deposit and mints LP tokens for the user. If the pair does not exist, this function will trigger its creation.

  • removeLiquidity: To remove liquidity, a user must first approve the router to spend their LP tokens. Then, they call removeLiquidity, which burns their LP tokens and returns their proportional share of the underlying tokens from the pool.

Advanced Topics

  • Reentrancy Protection (LOCK): All state-changing functions in the con_pairs contract are protected by a LOCK flag. This is a non-reentrancy guard that prevents a malicious token contract from making a recursive call back into the pair contract during a transaction, which is a common attack vector.

  • Fee-on-Transfer Tokens: As mentioned in the Token Creators guide, always use the dedicated ...SupportingFeeOnTransferTokens functions when interacting with tokens that have transfer fees to ensure the accounting is correct. The router achieves this by checking the contract's token balance before and after the transfer to determine the actual amount received, rather than assuming the full amount was transferred.