Passive Concentrated Liquidity Pools
Overview
Astroport's passive concentrated liquidity (PCL) pools optimize for a passive and automatic LP experience for concentrated liquidity. Instead of depositors actively managing their price ranges, liquidity becomes concentrated around an internal oracle price, the moving average of recent trades in a pair.
More details around how PCL pools function can be found here.
PCL pools are a custom pool type ({"custom": "concentrated"}) and hold two assets. New pools mint a tokenfactory LP denom, factory/<pool address>/astroport/share. The pool owner (the factory owner unless ownership was transferred) can change its parameters.
Links
- Contract Repo: https://github.com/astroport-fi/astroport-core/tree/main/contracts/pair_concentrated
- contract.rs: https://github.com/astroport-fi/astroport-core/blob/main/contracts/pair_concentrated/src/contract.rs
- pair_concentrated.rs: https://github.com/astroport-fi/astroport-core/blob/main/packages/astroport/src/pair_concentrated.rs
- Tests: https://github.com/astroport-fi/astroport-core/tree/main/contracts/pair_concentrated/tests
- Version documented:
astroport-pair-concentrated4.3.0 (astroport-core main). Pools created at different times can run older versions; a pool's cw2contract_infoshows its version.
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.
| 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 ConcentratedPoolParams (below) |
ConcentratedPoolParams
The values below are an example only.
| Params | Type | Description |
|---|---|---|
amp | Decimal | Amplification coefficient; affects trades close to price_scale |
gamma | Decimal | How gradually the curve moves from constant sum to constant product as the price moves away from price_scale. Lower is more gradual |
mid_fee | Decimal | The minimum fee, charged when the pool is balanced |
out_fee | Decimal | The maximum fee, charged when the pool is imbalanced |
fee_gamma | Decimal | How gradually the fee moves from mid_fee to out_fee |
repeg_profit_threshold | Decimal | Minimum profit before a repeg |
min_price_scale_delta | Decimal | Minimum change of price_scale when repegging |
price_scale | Decimal | Initial price scale: 1 x[0] = price_scale * x[1] |
ma_half_time | u64 | Half-time of the internal price oracle, in seconds |
track_asset_balances | Option<bool> | Record asset balances per block. Can't be turned off later |
fee_share | Option<FeeShareConfig> | Fee sharing: { "bps": u16, "recipient": Addr } |
allowed_xcp_profit_drop | Option<Decimal> | Allowed drop of xCP profit on each repeg attempt |
xcp_profit_losses_threshold | Option<Decimal> | Cap on total xCP profit losses |
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.
| 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.
| 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. The first deposit needs both assets; after that, single-sided deposits are accepted.
| 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.
| 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.
| 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 pool parameters. Only the pool owner can call it. params is a base64-encoded ConcentratedPoolUpdateParams.
| Params | Type | Description |
|---|---|---|
params | Binary | Base64-encoded ConcentratedPoolUpdateParams |
| Variants | Description |
|---|---|
update { ... } | Changes the fee parameters, repeg_profit_threshold, min_price_scale_delta, ma_half_time and the xCP profit limits immediately. Every field is optional |
promote { next_amp, next_gamma, future_time } | Moves amp and gamma gradually to the new values, reached at future_time |
stop_changing_amp_gamma {} | Stops an amp/gamma change and keeps the current values |
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.
| 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.
claim_ownership
Accepts an offer. Only the proposed owner can call it.
QueryMsg
pair
Returns the pool's PairInfo: its assets, address, LP denom and type.
| 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.
PoolResponse
| 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.
ConfigResponse
| Params | Type | Description |
|---|---|---|
block_time_last | u64 | Last time the cumulative prices were updated |
params | Option<Binary> | Base64-encoded ConcentratedPoolConfig (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 |
ConcentratedPoolConfig
| Params | Type | Description |
|---|---|---|
amp | Decimal | The current amplification |
gamma | Decimal | The current gamma |
price_scale | Decimal | The current price scale |
share
Returns the assets a given amount of LP tokens can be withdrawn for, as a Vec<Asset>.
| Params | Type | Description |
|---|---|---|
amount | Uint128 | The amount of LP tokens |
simulation
Simulates a swap and returns the amount received, the spread and the commission.
| Params | Type | Description |
|---|---|---|
offer_asset | Asset | The asset and amount to swap |
ask_asset_info | Option<AssetInfo> | The asset to receive |
SimulationResponse
| 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.
| Params | Type | Description |
|---|---|---|
offer_asset_info | Option<AssetInfo> | The asset to offer |
ask_asset | Asset | The asset and amount to receive |
ReverseSimulationResponse
| 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.
CumulativePricesResponse
| 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.
| Params | Type | Description |
|---|---|---|
seconds_ago | u64 | How far back to look, in seconds |
OracleObservation
| Params | Type | Description |
|---|---|---|
timestamp | u64 | The time of the observation |
price | Decimal | The observed price |
compute_d
Returns the current D invariant as a Decimal256.
lp_price
Returns the LP token's virtual price as a Decimal256.
asset_balance_at
Returns the pool's balance of an asset just before the given block height, or null if balances weren't tracked then. Balances are only tracked if the pool was created with track_asset_balances set.
| Params | Type | Description |
|---|---|---|
asset_info | AssetInfo | The pool asset to query |
block_height | Uint64 | The block height |
simulate_provide
Returns the amount of LP tokens a deposit would mint, as a Uint128.
| 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>.
| Params | Type | Description |
|---|---|---|
lp_amount | Uint128 | The amount of LP tokens |
MigrateMsg
Version 4.3 adds an optional exit-only mode to the migration. Migrating with exit_only set stops swaps, deposits and price queries, and later withdrawals pay out every asset except withheld, which stays in the pool. Only a migration sets it and there is no way back out. This is separate from the exit-only pool contract, which pays out every asset.
| Params | Type | Description |
|---|---|---|
exit_only | Option<ExitOnly> | If set, puts the pool in exit-only mode with withheld kept in the pool. Omit it ({}) for a normal migration |