Router

Smart routing for optimal swap execution across multiple pools, including multi-hop swaps

Table of Contents

• Overview

• Load Graph

• Find Best Route

• Pool TVL

• Utility Methods

---

Overview

The Router module finds the best swap path by:

1. Building a graph of all available pools and coin pairs

2. Discovering all possible 1-hop and 2-hop paths

3. Simulating each candidate path on-chain

4. Returning the optimal route with the best output

// Quick example: find best route for SUI -> USDC
const sdk = initFerraSDK({ network: 'mainnet', fullNodeUrl: '...', wallet: '0x...' })

await sdk.Router.loadGraphData()

const result = await sdk.Router.getBestInternalRouter(
  '0x2::sui::SUI',           // fromCoin
  '0x...::usdc::USDC',       // toCoin
  new BN('1000000000'),       // 1 SUI
  true,                       // isFixedInput
  100,                        // slippage (basis points, 100 = 1%)
  ''                          // partner object ID (empty if none)
)

if (result) {
  console.log('Best route found:')
  result.paths.forEach((path, i) => {
    console.log(`  Path ${i}: ${path.poolAddress.join(' -> ')}`)
    console.log(`  Amount out: ${path.amountOut.toString()}`)
  })
}

---

Load Graph

Before routing, you must load the pool graph. This fetches all pool and coin data from the protocol.

From Remote API

// Loads pool graph from the Ferra API
await sdk.Router.loadGraphData()

// Check if graph is loaded
console.log('Graph loaded:', sdk.Router.isGraphLoaded)

Custom Graph Data

Load graph with custom coin and path providers:

const coinData = {
  coins: [
    { address: '0x2::sui::SUI', decimals: 9 },
    { address: '0x...::usdc::USDC', decimals: 6 }
  ]
}

const pathData = {
  paths: [
    {
      base: '0x2::sui::SUI',
      quote: '0x...::usdc::USDC',
      addressMap: new Map([[60, '0xPoolAddress...']])  // tickSpacing -> poolAddress
    }
  ]
}

sdk.Router.loadGraph(coinData, pathData)

---

Find Best Route

Basic Usage

await sdk.Router.loadGraphData()

const result = await sdk.Router.getBestInternalRouter(
  '0x2::sui::SUI',           // fromCoin
  '0x...::usdc::USDC',       // toCoin
  new BN('1000000000'),       // amount (1 SUI)
  true,                       // isFixedInput
  100,                        // slippage points (100 = 1%)
  ''                          // partner ID
)

Parameters

Parameter	Type	Description
fromCoin	string	Source coin type
toCoin	string	Destination coin type
swapAmount	BN	Amount to swap
isFixedInput	boolean	true = fix input amount, false = fix output
slippagePoint	number	Slippage in basis points (100 = 1%)
partnerObjectId	string	Partner object ID for fee sharing (empty string if none)
multiPoolParams	PreSwapWithMultiPoolParams	Optional fallback params for direct pool swap

Result Structure

type BestInternalRouterResult = {
  paths: OnePath[]          // Optimal swap paths
  isExceed: boolean         // Whether liquidity is exceeded
}

type OnePath = {
  amountIn: BN              // Input amount for this path
  amountOut: BN             // Output amount for this path
  poolAddress: string[]     // Pool addresses in order (1 or 2 pools)
  a2b: boolean[]            // Direction for each pool hop
  rawAmountLimit: BN[]      // Slippage-adjusted limits per hop
  isExceed: boolean         // Whether this path exceeds liquidity
  coinType: string[]        // Coin types at each step
}

With Partner Fee

const result = await sdk.Router.getBestInternalRouter(
  fromCoin,
  toCoin,
  amount,
  true,
  100,
  '0xPartnerObjectId...'   // Partner receives fee share
)

With Multi-Pool Fallback

If the graph doesn't contain a direct route, fall back to multi-pool preswap:

const result = await sdk.Router.getBestInternalRouter(
  fromCoin,
  toCoin,
  amount,
  true,
  100,
  '',
  {
    poolAddresses: ['0xpool1...', '0xpool2...'],
    coinTypeA: fromCoin,
    coinTypeB: toCoin,
    a2b: true,
    byAmountIn: true,
    amount: '1000000000'
  }
)

Complete Example

import { initFerraSDK } from '@ferra-labs/damm'
import BN from 'bn.js'

const sdk = initFerraSDK({
  network: 'mainnet',
  fullNodeUrl: 'https://...',
  wallet: '0x...'
})

async function routeSwap() {
  // 1. Load graph
  await sdk.Router.loadGraphData()

  const fromCoin = '0x2::sui::SUI'
  const toCoin = '0x...::usdc::USDC'
  const amount = new BN('1000000000')  // 1 SUI

  // 2. Find best route
  const result = await sdk.Router.getBestInternalRouter(
    fromCoin,
    toCoin,
    amount,
    true,   // fixed input
    50,     // 0.5% slippage
    ''
  )

  if (!result || result.isExceed) {
    console.log('No viable route found')
    return
  }

  // 3. Log route details
  for (const path of result.paths) {
    console.log({
      pools: path.poolAddress,
      directions: path.a2b,
      amountIn: path.amountIn.toString(),
      amountOut: path.amountOut.toString(),
      coins: path.coinType
    })
  }
}

---

Pool TVL

Get all pools with their TVL (Total Value Locked) in USD:

const poolsWithTvl = await sdk.Router.getPoolWithTVL()

poolsWithTvl.forEach(pool => {
  console.log({
    address: pool.address,
    tvl: pool.tvl
  })
})

// Sort by TVL
const topPools = poolsWithTvl.sort((a, b) => b.tvl - a.tvl)

---

Utility Methods

Get Pool Address and Direction

Look up the pool address and swap direction for a coin pair:

const info = sdk.Router.getPoolAddressMapAndDirection(
  '0x2::sui::SUI',
  '0x...::usdc::USDC'
)

if (info) {
  console.log('Direction (a2b):', info.direction)
  // addressMap: tickSpacing -> poolAddress
  info.addressMap.forEach((poolAddr, tickSpacing) => {
    console.log(`  Tick spacing ${tickSpacing}: ${poolAddr}`)
  })
}

Get Token Info

const tokenInfo = sdk.Router.tokenInfo('0x2::sui::SUI')

if (tokenInfo) {
  console.log({
    address: tokenInfo.address,
    decimals: tokenInfo.decimals
  })
}

Get Fee Rate

const feeRate = sdk.Router.getFeeRate(
  '0x2::sui::SUI',
  '0x...::usdc::USDC',
  '0xPoolAddress...'
)

console.log('Fee rate:', feeRate)

---

Important Notes

• Always call loadGraphData() or loadGraph() before routing

• The router considers both 1-hop (direct) and 2-hop (intermediate) paths

• Up to 16 candidate paths are simulated to find the optimal route

• Multi-hop paths are sorted by TVL to prioritize liquid routes

• If no graph route is found, the router falls back to preSwapWithMultiPool