barterjs-sdk
Version:
Barter Network SDK
598 lines (547 loc) • 17.7 kB
Markdown
# 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
1. [Installation](#installation)
2. [Tokens and Chains](#tokenandchain)
3. [Fees](#fees)
4. [Vault Balance](#vaultbalance)
5. [Asset Bridging](#assetbridge)
6. [Cross-chain Swap(Still Under Development)](#crosschainswap)
7. [Omnichain Payment(Still Under Development)](#omnipayment)
<a name="installation"></a>
## Installation
```shell
# npm
npm i --save-dev barterjs-sdk
# yarn
yarn add barterjs-sdk
```
<a name="tokenandchain"></a>
## 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.
```typescript
// 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)
```
<a name="fees"></a>
## 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.
<br>
### Bridging Fee
To get the bridging fee, use the following method:
```typescript
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.
```typescript
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%,
}
}
```
<a name="vaultbalance"></a>
## 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
```typescript
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
```typescript
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'
}
```
<a name="assetbridge"></a>
## Asset Bridging
Barter Bridge allows bridging supported tokens from one blockchain to another.<br>
### Gas estimation
```typescript
async function gasEstimateBridgeToken({
token,
toChainId,
toAddress,
amount,
options,
}: BridgeRequestParam): Promise<string>; // estimated gas in string
```
### Parameters
```typescript
// 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
```typescript
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](#bridgeparam).
##### Example: Bridge 1 ethNear from Ethereum Mainnet to Near Network so the `toAddress` will receive 1 native Near coin.
```typescript
// 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
}
```
<a name="crosschainswap"></a>
## Cross-chain Swap(Still Under Development)
<a name="getroute"></a>
### getSwapRoute
get the best swap route calculated by Barter Smart Router
```typescript
// 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
```typescript
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
```typescript
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
```typescript
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);
```
<a name="omnipayment"></a>
## 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.
```typescript
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](#getroute).
##### 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.
```typescript
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
```typescript
async function omniPay(paymentInfo: PaymentInfo);
```
##### Example: pay ether for a NFT on Near that requires 100 $Near.
```typescript
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!_***