Stableswap Pools

Overview

The stableswap pool uses the 4A(Rx+Ry) + D formula, resulting in a constant price ∆x / ∆y = 1. More details around how the pool functions can be found here.

A stableswap pool holds two assets. New pools mint a tokenfactory LP denom, factory/<pool address>/astroport/share. The pool has an optional owner set in init_params; if none is set, the factory owner acts as owner.

InstantiateMsg

Pools are instantiated by the factory, not directly. The factory passes this message to the pool; you only choose pair_type, asset_infos and init_params in create_pair.

json

pair.rs

{
  "pair_type": {
    "stable": {}
  },
  "asset_infos": [
    {
      "native_token": {
        "denom": "ibc/E8481AD838C31D4FC12A504B10F9B4E2F830F8818D2735C2FFC707579B5FA60B"
      }
    },
    {
      "native_token": {
        "denom": "ibc/2C962DAB9F57FE0921435426AE75196009FAA1981BF86991203C8411F8980FDB"
      }
    }
  ],
  "token_code_id": 69,
  "factory_addr": "terra14x9fr055x5hvr48hzy2t4q7kvjvfttsvxusa4xsdcy702mnzsvuqprer8r",
  "init_params": "eyJhbXAiOjEwMCwib3duZXIiOm51bGx9"
}

Params	Type	Description
`pair_type`	`PairType`	The pool type
`asset_infos`	`Vec<AssetInfo>`	The two assets in the pool
`token_code_id`	`u64`	CW20 code ID kept in the factory config. New pools use a tokenfactory LP denom, so it isn't used for the LP token
`factory_addr`	`String`	The factory contract address
`init_params`	`Option<Binary>`	Required base64-encoded `StablePoolParams`: `amp` (amplification, greater than 0 and at most 1,000,000) and an optional `owner`

ExecuteMsg

`receive`

CW20 receive hook. A CW20 offer asset is swapped by sending it to the pool with the CW20 send message and a base64-encoded swap hook. CW20 tokens can't be swapped with swap directly.

json

pair.rs

{
  "receive": {
    "sender": "terra1...",
    "amount": "1000000",
    "msg": "<base64_encoded_json_string>"
  }
}

Params	Type	Description
`receive`	`Cw20ReceiveMsg`	CW20 receive message

`Cw20HookMsg::Swap`

The hook embedded in msg. The offer asset and amount come from the CW20 transfer.

json

pair.rs

{
  "swap": {
    "ask_asset_info": {
      "native_token": {
        "denom": "ibc/E8481AD838C31D4FC12A504B10F9B4E2F830F8818D2735C2FFC707579B5FA60B"
      }
    },
    "belief_price": "0.25",
    "max_spread": "0.005",
    "to": "terra1..."
  }
}

Params	Type	Description
`ask_asset_info`	`Option<AssetInfo>`	The asset to receive. Optional in a two-asset pool
`belief_price`	`Option<Decimal>`	The price the trader expects, used with `max_spread`
`max_spread`	`Option<Decimal>`	Maximum spread allowed. Defaults to 0.5%, at most 50%
`to`	`Option<String>`	Recipient of the ask asset. Defaults to the CW20 sender

`provide_liquidity`

Deposits assets into the pool and mints LP tokens. Native assets are attached to the message as funds. CW20 assets are pulled with transfer_from, so you must first increase the pool's allowance for them. On the first deposit, a small amount of LP is minted to the pool itself and stays locked.

json

pair.rs

{
  "provide_liquidity": {
    "assets": [
      {
        "info": {
          "native_token": {
            "denom": "ibc/E8481AD838C31D4FC12A504B10F9B4E2F830F8818D2735C2FFC707579B5FA60B"
          }
        },
        "amount": "1000000"
      },
      {
        "info": {
          "native_token": {
            "denom": "ibc/2C962DAB9F57FE0921435426AE75196009FAA1981BF86991203C8411F8980FDB"
          }
        },
        "amount": "1000000"
      }
    ],
    "slippage_tolerance": "0.01",
    "auto_stake": true,
    "receiver": "terra1...",
    "min_lp_to_receive": "990000"
  }
}

