Website • Documentation • SDK TS doc

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. Choose a messenger
    • CCTP and CCTP V2
    • OFT
    • X_RESERVE
    • LIFI_INTENTS
  • 4.1 Approve the transfer of tokens
  • 4.2 Send Tokens
  • Full example
• Other 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 maximum amount of extra gas
  • Getting the average transfer time
• Known Audit Warning

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);

SUI: Sui full nodes no longer serve JSON-RPC, so the SUI url must be the gRPC-web (sui.rpc.v2) base url of a full node, e.g. https://fullnode.mainnet.sui.io.

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 {tokens, chainId, name, oftBridgeAddress} = supportedChains[ChainSymbol.ETH];
// Choose one of the tokens supported on ETH
const usdcOnEthToken = tokens.find(token => token.symbol === 'USDC');

Every token is returned as a TokenWithChainDetails object. Besides the general token data (symbol, name, decimals, tokenAddress) it contains everything needed to find out which messengers the token can be sent with:

3. Choose a messenger

Every transfer is executed by one of the supported messengers (bridging protocols). The messenger is a required parameter of all route-dependent SDK methods: bridge.checkAllowance, bridge.rawTxBuilder.approve, bridge.rawTxBuilder.send, getAmountToBeReceived, getAmountToSend, getGasFeeOptions, getExtraGasMaxLimits and getAverageTransferTime.

Messenger.ALLBRIDGE and Messenger.WORMHOLE are deprecated and must not be used.

import {isLifiIntentsRouteSupported, Messenger} from "@allbridge/bridge-core-sdk";

function getAvailableMessengers(sourceToken: TokenWithChainDetails, destinationToken: TokenWithChainDetails): Messenger[] {
  const messengers: Messenger[] = [];
  if (sourceToken.cctpAddress && destinationToken.cctpAddress) {
    messengers.push(Messenger.CCTP);
  }
  if (sourceToken.cctpV2Address && destinationToken.cctpV2Address) {
    messengers.push(Messenger.CCTP_V2);
  }
  if (
    sourceToken.oftId &&
    sourceToken.oftId === destinationToken.oftId &&
    sourceToken.oftBridgeAddress &&
    destinationToken.oftBridgeAddress
  ) {
    messengers.push(Messenger.OFT);
  }
  if (sourceToken.xReserve && destinationToken.xReserve) {
    messengers.push(Messenger.X_RESERVE);
  }
  if (isLifiIntentsRouteSupported(sourceToken, destinationToken)) {
    messengers.push(Messenger.LIFI_INTENTS);
  }
  return messengers;
}

getAverageTransferTime returns null when the messenger is not available between the source and destination chains, so it can be used as an additional check. If a messenger is not supported for the chosen route, the SDK methods throw CCTPDoesNotSupportedError, OFTDoesNotSupportedError, LifiIntentsDoesNotSupportedError or SdkError (for xReserve).

TIP: For more details, see Example

CCTP and CCTP V2

Native USDC transfers through Circle CCTP. The bridge contract that has to be approved is token.cctpAddress (CCTP) or token.cctpV2Address (CCTP V2). The fee is a share of the transferred amount, see token.cctpFeeShare / token.cctpV2FeeShare; use getAmountToBeReceived to get the exact result.

Examples: EVM (CCTP), EVM (CCTP V2), EVM (CCTP V2, gas fee paid with stablecoin), Solana, Sui

OFT

Transfers through LayerZero OFT. Tokens on different chains are linked by token.oftId. The bridge contract that has to be approved is oftBridgeAddress of the source chain. The fee share is provided by the Allbridge Core API for the route, use getAmountToBeReceived to get the exact result.

Examples: Tron, Tron (gas fee paid with stablecoin)

X_RESERVE

Transfers through the xReserve protocol. The route configuration is in token.xReserve: bridgeAddress is the contract that has to be approved, feeShare and feeConst describe the fee. Because of the constant part of the fee there is a minimum transfer amount; getAmountToBeReceived throws an SdkError with the minimum amount if the amount is too low. Extra gas is not supported by this messenger: getExtraGasMaxLimits returns zero limits.

Examples: Stacks

LIFI_INTENTS

Transfers through LI.FI Intents, a solver marketplace: the tokens are locked in an escrow on the source chain and a solver pays the recipient on the destination chain within seconds. Native tokens (e.g. ETH) can be sent as well. The route configuration is in token.lifiIntents: bridgeAddress is the Allbridge LifiIntentsBridge contract that has to be approved (a native token needs no approval), destinations lists the destination tokens per chain. Amounts are market-priced quotes from the Allbridge Core API, not a deterministic fee: getAmountToBeReceived / getAmountToSend request a quote, sdk.lifiIntents.getQuote returns it with the Allbridge fee. The quote errors are typed: LifiIntentsAmountTooLowError (minAmount), LifiIntentsAmountTooHighError (maxAmount), LifiIntentsNoQuoteError and LifiIntentsQuoteError.

