README.md

Website • Documentation

Allbridge Core SDK

Provides an easy integration with the Allbridge Core Bridge for DApps in the browser or Node.js

Table of Contents

• Installing
• How to use
  • 1. Initialize SDK instance
  • 2. Get the list of supported tokens
  • 3.1 Approve the transfer of tokens
  • 3.2 Send Tokens
  • Full example
• Other operations
  • Transaction builder
    • Approve Transaction
    • Send Transaction
      • Solana Blockchain
  • Get information about sent transaction
  • Calculating amount of tokens to be received after fee
  • Calculating amount of tokens to send
  • Getting the amount of gas fee
  • Getting the average transfer time
• Semver

Installing

$ npm install @allbridge/bridge-core-sdk

How to use

1. Initialize SDK instance

const AllbridgeCoreSdk = require('@allbridge/allbridge-core-sdk');
const sdk = new AllbridgeCoreSdk();

2. Get the list of supported tokens

const supportedChains = await sdk.chainDetailsMap();
// extract information about ETH chain
const {bridgeAddress, tokens, chainId, name} = supportedChains[ChainSymbol.ETH];
// Choose one of the tokens supported on ETH
const usdtOnEthTokenInfo = tokens.find(tokenInfo => tokenInfo.symbol === 'USDT');

3.1 Approve the transfer of tokens

Before sending tokens the bridge has to be authorized to use user's tokens. This is done by calling the approve method on SDK instance.

const response = await sdk.approve(web3, {
  tokenAddress: tokenAddress,
  owner: senderAddress,
  spender: poolAddress,
});

TIP: To interact with the Tron blockchain:
use tronWeb instead of web3

3.2 Send Tokens

Initiate the transfer of tokens with send method on SDK instance.

await sdk.send(web3, {
  amount: '1.01',
  fromAccountAddress: senderAddress,
  sourceChainToken: usdtOnEthTokenInfo,
  toAccountAddress: recipientAddress,
  destinationChainToken: usdtOnTrxTokenInfo,
  messenger: Messenger.ALLBRIDGE,
});

TIP: To interact with the Tron blockchain:
use tronWeb instead of web3

Full example

Swap BUSD on BSC chain to USDT on TRX chain

const {
  AllbridgeCoreSdk,
  ChainSymbol,
  Messenger,
} = require("@allbridge/bridge-core-sdk");
const Web3 = require("web3");
require("dotenv").config();

async function runExample() {
  // sender address
  const fromAddress = '0x01234567890abcdef01234567890abcdef012345';
  // recipient address
  const toAddress = 'AbcDefGHIJklmNoPQRStuvwXyz1aBcDefG';

  // configure web3
  const web3 = new Web3('https://bsc-dataseed1.binance.org:443');
  const account = web3.eth.accounts.privateKeyToAccount(process.env.PRIVATE_KEY);
  web3.eth.accounts.wallet.add(account);

  const sdk = new AllbridgeCoreSdk();

  // fetch information about supported chains
  const chains = await sdk.chainDetailsMap();

  const bscChain = chains[ChainSymbol.BSC];
  const busdTokenInfo = bscChain.tokens.find(tokenInfo => tokenInfo.symbol === 'BUSD');

  const trxChain = chains[ChainSymbol.TRX];
  const usdtTokenInfo = trxChain.tokens.find(tokenInfo => tokenInfo.symbol === 'USDT');

  // authorize a transfer of tokens from sender's address
  await sdk.approve(web3, {
    tokenAddress: busdTokenInfo.tokenAddress,
    owner: fromAddress,
    spender: busdTokenInfo.poolAddress,
  });

  // initiate transfer
  const response = await sdk.send(web3, {
    amount: "1.01",
    fromAccountAddress: fromAddress,
    toAccountAddress: toAddress,
    sourceChainToken: busdTokenInfo,
    destinationChainToken: usdtTokenInfo,
    messenger: Messenger.ALLBRIDGE,
  });
  console.log("Tokens sent:", response.txId);
}

runExample();

TIP: For more details, see Examples

Other operations

Transaction builder

Approve Transaction

SDK method rawTransactionBuilder.approve can be used to create approve Transaction.

const rawTransactionApprove = await sdk.rawTransactionBuilder.approve(web3, approveData);

TIP: To interact with the Tron blockchain:
use tronWeb instead of web3

Send Transaction

SDK method rawTransactionBuilder.send can be used to create send Transaction.

const rawTransactionSend = await sdk.rawTransactionBuilder.send(sendParams, web3);

TIP:
To interact with the Tron blockchain:
use tronWeb instead of web3

Solana Blockchain

To create send transaction on Solana blockchain:

const { transaction, signer } = await sdk.rawTransactionBuilder.send(sendParams);

TIP: For more details, see Example

Get information about sent transaction

SDK method getTransferStatus can be used to get information about tokens transfer.

const transferStatus = await sdk.getTransferStatus(chainSymbol, txId);

Calculating amount of tokens to be received after fee

SDK method getAmountToBeReceived can be used to calculate the amount of tokens the receiving party will get after applying the bridging fee.

const amountToBeReceived = await sdk.getAmountToBeReceived(
  amountToSend,
  sourceTokenInfo,
  destinationTokenInfo
);

Calculating amount of tokens to send

SDK method getAmountToSend can be used to calculate the amount of tokens to send based on the required amount of tokens the receiving party should get.

const amountToSend = await sdk.getAmountToSend(
  amountToBeReceived,
  sourceTokenInfo,
  destinationTokenInfo
);

Getting the amount of gas fee

SDK method getTxCost can be used to fetch information about the amount of gas fee required to complete the transfer on the destination chain. Gas fee is paid during the send operation in the source chain currency.

const weiValue = await sdk.getTxCost(
  usdtOnEthTokenInfo, // from ETH
  usdtOnTrxTokenInfo, // to TRX
  Messenger.ALLBRIDGE
);

Getting the average transfer time

SDK method getAverageTransferTime can be used to get the average time in ms it takes to complete a transfer for a given combination of tokens and messenger.

const transferTimeMs = sdk.getAverageTransferTime(
  sourceTokenInfo,
  destinationTokenInfo,
  Messenger.ALLBRIDGE
);

Semver

Until bridge-core-sdk reaches a 1.0.0 release, breaking changes will be released with a new minor version. For example 0.3.1, and 0.3.4 will have the same API, but 0.4.0 will have breaking changes.