@allbridge/bridge-core-sdk

Website • Documentation • SDK TS doc

Allbridge Core SDK

Provides an easy integration with the Allbridge Core ChainBridgeService 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
  • Liquidity Pools operations
  • Transaction builder
    • Approve Transaction
    • Send Transaction
  • 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

Installing

$ npm install @allbridge/bridge-core-sdk

How to use

Find out how to integrate Allbridge Core SDK and Browser Extension Wallet

Evm Solana Stellar Tron

1. Initialize SDK

1) Initialize SDK instance with your node Rpc urls (RECOMMENDED)

import {AllbridgeCoreSdk, nodeRpcUrlsDefault} from "@allbridge/bridge-core-sdk";
// Connections to blockchains will be made through your rpc-urls passed during initialization
const sdk = new AllbridgeCoreSdk({
  ...nodeRpcUrlsDefault,
  TRX: "your trx-rpc-url",
  ETH: "your eth-rpc-url"
});
// Sdk will be using your rpc url for fetch data from blockchain to create tx
const rawTx = await sdk.bridge.rawTxBuilder.send(sendParams);

2) Initialize SDK instance (using passed provider for blockchains connections)

import {AllbridgeCoreSdk, nodeRpcUrlsDefault} from "@allbridge/bridge-core-sdk";

const sdk = new AllbridgeCoreSdk(nodeRpcUrlsDefault);
// The Provider parameter must be passed in order for it to be used to connect to the blockchain, for example:
const rawTx = await sdk.bridge.rawTxBuilder.send(sendParams, provider);

TIP: tested and developed for (Web3:v1.9.0, tronweb:v4.4.0), in other case use approach 1)

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 usdtOnEthToken = tokens.find(token => token.symbol === 'USDT');

3.1 Approve the transfer of tokens (only for Evm, Tron)

Before sending tokens, the bridge has to be authorized to use the tokens of the owner. This is done by building the approve transaction with SDK instance.

For Ethereum USDT - due to specificity of the USDT contract:
If the current allowance is not 0, this function will perform an additional transaction to set allowance to 0 before setting the new allowance value.

const rawTx = await sdk.bridge.rawTxBuilder.approve({
  token: sourceToken,
  owner: accountAddress
});

3.2 Send Tokens

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

const rawTx = await sdk.bridge.rawTxBuilder.send({
  amount: "1.01",
  fromAccountAddress: fromAddress,
  toAccountAddress: toAddress,
  sourceToken: sourceToken,
  destinationToken: destinationToken,
  messenger: Messenger.ALLBRIDGE,
});

Full example

Swap USDC on ETH chain to USDC on POL chain

import {
  AllbridgeCoreSdk,
  ChainSymbol,
  Messenger,
} from "@allbridge/bridge-core-sdk";
import Web3 from "web3";
import * as dotenv from "dotenv";
// Utils method
// For more details, see Examples (https://github.com/allbridge-public/allbridge-core-js-sdk/tree/main/examples)
// import { getEnvVar } from "../../../utils/env";
// import { sendEvmRawTransaction } from "../../../utils/web3";
// import { ensure } from "../../../utils/utils";

dotenv.config({path: ".env"});

async function runExample() {
    const fromAddress = getEnvVar("ETH_ACCOUNT_ADDRESS"); // sender address
    const toAddress = getEnvVar("TRX_ACCOUNT_ADDRESS"); // recipient address

    const sdk = new AllbridgeCoreSdk({ ...nodeRpcUrlsDefault, ETH: getEnvVar("WEB3_PROVIDER_URL") });

    const chains = await sdk.chainDetailsMap();

    const sourceChain = chains[ChainSymbol.ETH];
    const sourceToken = ensure(sourceChain.tokens.find((tokenInfo) => tokenInfo.symbol === "USDC"));

    const destinationChain = chains[ChainSymbol.POL];
    const destinationToken = ensure(destinationChain.tokens.find((tokenInfo) => tokenInfo.symbol === "USDC"));

    const amount = "1.01";

    //check if sending tokens already approved
    if (!(await sdk.bridge.checkAllowance({ token: sourceToken, owner: fromAddress, amount: amount }))) {
      // authorize the bridge to transfer tokens from sender's address
      const rawTransactionApprove = (await sdk.bridge.rawTxBuilder.approve({
        token: sourceToken,
        owner: fromAddress,
      })) as RawEvmTransaction;
      const approveTxReceipt = await sendEvmRawTransaction(rawTransactionApprove);
      console.log("Approve tx id:", approveTxReceipt.transactionHash);
    }

    // initiate transfer
    const rawTransactionTransfer = (await sdk.bridge.rawTxBuilder.send({
      amount: amount,
      fromAccountAddress: fromAddress,
      toAccountAddress: toAddress,
      sourceToken: sourceToken,
      destinationToken: destinationToken,
      messenger: Messenger.ALLBRIDGE,
    })) as RawEvmTransaction;
    console.log(`Sending ${amount} ${sourceToken.symbol}`);
    const txReceipt = await sendEvmRawTransaction(rawTransactionTransfer);
    console.log("tx id:", txReceipt.transactionHash);
  }

runExample();

TIP: For more details, see Examples

Other operations

Liquidity pools operations

SDK supports operation with Liquidity Pools
For more details, see Examples

Transaction builder

Approve Transaction

SDK method bridge.rawTxBuilder.approve can be used to create approve Transaction.

const rawTransactionApprove = await sdk.bridge.rawTxBuilder.approve(approveParams);

Send Transaction

SDK method bridge.rawTxBuilder.send can be used to create send Transaction.

const rawTransactionSend = await sdk.bridge.rawTxBuilder.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,
  sourceToken,
  destinationToken
);

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,
  sourceToken,
  destinationToken
);

Getting the amount of gas fee

The SDK method getGasFeeOptions allows to retrieve information about the available methods to pay the gas fee, as well as the amount of gas fee needed to complete a transfer on the destination chain. Gas fee is paid during the send operation and can be paid either in the source chain's currency or in source tokens.

The method returns an object with two properties:

• native: The amount of gas fee, denominated in unit of the source chain currency (e.g. wei for Ethereum).
• stablecoin: (optional) The amount of gas fee, denominated in unit of the source token. If this property is not present, it indicates that the stablecoin payment method is not available.

const {native, stablecoin} = await sdk.getGasFeeOptions(
  usdtOnEthToken, // from ETH
  usdtOnTrxToken, // to TRX
  Messenger.ALLBRIDGE
);
console.log(native);
// Output:
// {
//   int: "10000000000000000",
//   float: "0.01" // (0.01 ETH)
// }
console.log(stablecoin);
// Output:
// {
//   int: "10010000",
//   float: "10.01" // (10.01 USDT)
// }

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(
  sourceToken,
  destinationToken,
  Messenger.ALLBRIDGE
);

Known Audit Warning

Due to a dependency on @solana/web3.js, the package bigint-buffer@1.1.5 is present in the dependency tree and marked as vulnerable. This vulnerability is not exploitable in the context of this SDK, and no sensitive or user-facing code depends on bigint-buffer directly.

We are monitoring upstream packages for an official resolution.