Integration 👑🛠

EmpX DEX Aggregator Integration Guide

EmpSeal NPM package : https://www.npmjs.com/package/empseal-router

Please use our Npm package to integrate.

Overview

This guide explains how to integrate with our on-chain DEX aggregator to enable token swaps in your application. The integration can be implemented on both frontend and backend without deploying any additional smart contracts.

A DEX aggregator finds the best price for token swaps by analyzing multiple decentralized exchanges and optimizing the trade path.

Smart Contract Interface

solidity
interface EmpsealRouter {
    struct FormattedOffer {
        uint256[] amounts;
        address[] adapters;
        address[] path;
        uint256 gasEstimate;
    }

    struct Trade {
        uint256 amountIn;
        uint256 amountOut;
        address[] path;
        address[] adapters;
    }

    function findBestPath(
        uint256 _amountIn,
        address _tokenIn,
        address _tokenOut,
        uint256 _maxSteps
    ) external view returns (FormattedOffer memory);

    function swapNoSplit(
        Trade calldata _trade,
        address _from,
        address _to,
        uint256 _fee
    ) external returns (uint256);

    function swapNoSplitFromPLS(
        Trade calldata _trade,
        address _to,
        uint256 _fee
    ) external payable returns (uint256);

    function swapNoSplitToPLS(
        Trade calldata _trade,
        address _to,
        uint256 _fee
    ) external returns (uint256);

    event EmpXswap(
        address indexed _tokenIn, 
        address indexed _tokenOut, 
        uint256 _amountIn, 
        uint256 _amountOut
    );
}

Note:

1. The _fee parameter represents the percentage fee (in basis points) charged by the EmpsealRouter for a trade. For example, a value of 24 corresponds to a 0.24% fee. Transactions with a fee less than 0.24% will be reverted.

2. _maxSteps parameter in the findBestPath function are the hops/steps that'll be taken to find the best path for the trade, you can provide the number from 1 to 4 for the hops, For instance, a _maxSteps value of 3 allows the aggregator to explore up to three intermediate tokens to find the most optimized trade path.

Frontend Integration

1. Finding Best Swap Path

typescript
// Using wagmi
const { data, isLoading } = useReadContract({
    abi: RouterABI,
    address: ROUTER_ADDRESS,
    functionName: "findBestPath",
    args: [
        amountInBigInt,    // Amount in (converted to proper decimals)
        tokenInAddress,    // Input token address
        tokenOutAddress,   // Output token address
        BigInt("3"),       // Max steps
    ],
});

// Response contains:
// - amounts: BigInt[] (amounts for each step of the swap)
// - adapters: address[] (adapter addresses for the swap route)
// - path: address[] (token addresses in swap path)
// - gasEstimate: BigInt

1. Preparing Trade Data

typescript
// Format trade data for swap
const trade = {
    amountIn: data.amounts[0],
    amountOut: (data.amounts[data.amounts.length - 1] * BigInt(98)) / BigInt(100), // 2% slippage buffer
    path: data.path,
    adapters: data.adapters
};

Note:

When passing the amountOut value please make sure to apply some slippage buffer on the amountOut, because when these amounts pass through the contracts the amountOut value and the amounts[amounts.length -1] values get compared, and only allowed when amounts[amounts.length -1] >= amountOut.

Slippage occurs when the price of a token changes between the time a trade is initiated and when it's executed. Adding a buffer helps ensure the trade succeeds even if prices fluctuate slightly.

1. Executing Swap

typescript
// Using wagmi
const swap = async (trade, userAddress) => {
    const result = await writeContract({
        abi: RouterABI,
        address: ROUTER_ADDRESS,
        functionName: "swapNoSplit",
	args: [
        {
          adapters: trade.adapters,
          amountIn: trade.amountIn,
          amountOut: trade.amountOut,
          path: trade.path,
        },
        userAddress,
        BigInt("24"), // Fee (0.24%)
      ],
    });
    
    return result;
};

1. Native PLS Swaps

typescript
// Swap from native PLS through router
const swapFromPLS = async (trade, userAddress) => {
    const result = await writeContract({
        abi: RouterABI,
        address: ROUTER_ADDRESS,
        functionName: "swapNoSplitFromPLS",
        args: [
        {
          adapters: trade.adapters,
          amountIn: trade.amountIn,
          amountOut: trade.amountOut,
          path: trade.path,  // trade.path[0] == NATIVE (0x0000......0), "Path needs to begin with PLS"
        },
        userAddress,
        BigInt("24"), // Fee (0.24%)
      ],
      value: trade.amountIn, // Sending PLS as value
    });
    return result;
};

3.Swap to native PLS through router

const swapToPLS = async (trade, userAddress) => {
    const result = await writeContract({
        abi: RouterABI,
        address: ROUTER_ADDRESS,
        functionName: "swapNoSplitToPLS",
        args: [
        {
          adapters: trade.adapters,
          amountIn: trade.amountIn,
          amountOut: trade.amountOut,
          path: trade.path,  // trade.path[trade.path.length - 1] == NATIVE (0x0000......0), "Path needs to end with PLS"
        },
        userAddress,
        BigInt("24"), // Fee (0.24%)
      ],
    });
    return result;
};

Backend Integration

For backend integration, you can use any popular web3 library:

• ethers.js

• web3.js

• viem

• Other web3 libraries

The integration process remains the same - you'll need:

1. Contract ABI

2. Contract address

3. RPC endpoint

Libraries provide methods for:

Reading Data: Use findBestPath for pathfinding.

Building Transactions: Create and execute swapNoSplit calls.

