Multi-hop Routing

Overview

There are some cases where liquidity between a pair may be low or not exist and you need to perform a multi-hop swap between two or more pairs. The Router contract enables multi-hop swap operations for Cosmos native and CW20 tokens. Swaps execute one-by-one and the last swap will return the ask token.

The initial swap will contain the offer token which determines how the contract message gets proccessed by the Router contract. If the offer token is a native token, we can send an ExecuteMsg to the Router contract directly. Otherwise (if it's a CW20 token), we will need to encode our message within a Cw20ExecuteMsg that gets sent from the address of the token we are swapping.

Native Routing

Use when the initial offer asset is a Cosmos native token.

`execute_swap_operations`

To create a native multi-hop swap, you need to execute a contract message pointing to the execute_swap_operations endpoint in the Router contract

operations is the only required parameter and holds information regarding each swap stored in a vector containing objects of type SwapOperation.

NOTE

SwapOperation is a helper enum that filters between astro_swaps and native_swaps. The former gets processed as swaps through Astroport's liquidity pools and the latter gets swapped natively (only between native assets).

This should not be confused with Native Routing. Our initial offer asset in this section is still a native asset despite our swap being an astro_swap. As an astro_swap, we are simply swapping between a native and CW20 token through an Astroport liquidity pool.

{
  "execute_swap_operations": {
    "operations": [
      {
        "astro_swap": {
          "offer_asset_info": {
            "native_token": {
              "denom": "uluna"
            }
          },
          "ask_asset_info": {
            "token": {
              "contract_addr": usdcAddress
            }
          }
        }
      }, 
      {
        "astro_swap": {
          "offer_asset_info": {
            "token": {
              "contract_addr": usdcAddress
            }
          },
          "ask_asset_info": {
            "token": {
              "contract_addr": zeroAddress
            }
          }
        }
      }
    ], 
    "minimum_receive": beliefPrice,
    "max_spread": "0.005", 
    "to": "..."
  }
}

`Coins`

Since our initial offer token is a native asset, we need to send the native token along with the transaction message.

The code in this section is an example of what a complete swap message may look like using feather.js to send Coins with our transaction.

// testnet contract addresses
const routerAddress = 'terra1na348k6rvwxje9jj6ftpsapfeyaejxjeq6tuzdmzysps20l6z23smnlv64';
const usdcAddress = 'terra14m3gtr8072t0hsefclfn50w4tdcphn66hvcu8qqf9wmtjyc9uasszqckyc'
const zeroAddress = 'terra1juvel8n8tn3m3tnkq779nktrk7hf9t2kprx7wzs7jlz0gcaqrmqq6rlre5'
const nativeRouterSwap = new MsgExecuteContract(
wallet.key.accAddress('terra'),
routerAddress,
{
  "execute_swap_operations": {
    "operations": [
      {
        "astro_swap": {
          "offer_asset_info": {
            "native_token": {
              "denom": "uluna"
            }
          },
          "ask_asset_info": {
            "token": {
              "contract_addr": usdcAddress
            }
          }
        }
      }, 
      {
        "astro_swap": {
          "offer_asset_info": {
            "token": {
              "contract_addr": usdcAddress
            }
          },
          "ask_asset_info": {
            "token": {
              "contract_addr": zeroAddress
            }
          }
        }
      }
    ], 
    "minimum_receive": beliefPrice,
    "max_spread": "0.005", 
    "to": "..."
  }
}, 
new Coins({ "uluna": "100000" })
)
const fee = new Fee(2000000, { uluna: 200000 });
// // BROADCAST TRANSACTION
const tx = await wallet.createAndSignTx({
  msgs: [nativeRouterSwap],
  fee,
  chainID: 'pisco-1',
});
const result = await lcd.tx.broadcast(tx, 'pisco-1');
console.log(result);

Optional Parameters

The execute_swap_operations endpoint takes in the following optional parameters:

minimum_receive: Minimum expected return amount
max_spread: The difference between the ask amount before and after the swap. If the swap spread exceeds the provided max limit, the swap will fail.
to: Address receiving tokens (if different from sender)

{
  "execute_swap_operations": {
    "operations": [
      {
        "astro_swap": {
          "offer_asset_info": {
            "native_token": {
              "denom": "uluna"
            }
          },
          "ask_asset_info": {
            "token": {
              "contract_addr": usdcAddress
            }
          }
        }
      }, 
      {
        "astro_swap": {
          "offer_asset_info": {
            "token": {
              "contract_addr": usdcAddress
            }
          },
          "ask_asset_info": {
            "token": {
              "contract_addr": zeroAddress
            }
          }
        }
      }
    ], 
    "minimum_receive": beliefPrice,
    "max_spread": "0.005",
    "to": "..."
  }
}

`minimum_receive` + `max_spread`

If minimum_receive is provided in combination with max_spread, the pool will check the difference between the return amount (using belief_price) and the real pool price.

minimum_receive +/- the max_spread is the range of possible acceptable prices for this swap.

{
  "execute_swap_operations": {
    "operations": [
      {
        "astro_swap": {
          "offer_asset_info": {
            "native_token": {
              "denom": "uluna"
            }
          },
          "ask_asset_info": {
            "token": {
              "contract_addr": usdcAddress
            }
          }
        }
      }, 
      {
        "astro_swap": {
          "offer_asset_info": {
            "token": {
              "contract_addr": usdcAddress
            }
          },
          "ask_asset_info": {
            "token": {
              "contract_addr": zeroAddress
            }
          }
        }
      }
    ], 
    "minimum_receive": beliefPrice,
    "max_spread": "0.005",
    "to": "..."
  }
}

Calculating `minimum_receive`

Astroport's native solution to obtain minimum_receive is to query the simulate_swap_operations endpoint from the Router contract and to pass the result of this query into the swap message.

{
  "execute_swap_operations": {
    "operations": [
      {
        "astro_swap": {
          "offer_asset_info": {
            "native_token": {
              "denom": "uluna"
            }
          },
          "ask_asset_info": {
            "token": {
              "contract_addr": usdcAddress
            }
          }
        }
      }, 
      {
        "astro_swap": {
          "offer_asset_info": {
            "token": {
              "contract_addr": usdcAddress
            }
          },
          "ask_asset_info": {
            "token": {
              "contract_addr": zeroAddress
            }
          }
        }
      }
    ], 
    "minimum_receive": beliefPrice,
    "max_spread": "0.005",
    "to": "..."
  }
}

`simulate_swap_operations`

The simulate_swap_operations endpoint takes in two parameters:

offer_amount: The amount of tokens to swap
operations: The swap operations to perform

The operations parameter takes in the same vector of SwapOperation objects that our swap message contains.

{
  "simulate_swap_operations": {
    "offer_amount": "100000",
    "operations": [
      {
        "astro_swap": {
          "offer_asset_info": {
            "native_token": {
              "denom": "uluna"
            }
          },
          "ask_asset_info": {
            "token": {
              "contract_addr": usdcAddress
            }
          }
        }
      }, 
      {
        "astro_swap": {
          "offer_asset_info": {
            "token": {
              "contract_addr": usdcAddress
            }
          },
          "ask_asset_info": {
            "token": {
              "contract_addr": zeroAddress
            }
          }
        }
      }
    ]
  }
}

`execute_swap_operations`

To create a native multi-hop swap, you need to execute a contract message pointing to the execute_swap_operations endpoint in the Router contract

operations is the only required parameter and holds information regarding each swap stored in a vector containing objects of type SwapOperation.

NOTE

`Coins`

Since our initial offer token is a native asset, we need to send the native token along with the transaction message.

The code in this section is an example of what a complete swap message may look like using feather.js to send Coins with our transaction.

Optional Parameters

The execute_swap_operations endpoint takes in the following optional parameters:

minimum_receive: Minimum expected return amount
max_spread: The difference between the ask amount before and after the swap. If the swap spread exceeds the provided max limit, the swap will fail.
to: Address receiving tokens (if different from sender)

`minimum_receive` + `max_spread`

If minimum_receive is provided in combination with max_spread, the pool will check the difference between the return amount (using belief_price) and the real pool price.

minimum_receive +/- the max_spread is the range of possible acceptable prices for this swap.

Calculating `minimum_receive`

Astroport's native solution to obtain minimum_receive is to query the simulate_swap_operations endpoint from the Router contract and to pass the result of this query into the swap message.

`simulate_swap_operations`

The simulate_swap_operations endpoint takes in two parameters:

offer_amount: The amount of tokens to swap
operations: The swap operations to perform

The operations parameter takes in the same vector of SwapOperation objects that our swap message contains.

{
  "execute_swap_operations": {
    "operations": [
      {
        "astro_swap": {
          "offer_asset_info": {
            "native_token": {
              "denom": "uluna"
            }
          },
          "ask_asset_info": {
            "token": {
              "contract_addr": usdcAddress
            }
          }
        }
      }, 
      {
        "astro_swap": {
          "offer_asset_info": {
            "token": {
              "contract_addr": usdcAddress
            }
          },
          "ask_asset_info": {
            "token": {
              "contract_addr": zeroAddress
            }
          }
        }
      }
    ], 
    "minimum_receive": beliefPrice,
    "max_spread": "0.005", 
    "to": "..."
  }
}

CW20 Routing

Use when the initial offer asset is a CW20 token.

`Cw20HookMsg`

To perform a CW20 swap, you need to execute a contract message pointing to the send endpoint in the CW20 contract of the token you are swapping.

send includes the contract the tokens are being sent to (router contract), the amount to send/swap, and a binary encoded msg containing our contract call.

{
  "send": {
    "contract": routerAddress, 
    "amount": "1000000", 
    "msg": toBase64(
      {
        "execute_swap_operations": {
          "operations": [
            {
              "astro_swap": {
                "offer_asset_info": {
                  "token": {
                    "contract_addr": astroAddress
                  }
                },
                "ask_asset_info": {
                  "native_token": {
                    "denom": "uluna"
                  }
                }
              }
            }, 
            {
              "astro_swap": {
                "offer_asset_info": {
                  "native_token": {
                    "denom": "uluna"
                  }
                },
                "ask_asset_info": {
                  "token": {
                    "contract_addr": steakAddress
                  }
                }
              }
            }
          ], 
          "minimum_receive": nativeBeliefPrice,
          "max_spread": "0.005"
        }
      }
    )
  }
}

`execute_swap_operations`

Our encoded swap message performs a contract call to the execute_swap_operations endpoint in the Router contract. This is the same operation covered above in Native Routing.

{
  "send": {
    "contract": routerAddress, 
    "amount": "1000000", 
    "msg": toBase64(
      {
        "execute_swap_operations": {
          "operations": [
            {
              "astro_swap": {
                "offer_asset_info": {
                  "token": {
                    "contract_addr": astroAddress
                  }
                },
                "ask_asset_info": {
                  "native_token": {
                    "denom": "uluna"
                  }
                }
              }
            }, 
            {
              "astro_swap": {
                "offer_asset_info": {
                  "native_token": {
                    "denom": "uluna"
                  }
                },
                "ask_asset_info": {
                  "token": {
                    "contract_addr": steakAddress
                  }
                }
              }
            }
          ], 
          "minimum_receive": nativeBeliefPrice,
          "max_spread": "0.005"
        }
      }
    )
  }
}

Encoding our `Msg`

To encode our message, there are two common options:

An online base64 encoder
A custom function

The code in this section uses a custom function (toBase64) to display our binary message - this function needs to be defined elsewhere to be used. The actual string representation of our message would be an encoded binary.

{
  "send": {
    "contract": routerAddress, 
    "amount": "1000000", 
    "msg": toBase64(
      {
        "execute_swap_operations": {
          "operations": [
            {
              "astro_swap": {
                "offer_asset_info": {
                  "token": {
                    "contract_addr": astroAddress
                  }
                },
                "ask_asset_info": {
                  "native_token": {
                    "denom": "uluna"
                  }
                }
              }
            }, 
            {
              "astro_swap": {
                "offer_asset_info": {
                  "native_token": {
                    "denom": "uluna"
                  }
                },
                "ask_asset_info": {
                  "token": {
                    "contract_addr": steakAddress
                  }
                }
              }
            }
          ], 
          "minimum_receive": nativeBeliefPrice,
          "max_spread": "0.005"
        }
      }
    )
  }
}

`toBase64` Encoder

The code in this section is an example of what a send message may look like feather.js to define our custom function and encode our message.

const toBase64 = (obj) => {
  return Buffer.from(JSON.stringify(obj)).toString("base64");
};
const cw20RouterSwap = new MsgExecuteContract(
  wallet.key.accAddress('terra'),
  astroAddress,
  {
    "send": {
      "contract": routerAddress, 
      "amount": "1000000", 
      "msg": toBase64(
        {
          "execute_swap_operations": {
            "operations": [
              {
                "astro_swap": {
                  "offer_asset_info": {
                    "token": {
                      "contract_addr": astroAddress
                    }
                  },
                  "ask_asset_info": {
                    "native_token": {
                      "denom": "uluna"
                    }
                  }
                }
              }, 
              {
                "astro_swap": {
                  "offer_asset_info": {
                    "native_token": {
                      "denom": "uluna"
                    }
                  },
                  "ask_asset_info": {
                    "token": {
                      "contract_addr": steakAddress
                    }
                  }
                }
              }
            ], 
            "minimum_receive": nativeBeliefPrice,
            "max_spread": "0.005"
          }
        }
      )
    }
  }
)
const fee = new Fee(2000000, { uluna: 200000 });
// // BROADCAST TRANSACTION
const tx = await wallet.createAndSignTx({
  msgs: [cw20RouterSwap],
  fee,
  chainID: 'pisco-1',
});
const result = await lcd.tx.broadcast(tx, 'pisco-1');
console.log(result);

Calculating `minimum_receive`

Lastly, calculating minimum_receive for CW20 swaps is the exact same as it is for native swaps.

Note that since we are performing a CW20 swap, our initial offer asset is a CW20 token and not a native asset like uluna, but the logic remains the same. To learn more about this topic, refer to the section above.

{
  "simulate_swap_operations": {
"offer_amount": "1000000",
    "operations": [
      {
        "astro_swap": {
          "offer_asset_info": {
            "token": {
              "contract_addr": astroAddress
            }
          },
          "ask_asset_info": {
            "native_token": {
              "denom": "uluna"
            }
          }
        }
      }, 
      {
        "astro_swap": {
          "offer_asset_info": {
            "native_token": {
              "denom": "uluna"
            }
          },
          "ask_asset_info": {
            "token": {
              "contract_addr": steakAddress
            }
          }
        }
      }
    ]
  }
}

`Cw20HookMsg`

To perform a CW20 swap, you need to execute a contract message pointing to the send endpoint in the CW20 contract of the token you are swapping.

send includes the contract the tokens are being sent to (router contract), the amount to send/swap, and a binary encoded msg containing our contract call.

`execute_swap_operations`

Our encoded swap message performs a contract call to the execute_swap_operations endpoint in the Router contract. This is the same operation covered above in Native Routing.

Encoding our `Msg`

To encode our message, there are two common options:

An online base64 encoder
A custom function

`toBase64` Encoder

The code in this section is an example of what a send message may look like feather.js to define our custom function and encode our message.

Calculating `minimum_receive`

Lastly, calculating minimum_receive for CW20 swaps is the exact same as it is for native swaps.

{
  "send": {
    "contract": routerAddress, 
    "amount": "1000000", 
    "msg": toBase64(
      {
        "execute_swap_operations": {
          "operations": [
            {
              "astro_swap": {
                "offer_asset_info": {
                  "token": {
                    "contract_addr": astroAddress
                  }
                },
                "ask_asset_info": {
                  "native_token": {
                    "denom": "uluna"
                  }
                }
              }
            }, 
            {
              "astro_swap": {
                "offer_asset_info": {
                  "native_token": {
                    "denom": "uluna"
                  }
                },
                "ask_asset_info": {
                  "token": {
                    "contract_addr": steakAddress
                  }
                }
              }
            }
          ], 
          "minimum_receive": nativeBeliefPrice,
          "max_spread": "0.005"
        }
      }
    )
  }
}

Multi-hop Routing

Overview​

Native Routing​

execute_swap_operations​

Coins​

Optional Parameters​

minimum_receive + max_spread​

Calculating minimum_receive​

simulate_swap_operations​

execute_swap_operations​

Coins​

Optional Parameters​

minimum_receive + max_spread​

Calculating minimum_receive​

simulate_swap_operations​

CW20 Routing​

Cw20HookMsg​

execute_swap_operations​

Encoding our Msg​

toBase64 Encoder​

Calculating minimum_receive​

Cw20HookMsg​

execute_swap_operations​

Encoding our Msg​

toBase64 Encoder​

Calculating minimum_receive​

Overview

Native Routing

`execute_swap_operations`

`Coins`

Optional Parameters

`minimum_receive` + `max_spread`

Calculating `minimum_receive`

`simulate_swap_operations`

`execute_swap_operations`

`Coins`

Optional Parameters

`minimum_receive` + `max_spread`

Calculating `minimum_receive`

`simulate_swap_operations`

CW20 Routing

`Cw20HookMsg`

`execute_swap_operations`

Encoding our `Msg`

`toBase64` Encoder

Calculating `minimum_receive`

`Cw20HookMsg`

`execute_swap_operations`

Encoding our `Msg`

`toBase64` Encoder

Calculating `minimum_receive`