Katana Swap SDK

Overview

The Katana Swap SDK enables developers to easily integrate token swapping functionality into their applications on the Ronin blockchain. This SDK provides all the necessary tools to interact with Katana's decentralized exchange features, allowing seamless ERC20 token swaps.

Quickstart/Playground

Playground: tbd

Installation

With yarn

 yarn add @sky-mavis/katana-swap

With npm

 npm install @sky-mavis/katana-swap --save

Usage examples

Fetch data

Tokens

Get all tokens

import { ChainId, getAllTokens, DEFAULT_ERC20 } from '@sky-mavis/katana-swap';

const allPublicTokens = await getAllTokens(ChainId.mainnet);
const { mapTokens, arrTokens, arrTokenAddresses } = allPublicTokens

const tokenAddress = "0x97a9107c1793bc407d6f527b77e7fff4d812bece" // AXS
const AXS_TOKEN = mapTokens[tokenAddress]

// or get token from list default erc20 (only for some popular erc20 tokens)
const AXS_TOKEN = DEFAULT_ERC20[ChainId.mainnet].AXS

Balance

Get Ron balance

import { ChainId, getRonBalance } from '@sky-mavis/katana-swap';

const params = {
    chainId: ChainId.mainnet,
    account: "0x5Ef389000014ACA918BBFa7cAdF3e002F11D560c" // Your account
}

const ronBalance: BigNumber = await getRonBalance(params);

Get ERC20 tokens' balance

import { ChainId, getTokenBalances } from '@sky-mavis/katana-swap';

const AXSAddress = 
const params = {
    chainId: ChainId.mainnet,
    account: "0x5Ef389000014ACA918BBFa7cAdF3e002F11D560c" // Your account
    tokens: [DEFAULT_ERC20[ChainId.mainnet].AXS.address, DEFAULT_ERC20[ChainId.mainnet].WRON.address]
}

const tokenBalances: { [tokenAddress: string]: BigNumber | null } = await getTokenBalances(params);
const AXSBalance = tokenBalances[DEFAULT_ERC20[ChainId.mainnet].AXS.address]
const WRONBalance = tokenBalances[DEFAULT_ERC20[ChainId.mainnet].WRON.address]

Approval for Swap

Get permit allowance

import { ChainId, getPermitAllowance } from '@sky-mavis/katana-swap';

const params = {
    chainId: ChainId.mainnet,
    tokenAddress: DEFAULT_ERC20[ChainId.mainnet].AXS.address,
    owner: "0x5Ef389000014ACA918BBFa7cAdF3e002F11D560c" // Your account
}

const { amount, expiration, nonce } = await getPermitAllowance(params);

Get token allowance

import { ChainId, getTokenAllowance } from '@sky-mavis/katana-swap';

const params = {
    chainId: ChainId.mainnet,
    tokenAddress: DEFAULT_ERC20[ChainId.mainnet].AXS.address,
    owner: "0x5Ef389000014ACA918BBFa7cAdF3e002F11D560c" // Your account
}

const allowance: BigNumber = await getTokenAllowance(params);

RON Price USD

Get usd price of RON from Pyth contract

import { ChainId, getRonPricePyth } from '@sky-mavis/katana-swap';

const ronPriceUSD: number = await getRonPricePyth(ChainId.mainnet);

Trade

Get best trade

import { ChainId, getBestTrade, TradeType, KatanaTrade } from '@sky-mavis/katana-swap';

const params = {
    chainId: ChainId.mainnet,
    tokenInAddress: DEFAULT_ERC20[ChainId.mainnet].AXS.address,
    tokenOutAddress: DEFAULT_ERC20[ChainId.mainnet].WRON.address,
    tradeType: TradeType.EXACT_INPUT,
    amount: "1000000000000000000" // 1 AXS
}

const trade: KatanaTrade = await getBestTrade(params);

Get token price on Katana

import { ChainId, getTokenPrice, quoteTokenPrice } from '@sky-mavis/katana-swap';

const params = {
    chainId: ChainId.mainnet,
    tokenAddress: DEFAULT_ERC20[ChainId.mainnet].AXS.address,
}

const price = await getTokenPrice(params);
const ronPriceUSD: number = await getRonPricePyth(ChainId.mainnet);

const params = {
    tokenPrice: price,
    ronPriceUSDFromPyth: ronPriceUSD,
    amount: '20' // 20 AXS token
}
const usdQuotePrice: number | null = quoteTokenPrice(params)

Main actions

Approval

Approve token

import { ChainId, approveToken } from '@sky-mavis/katana-swap';

const wallet = createWalletClient()
const params = {
    chainId: ChainId.mainnet,
    tokenAddress: DEFAULT_ERC20[ChainId.mainnet].AXS.address,
    wallet,
}
const tx: ContractTransaction = await approveToken(params);

Sign permit allowance

import { ChainId, signPermitAllowance, createPermitObj, getPermitAllowance } from '@sky-mavis/katana-swap';


const wallet = createWalletClient()

const tokenAddress = DEFAULT_ERC20[ChainId.mainnet].AXS.address;

const { nonce } = await getPermitAllowance({
    chainId: ChainId.mainnet,
    tokenAddress,
    owner: wallet.account,
});

const params = {
    chainId: ChainId.mainnet,
    wallet,
    permit: createPermitObj({
        chainId: ChainId.mainnet,
        token: tokenAddress,
        nonce
    })
}

const permitSignature = await signPermitAllowance(params);

Swap

