🔀Router

The router contract is used to execute multi-hop swaps. Say there are two pools: ATOM-JUNO and JUNO-LUNA. There is no way to directly swap ATOM for LUNA, as there is no ATOM-LUNA pool. With the router contract, it is possible to can concatenate swap operations so that it becomes possible to swap ATOM for LUNA via JUNO, i.e. ATOM->JUNO->LUNA.

The router is mainly used by bots and the UI.

The code for the router contract can be found here.

---

The following are the messages that can be executed on the router:

Instantiate

Instantiates the router. Requires to have instantiated the factory first.

{
  "terraswap_factory": "migaloo1..."
}

Key	Type	Description
terraswap_factory	String	Contract address for the pool factory

Migrate

Migrates the router.

{}

ExecuteMsg

Asset minimum receive

Checks whether the amount returned after the swap exceeds the minimum_receive amount. Internally called by the router.

{
  "assert_minimum_receive": {
    "asset_info": {
      "native_token": {
        "denom": "ibc/C4CFF46FD6DE35CA4CF4CE031E643C8FDC9BA4B99AE598E9B0ED98FE3A2319F9"
      }
    },
    "prev_balance": "1000",
    "minimum_receive": "1000",
    "receiver": ""
  }
}

Key	Type	Description
asset_info	AssetInfo	Asset info to perform the validation with
prev_balance	Uint128	Receivers balance before the swap
minimum_receive	Uint128	Minimum amount to be received after the swap
receiver	String	Receiver address for the swap

Swap Operations

Executes swap operations. It can be a multi-hop swap as the example described above, but it doesn't need to be.

{
  "execute_swap_operations": {
    "operations": [
      {
        "terra_swap": {
          "offer_asset_info": {
            "native_token": {
              "denom": "ibc/C4CFF46FD6DE35CA4CF4CE031E643C8FDC9BA4B99AE598E9B0ED98FE3A2319F9"
            }
          },
          "ask_asset_info": {
            "native_token": {
              "denom": "uwhale"
            }
          }
        }
      },
      {
        "terra_swap": {
          "offer_asset_info": {
            "native_token": {
              "denom": "uwhale"
            }
          },
          "ask_asset_info": {
            "token": {
              "contract_addr": "migaloo1..."
            }
          }
        }
      }
    ],
    "minimum_receive": "1000",
    "to": "migaloo1...",
    "max_spread": "0.1"
  }
}

Key	Type	Description
operations	Vec<SwapOperation>	Swap operations to be executed
minimum_receive	Option<Uint128>	Minimum desired amount to be received after the swap
to	Option<String>	Receiver address in case it is different from the sender
max_spread	Option<Decimal>	Max desired spread to perform the swap with

Swap Operation

Executes a swap operation. This is called internally by the contract itself.

{
  "execute_swap_operation": {
    "operation": {
      "terra_swap": {
        "offer_asset_info": {
          "native_token": {
            "denom": "ibc/C4CFF46FD6DE35CA4CF4CE031E643C8FDC9BA4B99AE598E9B0ED98FE3A2319F9"
          }
        },
        "ask_asset_info": {
          "native_token": {
            "denom": "uwhale"
          }
        }
      }
    },
    "to": "migaloo1...",
    "max_spread": "0.1"
  }
}

Key	Type	Description
operations	SwapOperation	Swap operation to be executed
to	Option<String>	Receiver address in case it is different from the sender
max_spread	Option<String>	Max desired spread to perform the swap with

Receive (Cw20ReceiveMsg)

Receives a Cw20ReceiveMsg message, being the only valid message ExecuteSwapOperations, used to execute swap operations when the token to be swapped is a cw20 token.

{
  "send": {
    "contract": "router_contract_address",
    "amount": "1000",
    "msg": "ewogI...7fQp9"
  }
}

Key	Type	Description
contract	String	Contract to send the msg to
amount	Uint128	Amount of tokens to be sent
msg	Binary	Encoded message in base64

where ewogI...7fQp9 is the ExecuteSwapOperations message, encoded in base64.

