MultiHop Swap

Explanation of the MultiHopSwap transaction

Overview

Multihop swap provides a swapping mechanism to achieve better prices by routing through a series of pools.Rather than swapping directly from TokenA to TokenB a user may be able to get a better price if they swap from TokenA to TokenC to TokenD to TokenB. When performing a multohop swap the user provides an array of Denoms that they would like to swap through. For example if the user supplied the following array of Denoms [“TokenA”, “TokenC”, “TokenD”, “TokenB”], the following swaps would be performed: Swap TokenA for TokenC; Swap TokenC for TokenD; Swap TokenD for TokenB.

The underlying swaps (hops) within a Multihop Swap are performed using the same mechanism as the basic Swap function. Unlike the the basic swap however, the complete amount of specified by AmountIn will always be used. If there is insufficient liquidity in a route to swap 100% of the AmountIn the route will fail. Additionally, rather than supply an explicit argument for TokenIn the first denom in each Routes array is used as the TokenIn.

MultihopSwap also allows users to set an ExitLimitPrice. For a route to succeed the final conversion rate for the entry token and ExitToken must be less than the ExitLimitPrice. For a Multihop swap to succeed the following test must be satisfied:

$ExitLimitPrice <= \frac{AmountOfExitToken}{ AmountIn}$

Multihop swap also allows users to supply multiple different routes. By default, the first route that does not run out of liquidity, hit the ExitLimitPrice or return an error will be used. Multihop swap also provides a PickBestRoute option. When PickBestRoute is true all routes will be run and the route that results in the greatest amount of the resulting TokenOut for at final hop will be used. This option to dynamically pick the best route at runtime significantly reduces the risk of front running.

Multihop Swap Message

message MultiHopRoute {
    repeated string hops = 1;
}

message MsgMultiHopSwap {
    string creator = 1;
    string receiver = 2;
    repeated MultiHopRoute routes = 3;
    string amount_in = 4 [
        (gogoproto.moretags) = "yaml:\"amount_in\"",
        (gogoproto.customtype) = "github.com/cosmos/cosmos-sdk/types.Int",
        (gogoproto.nullable) = false,
        (gogoproto.jsontag) = "amount_in"
    ];
    string exit_limit_price = 5 [
        (gogoproto.moretags) = "yaml:\"exit_limit_price\"",
        (gogoproto.customtype) = "github.com/neutron-org/neutron/v2/utils/math.PrecDec",
        (gogoproto.nullable) = false,
        (gogoproto.jsontag) = "exit_limit_price"
    ];
    // If pickBestRoute == true then all routes are run and the route with the
    // best price is chosen otherwise, the first succesful route is used.
    bool pick_best_route = 6;
}

MsgMultiHopSwap

Field	Description
Creator string (sdk.AccAddress)	Account from which TokenIn is debited
Receiver string (sdk.AccAddress)	Account to which TokenOut is credited
Routes []MultiHopRoute	Array of possible routes
AmountIn sdk.Int	Amount of TokenIn to swap
ExitLimitPrice sdk.Dec	Minimum price that that must be satisfied for a route to succeed
PickBestRoute bool	If true all routes are run and the route with the best price is used

Multihop Route

Field	Description
Hops []String	Array of denoms to route through