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 source 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 endpoint, representing tokens that can be sent from the sending chain and a /to-token-list endpoint, representing tokens that can be received on the destination chain. These two lists need to be separately shown to a user.

  3. 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 with amounts of each 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. For more details, refer to /quote endpoint.

  4. 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 the /route/start endpoint.
    • Setting includeFirstTxDetails to true returns the transaction data for the first transaction in the response of the POST request to the /route/start endpoint.
    • Alternatively, it can be set to false and no transaction data will be returned. In this case, /route/build-next-tx endpoint can be called which will return the transaction data for the first transaction.

  5. 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. This is only relevant to ERC20 tokens. approvalData returns null for native tokens.

      The allowance can be checked by calling the check-allowance endpoint. The approvalData param in the quote response has all the data to pass as query params to the check-allowance endpoint.

      For obtaining user approval, you can alternatively use the /approval/build-tx endpoint to create the necessary transaction data.

      info

      userTxIndex and activeRouteId must 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,
      });

  6. Checking the Transaction Status:

  7. Building the next transaction data