🧪Router

Contract used to simulate and execute swaps for Astroport pools

1. Overview

The Router contract contains logic to specify a custom (multi-hop) path to swap tokens on Astroport.

For example, someone can specify paths to swap the following tokens:

  • bLUNA -> LUNA -> UST

  • ANC -> UST -> ASTRO

The contract will check whether the resulting token (in these cases, UST and ASTRO respectively) is the correct one as well as check that the amount of tokens received is equal to or higher than the minimum amount asked.

The router contract code can be found here.

2. Variables and Functions

Constants

Name
Description

MAX_SWAP_OPERATIONS

The maximum number of swaps that can happen in a multi-hop swap operation

Structs

Name
Description
Contains

InstantiateMsg

This struct holds data used to instantiate the router contract

  • astroport_factory - The address of the Astroport factory

ConfigResponse

This struct holds data returned when querying for the router contract configuration

  • astroport_factory - The address of the Astroport factory

SimulateSwapOperationsResponse

This struct holds data returned when simulating a swap

  • amount - The amount of ask tokens returned by the simulation

Config

This struct holds the config data for the router

  • astroport_factory - The address of the Astroport factory

Functions

Name
Params
Description

instantiate

(deps: DepsMut, _env: Env, _info: MessageInfo, msg: InstantiateMsg)

This function instantiates a new router contract

execute

(deps: DepsMut, env: Env, info: MessageInfo, msg: ExecuteMsg) -> Result<Response, ContractError>

Exposes all the execute functions available in the contract

receive_cw20

(deps: DepsMut, env: Env, info: MessageInfo, cw20_msg: Cw20ReceiveMsg) -> Result<Response, ContractError>

Receives a message of type [Cw20ReceiveMsg] and processes it depending on the received template

execute_swap_operations

(deps: DepsMut, env: Env, _info: MessageInfo, sender: Addr, operations: Vec<SwapOperation>, minimum_receive: Option<Uint128>, to: Option<Addr>, max_spread: Option<Decimal>) -> Result<Response, ContractError>

Executes swap operations

assert_minimum_receive

(deps: Deps, asset_info: AssetInfo, prev_balance: Uint128, minimum_receive: Uint128, receiver: Addr)

Internal function that checks if an ask amount is equal to or above a minimum amount. AssetInfo is imported from the asset file

query

(deps: Deps, _env: Env, msg: QueryMsg) -> Result<Binary, ContractError>

Exposes all the queries available in the contract

query_config

(deps: Deps) -> Result<ConfigResponse, ContractError>

Returns the router contract configuration

migrate

(_deps: DepsMut, _env: Env, _msg: MigrateMsg) -> StdResult<Response>

Used for the contract migration

simulate_swap_operations

(deps: Deps, offer_amount: Uint128, operations: Vec<SwapOperation>) -> Result<SimulateSwapOperationsResponse, ContractError>

Internal function that simulates a one or multi-hop swap and returns the end result

assert_operations

(api: &dyn Api, operations: &[SwapOperation]) -> Result<(), ContractError>

Internal function that validates swap operations

3. Walkthrough

The following are examples and descriptions of core functions that can be called by anyone to specify a custom (multi-hop) path to swap tokens on Astroport.

execute_swap_operations

Any address can call the execute_swap_operations function to perform multi-hop swap operations. Hopes execute one-by-one and the last swap will return the ask (requested) token.

The execute_swap_operations function can takes in AstroSwap or NativeSwap for the operations parameter. The former performs a swap with non-native tokens via one of the Astroport pools while the latter performs native swaps using Terra's built-in market module. The function also takes in an offer and and ask info for both swaps in the operation, as well as additional parameters:

  • minimum_received - Used to guarantee that the ask amount is above a minimum amount

  • to - This is the recipient of the ask tokens

  • max_spread - The spread is calculated as the difference between the ask amount (using the constant pool price) before and after the swap operation. Once max_spread is set, it will be compared against the actual swap spread. In case the swap spread exceeds the provided max limit, the swap will fail. Note that the spread is calculated before commission deduction in order to properly represent the pool's ratio change

