Coinfair Swap Protocol Integration Guide
This document provides guidance on integrating with the Coinfair swap protocol, focusing on how to select the optimal swap path in the frontend.
How to Select the Optimal Swap Path
Pool Types and Fee Combinations
Coinfair supports multiple pool types and fee combinations:
Pool Types (5 types): 1, 2, 3, 4, 5
Fee Types (3 rates): 3, 5, 10
Optimal Path Selection Process
Finding the optimal trading path requires a comprehensive evaluation of all possible combinations:
1. Initialization and Setup
Establish connection to blockchain provider
Initialize Router and Factory contract interfaces
Setup multicall infrastructure for batch queries
Define available pool types, fee rates, and intermediary tokens
2. Direct Path Evaluation
For all 15 combinations of pool types and fee rates:
Create a direct path array:
[TokenA, TokenB]Create corresponding poolTypePath and feePath arrays
Prepare requests to
Router.getAmountsOut()orRouter.getAmountsIn()
3. Multi-Hop Path Evaluation
For each intermediary token:
Skip if intermediary is the same as input or output token
For all combinations of first-hop and second-hop parameters:
Create a multi-hop path array:
[TokenA, Intermediary, TokenB]Create corresponding poolTypePath and feePath arrays with both hops' parameters
Prepare requests to
Router.getAmountsOut()orRouter.getAmountsIn()
4. Comparison and Selection
For exact input swaps: select the path with maximum output amount
For exact output swaps: select the path with minimum input amount
Consider gas costs when comparing direct vs. multi-hop paths
Return the optimal path information
(path, poolTypePath, feePath, expected amounts)
TypeScript Implementation
import { ethers } from 'ethers';
import { Contract } from '@ethersproject/contracts';
import { Provider } from '@ethersproject/providers';
import { Multicall } from 'ethereum-multicall';
// Configuration constants
const POOL_TYPES = [1, 2, 3, 4, 5];
const FEE_TYPES = [3, 5, 10];
// Intermediate tokens for multi-hop paths
const INTERMEDIARY_TOKENS = [
'0x55d398326f99059fF775485246999027B3197955',
'0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d',
'0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c'
];
// Contract addresses (to be filled with actual addresses)
const ROUTER_ADDRESS = '0x2b5970d94908664aC5023c08FCd48Bf4DBE3E034';
const FACTORY_ADDRESS = '0xBBC73Eaaa789c0Eb860749855B3928f6b851685F';
/**
* PathFinder class for finding optimal swap paths
*/
export class PathFinder {
private router: Contract;
private factory: Contract;
private provider: Provider;
private multicall: Multicall;
constructor(provider: Provider, signer?: ethers.Signer) {
this.provider = provider;
this.router = new Contract(
ROUTER_ADDRESS,
[
'function getAmountsOut(uint amountIn, address[] path, uint8[] poolTypes, uint[] fees) view returns (uint[] amounts, address[] pairs)',
'function getAmountsIn(uint amountOut, address[] path, uint8[] poolTypes, uint[] fees) view returns (uint[] amounts, address[] pairs)'
],
signer || provider
);
this.factory = new Contract(
FACTORY_ADDRESS,
['function getPair(address tokenA, address tokenB, uint8 poolType, uint fee) view returns (address pair)'],
provider
);
this.multicall = new Multicall({ ethersProvider: provider });
}
/**
* Find the best path for a token swap
* @param tokenIn Input token address
* @param tokenOut Output token address
* @param amountIn Input amount (in wei)
* @param exactOutput Whether this is an exact output swap
* @param amountOut Output amount (for exact output swaps)
* @returns Best path information
*/
async findBestPath(
tokenIn: string,
tokenOut: string,
amountIn: ethers.BigNumber,
exactOutput: boolean = false,
amountOut?: ethers.BigNumber
) {
let bestPath = null;
let bestAmountOut = ethers.BigNumber.from(0);
let bestAmountIn = ethers.constants.MaxUint256;
// 1. Check direct paths
const directPathResults = await this.checkDirectPaths(tokenIn, tokenOut, amountIn, exactOutput, amountOut);
if (exactOutput) {
if (directPathResults.bestAmountIn.lt(bestAmountIn)) {
bestAmountIn = directPathResults.bestAmountIn;
bestPath = directPathResults.bestPath;
}
} else {
if (directPathResults.bestAmountOut.gt(bestAmountOut)) {
bestAmountOut = directPathResults.bestAmountOut;
bestPath = directPathResults.bestPath;
}
}
// 2. Check single-hop paths through intermediary tokens
for (const intermediary of INTERMEDIARY_TOKENS) {
// Skip if intermediary is the same as input or output token
if (intermediary === tokenIn || intermediary === tokenOut) continue;
const multiHopResults = await this.checkMultiHopPath(tokenIn, intermediary, tokenOut, amountIn, exactOutput, amountOut);
if (exactOutput) {
if (multiHopResults.bestAmountIn.lt(bestAmountIn)) {
bestAmountIn = multiHopResults.bestAmountIn;
bestPath = multiHopResults.bestPath;
}
} else {
if (multiHopResults.bestAmountOut.gt(bestAmountOut)) {
bestAmountOut = multiHopResults.bestAmountOut;
bestPath = multiHopResults.bestPath;
}
}
}
// If no path found, throw error
if (!bestPath) {
throw new Error("No valid swap path found");
}
return {
...bestPath,
expectedOut: exactOutput ? amountOut : bestAmountOut,
expectedIn: exactOutput ? bestAmountIn : amountIn
};
}
/**
* Check all direct path combinations using multicall
*/
private async checkDirectPaths(
tokenIn: string,
tokenOut: string,
amountIn: ethers.BigNumber,
exactOutput: boolean,
amountOut?: ethers.BigNumber
) {
const multicallContext = [];
// Prepare multicall requests
for (const poolType of POOL_TYPES) {
for (const fee of FEE_TYPES) {
const path = [tokenIn, tokenOut];
const poolTypePath = [poolType];
const feePath = [fee];
multicallContext.push({
reference: `${poolType}-${fee}`,
contractAddress: ROUTER_ADDRESS,
abi: [
exactOutput
? 'function getAmountsIn(uint amountOut, address[] path, uint8[] poolTypes, uint[] fees) view returns (uint[] amounts, address[] pairs)'
: 'function getAmountsOut(uint amountIn, address[] path, uint8[] poolTypes, uint[] fees) view returns (uint[] amounts, address[] pairs)'
],
calls: [
{
reference: 'amounts',
methodName: exactOutput ? 'getAmountsIn' : 'getAmountsOut',
methodParameters: exactOutput
? [amountOut, path, poolTypePath, feePath]
: [amountIn, path, poolTypePath, feePath]
}
]
});
}
}
// Execute multicall
const { results } = await this.multicall.call(multicallContext);
// Process results
let bestPath = null;
let bestAmountOut = ethers.BigNumber.from(0);
let bestAmountIn = ethers.constants.MaxUint256;
for (const poolType of POOL_TYPES) {
for (const fee of FEE_TYPES) {
const key = `${poolType}-${fee}`;
if (results[key] && results[key].success) {
const [amounts, pairs] = results[key].callsReturnContext[0].returnValues;
if (exactOutput) {
// For exact output, we want to minimize input amount
const inputAmount = ethers.BigNumber.from(amounts[0].hex);
if (inputAmount.lt(bestAmountIn)) {
bestAmountIn = inputAmount;
bestPath = {
path: [tokenIn, tokenOut],
poolTypePath: [poolType],
feePath: [fee]
};
}
} else {
// For exact input, we want to maximize output amount
const outputAmount = ethers.BigNumber.from(amounts[1].hex);
if (outputAmount.gt(bestAmountOut)) {
bestAmountOut = outputAmount;
bestPath = {
path: [tokenIn, tokenOut],
poolTypePath: [poolType],
feePath: [fee]
};
}
}
}
}
}
return { bestPath, bestAmountOut, bestAmountIn };
}
/**
* Check all multi-hop path combinations for a specific intermediary token
*/
private async checkMultiHopPath(
tokenIn: string,
intermediary: string,
tokenOut: string,
amountIn: ethers.BigNumber,
exactOutput: boolean,
amountOut?: ethers.BigNumber
) {
const multicallContext = [];
// Prepare multicall requests for all combinations
for (const firstPoolType of POOL_TYPES) {
for (const firstFee of FEE_TYPES) {
for (const secondPoolType of POOL_TYPES) {
for (const secondFee of FEE_TYPES) {
const path = [tokenIn, intermediary, tokenOut];
const poolTypePath = [firstPoolType, secondPoolType];
const feePath = [firstFee, secondFee];
multicallContext.push({
reference: `${firstPoolType}-${firstFee}-${secondPoolType}-${secondFee}`,
contractAddress: ROUTER_ADDRESS,
abi: [
exactOutput
? 'function getAmountsIn(uint amountOut, address[] path, uint8[] poolTypes, uint[] fees) view returns (uint[] amounts, address[] pairs)'
: 'function getAmountsOut(uint amountIn, address[] path, uint8[] poolTypes, uint[] fees) view returns (uint[] amounts, address[] pairs)'
],
calls: [
{
reference: 'amounts',
methodName: exactOutput ? 'getAmountsIn' : 'getAmountsOut',
methodParameters: exactOutput
? [amountOut, path, poolTypePath, feePath]
: [amountIn, path, poolTypePath, feePath]
}
]
});
}
}
}
}
// Execute multicall
const { results } = await this.multicall.call(multicallContext);
// Process results
let bestPath = null;
let bestAmountOut = ethers.BigNumber.from(0);
let bestAmountIn = ethers.constants.MaxUint256;
for (const firstPoolType of POOL_TYPES) {
for (const firstFee of FEE_TYPES) {
for (const secondPoolType of POOL_TYPES) {
for (const secondFee of FEE_TYPES) {
const key = `${firstPoolType}-${firstFee}-${secondPoolType}-${secondFee}`;
if (results[key] && results[key].success) {
const [amounts, pairs] = results[key].callsReturnContext[0].returnValues;
if (exactOutput) {
// For exact output, we want to minimize input amount
const inputAmount = ethers.BigNumber.from(amounts[0].hex);
if (inputAmount.lt(bestAmountIn)) {
bestAmountIn = inputAmount;
bestPath = {
path: [tokenIn, intermediary, tokenOut],
poolTypePath: [firstPoolType, secondPoolType],
feePath: [firstFee, secondFee]
};
}
} else {
// For exact input, we want to maximize output amount
const outputAmount = ethers.BigNumber.from(amounts[2].hex);
if (outputAmount.gt(bestAmountOut)) {
bestAmountOut = outputAmount;
bestPath = {
path: [tokenIn, intermediary, tokenOut],
poolTypePath: [firstPoolType, secondPoolType],
feePath: [firstFee, secondFee]
};
}
}
}
}
}
}
}
return { bestPath, bestAmountOut, bestAmountIn };
}
}
/**
* Swap executor for performing token swaps
*/
export class SwapExecutor {
private router: Contract;
constructor(signer: ethers.Signer) {
this.router = new Contract(
ROUTER_ADDRESS,
[
// Exact input swaps
'function swapExactTokensForTokens(uint amountIn, uint amountOutMin, address[] calldata path, uint8[] calldata poolTypePath, uint[] calldata feePath, address to, uint deadline) external returns (uint[] memory amounts)',
'function swapExactETHForTokens(uint amountOutMin, address[] calldata path, uint8[] calldata poolTypePath, uint[] calldata feePath, address to, uint deadline) external payable returns (uint[] memory amounts)',
'function swapExactTokensForETH(uint amountIn, uint amountOutMin, address[] calldata path, uint8[] calldata poolTypePath, uint[] calldata feePath, address to, uint deadline) external returns (uint[] memory amounts)',
// Exact output swaps
'function swapTokensForExactTokens(uint amountOut, uint amountInMax, address[] calldata path, uint8[] calldata poolTypePath, uint[] calldata feePath, address to, uint deadline) external returns (uint[] memory amounts)',
'function swapETHForExactTokens(uint amountOut, address[] calldata path, uint8[] calldata poolTypePath, uint[] calldata feePath, address to, uint deadline) external payable returns (uint[] memory amounts)',
'function swapTokensForExactETH(uint amountOut, uint amountInMax, address[] calldata path, uint8[] calldata poolTypePath, uint[] calldata feePath, address to, uint deadline) external returns (uint[] memory amounts)',
// Swaps supporting fee on transfer
'function swapExactTokensForTokensSupportingFeeOnTransferTokens(uint amountIn, uint amountOutMin, address[] calldata path, uint8[] calldata poolTypePath, uint[] calldata feePath, address to, uint deadline) external',
'function swapExactETHForTokensSupportingFeeOnTransferTokens(uint amountOutMin, address[] calldata path, uint8[] calldata poolTypePath, uint[] calldata feePath, address to, uint deadline) external payable',
'function swapExactTokensForETHSupportingFeeOnTransferTokens(uint amountIn, uint amountOutMin, address[] calldata path, uint8[] calldata poolTypePath, uint[] calldata feePath, address to, uint deadline) external'
],
signer
);
}
// Swap execution methods would be implemented here
} Last updated