Skip to main content

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-router 2.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). With pool_swap, pools that aren't registered in the factory, such as the USDC transmuter on Terra, can be part of a route. minimum_receive is required and is the route's only price check.
  • Router 1.3 (astroport-router 1.3.1) is still live with its old API: every hop is resolved through the factory, minimum_receive is optional and max_spread is 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.

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.

json
msg.rs
Copy

_3
{
_3
"astroport_factory": "terra14x9fr055x5hvr48hzy2t4q7kvjvfttsvxusa4xsdcy702mnzsvuqprer8r"
_3
}

ParamsTypeDescription
astroport_factoryStringThe 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.

json
msg.rs
Copy

_37
{
_37
"execute_swap_operations": {
_37
"operations": [
_37
{
_37
"astro_swap": {
_37
"offer_asset_info": {
_37
"native_token": {
_37
"denom": "uluna"
_37
}
_37
},
_37
"ask_asset_info": {
_37
"native_token": {
_37
"denom": "ibc/2C962DAB9F57FE0921435426AE75196009FAA1981BF86991203C8411F8980FDB"
_37
}
_37
}
_37
}
_37
},
_37
{
_37
"pool_swap": {
_37
"pool_addr": "terra1p3sea2vjewtr9ap4hv7nc75k5jc852ftf0w5u06wsk420y5urc9s9xtxdj",
_37
"offer_asset_info": {
_37
"native_token": {
_37
"denom": "ibc/2C962DAB9F57FE0921435426AE75196009FAA1981BF86991203C8411F8980FDB"
_37
}
_37
},
_37
"ask_asset_info": {
_37
"native_token": {
_37
"denom": "ibc/E8481AD838C31D4FC12A504B10F9B4E2F830F8818D2735C2FFC707579B5FA60B"
_37
}
_37
}
_37
}
_37
}
_37
],
_37
"minimum_receive": "390000",
_37
"to": "terra1..."
_37
}
_37
}

ParamsTypeDescription
operationsVec<SwapOperation>The hops of the route, between 1 and 50
minimum_receiveUint128Required, greater than zero. The least amount of the last ask asset the receiver must get, otherwise the whole transaction reverts
toOption<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.

json
msg.rs
Copy

_31
[
_31
{
_31
"astro_swap": {
_31
"offer_asset_info": {
_31
"native_token": {
_31
"denom": "untrn"
_31
}
_31
},
_31
"ask_asset_info": {
_31
"native_token": {
_31
"denom": "factory/neutron1ffus553eet978k024lmssw0czsxwr97mggyv85lpcsdkft8v9ufsz3sa07/astro"
_31
}
_31
}
_31
}
_31
},
_31
{
_31
"pool_swap": {
_31
"pool_addr": "terra1p3sea2vjewtr9ap4hv7nc75k5jc852ftf0w5u06wsk420y5urc9s9xtxdj",
_31
"offer_asset_info": {
_31
"native_token": {
_31
"denom": "ibc/2C962DAB9F57FE0921435426AE75196009FAA1981BF86991203C8411F8980FDB"
_31
}
_31
},
_31
"ask_asset_info": {
_31
"native_token": {
_31
"denom": "ibc/E8481AD838C31D4FC12A504B10F9B4E2F830F8818D2735C2FFC707579B5FA60B"
_31
}
_31
}
_31
}
_31
}
_31
]

VariantsDescription
astro_swapSwap in the factory's pool for this asset pair. The factory must know a pool for the two assets
pool_swapSwap 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).

json
msg.rs
Copy

_7
{
_7
"send": {
_7
"contract": "terra1txm8xcy8mete9e5zh5ktqr4jm4cq4ja8djttg3zkqll64x4ksq7qknaesf",
_7
"amount": "1000000",
_7
"msg": "<base64 of the hook message>"
_7
}
_7
}

ParamsTypeDescription
contractStringThe router address
amountUint128The amount of the CW20 token to swap
msgBinaryBase64 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.

json
msg.rs
Copy

_3
{
_3
"config": {}
_3
}

ParamsTypeDescription
astroport_factoryStringThe 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.

json
msg.rs
Copy

_36
{
_36
"simulate_swap_operations": {
_36
"offer_amount": "10000000",
_36
"operations": [
_36
{
_36
"astro_swap": {
_36
"offer_asset_info": {
_36
"native_token": {
_36
"denom": "uluna"
_36
}
_36
},
_36
"ask_asset_info": {
_36
"native_token": {
_36
"denom": "ibc/2C962DAB9F57FE0921435426AE75196009FAA1981BF86991203C8411F8980FDB"
_36
}
_36
}
_36
}
_36
},
_36
{
_36
"pool_swap": {
_36
"pool_addr": "terra1p3sea2vjewtr9ap4hv7nc75k5jc852ftf0w5u06wsk420y5urc9s9xtxdj",
_36
"offer_asset_info": {
_36
"native_token": {
_36
"denom": "ibc/2C962DAB9F57FE0921435426AE75196009FAA1981BF86991203C8411F8980FDB"
_36
}
_36
},
_36
"ask_asset_info": {
_36
"native_token": {
_36
"denom": "ibc/E8481AD838C31D4FC12A504B10F9B4E2F830F8818D2735C2FFC707579B5FA60B"
_36
}
_36
}
_36
}
_36
}
_36
]
_36
}
_36
}

ParamsTypeDescription
offer_amountUint128The amount of the first offer asset
operationsVec<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.

json
msg.rs
Copy

_21
{
_21
"reverse_simulate_swap_operations": {
_21
"ask_amount": "1000000",
_21
"operations": [
_21
{
_21
"astro_swap": {
_21
"offer_asset_info": {
_21
"native_token": {
_21
"denom": "untrn"
_21
}
_21
},
_21
"ask_asset_info": {
_21
"native_token": {
_21
"denom": "factory/neutron1ffus553eet978k024lmssw0czsxwr97mggyv85lpcsdkft8v9ufsz3sa07/astro"
_21
}
_21
}
_21
}
_21
}
_21
]
_21
}
_21
}

ParamsTypeDescription
ask_amountUint128The amount of the last ask asset to receive
operationsVec<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_swap only (factory pools). native_swap is part of the type but isn't supported on Terra or Neutron, and there is no pool_swap.
  • execute_swap_operations takes operations, an optional minimum_receive, an optional to and an optional max_spread. max_spread is checked on every hop.
  • The config, simulate_swap_operations and reverse_simulate_swap_operations queries 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
}

NOTE

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.