☑️Transaction Prerequisites

This page describes the concept of Transaction Prerequisites and how to handle it in Rango API workflow.

Transaction Prerequisites are blockchain specific setup transactions that must be completed before a swap can execute successfully. Depending on the source or destination blockchain and asset type, users may need to sign/authorize another transaction before the main transaction is submitted onchain.

Make sure your implementation checks and handles all of the prerequisites provided by Rango API, and do not consider only the source blockchain network and source wallet. In some cases, such as bridging into non-native Stellar or XRPLedger tokens, you must provide a trustline for the desintation token (obviously, on the destination blockchain network) before initiating the bridge/swap on the source token.

The list of possible prerequisites are given in the sections below.

Stellar Change Trust Prerequisite

When bridging/swapping to SAC tokens on the Stellar network (except for the native XLM) the receiving wallet must have enough trust in that token. This can be done via a Change Trust Operation on the Stellar network.

In such cases, Rango provides a prerequisite in response of /swap endpoint which must be handled before broadcasting the main bridge or swap transaction. Example EVM Transaction with Stellar ChangeTrust prerequisite when briding from Evm chains to Stellar network.

{
   ..., // other swap endpoint response fields
   "tx": {
      "blockChain": "ARBITRUM",
      "from": "0x....",
      "to": "0x...",
      "spender": "0x...",
      "data": "0x...",
      "value": 1000000000000000000,
      "prerequisites": [
         {
            "code": "USDC",
            "issuer": "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
            "value": "922337203685.4775807",
            "wallet": "G....." // user's stellar wallet address
         }
      ]
   }
}

In this case, you must make sure the required trust-line for this Stellar Asset is ensured on the stellar blockchain network for the user. If it is not ensured, you must ask the user to sign a ChangeTrust Operation for this asset and broadcast it to the Stellar network before signing and broadcasting the EVM transaction.

XRP Ledger Change Trust Prerequisite

Similar to the Stellar Trust Line requirement, receiving tokens on XRPLedger requires a trust between the receiving wallet and the issuer of the token. This can be done by signing and broadcasting a TrustSet transaction on the XRP Ledger network.

In such cases, Rango provides a prerequisite in response of /swap endpoint which must be handled before broadcasting the main bridge or swap transaction. Example EVM Transaction with XRPLedger Change Trust prerequisite when briding from Evm chains to XRPL network.

{
   ..., // other swap endpoint response fields
   "tx": {
      "blockChain": "ARBITRUM",
      "from": "0x....",
      "to": "0x...",
      "spender": "0x...",
      "data": "0x...",
      "value": 1000000000000000000,
      "prerequisites": [
         {
            "currency": "RLUSD",
            "issuer": "rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De",
            "value": "1000000000",
            "wallet": "r..." // user's xrpl wallet address
         }
      ]
   }
}

In this case, you must make sure the required trust for this asset is ensured on the XRPL blockchain network for the user. If it is not ensured, you must ask the user to sign a TrustSet Transaction for this asset and broadcast it to the XRPL network before signing and broadcasting the EVM transaction.