AddSwapRoutes

Adds swap routes to the router. This is needed so other contracts such as the fee collector contract can aggregate fees into a single token by passing the offer and ask asset.

{
  "add_swap_routes": {
    "swap_routes": [
      {
        "offer_asset_info": {
          "token": {
            "contract_addr": "migaloo1..."
          }
        },
        "ask_asset_info": {
          "native_token": {
            "denom": "uwhale"
          }
        },
        "swap_operations": [
          {
            "terra_swap": {
              "offer_asset_info": {
                "token": {
                  "contract_addr": "migaloo1..."
                }
              },
              "ask_asset_info": {
                "native_token": {
                  "denom": "ibc/27394FB092D2ECCD56123C74F36E4C1F926001CEADA9CA97EA622B25F41E5EB2"
                }
              }
            }
          },
          {
            "terra_swap": {
              "offer_asset_info": {
                "native_token": {
                  "denom": "ibc/27394FB092D2ECCD56123C74F36E4C1F926001CEADA9CA97EA622B25F41E5EB2"
                }
              },
              "ask_asset_info": {
                "native_token": {
                  "denom": "uwhale"
                }
              }
            }
          }
        ]
      }
    ]
  }
}

Key	Type	Description
swap_routes	Vec<SwapRoute>	The swap routes to be recorded into the router

RemoveSwapRoutes

Removes swap routes from the router. This is needed to clean up swap routes from state when are not needed anymore.

{
  "remove_swap_routes": {
    "swap_routes": [
      {
        "offer_asset_info": {
          "token": {
            "contract_addr": "migaloo1..."
          }
        },
        "ask_asset_info": {
          "native_token": {
            "denom": "uwhale"
          }
        },
        "swap_operations": [
          {
            "terra_swap": {
              "offer_asset_info": {
                "token": {
                  "contract_addr": "migaloo1..."
                }
              },
              "ask_asset_info": {
                "native_token": {
                  "denom": "ibc/27394FB092D2ECCD56123C74F36E4C1F926001CEADA9CA97EA622B25F41E5EB2"
                }
              }
            }
          },
          {
            "terra_swap": {
              "offer_asset_info": {
                "native_token": {
                  "denom": "ibc/27394FB092D2ECCD56123C74F36E4C1F926001CEADA9CA97EA622B25F41E5EB2"
                }
              },
              "ask_asset_info": {
                "native_token": {
                  "denom": "uwhale"
                }
              }
            }
          }
        ]
      }
    ]
  }
}

Key	Type	Description
swap_routes	Vec<SwapRoute>	The swap routes to be removed from the router

Queries

Config

Retrieves the configuration of the router contract.

Query

{
  "config": {}
}

Response (ConfigResponse)

{
  "terraswap_factory": "migaloo1..."
}

Key	Type	Description
terraswap_factory	String	Pool factory contract address

Simulate swap operations

Performs a simulation for swap operations.

Query

{
  "simulate_swap_operations": {
    "operations": [
      {
        "terra_swap": {
          "offer_asset_info": {
            "native_token": {
              "denom": "uluna"
            }
          },
          "ask_asset_info": {
            "native_token": {
              "denom": "ibc/27394FB092D2ECCD56123C74F36E4C1F926001CEADA9CA97EA622B25F41E5EB2"
            }
          }
        }
      },
      {
        "terra_swap": {
          "offer_asset_info": {
            "native_token": {
              "denom": "ibc/27394FB092D2ECCD56123C74F36E4C1F926001CEADA9CA97EA622B25F41E5EB2"
            }
          },
          "ask_asset_info": {
            "native_token": {
              "denom": "ibc/4CD525F166D32B0132C095F353F4C6F033B0FF5C49141470D1EFDA1D63303D04"
            }
          }
        }
      }
    ],
    "offer_amount": "1000"
  }
}

Key	Type	Description
offer_amount	Uint128	Offer asset amount to simulate the swap with
operations	Vec<SwapOperation>	Swap operations to be simulated

