Skip to main content

Multi Transaction Bridging

note

Note : Additional information about integration of API endpoints is specified on the endpoint page. To see a visual example of the flow mentioned below, check out the Bungee App.

Multi Transaction Bridging involves 2 or more transactions for the user either on the sending or destination chain. Multi Transaction Bridging on the sending chain encompasses both swapping and bridging. While on the destination chain generally involves a transaction for swapping assets or claiming them. For an ERC-20 token being bridged, the user would need to allow it's spending on the sending chain. Likewise, for a swap transaction it needs to be approved again. Multi Transaction Bridging truly enables ANY-to-ANY cross-chain asset movement.

Integrating with Multi Transaction Bridging flow is similar to Single Tx Bridging, except for how we fetch the quote and make a request for bridging data.

How to integrate Multi Transaction Bridging?​

  1. The UI first needs to be populated with the sending and destination chains. The user first selects these, which determine the tokens that can be bridged. Supported Chains Endpoint

  2. Once the user has selected their sending and destination chains, the token list needs to be populated for them to choose sending and receiving tokens. Not all assets can be bridged from the sending chain and received on the destination chain. Hence, there is a from-token-list, representing tokens that can be sent from the sending chain and to-token-list, representing tokens that can be received on the destination chain. These two lists need to be separately shown to a user.

  1. Once the user has chosen the sending token and receiving token for the respective sending and destination chains, the routes between these chains needs to be fetched from the /quote endpoint endpoint with amount of sending token. These routes need to be shown to the user. These routes also consider any swaps involved.
info

For receiving assets on a different address on the destination chain, the recipient param needs to be assigned to the receiving address. If it is not passed in the request, the sender is considered as recipient.

  • Each route for bridging tokens between the chains is an object in the routes array
  • The userTxs array in each route from quote includes all the transactions involved in the route and userTxType can be used to infer the type of transaction. This data can be used to break down and display components of the route on the UI. All userTxType can be found here.
  • In a swap + bridge transaction on the sending chain, the transaction type is fund-movr and it encompasses the dex swap and bridging transaction metadata in the steps array nested in the route. In some routes such as the one involving the Polygon Native bridge, the dex swap needs to be performed first by the user and then bridged as the Polygon Native bridge requires only wallet users to burn the token. In such cases, a separate transaction with type dex-swap is returned.
  • The steps array nested in a route just returns the meta steps of a transaction
  • bridgeRouteErrors returned in the quote response indicates the reason for a given bridge not returning a route for selected chain/token/amount input. The error codes can be used to show users appropriate messages on the UI in case no routes are found.

quote.md

  1. Start a trip
  • Trips are a bridging journey from source to destination chain on a given route.
  • Pass the route object in the body and make a POST request to /route/start.
  • Setting includeFirstTxDetails to true returns the Tx data for the first transaction in the response of /route/start
  • Alternatively, it can be set to false and no transaction data will be returned. In this case, /route/build-next-tx can be called which will return the transaction data of the first tx.
  1. Using received transaction data, checking status & fetching next transaction data

  • The returned transaction data has txData and txTarget which can be used to send a bridging transaction.

  • IMPORTANT: If the approvalData object returns an object, then the user's token allowance needs to be checked and if it is not sufficient, user has to give token approval first.

  • approvalData is null for native tokens.

  • Endpoints:

  • NOTE : userTxIndex and activeRouteId needs to be stored somewhere as it is required in subsequent API calls**.** On the user's browser, it is recommended to store it in the local storage.

  • Once the approval step has completed, the main bridging transaction needs to be sent by the user. txTarget & txData from the response need to be used here.

const tx = await signer.sendTransaction({
  to: apiReturnData.result.txTarget,
  data: apiReturnData.result.txData,
});
  1. Checking Transaction Status:
  1. Building the next transaction data
  • /route/build-next-tx endpoint returns the transaction data for the next tx. However, as mentioned earlier, it cannot be executed until the /prepare API returns ready status.
  • Once it returns ready, the next transaction can be executed. When /route/prepare endpoint returns completed status, there is not further transaction to be executed and the route can be marked as fully done.
  • Its status can be tracked using the /prepare API.