Params	Type	Description
`assets`	`Vec<Asset>`	The assets to deposit
`slippage_tolerance`	`Option<Decimal>`	Fails the deposit if the pool price moves more than this against the deposit ratio
`auto_stake`	`Option<bool>`	If true, the minted LP tokens are staked in the Incentives contract on behalf of `receiver`. Defaults to false
`receiver`	`Option<String>`	Receiver of the LP tokens. Defaults to the sender
`min_lp_to_receive`	`Option<Uint128>`	Fails the deposit if fewer LP tokens would be minted

`withdraw_liquidity`

Burns LP tokens and returns the matching share of each pool asset. Attach the LP tokens (the pool's tokenfactory denom, for example factory/terra1...pool/astroport/share) as funds. Only balanced withdrawals are allowed: leave assets empty, otherwise the call fails. LP tokens staked in Incentives must be unstaked first. Older pools with a CW20 LP token are withdrawn from by sending the LP token to the pool with a {"withdraw_liquidity":{}} hook.

json

pair.rs

{
  "withdraw_liquidity": {
    "assets": [],
    "min_assets_to_receive": [
      {
        "info": {
          "native_token": {
            "denom": "uluna"
          }
        },
        "amount": "990000"
      },
      {
        "info": {
          "native_token": {
            "denom": "ibc/E8481AD838C31D4FC12A504B10F9B4E2F830F8818D2735C2FFC707579B5FA60B"
          }
        },
        "amount": "247000"
      }
    ]
  }
}

Params	Type	Description
`assets`	`Vec<Asset>`	Must be empty. Imbalanced withdrawals are disabled
`min_assets_to_receive`	`Option<Vec<Asset>>`	Fails the withdrawal if less than these amounts would be returned

`swap`

Swaps a native offer asset, attached as funds. For a CW20 offer asset use receive.

json

pair.rs

{
  "swap": {
    "offer_asset": {
      "info": {
        "native_token": {
          "denom": "ibc/E8481AD838C31D4FC12A504B10F9B4E2F830F8818D2735C2FFC707579B5FA60B"
        }
      },
      "amount": "1000000"
    },
    "ask_asset_info": {
      "native_token": {
        "denom": "ibc/2C962DAB9F57FE0921435426AE75196009FAA1981BF86991203C8411F8980FDB"
      }
    },
    "belief_price": "0.25",
    "max_spread": "0.005",
    "to": "terra1..."
  }
}

Params	Type	Description
`offer_asset`	`Asset`	The asset and amount to swap. Must match the attached funds
`ask_asset_info`	`Option<AssetInfo>`	The asset to receive. Optional in a two-asset pool
`belief_price`	`Option<Decimal>`	The price the trader expects. With `max_spread`, the swap fails if the return is worse than this price by more than `max_spread`
`max_spread`	`Option<Decimal>`	Maximum spread allowed, before fees. Defaults to 0.5%, at most 50%
`to`	`Option<String>`	Recipient of the ask asset. Defaults to the sender

`update_config`

Changes the amplification or fee sharing. Only the pool owner (or the factory owner if the pool has none) can call it. params is a base64-encoded StablePoolUpdateParams.

json

pair.rs

{
  "update_config": {
    "params": "eyJzdGFydF9jaGFuZ2luZ19hbXAiOnsibmV4dF9hbXAiOjIwMCwibmV4dF9hbXBfdGltZSI6MTczMTMwMDAwMH19"
  }
}

Params	Type	Description
`params`	`Binary`	Base64-encoded `StablePoolUpdateParams`

Variants	Description
`start_changing_amp { next_amp, next_amp_time }`	Moves the amplification gradually to `next_amp`, reached at `next_amp_time`. The change takes at least one day and changes amp by at most a factor of 10
`stop_changing_amp {}`	Stops the change and keeps the current amplification
`enable_fee_share { fee_share_bps, fee_share_address }`	Sends `fee_share_bps` of each swap's fee to `fee_share_address`. Greater than 0 and at most 1000 (10%)
`disable_fee_share`	Stops fee sharing

`propose_new_owner`

Creates an offer to change the pool owner. Only the current owner can call it. The offer expires after expires_in seconds.

json

pair.rs

{
  "propose_new_owner": {
    "owner": "terra1...",
    "expires_in": 604800
  }
}

Params	Type	Description
`owner`	`String`	Newly proposed pool owner
`expires_in`	`u64`	Seconds until the offer expires

`drop_ownership_proposal`

Removes an existing offer to change the pool owner. Only the current owner can call it.

json

pair.rs

{
  "drop_ownership_proposal": {}
}

`claim_ownership`

Accepts an offer. Only the proposed owner can call it.

json

pair.rs

{
  "claim_ownership": {}
}

QueryMsg

`pair`

Returns the pool's PairInfo: its assets, address, LP denom and type.

json

pair.rs

{
  "pair": {}
}

json

{
  "asset_infos": [
    {
      "native_token": {
        "denom": "ibc/E8481AD838C31D4FC12A504B10F9B4E2F830F8818D2735C2FFC707579B5FA60B"
      }
    },
    {
      "native_token": {
        "denom": "ibc/2C962DAB9F57FE0921435426AE75196009FAA1981BF86991203C8411F8980FDB"
      }
    }
  ],
  "contract_addr": "terra1...pool",
  "liquidity_token": "factory/terra1...pool/astroport/share",
  "pair_type": {
    "stable": {}
  }
}

Params	Type	Description
`asset_infos`	`Vec<AssetInfo>`	The pool's assets
`contract_addr`	`Addr`	The pool address
`liquidity_token`	`String`	The LP token: a tokenfactory denom for pools created by current factories, a CW20 address for older pools
`pair_type`	`PairType`	The pool type

`pool`

Returns the pool's asset balances and the total LP supply.

json

pair.rs

{
  "pool": {}
}

`PoolResponse`

json

pair.rs

{
  "assets": [
    {
      "info": {
        "native_token": {
          "denom": "ibc/E8481AD838C31D4FC12A504B10F9B4E2F830F8818D2735C2FFC707579B5FA60B"
        }
      },
      "amount": "1000000000"
    },
    {
      "info": {
        "native_token": {
          "denom": "ibc/2C962DAB9F57FE0921435426AE75196009FAA1981BF86991203C8411F8980FDB"
        }
      },
      "amount": "250000000"
    }
  ],
  "total_share": "500000000"
}

Params	Type	Description
`assets`	`Vec<Asset>`	The assets in the pool with their amounts
`total_share`	`Uint128`	The total amount of LP tokens issued

`config`

Returns the pool configuration.

json

pair.rs

{
  "config": {}
}

`ConfigResponse`

json

pair.rs

{
  "block_time_last": 1730700000,
  "params": "eyJhbXAiOiIxMDAiLCJmZWVfc2hhcmUiOm51bGx9",
  "owner": "terra1k9j8rcyk87v5jvfla2m9wp200azegjz0eshl7n2pwv852a7ssceqsnn7pq",
  "factory_addr": "terra14x9fr055x5hvr48hzy2t4q7kvjvfttsvxusa4xsdcy702mnzsvuqprer8r",
  "tracker_addr": null
}

Params	Type	Description
`block_time_last`	`u64`	Last time the cumulative prices were updated
`params`	`Option<Binary>`	Base64-encoded `StablePoolConfig` (below)
`owner`	`Addr`	The pool owner, or the factory owner if the pool has none
`factory_addr`	`Addr`	The factory contract address
`tracker_addr`	`Option<Addr>`	The tokenfactory tracker contract, if the pool has one

`StablePoolConfig`

json

pair.rs

{
  "amp": "100",
  "fee_share": null
}

Params	Type	Description
`amp`	`Decimal`	The current amplification
`fee_share`	`Option<FeeShareConfig>`	Fee sharing, if enabled: `{ "bps": u16, "recipient": Addr }`

`share`

Returns the assets a given amount of LP tokens can be withdrawn for, as a Vec<Asset>.

json

pair.rs

{
  "share": {
    "amount": "1000000"
  }
}

Params	Type	Description
`amount`	`Uint128`	The amount of LP tokens

`simulation`

Simulates a swap and returns the amount received, the spread and the commission.

json

pair.rs

{
  "simulation": {
    "offer_asset": {
      "info": {
        "native_token": {
          "denom": "ibc/E8481AD838C31D4FC12A504B10F9B4E2F830F8818D2735C2FFC707579B5FA60B"
        }
      },
      "amount": "1000000"
    },
    "ask_asset_info": {
      "native_token": {
        "denom": "ibc/2C962DAB9F57FE0921435426AE75196009FAA1981BF86991203C8411F8980FDB"
      }
    }
  }
}

Params	Type	Description
`offer_asset`	`Asset`	The asset and amount to swap
`ask_asset_info`	`Option<AssetInfo>`	The asset to receive

`SimulationResponse`

json

pair.rs

{
  "return_amount": "249000",
  "spread_amount": "250",
  "commission_amount": "750"
}

Params	Type	Description
`return_amount`	`Uint128`	The amount of the ask asset returned
`spread_amount`	`Uint128`	The spread, in the ask asset
`commission_amount`	`Uint128`	The fee charged, in the ask asset

`reverse_simulation`

Simulates a swap from the ask side: returns the offer amount needed to receive ask_asset.

json

pair.rs

{
  "reverse_simulation": {
    "offer_asset_info": {
      "native_token": {
        "denom": "ibc/E8481AD838C31D4FC12A504B10F9B4E2F830F8818D2735C2FFC707579B5FA60B"
      }
    },
    "ask_asset": {
      "info": {
        "native_token": {
          "denom": "ibc/2C962DAB9F57FE0921435426AE75196009FAA1981BF86991203C8411F8980FDB"
        }
      },
      "amount": "250000"
    }
  }
}

Params	Type	Description
`offer_asset_info`	`Option<AssetInfo>`	The asset to offer
`ask_asset`	`Asset`	The asset and amount to receive

`ReverseSimulationResponse`

json

pair.rs

{
  "offer_amount": "1004000",
  "spread_amount": "250",
  "commission_amount": "750"
}

Params	Type	Description
`offer_amount`	`Uint128`	The amount of the offer asset needed
`spread_amount`	`Uint128`	The spread, in the ask asset
`commission_amount`	`Uint128`	The fee charged, in the ask asset

`cumulative_prices`

Returns the pool's cumulative prices, which can be sampled twice to compute a TWAP.

json

pair.rs

{
  "cumulative_prices": {}
}

`CumulativePricesResponse`

json

pair.rs

{
  "assets": [
    {
      "info": {
        "native_token": {
          "denom": "ibc/E8481AD838C31D4FC12A504B10F9B4E2F830F8818D2735C2FFC707579B5FA60B"
        }
      },
      "amount": "1000000000"
    },
    {
      "info": {
        "native_token": {
          "denom": "ibc/2C962DAB9F57FE0921435426AE75196009FAA1981BF86991203C8411F8980FDB"
        }
      },
      "amount": "250000000"
    }
  ],
  "total_share": "500000000",
  "cumulative_prices": [
    [
      {
        "native_token": {
          "denom": "ibc/E8481AD838C31D4FC12A504B10F9B4E2F830F8818D2735C2FFC707579B5FA60B"
        }
      },
      {
        "native_token": {
          "denom": "ibc/2C962DAB9F57FE0921435426AE75196009FAA1981BF86991203C8411F8980FDB"
        }
      },
      "123456789"
    ],
    [
      {
        "native_token": {
          "denom": "ibc/2C962DAB9F57FE0921435426AE75196009FAA1981BF86991203C8411F8980FDB"
        }
      },
      {
        "native_token": {
          "denom": "ibc/E8481AD838C31D4FC12A504B10F9B4E2F830F8818D2735C2FFC707579B5FA60B"
        }
      },
      "987654321"
    ]
  ]
}

Params	Type	Description
`assets`	`Vec<Asset>`	The assets in the pool with their amounts
`total_share`	`Uint128`	The total amount of LP tokens issued
`cumulative_prices`	`Vec<(AssetInfo, AssetInfo, Uint128)>`	The cumulative price of each asset pair (offer, ask, price)

`observe`

Returns the price observed seconds_ago seconds ago. If there is no observation at that exact time, it is interpolated from the surrounding ones.

json

pair.rs

{
  "observe": {
    "seconds_ago": 3600
  }
}

Params	Type	Description
`seconds_ago`	`u64`	How far back to look, in seconds

`OracleObservation`

json

observation.rs

{
  "timestamp": 1730700000,
  "price": "0.25"
}

Params	Type	Description
`timestamp`	`u64`	The time of the observation
`price`	`Decimal`	The observed price

`query_compute_d`

Returns the current D invariant as a Uint128.

json

pair.rs

{
  "query_compute_d": {}
}

`simulate_provide`

Returns the amount of LP tokens a deposit would mint, as a Uint128.

json

pair.rs

{
  "simulate_provide": {
    "assets": [
      {
        "info": {
          "native_token": {
            "denom": "ibc/E8481AD838C31D4FC12A504B10F9B4E2F830F8818D2735C2FFC707579B5FA60B"
          }
        },
        "amount": "1000000"
      },
      {
        "info": {
          "native_token": {
            "denom": "ibc/2C962DAB9F57FE0921435426AE75196009FAA1981BF86991203C8411F8980FDB"
          }
        },
        "amount": "250000"
      }
    ],
    "slippage_tolerance": "0.01"
  }
}

Params	Type	Description
`assets`	`Vec<Asset>`	The assets to deposit
`slippage_tolerance`	`Option<Decimal>`	The slippage tolerance the deposit would use

`simulate_withdraw`

Returns the assets a given amount of LP tokens would be withdrawn for, as a Vec<Asset>.

json

pair.rs

{
  "simulate_withdraw": {
    "lp_amount": "1000000"
  }
}

Params	Type	Description
`lp_amount`	`Uint128`	The amount of LP tokens

Stableswap Pools

Overview​

Links​

InstantiateMsg​

ExecuteMsg​

receive​

Cw20HookMsg::Swap​

provide_liquidity​

withdraw_liquidity​

swap​

update_config​

propose_new_owner​

drop_ownership_proposal​

claim_ownership​

QueryMsg​

pair​

pool​

PoolResponse​

config​

ConfigResponse​

StablePoolConfig​

share​

simulation​

SimulationResponse​

reverse_simulation​

ReverseSimulationResponse​

cumulative_prices​

CumulativePricesResponse​

observe​

OracleObservation​

query_compute_d​

simulate_provide​

simulate_withdraw​

Overview

Links

InstantiateMsg

ExecuteMsg

`receive`

`Cw20HookMsg::Swap`

`provide_liquidity`

`withdraw_liquidity`

`swap`

`update_config`

`propose_new_owner`

`drop_ownership_proposal`

`claim_ownership`

QueryMsg

`pair`

`pool`

`PoolResponse`

`config`

`ConfigResponse`

`StablePoolConfig`

`share`

`simulation`

`SimulationResponse`

`reverse_simulation`

`ReverseSimulationResponse`

`cumulative_prices`

`CumulativePricesResponse`

`observe`

`OracleObservation`

`query_compute_d`

`simulate_provide`

`simulate_withdraw`