Response (SimulateSwapOperationsResponse)

{
  "amount": "5000"
}

Key	Type	Description
amount	Uint128	Ask asset amount that would be returned after the swap

Reverse simulate swap operations

Performs a reverse simulation for swap operations, i.e. given the ask asset, how much of the offer asset is needed to perform the swap.

Query

{
  "reverse_simulate_swap_operations": {
    "operations": [
      {
        "terra_swap": {
          "offer_asset_info": {
            "native_token": {
              "denom": "ibc/C4CFF46FD6DE35CA4CF4CE031E643C8FDC9BA4B99AE598E9B0ED98FE3A2319F9"
            }
          },
          "ask_asset_info": {
            "native_token": {
              "denom": "uwhale"
            }
          }
        }
      },
      {
        "terra_swap": {
          "offer_asset_info": {
            "native_token": {
              "denom": "uwhale"
            }
          },
          "ask_asset_info": {
            "token": {
              "contract_addr": "migaloo1"
            }
          }
        }
      }
    ],
    "ask_amount": "1000"
  }
}

Key	Type	Description
ask_amount	Uint128	Ask asset amount to simulate the swap with
operations	Vec<SwapOperation>	Swap operations to be simulated

Response (SimulateSwapOperationsResponse)

{
  "amount": "5000"
}

Key	Type	Description
amount	Uint128	Ask asset amount that would be returned after the swap

Swap Route

Gets the swap route for the given offer and ask assets.

Query

{
  "swap_route": {
    "offer_asset_info": {
      "token": {
        "contract_addr": "migaloo1..."
      }
    },
    "ask_asset_info": {
      "native_token": {
        "denom": "uwhale"
      }
    }
  }
}

Key	Type	Description
offer_asset_info	AssetInfo	Offer asset, i.e. input asset
ask_asset_info	AssetInfo	Ask asset, i.e. output asset

Response (Vec<SwapOperation>)

{
  "data": [
    {
      "terra_swap": {
        "offer_asset_info": {
          "token": {
            "contract_addr": "migaloo1..."
          }
        },
        "ask_asset_info": {
          "native_token": {
            "denom": "ibc/C4CFF46FD6DE35CA4CF4CE031E643C8FDC9BA4B99AE598E9B0ED98FE3A2319F9"
          }
        }
      }
    },
    {
      "terra_swap": {
        "offer_asset_info": {
          "native_token": {
            "denom": "ibc/C4CFF46FD6DE35CA4CF4CE031E643C8FDC9BA4B99AE598E9B0ED98FE3A2319F9"
          }
        },
        "ask_asset_info": {
          "native_token": {
            "denom": "uwhale"
          }
        }
      }
    }
  ]
}

Key	Type	Description
data	Vec<SwapOperation>	Swap operations needed to accomplish the swap with the offer and ask asset

Swap Routes

Gets all swap routes registered.

Query

{
  "swap_routes": {}
}

Response (Vec<SwapRouteResponse>)

{
  "data": [
    {
      "offer_asset": "migaloo1...",
      "ask_asset": "uwhale",
      "swap_route": [
        {
          "terra_swap": {
            "offer_asset_info": {
              "token": {
                "contract_addr": "migaloo1..."
              }
            },
            "ask_asset_info": {
              "native_token": {
                "denom": "ibc/C4CFF46FD6DE35CA4CF4CE031E643C8FDC9BA4B99AE598E9B0ED98FE3A2319F9"
              }
            }
          }
        },
        {
          "terra_swap": {
            "offer_asset_info": {
              "native_token": {
                "denom": "ibc/C4CFF46FD6DE35CA4CF4CE031E643C8FDC9BA4B99AE598E9B0ED98FE3A2319F9"
              }
            },
            "ask_asset_info": {
              "native_token": {
                "denom": "uwhale"
              }
            }
          }
        }
      ]
    }
  ]
}

Key	Type	Description
data	SwapRouteResponse	A list of all swap routes registered on the router for each offer and ask asset combination