import { 
    ChainId, 
    swap, 
    DEFAULT_ERC20, 
    SwapRouterNativeAssets, 
    getBestTrade, 
    getRonBalance, 
    checkIsInsufficientRonBalance,
    checkIsInsufficientBalance,
    checkIsTokenApproved,
    approveToken,
    getIntervalTimeCheckPermit,
    checkIsValidPermitAllowanceSignature,
    checkIsValidPermitAllowance,
    createPermitObj,
    signPermitAllowance
} from '@sky-mavis/katana-swap';

const chainId = ChainId.mainnet;
const tokenInAddress = DEFAULT_ERC20[chainId].AXS.address;
const tokenOutAddress =  SwapRouterNativeAssets.RON;
const amount = '1000000000000000000';
const tradeType = TradeType.EXACT_INPUT;
const wallet = createWalletClient()

// find best trade
const findBestTradeParams {
    chainId,
    tokenInAddress,
    tokenOutAddress,
    amount,
    tradeType
}
const trade = await getBestTrade(findBestTradeParams)

// get balance
const { ronBalance, isInsufficient: isInsufficientRONBalance } = await checkIsInsufficientRonBalance({
    chainId,
    account: wallet.account,
    amount,
});

const { tokenBalance: axsBalance, isInsufficient: isInsufficientTokenBalance } = await checkIsInsufficientBalance({
    chainId,
    account: wallet.account,
    token
    amount,
});

// approve token
const { allowance, isApproved } = await checkIsTokenApproved({
    chainId,
    tokenAddress: tokenInAddress,
    owner: wallet.account,
    amount,
})

const txApproved = await approveToken({
    chainId,
    tokenAddress: tokenInAddress,
    wallet,
})

// permit allowance
const { amount: permitAllowance, expiration: permitExpiration, nonce } = await getPermitAllowance({
    chainId: ChainId.mainnet,
    tokenAddress,
    owner: wallet.account,
});

// Signature and PermitAllowance will expire, so they should be rechecked at an interval.
const currentTime = getIntervalTimeCheckPermit()

const isValidPermitAllowance = checkIsValidPermitAllowance({
    permitAllowance,
    permitExpiration,
    amount,
    now: currentTime
})

let permitSignature = undefined; // local state

const isValidSignature = checkIsValidPermitAllowanceSignature({
    chainId,
    token: tokenInAddress,
    signature: permitSignature,
    now: currentTime
})

const shouldRequestSignature = !(isValidPermitAllowance || isValidSignature);

// should request signature 
if (shouldRequestSignature) {
    permitSignature = await signPermitAllowance({
        chainId,
        wallet,
        permit: createPermitObj({
            chainId: ChainId.mainnet,
            token: tokenAddress,
            nonce
        })
    })
}

// swap (only when !shouldRequestSignature && isApproved)
const swapParams = {
    chainId: ChainId.mainnet,
    wallet,
    trade,
    permitSignature
}

const txReceipt = await swap(swapParams);

Wrap RON, unwrap RON

import { ChainId, wrapRon, unwrapRon } from '@sky-mavis/katana-swap';

const wallet = createWalletClient();

// wrap RON
const params = {
    chainId: ChainId.mainnet,
    wallet,
    amount: '10',
};
const tx = await wrapRon(params);

// unwrap RON
const params = {
    chainId: ChainId.mainnet,
    wallet,
    amount: '10',
};
const tx = await unwrapRon(params);

Utilities functions

Create wallet client

import { ChainId } from '@sky-mavis/katana-swap';

const createWalletClient = () => {
  const provider = new ethers.providers.Web3Provider(window.ronin.provider);

  return {
    account: '0x5Ef389000014ACA918BBFa7cAdF3e002F11D560c',
    provider
  };
};

Approval

Check is token approved

import { ChainId, checkIsTokenApproved, DEFAULT_ERC20 } from '@sky-mavis/katana-swap';

const { allowance, isApproved } = await checkIsTokenApproved({
    chainId,
    tokenAddress: DEFAULT_ERC20[chainId].AXS.address,
    owner: "0x5Ef389000014ACA918BBFa7cAdF3e002F11D560c",
    amount: "1000000000000000000",
})

Check is valid permit allowance signature

import { ChainId, checkIsValidPermitAllowanceSignature, DEFAULT_ERC20 } from '@sky-mavis/katana-swap';

const currentTime = getIntervalTimeCheckPermit()
const isValidSignature = checkIsValidPermitAllowanceSignature({
    chainId,
    token: DEFAULT_ERC20[chainId].AXS.address,
    signature, // local state variable that store user signature
    now: currentTime,
})

Check is valid permit allowance

import { ChainId, checkIsValidPermitAllowance, DEFAULT_ERC20 } from '@sky-mavis/katana-swap';

const currentTime = getIntervalTimeCheckPermit()
const { amount: permitAllowance, expiration: permitExpiration, nonce } = await getPermitAllowance({
    chainId: ChainId.mainnet,
    tokenAddress: DEFAULT_ERC20[chainId].AXS.address,
    owner: "0x5Ef389000014ACA918BBFa7cAdF3e002F11D560c",
});

const isValidPermitAllowance = checkIsValidPermitAllowance({
    permitAllowance,
    permitExpiration,
    amount,
    now: currentTime,
})

Create permit object

import { ChainId, createPermitObj, DEFAULT_ERC20 } from '@sky-mavis/katana-swap';

const { nonce } = await getPermitAllowance({
    chainId: ChainId.mainnet,
    tokenAddress: DEFAULT_ERC20[chainId].AXS.address,
    owner: "0x5Ef389000014ACA918BBFa7cAdF3e002F11D560c",
});

const permit = createPermitObj({
    chainId: ChainId.mainnet,
    token: DEFAULT_ERC20[chainId].AXS.address,
    nonce
})