Router
Overview
The Router contract performs multi-hop swaps across Astroport pools, for native and CW20 tokens. Two router versions are live on each chain:
- Router 2.0 (
astroport-router2.0.0) is the recommended router. A hop is either a pool the factory knows for an asset pair (astro_swap) or a pool given by address (pool_swap). Withpool_swap, pools that aren't registered in the factory, such as the USDC transmuter on Terra, can be part of a route.minimum_receiveis required and is the route's only price check. - Router 1.3 (
astroport-router1.3.1) is still live with its old API: every hop is resolved through the factory,minimum_receiveis optional andmax_spreadis checked per hop. See Router 1.3.
Router 2.0 is deployed as its own instance. Router 1.x instances keep their old API and can't be migrated to 2.0. The Maker 2.0 contracts swap through Router 2.0.
Links
- Terra Router 2.0: terra1txm8xcy8mete9e5zh5ktqr4jm4cq4ja8djttg3zkqll64x4ksq7qknaesf
- Neutron Router 2.0: neutron1xuh7nqt486gkvkxdwt773fzs5uptxy0ylzehm3spq7rx8r2kaspqzu0hv6
- Terra Router 1.3.1: terra18plp90j0zd596zt3zdsf0w9vvk5ukwlwzwkksxv9mdu8rscat9sqndk5qz
- Neutron Router 1.3.1: neutron1rwj6mfxzzrwskur73v326xwuff52vygqk73lr7azkehnfzz5f5wskwekf4
- Contract Repo: https://github.com/astroport-fi/astroport-core/tree/main/contracts/router
- contract.rs: https://github.com/astroport-fi/astroport-core/blob/main/contracts/router/src/contract.rs
- msg.rs (2.0 types): https://github.com/astroport-fi/astroport-core/blob/main/contracts/router/src/msg.rs
- router.rs (1.x types): https://github.com/astroport-fi/astroport-core/blob/main/packages/astroport/src/router.rs
- Tests: https://github.com/astroport-fi/astroport-core/tree/main/contracts/router/tests
The 2.0 message types live in the router crate (astroport_router::msg, use it with the library feature), not in the shared astroport package. astroport::router keeps the 1.x types.
Price protection
Pools' own spread checks are disabled on every hop, including single-hop swaps. The only price guarantee is minimum_receive: after the last hop, the router checks that the receiver got at least that amount of the ask asset and reverts the whole transaction otherwise. It is required and must be greater than zero.
The bound is only as good as the number you send. Set minimum_receive from a price you trust (for example your own quote minus slippage), not from a hop's own simulation. minimum_receive: "1" is accepted but protects almost nothing.
Nested routes are refused: a route can't be started while another one is in progress (RouteInProgress).
Choosing pools
pool_swap accepts any address. The router checks that the pool's pair {} query reports that address and both assets, which catches mistyped routes, but it can't prove a contract is a genuine Astroport pool. Only build pool_swap routes from pools you trust.
Each hop offers the router's whole balance of the offer asset. The router holds nothing between transactions, so this is only the route's own funds plus anything sent to the router by mistake.
A route has at most 50 hops. Each hop must offer the asset the previous hop asked for, and a hop can't offer and ask for the same asset.
InstantiateMsg
Initializes the contract with the Astroport factory address, used to resolve astro_swap hops.
| Params | Type | Description |
|---|---|---|
astroport_factory | String | The Astroport factory contract address |
ExecuteMsg
execute_swap_operations
Swaps the attached amount along the route. Hops execute one by one and the last one sends the ask asset to to (the sender if omitted). Anyone can call it.
The response data contains the total return_amount (a SwapResponseData). It is only set when the route starts with a native asset; a CW20 send resets the response data.
This example, on Terra, swaps 10 LUNA for USDC (Noble) through the factory's LUNA/USDC pool, then USDC for USDC.inj through the USDC transmuter, a pool that isn't registered in the factory. Attach the uluna to the message.
| Params | Type | Description |
|---|---|---|
operations | Vec<SwapOperation> | The hops of the route, between 1 and 50 |
minimum_receive | Uint128 | Required, greater than zero. The least amount of the last ask asset the receiver must get, otherwise the whole transaction reverts |
to | Option<String> | The recipient of the last ask asset. Defaults to the sender |
On Neutron, this route swaps ATOM for NTRN in a pool given by address, then NTRN for ASTRO through the factory's NTRN/ASTRO pool:
_36{_36 "execute_swap_operations": {_36 "operations": [_36 {_36 "pool_swap": {_36 "pool_addr": "neutron15d0se9nw9stqx9ms9ey85gfpraqwl80t5urmjfk2jwtqxpxk3x3qctjt4n",_36 "offer_asset_info": {_36 "native_token": {_36 "denom": "ibc/C4CFF46FD6DE35CA4CF4CE031E643C8FDC9BA4B99AE598E9B0ED98FE3A2319F9"_36 }_36 },_36 "ask_asset_info": {_36 "native_token": {_36 "denom": "untrn"_36 }_36 }_36 }_36 },_36 {_36 "astro_swap": {_36 "offer_asset_info": {_36 "native_token": {_36 "denom": "untrn"_36 }_36 },_36 "ask_asset_info": {_36 "native_token": {_36 "denom": "factory/neutron1ffus553eet978k024lmssw0czsxwr97mggyv85lpcsdkft8v9ufsz3sa07/astro"_36 }_36 }_36 }_36 }_36 ],_36 "minimum_receive": "1700000000"_36 }_36}
SwapOperation
A hop of a route.
| Variants | Description |
|---|---|
astro_swap | Swap in the factory's pool for this asset pair. The factory must know a pool for the two assets |
pool_swap | Swap in a specific pool, given by pool_addr. The pool doesn't have to be registered in the factory, but its pair {} query must report that address and both assets |
offer_asset_info and ask_asset_info are AssetInfo values: {"native_token": {"denom": "..."}} or {"token": {"contract_addr": "..."}}.
receive
CW20 receive hook, used when the first offer asset is a CW20 token. Send the token to the router with a CW20 send whose msg is the base64-encoded execute_swap_operations message below (the same fields as the execute message).
| Params | Type | Description |
|---|---|---|
contract | String | The router address |
amount | Uint128 | The amount of the CW20 token to swap |
msg | Binary | Base64 of a Cw20HookMsg::ExecuteSwapOperations, for example {"execute_swap_operations":{"operations":[...],"minimum_receive":"123"}} |
execute_swap_operation
Executes a single hop. Only the router itself can call it; execute_swap_operations uses it for every hop.
QueryMsg
config
Returns the router's configuration.
| Params | Type | Description |
|---|---|---|
astroport_factory | String | The Astroport factory contract address |
simulate_swap_operations
Simulates a route for an offer amount and returns the amount received, as {"amount": "..."} (SimulateSwapOperationsResponse). Takes the same operations as execute_swap_operations.
| Params | Type | Description |
|---|---|---|
offer_amount | Uint128 | The amount of the first offer asset |
operations | Vec<SwapOperation> | The route |
reverse_simulate_swap_operations
Simulates a route backwards: returns the offer amount needed to receive ask_amount, as a plain Uint128 string.
| Params | Type | Description |
|---|---|---|
ask_amount | Uint128 | The amount of the last ask asset to receive |
operations | Vec<SwapOperation> | The route |
Router 1.3
Router 1.3.1 stays live on both chains for existing integrations. Its messages are the 1.x types in astroport::router:
- Hops are
astro_swaponly (factory pools).native_swapis part of the type but isn't supported on Terra or Neutron, and there is nopool_swap. execute_swap_operationstakesoperations, an optionalminimum_receive, an optionaltoand an optionalmax_spread.max_spreadis checked on every hop.- The
config,simulate_swap_operationsandreverse_simulate_swap_operationsqueries have the same shape as in 2.0.
_22{_22 "execute_swap_operations": {_22 "operations": [_22 {_22 "astro_swap": {_22 "offer_asset_info": {_22 "native_token": {_22 "denom": "untrn"_22 }_22 },_22 "ask_asset_info": {_22 "native_token": {_22 "denom": "factory/neutron1ffus553eet978k024lmssw0czsxwr97mggyv85lpcsdkft8v9ufsz3sa07/astro"_22 }_22 }_22 }_22 }_22 ],_22 "minimum_receive": "1000000",_22 "max_spread": "0.01"_22 }_22}
New integrations should use Router 2.0. It can route through pools the factory doesn't know, and its required minimum_receive makes the route's price check explicit.