barterjs-sdk
v1.0.0-beta.38
Published
Barter Network SDK
Downloads
114
Maintainers
Readme
BarterJS SDK
BarterJS SDK aims to facilitate the development of cross-chain functionality by letting developers integrate asset cross-chain feature in their application with minimal effort possible.
Table of Contents
- Installation
- Tokens and Chains
- Fees
- Vault Balance
- Asset Bridging
- Cross-chain Swap(Still Under Development)
- Omnichain Payment(Still Under Development)
Installation
# npm
npm i --save-dev barterjs-sdk
# yarn
yarn add barterjs-sdk
Tokens and Chains
Currently Barter only support limited chains and tokens and Barter will provide lists of supported chains and tokens in the format of constants.
// To get supported blockchain id
const supportedChainIdList = SUPPORTED_CHAIN_IDS_LIST
// To get supported token list by chain id
const supportedTokenList = ID_TO_SUPPORTED_TOKEN(ChainId.Mainnet)
Fees
Barter charges a small fees for bridging or exchanging cross-chain assets. It is subject to what kind of token you want to bridge or swap.
Bridging Fee
To get the bridging fee, use the following method:
async function getBridgeFee(
srcToken: BaseCurrency, // source token, can be the format of native coin or token
targetChain: number, // target blockchain id
amount: string, // amount to bridge, in minimal unit
mapRpcProvider: BarterJsonRpcProvider // map relay chain rpc provider information
): Promise<BarterFee>
// Provider format
type BarterJsonRpcProvider = {
chainId: number;
url?: string; // use default if not presented
};
// return type
interface BarterFee {
feeToken: BaseCurrency; // fee currency to charge, usally in the format of source token
amount: string; // amount to charge
feeDistribution?: BarterFeeDistribution; // fee distribution
}
type BarterFeeDistribution = {
protocol: number; // base protocol fees in bps
compensation: number; // gas compensation on target chain
lp?: number;
};
Example: get the fee for bridging 1 Ether from Ehtereum Mainnet to BSC Mainnet.
const mapRpcProvider = {
url: 'http://18.142.54.137:7445',
chainId: 212,
}
// get the fees for bridging one ether from Ethereum Mainnet to Binance Smart Chain
const fee: BarterFee = await getBridgeFee(
Ether,
ChainId.BSC_MAINNET,
'1000000000000000000',
mapRpcProvider
)
console.log("brige fee", fee);
Output
bridge fee {
feeToken: Token {
address: '0x0000000000000000000000000000000000000000',
chainId: 1,
decimals: 18,
symbol: 'ETH',
name: 'Ether',
isNative: true,
isToken: false
},
amount: '20000000000000',
feeDistribution: {
protocol: 1, // 0.01%
compensation: 1 // 0.01%,
}
}
Vault Balance
In Barter, we deploy one Vault
smart contract for each blockchain we connected in order to hold asset on that chain. To get the balance of certain token in the vault
async function getVaultBalance(
fromChainId: number, // from chain id
fromToken: BaseCurrency, // from token
toChainId: number, // to chain id
rpcProvider: BarterJsonRpcProvider // map relay chain rpc provider
): Promise<VaultBalance>;
// return type
interface VaultBalance {
token: BaseCurrency; // vault token
balance: string; // amount of token in target chain
}
Example: get the balance of Near native token in the vault of Near chain where source chain is Ethereum
const balance: VaultBalance = await getVaultBalance(
ChainId.ETH_MAINNET,
ETH_NEAR,
ChainId.NEAR_MAINNET,
provider
);
console.log('vault balance', balance);
Output:
vault balance {
token: NearNativeCoin {
address: '0x0000000000000000000000000000000000000000',
chainId: 1313161556,
decimals: 24,
symbol: 'NEAR',
name: 'NEAR',
isNative: true,
isToken: false
},
balance: '8000000000000000000000000'
}
Asset Bridging
Barter Bridge allows bridging supported tokens from one blockchain to another.
Gas estimation
async function gasEstimateBridgeToken({
token,
toChainId,
toAddress,
amount,
options,
}: BridgeRequestParam): Promise<string>; // estimated gas in string
Parameters
// BridgeRequestParam
type BridgeRequestParam = {
token: BaseCurrency;
fromChainId: ChainId;
toChainId: ChainId;
toAddress: string;
amount: string;
options: BridgeOptions;
};
// BridgeOptions
type BridgeOptions = {
signerOrProvider?: Signer | Provider | Eth; // When source chain is EVM provide Ethers.js Signer/Provider infor or Web3.js Eth info
nearConfig?: NearNetworkConfig; // when source chain is Near, provide nearConfig Object
gas?: string; // maunally input gas
};
// BarterTransactionReceipt
interface BarterTransactionReceipt {
to: string;
from: string;
gasUsed: string;
transactionHash: string;
blockHash?: string;
blockNumber?: number;
}
bridgeToken
async function bridgeToken({
fromToken,
toChainId,
toAddress, // recipient address
amount, // amount of 'fromToken' to bridge
options,
}: BridgeRequestParam): Promise<BarterTransactionReceipt>;
for more detail on BridgeRequestParam
and BarterContractCallRecept
, please see parameters.
Example: Bridge 1 ethNear from Ethereum Mainnet to Near Network so the toAddress
will receive 1 native Near coin.
// initiate BarterBridge Class
const bridge: BarterBridge = new BarterBridge();
// assemble bridge request parameters
const bridgeRequest: BridgeRequestParam = {
fromToken: ETH_NEAR,
fromChainId: ChainId.ETH_MAINNET,
toChainId: ChainId.NEAR_MAINNET,
toAddress: 'toaddress.near',
amount: '1000000000000000000',
options: {
signerOrProvider: web3.eth, // here we use web3.js as example, but we are ethers.js compitable as well
gas: '61795',
},
};
const receipt: BarterTransactionReceipt = await bridge.bridgeToken(
bridgeRequest
);
console.log('tx receipt', receipt);
Output:
tx receipt {
to: '0x...726f1',
from: '0x...386cc',
gasUsed: '61795',
blockHash: '0xeaf24e6311ed95390d0cc0d378214f2d4c4780fe052439d1ad6e9f811c6d2675',
transactionHash: '0x40e351687cc6eeb8a59ba4ddf395711e6b3c6c328c908cd41d126977a24b59ac',
blockNumber: 767820
}
Cross-chain Swap(Still Under Development)
getSwapRoute
get the best swap route calculated by Barter Smart Router
// get best route method
function getBestRoute(
{
fromToken: BaseCurrency,
toToken: BaseCurrency,
amountIn: string,
amountOutMin: string,
tradeType: TradeType,
options: SwapOptions
}: SwapRouteRequest
): Promise<CrossChainSwapRoute>;
// TradeType
export enum TradeType {
EXACT_INPUT = 0, // regular direction,fromToken -> toToken
EXACT_OUTPUT = 1, // reverse direction, toToken -> fromToken
}
// SwapOptions
type SwapOptions = {
signerOrProvider?: Signer | Provider | Eth; // When source chain is EVM provide Ethers.js Signer/Provider infor or Web3.js Eth info
nearConfig?: NearNetworkConfig; // mandatory when src chain is near
useAggregator?: boolean; // whether Barter's Smart Router Aggregator or not
gas?: string;
};
// return type: CrossChainSwapRoute
type CrossChainSwapRoute = {
// source chain swap route. e.g. if source chain is Ethereum, this will be the swap route on Ethereum
srcRoute: BarterSwapRoute;
// swap route on MAP relay Chain
relayRoute: BarterSwapRoute;
// swap route on target chain. e.g. if target chain is Binance Smart Chain, this will be the route of BSC.
targetRoute: BarterSwapRoute;
}
type BarterSwapRoute = {
/**
* The quote for the swap.
* For EXACT_IN swaps this will be an amount of token out.
* For EXACT_OUT this will be an amount of token in.
*/
quote: string;
/**
* The quote adjusted for the estimated gas used by the swap.
* This is computed by estimating the amount of gas used by the swap, converting
* this estimate to be in terms of the quote token, and subtracting that from the quote.
* i.e. quoteGasAdjusted = quote - estimatedGasUsedQuoteToken
*/
quoteGasAdjusted: string;
/**
* The estimate of the gas used by the swap.
*/
estimatedGasUsed: string;
/**
* The estimate of the gas used by the swap in terms of the quote token.
*/
estimatedGasUsedQuoteToken: string;
/**
* The estimate of the gas used by the swap in USD.
*/
estimatedGasUsedUSD: string;
/**
* The gas price used when computing quoteGasAdjusted, estimatedGasUsedQuoteToken, etc.
*/
gasPrice: string;
/**
* The routes of the swap.
*/
route: RouteWithValidQuote[];
/**
* The block number used when computing the swap.
*/
blockNumber: string;
/**
* Dex name that doing the swap, e.g. Uniswap, Pancakeswap, etc...
*/
platform: string;
};
// RouteWithValidQuote
class RouteWithValidQuote {
public amount: string; // amountIn
public quote: string; // amountOut
public percent: number; // percentage of the total amountIn
public route: Route; // swap route
public quoteToken: Token;
public gasEstimate: BigNumber;
public gasCostInToken: string;
public gasCostInUSD: string;
public tradeType: TradeType;
public poolAddresses: string[]; // pool address for perfoming the swap
public tokenPath: Token[]; // corresponding
}
class Route {
pairs: Pair[]
path: Token[]
}
class Pair {
// the current mid price of the pair in terms of token0, i.e. the ratio of reserve1 to reserve0
token0Price: string;
// the current mid price of the pair in terms of token1, i.e. the ratio of reserve0 to reserve1
token1Price: string;
chainId: number;
token0: Token;
token1: Token;
reserve0: string;
reserve1: string;
}
Example: Get the best route swapping 100 Ether on Ethereum Mainnet for at least 43200 Near on Near Network
const swapRouteRequest: SwapRouteRequest = {
fromToken: ETH_MAINNET,
toToken: NEAR_MAINNET,
amountIn: "100000000000000000000", // 100 ehter
amountOutMin: "432000000000000000000000000000", // 43200 near
tradeType: TradeType.EXACT_IN,
options: {
signerOrProvider,
userAggregator: true,
}
}
const bestRoute: CrossChainSwapRoute = getBestRoute(SwapRouteRequest);
console.log(bestRoute);
Output
CrossChainSwapRoute: {
// srcRoute: swap 100 ether for 134000 usdt on Uniswap
srcRoute: {
quote: '134000000000000000000000',
quoteGasAdjusted: '134000000000000000000000',
estimatedGasUsed: '10000',
estimatedGasUsedQuoteToken: '0.5',
estimatedGasUsedUSD: '0.5',
gasPrice: "90",
// swap route
route: [
amount: '100000000000000000000', // amountIn in ether: 100 ether in
quote: '134000000000000000000000', // amountOut in USDT: 134000 USDT out
percent: 100, // swap 100% percent of provided token in this route
route: {
pairs: [
token0Price: '1345',
token1Price: '1',
chainId: 1,
token0: Ether,
token1: USDT,
reserve0: '123456000000000000000000', // reserve of Ether
reserve1: '165431040000000000000000000', // reserve of USDT
]
path: [
Ether,
USDT
]
},
quoteToken: USDT,
gasEstimate: 10000,
gasCostInToken: '0.5',
gasCostInUSD: '0.5'',
tradeType: 'EXACT_IN',
poolAddresses: '0xabc......123;, // pool address for perfoming the swap
tokenPath: [Ether, USDT],
],
blockNumber: 123456,
platform: "Uniswap",
},
// swap route on MAP Relay Chain: swap 1340 mapUSDT for 1340 mapUSDC
relayRoute: {
quote: '134000000000000000000000',
quoteGasAdjusted: '134000000000000000000000',
estimatedGasUsed: '10000',
estimatedGasUsedQuoteToken: '0.01',
estimatedGasUsedUSD: '0.01',
gasPrice: "90",
// swap route
route: [
amount: '134000000000000000000000', // amountIn in mapUSDT: 134000 mapUSDT in
quote: '134000000000000000000000', // amountOut in mapUSDC: 134000 mapUSDC out
percent: 100, // swap 100% percent of provided token in this route
route: {
pairs: [
token0Price: '1',
token1Price: '1',
chainId: 34434, // map relay chain id
token0: MAP_USDT,
token1: MAP_USDC,
reserve0: '123456000000000000000000', // reserve of Ether
reserve1: '123456000000000000000000', // reserve of USDT
]
path: [
MAP_USDT,
MAP_USDC
]
},
quoteToken: USDT,
gasEstimate: 10000,
gasCostInToken: '0.01',
gasCostInUSD: '0.01'',
tradeType: 'EXACT_IN',
poolAddresses: '0xabc......123;, // pool address for perfoming the swap
tokenPath: [MAP_USDT, MAP_USDC],
],
blockNumber: 23331,
platform: "MAP Relay Chain",
}
// target route on Near: swap 134000 usdc for 43200 near
targetRoute: {
quote: '43200000000000000000000000000',
quoteGasAdjusted: '43200000000000000000000000000',
estimatedGasUsed: '10000',
estimatedGasUsedQuoteToken: '0.03',
estimatedGasUsedUSD: '0.1',
gasPrice: "90",
// swap route swap 134000 usdc for 43200 near on Ref.fi
route: [
amount: '134000000000000000000000', // amountIn in USDC: 134000 USDC in
quote: '43200000000000000000000000000', // amountOut in Near: 43200 near out
percent: 100, // swap 100% percent of provided token in this route
route: {
pairs: [
token0Price: '1',
token1Price: '1',
chainId: 1313161556, // near chain id
token0: NEAR_USDC,
token1: NEAR,
reserve0: '123456000000000000000000', // reserve of Ether
reserve1: '123456000000000000000000', // reserve of USDT
]
path: [
NEAR_USDC,
NEAR
]
},
quoteToken: USDT,
gasEstimate: 10000,
gasCostInToken: '0.01',
gasCostInUSD: '0.01'',
tradeType: 'EXACT_IN',
poolAddresses: 'pool.near;, // pool address for perfoming the swap
tokenPath: [NEAR_USDC, NEAR],
],
blockNumber: 234556,
platform: "Ref Finance",
},
}
swap
do cross-chain swap
async function omniSwap({
... // too long... omitted for simplicity
}: CrossChainSwapRoute) // the input is what we get after invoking getBestRoute
Example: swap 100 ethers on Ethereum Mainnet for at least 43200 nears on Near network
const swapRouteRequest: SwapRouteRequestParam = {
fromToken: ETH_MAINNET,
toToken: NEAR_MAINNET,
amountIn: "100000000000000000000", // 100 ehter
amountOutMin: "432000000000000000000000000000", // 43200 near
options: {
signerOrProvider,
userAggregator: true,
}
}
const bestRoute: CrossChainSwapRoute = getBestRoute(swapRouteRequest);
const result = await omniSwap(bestRoute);
Omnichain Payment(Still Under Development)
Pay whatever crypto users want, merchant will always get their desired token.
getPaymentInfo
get minimal amount of token needed to meet required price, as well as the swap route.
async function getPaymentInfo({
paidToken: Token,
requiredToken: Token,
requiredAmount: string,
toAddress: string,
options: SwapOptions}: PaymentInfoRequest): Promise<PaymentInfo>
type PaymentInfo = {
paidToken: Token
amountInMin: string, // minimum amount of token needed to complete purchase
swapRoute: CrossChainSwapRoute
}
For more information on CrossChainSwapRoute
, please see getSwapRoute.
Example: get the payment info of Alice paying Ether on Ethereum Mainnet to get a NFT that requires Near coin as payment price at 100 $Near.
const paymentInfoRequest: PaymentInfoRequest = {
paidToken: Ether,
requiredToken: Near,
requiredAmount: '100000000000000000000000000', // 100 Near with 24 decimal
toAddress: 'seller.near',
options: {
signerOrProvider: ethersSigner
}
}
const paymentInfo: PaymentInfo = await getPaymentInfo(paymentInfoRequest);
console.log(paymentInfo);
Output
PaymentInfo: {
paidToken: Ether,
amountInMin: '400000000000000000', // at least 0.4 ether required
swapRoute: ... // ommited, CrossChainSwapRoute for more info.
}
payment
make a payment
async function omniPay(paymentInfo: PaymentInfo);
Example: pay ether for a NFT on Near that requires 100 $Near.
const paymentInfoRequest: PaymentInfoRequest = {
paidToken: Ether,
requiredToken: Near,
requiredAmount: '100000000000000000000000000', // 100 Near with 24 decimal
toAddress: 'seller.near',
options: {
signerOrProvider: ethersSigner
}
}
const paymentInfo: PaymentInfo = await getPaymentInfo(paymentInfoRequest);
const result = await omniPay(paymentInfo);
Note: BarterJS SDK is still under development, all contents are subject to change. Stay tuned for our first relase!