feat: split route multi hop swap message

Background

Currently, we only support multi-hop swaps that do not allow for route splitting within the same denom pair.

Splitting swaps across multiple pools for the same token pair can be beneficial for several reasons, primarily relating to reduced slippage, price impact, and potentially lower fees. Here's a detailed explanation of these advantages:

Reduced slippage: When a large trade is executed in a single pool, it can be significantly affected if someone else executes a large swap against that pool.

Lower price impact: when executing a large trade in a single pool, the price impact can be substantial, leading to a less favorable exchange rate for the trader. By splitting the swap across multiple pools, the price impact in each pool is minimized, resulting in a better overall exchange rate.

Improved liquidity utilization: Different pools may have varying levels of liquidity, fees, and price curves. By splitting swaps across multiple pools, the router can utilize liquidity from various sources, allowing for more efficient execution of trades. This is particularly useful when the liquidity in a single pool is not sufficient to handle a large trade or when the price curve of one pool becomes less favorable as the trade size increases.

Potentially lower fees: In some cases, splitting swaps across multiple pools may result in lower overall fees. This can happen when different pools have different fee structures, or when the total fee paid across multiple pools is lower than the fee for executing the entire trade in a single pool with higher slippage.

Suggested Design

The core of our smart router is going to be implemented in frontend. However, we still want to expose an interface for the frontend to interact with via single transaction. There are several options to implementing this with different trade-offs. The trade-offs are discussed next in this section.

The following are the parameters that we aim to optimize for:

Gas efficiency: minimize gas costs for the user so that we can design a cost-effective router.
Upgradability: allow for easy upgrades of the logic.
API Breakage: we want to design it in such as to minimize the likelihood of being locked into a single API.
User experience:: easy for clients to use and interact with, especially, our main client - frontend.
Security: it should be implemented in such a way as to minimize the likelihood of exploits coming up.

Option 1: Implement a new on-chain swap message with support for split routes and multi-hop.

Pros:

Quickest and simplest option to implement

Cons:

Once implemented, this API will not be simple to deprecate
Most changes are state-breaking, requiring a chain upgrade. On the other hand, a contract can be easily upgraded w/o chain upgrade.

Option 2: Implement a Cosmwasm contract with split route functionality.

General Pros:

Easy upgradeability, do not require chain upgrades
Easier to deprecate and change APIs

General Cons:

Additional gas costs.
- MsgExecute charges a fixed gas cost here
- Reply messages have additional costs charged here

2.1 Completely New Contract

Pros:

Implementation flexibility and opportunity to customize it as needed

Cons:

Another swap router contract

2.2 Integrate Existing Swap Router

Pros:

Avoid fragmenting contracts that perform similar tasks

Cons:

Dependency on separate systems
- The existing contract is currently tailored for cross-chain swaps. As a result, if we make the existing contract more general, it will remove the flexibility from customizing the contract for cross-chain swaps on a needs basis.

General Details

Suggested message structure

# particularly for balancer pools & large trades, split-swapping through high liquidity pools will achieve a better price
{
  routes [
    {
      pools: [
        {
          pool_id: 1
          token_out_denom: "ujuno"
        },
        {
          pool_id: 6
          token_out_denom: "uusdc"
        }
      ]
      tokenInAmount: Int
    },
    {
      pools: [
        {
          pool_id: 4
          token_out_denom: "ustars"
        },
        {
          pool_id: 3
          token_out_denom: "ujuno"
        },
        {
          pool_id: 2
          token_out_denom: "uusdc"
        }
      ]
      tokenInAmount: Int
    }
  ],
  tokenInDenom: "uosmo",
  tokenOutDenom: "uusdc",
  minOutAmount: Int
}

# OSMO/DAI (balancer) & OSMO/DAI (CL)
{
  routes [
    {
      pools: [
        {
          pool_id: 1
          token_out_denom: "udai"
        },
      ]
      tokenInAmount: Int
    },
    {
      pools: [
        {
          pool_id: 4
          token_out_denom: "udai"
        },
      ]
      tokenInAmount: Int
    }
  ],
  tokenInDenom: "uosmo",
  tokenOutDenom: "udai"
  minOutAmount: Int
}
# at the end minOutAmount is checked (for slippage)

Sources

Uniswap split route handling: https://github.com/Uniswap/universal-router/blob/a88bc6e15af738b61d7bee8feb7df8d2a6e26347/contracts/modules/uniswap/v3/V3SwapRouter.sol#L89-L112
Building blocks for a dex router: https://medium.com/@ValveFinance/building-blocks-for-dex-router-construction-analysis-acc03b9f15d8

Acceptance Criteria

design determined
implemented

osmosis-labs / osmosis