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, Environment, BridgeTransfer } from '@avalabs/bridge-unified';

// create a new service for an environment
const unifiedService = createUnifiedBridgeService({
  environment: Environment.TEST,
});

// init the service, fetch and setup its configs
await unifiedService.init();

// 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

createUnifiedBridgeService({ environment, disabledBridgeTypes? })

Returns a new unifiedBridgeService for the given environment, using all supported bridge integrations by default. Individual bridges can be turned off via the disabledBridgeTypes array.

environment

Type: Environment

Defines if the bridge service should use testnet or mainnet.

disabledBridgeTypes

Type: BridgeType[] | undefined

Disables the integration of the provided BridgeTypes.

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
  bridges, // the list of enabled bridge integrations
  init,
  updateConfigs,
  getAssets,
  getFees,
  transferAsset,
  trackTransfer,
}

init

Type: () => Promise<void>

Initializes the unified service by attempting to fetch the configurations of the enabled bridges.

updateConfigs

Type: () => Promise<void>

Attempts to fetch the configurations of the enabled bridges.

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.

transferAsset

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

Starts a new bridge transfer, executing every required step in a single call. Transactions signing is done by either the provided sourceProvider or a custom sign callback. Clients using their 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).