Single Transaction Bridging

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. 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.
For Single Transaction Flow, singleTxOnlyflag needs to be set to true for both token lists
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.
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
Token approval transaction
Indicates a Swap+Bridge or only Bridging transaction
User transaction to claim funds on destination chain
Transaction for swapping tokens
Users sign a message with intent to bridge
NOTE : The singleTxOnly flag in /quote needs to be set to true
  • 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.
4. Once the user has chosen the route they want to bridge with, for the transaction to go through, Socket contracts need approval to spend users' 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 has all the data to pass as query params to the check-allowance endpoint.
NOTE : This is only relevant to ERC20 tokens. approvalData is returned 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.
Alternatively, the approval build-tx endpoint can be called to generate the transaction data to get approval from the user.
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 page below.
7. The status of the transaction can be tracked by polling the Socket Bridge Status API