Multi Transaction Bridging
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. 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.
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.
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 amount of sending token. These routes need to be shown to the user. These routes also consider any swaps involved.
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.
  • In a swap + bridge single 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
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 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.
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 some data (as shown in response below), this means the user has to give token approval first. If the approvalData is null, then there’s no need for an approval transaction (in case of native tokens, or if Socket contracts already have approval)
  • 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
6. Checking Transaction Status :
  • Once the main bridging transaction is initiated, the /route/prepare endpoint needs to be called with the userTxIndex, activeRouteId [Returned in /route/start] & transaction hash [Hash of transaction user performed]
  • /route/prepare needs to be called periodically to check if the next transaction can be initiated. Then, route/build-next-tx can be called again which will return the transaction data for the next transaction.
  • NOTE : Approval transactions are complementary to the main bridging transaction & their hash shouldn’t be sent to the /prepare API
  • Prepare has 3 responses which can be found here
7. Building the next transaction data
  • route/build-next-tx returns the transaction data for the next tx. However, as mentioned earlier, it cannot be executed until the /route/prepare endpoint returns ready status.
  • Once it returns ready, the next transaction can be executed. When /route/prepare returns completed status, there is not further transaction to be executed and the route can be marked as fully done.
  • It's status can be tracked using the /prepare endpoint