Event Monitoring: Track EmpXswap events for real-time updates.

Approvals: Approve tokens before initiating swaps.

Important Notes

Path Finding

• _maxSteps must be between 1 and 4

• Empty path/adapters arrays indicate no valid route found

• Gas estimate is provided in the FormattedOffer struct

Swapping

• Always approve tokens before swapping

• Handle token decimals correctly

• Check that received amount matches or exceeds expected amount

• Handle fees if applicable

• Monitor EmpXswap events for swap tracking

Error Handling

• Check for empty paths in findBestPath response, If findBestPath returns empty paths, it means no valid trade route was found. This might occur if liquidity is insufficient or the token pair is not supported.

• Verify sufficient allowance and balance

• Implement slippage protection using amountOut

A Detailed Example of Integration

This is an example walkthrough on how one could integrate EMPX.

1. Prerequisites

Dependencies:

Ensure you install the required libraries in its frontend or backend codebase:

npm install wagmi ethers

Configuration:

Set the EmpsealRouter contract address and ABI in the application. For example:

import RouterABI from './RouterABI.json';
// RouterABI URL: https://oldscan.gopulse.com/#/address/0x0Cf6D948Cf09ac83a6bf40C7AD7b44657A9F2A52?tab=contract_code

const ROUTER_ADDRESS = "0x0Cf6D948Cf09ac83a6bf40C7AD7b44657A9F2A52";

2.Fetching Best Swap Path

Users want to swap USDT for WETH. The frontend will:

Input Data: The user provides:

Input token: USDT Output token: WETH Amount to swap: 100 USDT

Find Best Path: Call findBestPath to determine the optimal route:

import { useReadContract } from 'wagmi';

const { data, isLoading, error } = useReadContract({
    abi: RouterABI,
    address: ROUTER_ADDRESS,
    functionName: "findBestPath",
    args: [
        BigInt("1000000"), // Amount in (USDT has 6 decimals, so 100 * 10^6)
        "0xdAC17F958D2ee523a2206206994597C13D831ec7", // USDT address
        "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", // WETH address
        BigInt("3"), // Max steps
    ],
});

if (data) {
    console.log("Best Path:", data.path);
    console.log("Adapters:", data.adapters);
    console.log("Amounts:", data.amounts);
}

Response Example:

{
    "path": ["0xdAC17F958D2ee523a2206206994597C13D831ec7", "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eb48", "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"],
    "adapters": ["0xAdapterA", "0xAdapterB"],
    "amounts": ["1000000", "998000", "995000"],
    "gasEstimate": "21000"
}

1. Preparing Trade Data

Format the response from findBestPath into a Trade structure:

const trade = {
    amountIn: data.amounts[0], // 1000000 USDT
    amountOut: (data.amounts[data.amounts.length - 1] * BigInt(98)) / BigInt(100), // 2% slippage protection
    path: data.path,
    adapters: data.adapters,
};

1. Token Approval

import { writeContract } from 'wagmi';

const approve = async (tokenAddress, userAddress, amount) => {
    const result = await writeContract({
        abi: ERC20ABI,
        address: tokenAddress,
        functionName: "approve",
        args: [ROUTER_ADDRESS, amount],
    });
    return result;
};

// Approve 1000000 USDT
await approve("0xdAC17F958D2ee523a2206206994597C13D831ec7", userAddress, BigInt("1000000"));

1. Executing the Swap

Once approved, call swapNoSplit to execute the trade:

const swap = async (trade, userAddress) => {
    const result = await writeContract({
        abi: RouterABI,
        address: ROUTER_ADDRESS,
        functionName: "swapNoSplit",
        args: [
            {
                adapters: trade.adapters,
                amountIn: trade.amountIn,
                amountOut: trade.amountOut,
                path: trade.path,
            },
            userAddress,
            BigInt("24"), // 0.24% fee
        ],
    });
    return result;
};

await swap(trade, userAddress);

1. Native PLS Swap Example

Swap From PLS

const swapFromPLS = async (trade, userAddress) => {
    const result = await writeContract({
        abi: RouterABI,
        address: ROUTER_ADDRESS,
        functionName: "swapNoSplitFromPLS",
        args: [
            {
                adapters: trade.adapters,
                amountIn: trade.amountIn,
                amountOut: trade.amountOut,
                path: trade.path, // trade.path[0] == 0x000...0 (native PLS)
            },
            userAddress,
            BigInt("24"), // 0.24% fee
        ],
        value: trade.amountIn, // Send native PLS value
    });
    return result;
};

Swap To PLS

const swapToPLS = async (trade, userAddress) => {
    const result = await writeContract({
        abi: RouterABI,
        address: ROUTER_ADDRESS,
        functionName: "swapNoSplitToPLS",
        args: [
            {
                adapters: trade.adapters,
                amountIn: trade.amountIn,
                amountOut: trade.amountOut,
                path: trade.path, // trade.path[trade.path.length - 1] == 0x000...0 (native PLS)
            },
            userAddress,
            BigInt("24"), // 0.24% fee
        ],
    });
    return result;
};

1. Error Handling

Check for empty paths returned by findBestPath:

if (!data.path.length) {
    throw new Error("No valid trade route found. Ensure sufficient liquidity exists.");
}

Monitor for EmpXswap events to verify the swap success.

1. Frontend UX

Display the estimated trade path, output amount, and fees to users before executing the swap. Add a "slippage tolerance" option for user customization.

EmpX is a revolutionary Onchain aggregator changing the DEFI landscape. We would love to hear from you and collaborate. Get in touch with us🤝