Bridge and swap

The SDK offers convenient functions to make bridge and swaps that handle all the low level logic of fetching/committing quotes and making the correct blockchain transactions needed.

Introduction

Cross chain swaps in general work the same way as a standard bridge:

1. Fetch bridge config and additionally also a new config for supported swap tokens.
2. Generate a swap quote.
3. Commit the quote.
4. Deposit funds into the bridge contract.
5. Rhino handles the swap and bridge logic under the hood and sends the funds to the recipient on the destination chain.

Making cross chain swaps

To make cross chain swaps you can use the same bridge or prepareBridge functions. The only difference is:

• Instead of the token field, a swap requires tokenIn and tokenOut fields
• The type: 'bridgeSwap' to indicate that a swap should be performed

const bridgeResult = await rhinoSdk.bridge({
  type: 'bridgeSwap',
  amount: '100',
  tokenIn: SupportedTokens.USDT,
  tokenOut: 'agEUR',
  chainIn: SupportedChains.ARBITRUM_ONE,
  chainOut: SupportedChains.BASE,
  depositor: 'DEPOSITOR_ADDRESS',
  recipient: 'RECIPIENT_ADDRESS',
  mode: 'pay',
}, {
  getChainAdapter: chainConfig =>
    getEvmChainAdapterFromPrivateKey(
      'YOUR_PRIVATE_KEY',
      chainConfig,
    ),
})

Swap quotes

When using the prepareBridge function with swaps or using the checkQuote hook, you will receive a quote object that contains familiar properties to a bridge only transaction. However in the edge case that the swap is being facilitated by an external aggregator then there will be additional properties in the response such as:

• bridgePayAmount: The amount of tokenIn that will be paid
• bridgePayAmountUsd: The USD value of the pay amout
• minReceiveAmount: The minimum amount of tokenOut that will be received on the destination chain after considering slippage.
• minReceiveAmountUsd: The USD value of the minimum receive amount
• usdPriceTokenIn: The current USD price of tokenIn
• usdPriceTokenOut: The current USD price of tokenOut

Failed swaps

The main reasons that a swap fails are:

1. Unsupported Quote Mode (mode: "receive")
Returns HTTP 422 (Receive mode is not supported for the selected tokens)

This error is generated where receive mode is incompatible with the chain and token pairings provided. To solve this, change the chain and tokens, or select pay mode instead.

2. Amount Below Minimum Threshold / Fees Exceed Output
Returns HTTP 422 or 500

This error is generated when the amount being sent on the source chainis below Rhino’s minimum threshold or when the amount that will be received on the destination chain is below the applicable fees. To solve this, send a larger amount.

3. Unsupported Route or Unconfigured Token Pair
Returns HTTP 422 (No common aggregators found or Operation unavailable at this time)

This error is generated when the requesting pairs not supported. This could be because the token does not exist on the chain e.g tokenIn = USDT and chainIn = Base, or where the token/chain is not supported through the Rhino.fi feature e.g chainIn = BITCOIN for a bridge transaction rather than an Smart Deposit Address related transaction. To solve this, check the supported token and chain pairings in the Bridge and Smart Deposit Address config.

Any failed swaps will either be returned to the given refundAddress or will be manually refunded via the Rhino.fi compliance team.

N.B where a swap fails then the bridge function will return an error with type SwapFailed that contains metadata about the refund (refund chain, token, amount and transaction hash), and the onBridgeStatusChange hook will also first report swap-failed and then follow up with failed-swap-refunded once the refund has been processed.