Skip to main content

Single Transaction Bridging

note

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

Single Transaction Bridging mode involves a single transaction on the sending chain and no transaction on the destination chain. This single transaction encompasses both swapping and bridging. For an ERC-20 token being bridged, the user would need to allow it's spending on the sending chain in addition to the single transaction to swap and bridge. Single Transaction Bridging flow would limit the number of token options a user can receive on the destination chain, since these would just be tokens supported by bridges.

How to integrate Single Transaction Flow?​

  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.

    NOTE : For Single Transaction Flow, singleTxOnly flag needs to be set to true on both token-list endpoints.

  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.

    NOTE : The singleTxOnly flag in /quote needs to be set to true for quotes with only one user transaction to bridge.

    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.

    A breakdown of the response to the /quote endpoint output:

    • 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.

      userTxTypeDescription
      approveToken approval transaction
      fund-movrIndicates a Swap+Bridge or only Bridging transaction
      claimUser transaction to claim funds on destination chain
      dex-swapTransaction for swapping tokens
      signUsers sign a message with intent to bridge

    • 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 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. Once the user has chosen the route they want to bridge with, for the transaction to go through, Socket contracts will need user approval to spend the tokens. Hence, allowance of token spending needs to be checked. 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.

    info

    This is only relevant to ERC20 tokens. approvalData returns null for native tokens

  5. If the Socket contract does not have approval to spend a users' sending token, the approvalData fetched from the quote is to be used to make a smart contract method call on the frontend to give Socket contracts approval to spend user tokens on behalf of user. Method to use from popular frameworks:

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

  6. Once the contract has approval to spend a users' sending token, the callData for the route needs to be fetched from the /server/build-tx endpoint. This is followed by a smart contract method call on the frontend, which is explained in the Single Transaction Bridging Example page.

  7. The status of the transaction can be tracked by polling the Socket Bridge Status API. The status of the transaction can be checked by calling the /bridge-status endpoint.