Migrate from V2 to V3

This document provides a detailed outline of the key changes between XSwapper (V2) and YBridge (V3) and guides you through the necessary steps to migrate your system

Overview of Changes

The update from v2 to v3 introduces a couple of significant changes that will affect the way you interact with the system. Most notably, there have been changes in the naming convention of certain prefixes, a shift in how bridge fee settings are retrieved, and alterations to the semantics of certain event parameters.

Parameter Naming Convention Changes

In YBridgeV3, the prefix convention has changed as follows:

• From from- to src-: All instances where the prefix from- was used are now replaced with src-. This change affects all contract codes.

• From to- to dst-: Similarly, to- has been replaced with dst-. As with src-, this applies to all contract codes.

Bridge Fee Settings

The method for obtaining bridge fee settings in the contract has been moved:

• From Blockchain to API: In the previous version, the bridge fee settings could be retrieved directly from the blockchain. In YBridgeV3, however, these settings are no longer available on the blockchain and must be accessed via the API ( Get Fee Structure)since the fee setting is now managed by validators off-chain.

Event Changes

• event SwapRequested

event SwapRequested(uint256 _swapId, address indexed _aggregatorAdaptor, DstChainDescription _dstChainDesc, IERC20 _srcToken, IERC20 indexed _vaultToken, uint256 _vaultTokenAmount, address _receiver, uint256 _srcTokenAmount, uint256 _expressFeeAmount, address indexed _referrer);

Previously there were _xyFee and _gasFee in the place of _srcTokenAmount and _expressFeeAmount. The removal is because the fee calculation is now handled by validators off-chain.

As for the new added _srcTokenAmount is to log the original amount of the source token (not the bridge token).

The _expressFeeAmount logs the amount of express fee paid by user.

---

Migration Steps

For developers who are interacting directly with the system's interfaces and events, the following updates are important to note:

Update Parameter Names to Follow New Conventions

While the interface for initiating a swap request remains unchanged, you're suggested to update the parameter names to reflect the new prefix conventions:

• Search for any instances where -from- and -to- are used in the parameters of functions and events.

• Replace from with src and to with dst to align with the new naming convention.

  Here is an example of how to update your swap request parameters:

  struct SwapDescription {
  -   IERC20 fromToken;
  -   IERC20 toToken;
      address receiver;
      uint256 amount;
      uint256 minReturnAmount;
  }
  
  struct SwapDescription {
  +   IERC20 srcToken;
  +   IERC20 dstToken;
      address receiver;
      uint256 amount;
      uint256 minReturnAmount;
  }
  
  
  function swapWithReferrer(
      address aggregatorAdaptor,
      IDexAggregatorAdaptor.SwapDescription memory swapDesc,
      bytes memory aggregatorData,
  -   ToChainDescription calldata toChainDesc,
      address referrer
  )
  
  function swapWithReferrer(
      address aggregatorAdaptor,
      IDexAggregatorAdaptor.SwapDescription memory swapDesc,
      bytes memory aggregatorData,
  +   DstChainDescription calldata dstChainDesc,
      address referrer
  )

Monitor Swap Completion

On the Source Chain

If you are currently monitoring a swap is successfully requested by listening to event SwapRequested, you should be careful that the bridge fee amount paid could no longer be retrieved in the event.

On the Destination Chain

If you are currently monitoring the completion of a swap request on the destination chain by polling function getEverClosed, no action is required. The method for checking whether a swap is closed remain the same in YBridgeV3:

If you are currently monitoring the completion of a swap request on the destination chain by listening to event CloseSwapCompleted or event SwappedForUser, you might need to update the parameter names as mentioned above.

Update Bridge Fee Retrieval Method

• Identify any instances where bridge fee settings are being retrieved from the blockchain.

• Replace these instances with the appropriate API calls to fetch the bridge fee settings.

  Example:

  - // Old method: Retrieve bridge fees from blockchain
  - const bridgeFees = getBridgeFeesFromBlockchain();
  + // New method: Retrieve bridge fees from API
  + const bridgeFees = getBridgeFeesFromAPI();
  
  // The detail of bridge fee API can be found here:
  // *****URL GOES HERE*****