Swap bLUNA -> LUNA -> UST

{
    "execute_swap_operations": {
      "operations": [
        {
            "astro_swap": {
              "offer_asset_info": {
                "token": {
                  "contract_addr": "terra1kc87mu460fwkqte29rquh4hc20m54fxwtsx7gp"
                }
              },
              "ask_asset_info": {
                "native_token": {
                  "denom": "uluna"
                }
              }
            }
        },
        {
            "native_swap":{
              "offer_denom":"uluna",
              "ask_denom":"uusd"
            }
        }
      ],
      "minimum_receive": "123",
      "to": "terra...",
      "max_spread": "0.05"
    }
  }

Swap ANC -> UST -> ASTRO

{
    "execute_swap_operations": {
      "operations": [
        {
            "astro_swap": {
              "offer_asset_info": {
                "token": {
                  "contract_addr": "terra14z56l0fp2lsf86zy3hty2z47ezkhnthtr9yq76"
                }
              },
              "ask_asset_info": {
                "native_token": {
                  "denom": "uusd"
                }
              }
            }
        },
        {
          "astro_swap": {
            "offer_asset_info": {
              "native_token": {
                "denom": "uusd"
              }
            },
            "ask_asset_info": {
              "token": {
                "contract_addr": "terra1xj49zyqrwpv5k928jwfpfy2ha668nwdgkwlrg3"
              }
            }
          }
        }
      ],
      "minimum_receive": "123",
      "to": "terra...",
      "max_spread": "0.05"
    }
  }

assert_minimum_receive

Checks that the swap amount exceeds minimum_receive. This is an internal function.

{
  "assert_minimum_receive": {
    "asset_info": {
      "token": {
        "contract_addr": "terra..."
      }
    },
    "prev_balance": "123",
    "minimum_receive": "123",
    "receiver": "terra..."
  }
}

config

Returns general settings for the router contract, including the astroport_factory contract address.

{
  "config": {}
}

simulate_swap_operations

An address can call the simulate_swap_operations query to simulate a one or multi-hop swap operation. The query takes in AstroSwap or NativeSwap for the operations parameter. The function also takes in an offer and and ask for both tokens in the operation, as well as additional parameters:

  • offer_amount - This is the number of offer assets being swapped.

Simulate bLUNA -> LUNA -> UST

{
  "simulate_swap_operations": {
    "offer_amount": "123",
    "operations": [
     {
        "astro_swap": {
          "offer_asset_info": {
            "token": {
                "contract_addr": "terra1kc87mu460fwkqte29rquh4hc20m54fxwtsx7gp"
              }
          },
          "ask_asset_info": {
            "native_token": {
                "denom": "uluna"
              }
          }
        }
      },
      {
        "native_swap": {
          "offer_denom": "uluna",
          "ask_denom": "uusd"
        }
      }
    ]
  }
}

Simulate ANC -> UST -> ASTRO

{
    "simulate_swap_operations": {
      "offer_amount": "123",
      "operations": [
       {
          "astro_swap": {
            "offer_asset_info": {
              "token": {
                  "contract_addr": "terra14z56l0fp2lsf86zy3hty2z47ezkhnthtr9yq76"
                }
            },
            "ask_asset_info": {
              "native_token": {
                  "denom": "uusd"
                }
            }
          }
        },
        {
            "astro_swap": {
              "offer_asset_info": {
                "native_token": {
                    "denom": "uusd"
                  }
              },
              "ask_asset_info": {
                "token": {
                    "contract_addr": "terra1xj49zyqrwpv5k928jwfpfy2ha668nwdgkwlrg3"
                  }
              }
            }
          }
      ]
    }
  }
PreviousStableswap PoolNextOracles

Last updated

Was this helpful?