@avalabs/bridge-unified

A package for routing tokens from Chain A to Chain B, and unifying multiple bridge tools into one.

What is this?

The bridging ecosystem is complex. There are often multiple tools that can be used to bridge tokens from one chain to another, and sometimes to get a token from chain A to C you need to use multiple bridging tools and route through chain B first. This package simplifies that process by creating the Unified Bridge API, a standard interface for bridging tokens from one chain to another without having to worry about the underlying tools or the underlying intermediary chains.

These are the bridges we currently support:

• CCTP - preferred for brdiging USDC between Ethereum and Avalanche C-Chain. See the bridges/cctp folder.

Future bridges we plan to support:

• Avalanche Bridge - is capable of transferring a fixed list of tokens between Ethereum and Avalanche C-Chain.
• Teleporter - for moving tokens between subnets.
• Cross-Chain Transfer - for moving tokens between the three Avalanche Primary Network chains (X-Chain, C-Chain, and P-Chain).

Getting Started

  npm install @avalabs/bridge-unified
  # or
  yarn add @avalabs/bridge-unified
  # or
  pnpm add @avalabs/bridge-unified

Usage

import { createUnifiedBridgeService, getEnabledBridgeServices, Environment, BridgeTransfer } from '@avalabs/bridge-unified';

const environment = Environment.TEST;
// use all available bridges
const disabledBridgeTypes = []

// fetch all available bridge services
const enabledBridgeServices = await getEnabledBridgeServices(environment, disabledBridgeTypes);

// create a new service for a given environment and list of bridge services
const unifiedService = createUnifiedBridgeService({
  environment,
  enabledBridgeServices
});

// get the list of supported assets, grouped by caip2 (https://chainagnostic.org/CAIPs/caip-2) chain IDs
const assets = await unifiedService.getAssets()

// get the bridge fee(s) of the provided transfer
const fees = await unifiedService.getFees({...})

// start a new bridge transfer and store its state
const bridgeTransfer = await unifiedService.transferAsset({...})

// create an update listener for tracking
const updateListener = (transfer: BridgeTransfer) => {
  console.log(transfer)
}

// start tracking the transfer's state. whenever the state changes, it will call the provided `updateListener`
const { cancel, result } = await unifiedService.trackTransfer({bridgeTransfer, updateListener, ...})

// immediatelly stops tracking and rejects the tracker's promise
// cancel()

// wait for the transfer to finish and get its final state
const finalizedBridgeTransfer = await result

API

getEnabledBridgeServices(environment, disabledBridgeTypes);

Type: (environment: Environment, disabledBridgeTypes: BridgeType[]) => Promise<BridgeServicesMap>

Returns all available bridge services for a given environment (excluding disabledBridgeTypes). Any bridge service which fails to initialize will be absent from this returned value.

environment

Type: Environment

Defines if the bridge service should use testnet or mainnet.

disabledBridgeTypes

Type: BridgeType[]

Disables the integration of the provided BridgeTypes.

enabledBridgeServices

Type: BridgeServicesMap => Map<BridgeType, BridgeService>

This includes all the bridge services which were initialized successfully, to pass to createUnifiedBridgeService.

createUnifiedBridgeService({ environment, enabledBridgeServices })

Returns a new unifiedBridgeService for the given environment and enabledBridgeServices map.

unifiedBridgeService

Contains all the required properties and methods to prepare, initiate or track a bridge transfer. Automatically picks the right (enabled) bridge integration to use based on the provided params.

{
  environment, // the provided Environment during initialization
  getAssets,
  getFees,
  estimateGas,
  canTransferAsset,
  transferAsset,
  trackTransfer,
}

getAssets

Type: () => Promise<ChainAssetMap>

Returns the aggregated list of assets supported by the enabled bridges grouped by caip2 chain IDs.

getFees

Type: (params: FeeParams) => Promise<AssetFeeMap>

Calculates and returns the bridge fees in tokenAddress - amount pairs for a given bridge transfer.

estimateGas

Type: (params: TransferParams) => Promise<bigint>

Estimates the gas cost of a specific transfer.

getMinimumTransferAmount

Type: (params: FeeParams) => Promise<bigint>

Calculates and returns the minimum transfer amount for a given bridge transfer.

transferAsset

Type: (params: TransferParams) => Promise<BridgeTransfer>

Starts a new bridge transfer, executing every required step in a single call. Transactions signing is done by a custom sign callback. The custom sign implementation may use their own solution or the default dispatch callback to submit the transaction to the network. Returns a BridgeTransfer containing all the (known) initial values such as: environment, addresses, amount, fee, transaction hash, required and actual block confirmation counts, etc.

trackTransfer

Type: (params: TrackingParams) => ({cancel, result})

Tracks the given BridgeTransfer's progress and invokes the provided listener callback whenever a change happens.

cancel

Type: () => void

If it's still pending, rejects the tracker's promise (result) immediatelly and breaks its loop under the hood.

result

Type: Promise<BridgeTransfer>

Resolves with the finalized BridgeTransfer (if not canceled before).