Empseal Router Package (PulseChain)

Overview

The Empseal Router Package helps users find the best swap routes on PulseChain. This package retrieves optimal trading paths across various DEXs, ensuring the most efficient swaps.

Features

• Finds the best swap route for given token pairs.
• Supports both ERC-20 tokens and Native PLS.
• Returns gas estimates for swaps.
• Uses a lightweight ethers.js integration.

Installation

npm install empseal-router

Usage

Importing the Package

const { findBestPath } = require("empseal-router");

Finding the Best Path

async function main() {
    const amountIn = "1000000000000000000"; // 1 Token (assuming 18 decimals)
    const tokenIn = "0x95B303987A60C71504D99Aa1b13B4DA07b0790ab"; // Example address
    const tokenOut = "0xA1077a294dDE1B09bB078844df40758a5D0f9a27"; 
    const maxSteps = 3; // We recommend using 3 steps, limit is from 1 to 4

    try {
        const result = await findBestPath(amountIn, tokenIn, tokenOut, maxSteps);
        console.log("Best path:", result);
    } catch (error) {
        console.error("Error finding path:", error);
    }
}

main();

Example Response

{
    "amounts": ["1000000000000000000", "980000000000000000"],
    "path": ["0x95B303987A60C71504D99Aa1b13B4DA07b0790ab", "0xA1077a294dDE1B09bB078844df40758a5D0f9a27"],
    "adapters": ["0x1234567890123456789012345678901234567890"]
}

⚠️ Handling PLS & WPLS: This package works with WPLS for all swaps. If you need to swap native PLS, you must first wrap (deposit) it into WPLS before calling the swap function. Likewise, if you receive WPLS but need PLS, you must unwrap (withdraw) it manually.

Gather tradeInfo

const tradeInfo = {
    amountIn: result.amounts[0],
    amountOut: (result.amounts[result.amounts.length -1] * BigInt(98) / BigInt(100)), // 2% slippage buffer
    amounts: result.amounts,
    path: result.path,
    adapters: result.adapters,
};

Collect the trade information to send to writeContract functions like swapNoSplit, swapNoSplitFromPLS, swapNoSplitToPLS.

Important Note: Before calling the swap functions, the integrator must ensure that the user has approved the router contract to spend the necessary amount of tokens. This can be done using the approve function on the ERC-20 token contract.

Example: 
        const tokenContract = new ethers.Contract(tokenIn, ERC20_ABI, signer);
        const amountToApprove = ethers.parseUnits("100", 18); // Adjust the amount
        const approval = await tokenContract.approve(ROUTER_ADDRESS, amountToApprove);

Executing a Swap (For Integrators)

Once the best path is found, integrators can call contract write functions using ethers.js. For more detailed & advanced integration (frontend & backend) guide refer: Integration Guide

Get Call Data for Swaps

Once trade information is obtained, integrators can use the following functions to get calldata for executing swaps:

const { getSwapNoSplitCalldata, getSwapNoSplitFromPLSCalldata, getSwapNoSplitToPLSCalldata, ROUTER_ABI } = require("empseal-router");

const userAddress = "0xWalletAddressHere";
const abi = ROUTER_ABI;

const calldataSwap = getSwapNoSplitCalldata(tradeInfo, userAddress, abi);
const calldataSwapFromPLS = getSwapNoSplitFromPLSCalldata(tradeInfo, userAddress, abi);
const calldataSwapToPLS = getSwapNoSplitToPLSCalldata(tradeInfo, userAddress, abi);

Sending Transactions example

After getting the calldata, integrators can use ethers.js or their preferred library to send the transaction:

Example using ethers.js

const { ethers } = require("ethers");
const signer = new ethers.Wallet(process.env.PRIVATE_KEY, provider);
const contract = new ethers.Contract(ROUTER_ADDRESS, ROUTER_ABI, signer);

async function executeSwap(calldata, value = "0") {
    try {
        const tx = await contract.sendTransaction({
            to: ROUTER_ADDRESS,
            data: calldata,
            value: ethers.BigNumber.from(value)
        });
        await tx.wait();
        console.log("Transaction successful:", tx.hash);
    } catch (error) {
        console.error("Transaction failed:", error);
    }
}

executeSwap(calldataSwap);

Configuration

The package includes predefined constants for PulseChain addresses:

Constants

const {
    ROUTER_ADDRESS,
    ROUTER_ABI,
    NATIVE_PLS_ADDRESS,
    WPLS_ADDRESS
} = require("empseal-router");

Explanation

| Constant | Value | |----------|-------| | ROUTER_ADDRESS | Address of the router contract | | ROUTER_ABI | Router ABI | | NATIVE_PLS_ADDRESS | Address representing Native PLS (0x0000...0000) | | WPLS_ADDRESS | Wrapped PLS Address |

Advanced Usage

Finding the Best Path for Native PLS

To find a swap route for Native PLS, use NATIVE_PLS_ADDRESS in place of the input or output token:

const result = await findBestPath(amountIn, NATIVE_PLS_ADDRESS, tokenOut, maxSteps);

Testing

To run the test script:

node testPathFind.js

Contributing

We welcome contributions! Please submit an issue or pull request on GitHub.

License

ISC