The order transaction is built by the Core API and is short-lived (the quote is valid for 40-120 s, the transaction reverts after about 10 min), so approve first and create the order right before signing:

const messenger = Messenger.LIFI_INTENTS;
if (!(await sdk.bridge.checkAllowance({token: sourceToken, owner: fromAddress, amount, messenger}))) {
  const rawTransactionApprove = await sdk.bridge.rawTxBuilder.approve({token: sourceToken, owner: fromAddress, messenger});
  // sign and send rawTransactionApprove, wait for it to be mined
}
// creates the order and returns its LifiIntentsBridge call; order.orderId is the transfer id for getTransferStatus
const {rawTransaction, order} = await sdk.lifiIntents.buildSendTransaction({
  amount,
  fromAccountAddress: fromAddress,
  toAccountAddress: toAddress,
  sourceToken,
  destinationToken,
});
// sign and send rawTransaction at once

bridge.rawTxBuilder.send with Messenger.LIFI_INTENTS does the same and returns only the raw transaction. The gas fee is zero and extra gas is not supported by this messenger: getExtraGasMaxLimits returns zero limits. An unfilled order is refunded to the sender by LI.FI (getTransferStatus reports refunded); the Allbridge fee is not refunded.

From Solana no approval is needed: buildSendTransaction returns an unsigned VersionedTransaction (RawBridgeSolanaTransaction) of the Allbridge lifi-intents-bridge program with the sender as the fee payer and a fresh blockhash, so sign and send it at once. The recipient on Solana is the wallet (owner) address: the solver pays its associated token account.

To Solana the solver does not create that account: an order to a recipient without it is not filled and is refunded. Check it before sending and ask the recipient to create the account first (a native SOL transfer needs none):

if (!(await sdk.utils.sol.hasTokenAccount(toAddress, destinationToken))) {
  // warn: the recipient has no token account for destinationToken on Solana
}

Examples: EVM, Solana

4.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. The spender depends on the messenger, so the messenger parameter is required.

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

Use bridge.checkAllowance to find out whether the approval is already enough:

const isApproved = await sdk.bridge.checkAllowance({
  token: sourceToken,
  owner: accountAddress,
  amount: "1.01",
  messenger: Messenger.CCTP_V2,
});

4.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.CCTP_V2,
});

Full example

Send USDC from ETH chain to ARB chain using CCTP V2

import {
  AllbridgeCoreSdk,
  ChainSymbol,
  Messenger,
  nodeRpcUrlsDefault,
  RawEvmTransaction,
} from "@allbridge/bridge-core-sdk";
import * as dotenv from "dotenv";
// Utils method
// For more details, see Examples (https://github.com/allbridge-io/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("ARB_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.ARB];
  const destinationToken = ensure(destinationChain.tokens.find((tokenInfo) => tokenInfo.symbol === "USDC"));

  const amount = "1.01";
  const messenger = Messenger.CCTP_V2;

  //check if sending tokens already approved
  if (!(await sdk.bridge.checkAllowance({ token: sourceToken, owner: fromAddress, amount, messenger }))) {
    // authorize the bridge to transfer tokens from sender's address
    const rawTransactionApprove = (await sdk.bridge.rawTxBuilder.approve({
      token: sourceToken,
      owner: fromAddress,
      messenger,
    })) 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,
  })) 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

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 of the chosen messenger.

const amountToBeReceived = await sdk.getAmountToBeReceived(
  amountToSend,
  sourceToken,
  destinationToken,
  Messenger.CCTP_V2
);

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,
  Messenger.CCTP_V2
);

TIP: For more details, see Example

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, in source tokens or in ABR tokens (see gasFeePaymentMethod in SendParams).

The method returns an object with the following 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.
• abr: (optional) The amount of gas fee, denominated in unit of the ABR token. Present only if the source chain has abrPayer and the chosen messenger is available for ABR payments.

const {native, stablecoin, abr} = await sdk.getGasFeeOptions(
  usdcOnEthToken, // from ETH
  usdcOnArbToken, // to ARB
  Messenger.CCTP_V2
);
console.log(native);
// Output:
// {
//   int: "10000000000000000",
//   float: "0.01" // (0.01 ETH)
// }
console.log(stablecoin);
// Output:
// {
//   int: "10010000",
//   float: "10.01" // (10.01 USDC)
// }

Getting the maximum amount of extra gas

Extra gas is an additional amount of the destination chain currency that can be delivered together with the transfer (see extraGas in SendParams). SDK method getExtraGasMaxLimits returns the maximum extra gas value for every gas fee payment method, as well as the maximum amount that can be received on the destination chain.

const extraGasLimits = await sdk.getExtraGasMaxLimits(
  sourceToken,
  destinationToken,
  Messenger.CCTP_V2
);

TIP: For more details, see Example

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. Returns null if the messenger is not supported for the route.

const transferTimeMs = sdk.getAverageTransferTime(
  sourceToken,
  destinationToken,
  Messenger.CCTP_V2
);

Known Audit Warning

Due to a dependency on @solana/web3.js, the package [email protected] 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.