🌊Pool Manager

The Pool Manager is a contract that handles liquidity pools in the MANTRA DEX. The contract facilitates the creation and management of various types of liquidity pools, liquidity provision, token swaps, and multi-hop operations across different pools.

The Pool Manager enables permissionless creation of liquidity pools, requiring a fee to prevent spam. It supports multiple pools for the same asset pair, each with a unique identifier. Users can provide liquidity, perform swaps, and execute multi-hop operations across different pools.

Pool types

There are two types of pools supported by the Pool Manager, constant product (xyk) and stableswaps.

XYK Pool

The xyk pool is based on a constant product invariant:

$$XY=k$$

Where X and Y are the reserves for each token in the pool, while k is a constant. The product of the number of tokens on each side of the pool should remain constant across trading operations. With X being the current balance of the pool's source asset and Y being that of the target asset:

$$XY=k=(X+∆x)(Y−∆y)$$

To determine the value of the ask asset ∆y given the trader's offered asset ∆x:

$$∆y = Y∆x/(X+∆x)$$

The market price is calculated by dividing the number of pool's target token into the source asset (also called the pool ratio).

The spread between the executed and the expected trade is:

$$spread= (Y∆x/X) − (Y∆x/ (X+∆x))$$

The deeper the pool the smaller the spread.

Stableswap

The stableswap pool implements the StableSwap curve described by the Curve protocol @ https://curve.fi/files/stableswap-paper.pdf.

It is possible to create a stableswap pool with 2-4 assets in it, and it is designed to have a low slippage for stable assets, making it ideal for stablecoin trading.

Instantiate

Instantiates an instance of the pool manager contract

{
  "fee_collector_addr": "mantra1...",
  "farm_manager_addr": "mantra1...",
  "pool_creation_fee": {
    "denom": "uom",
    "amount": "1000000000"
  }
}

Key	Type	Description
fee_collector_addr	String	The fee collector contract address.
farm_manager_addr	String	The farm manager contract address.
pool_creation_fee	Coin	How much it costs to create a pool.

ExecuteMsg

CreatePool

Creates a new pool with the provided assets, their decimals for calculation fees, pool type and the identifier for a pool.

Creation of pools in the pool manager is permissionless, but a fee must be paid to create a pool which is specified in the contract configuration. Additionally, the user creating the pool must pay the token factory fee to create a subdenom, since the pool manager uses the token factory to issue the LP tokens.

All pools and their information are stored in the pool manager contract on the POOLS map, and any amount of pools with any variation of assets can be created.

For example, two or more pools with the assets uom and uusdc can be created at anytime with different pool identifiers. A good example is two pools, same assets different pool types (stableswap vs constant product) however any variation is possible.

The contract will assign a prefix to the pool identifier. If the user creates a pool without specifying a custom identifier, the contract will assign the prefix p., followed by a number. For example, p.1, p.2, etc. On the other hand, if the user specifies a custom identifier, the contract will use the prefix o., followed by the custom identifier. For example, o.my_pool.

XYK Pool

{
  "create_pool": {
    "asset_denoms": [
      "uom",
      "uusdc"
    ],
    "asset_decimals": [
      6,
      6
    ],
    "pool_fees": {
      "protocol_fee": {
        "share": "0.001"
      },
      "swap_fee": {
        "share": "0.002"
      },
      "burn_fee": {
        "share": "0"
      },
      "extra_fees": [
        {
          "share": "0.001"
        }
      ]
    },
    "pool_type": "constant_product",
    "pool_identifier": "uom.uusdy.pool"
  }
}

Stableswap

{
  "create_pool": {
    "asset_denoms": [
      "uusdt",
      "uusdc"
    ],
    "asset_decimals": [
      6,
      6
    ],
    "pool_fees": {
      "protocol_fee": {
        "share": "0.0002"
      },
      "swap_fee": {
        "share": "0.0003"
      },
      "burn_fee": {
        "share": "0"
      },
      "extra_fees": []
    },
    "pool_type": {
      "stable_swap": {
        "amp": 85
      }
    },
    "pool_identifier": "uusdt.uusdc.pool"
  }
}

Key	Type	Description
asset_denoms	Vec<String>	The asset denoms for the pool.
asset_decimals	Vec<u8>	The decimals for the given asset denoms, provided in the same order as asset_denoms.
pool_fees	PoolFee	The fees for the pool.
pool_type	PoolType	The type of pool to create. It can be either constant product or stableswap.
pool_identifier	Option<String>	The identifier for the pool. If not set, a number (pool counter) will be assigned as pool id.

ProvideLiquidity

Provides liquidity to the pool specified by the pool_identifier. Liquidity balances are stored on a per-pool basis in order to not double count the assets of other pools with the same assets.

If lock_position_identifier is provided, the LP tokens will be locked in the farm manager for the specified duration.

Otherwise, the LP tokens will be sent to the receiver address.

The amount of liquidity to be provided is determined by the amount of assets provided in info.funds. If only one asset is provided then a single sided liquidity provision will be attempted.

Note: It's only possible to lock an LP position in the farm for the same user providing the liquidity, and not do it on behalf of another user.

{
  "provide_liquidity": {
    "slippage_tolerance": "0.01",
    "max_spread": "0.1",
    "receiver": "mantra1...",
    "pool_identifier": "uom.uusdy.pool",
    "unlocking_duration": 2678400,
    "lock_position_identifier": "lp.lock.identifier"
  }
}

Key	Type	Description
slippage_tolerance	Option<Decimal>	A percentage value representing the acceptable slippage for the operation. When provided, if the slippage exceeds this value, the liquidity provision will not be executed.
max_spread	Option<Decimal>	The decimals for the given asset denoms, provided in the same order as asset_denoms. The maximum allowable spread between the bid and ask prices for the pool. When provided, if the spread exceeds this value, the liquidity provision will not be executed.
receiver	Option<String>	The receiver of the LP.
pool_identifier	String	The identifier for the pool to provide liquidity for.
unlocking_duration	Option<u64>	The amount of time in seconds to unlock tokens if taking part on the farms. If not passed, the tokens will not be locked and the LP tokens will be returned to the user.
lock_position_identifier	Option<String>	The identifier of the position to lock the LP tokens in the farm manager, if any.

Swap

Swaps an offer asset to another asset in the pool specified by the pool_identifier. By providing a pool identifier when performing a swap, only the desired asset need be specified in the swap message The amount to be swapped is provided in info.funds

{
  "swap": {
    "ask_asset_denom": "uusdc",
    "belief_price": "0.5",
    "max_spread": "5000",
    "receiver": "mantra1...",
    "pool_identifier": "uom.uusdy.pool"
  }
}

Key	Type	Description
ask_asset_denom	String	The return asset of the swap.
belief_price	Option<Decimal>	The belief price of the swap.
max_spread	Option<Decimal>	The maximum spread to incur when performing the swap. If the spread exceeds this value, the swap will not be executed.
receiver	Option<String>	The recipient of the output tokens. If not provided, the tokens will be sent to the sender of the message.
pool_identifier	String	The identifier for the pool to swap in.

WithdrawLiquidity

Withdraws liquidity from the pool specified by the pool_identifier. A withdrawal of liquidity will result in the burning of any LP tokens that are returned as a part of the withdrawal. The LP token should be sent in the transaction.

{
  "withdraw_liquidity": {
    "pool_identifier": "uom.uusdy.pool"
  }
}

Key	Type	Description
pool_identifier	String	The identifier for the pool to withdraw from.

ExecuteSwapOperations

Execute multiple SwapOperations to allow for multi-hop swaps. The routes are to be computed off-chain and passed in to the contract.

{
  "execute_swap_operations": {
    "operations": [
      {
        "mantra_swap": {
          "token_in_denom": "uluna",
          "token_out_denom": "uom",
          "pool_identifier": "uluna_uom_pool"
        }
      },
      {
        "mantra_swap": {
          "token_in_denom": "uom",
          "token_out_denom": "uusdc",
          "pool_identifier": "uom.uusdy.pool"
        }
      }
    ],
    "minimum_receive": "1000000",
    "receiver": "mantra1...",
    "max_spread": "0.1"
  }
}

Key	Type	Description
operations	Vec<SwapOperation>	The operations that should be performed in sequence. The amount in each swap will be the output from the previous swap. The first swap will use whatever funds are sent in the [MessageInfo].
minimum_receive	Option<Uint128>	The minimum amount of the output (i.e., final swap operation token) required for the message to succeed.
receiver	Option<String>	The (optional) recipient of the output tokens. If left unspecified, tokens will be sent to the sender of the message.
max_spread	Option<Decimal>	The (optional) maximum spread to incur when performing any swap. Maximum 50%. If left unspecified, it will use the default max spread value from the contract.

UpdateConfig

Updates the configuration of the contract. If a field is not specified (i.e., set to None), it will not be modified.

{
  "update_config": {
    "fee_collector_addr": "mantra1...",
    "farm_manager_addr": "mantra1...",
    "pool_creation_fee": {
      "denom": "uom",
      "amount": "1000000000"
    },
    "feature_toggle": {
      "withdrawals_enabled": true,
      "deposits_enabled": true,
      "swaps_enabled": true
    }
  }
}

Key	Type	Description
fee_collector_addr	Option<String>	The new fee collector contract address.
farm_manager_addr	Option<String>	The new farm manager contract address.
pool_creation_fee	Option<Coin>	The new fee that must be paid when a pool is created.
feature_toggle	Option<FeatureToggle>	The new feature toggles of the contract, allowing fine-tuned control over which operations are allowed.

UpdateOwnership(::cw_ownable::Action)

Implements cw_ownable. Updates the contract's ownership. ::cw_ownable::Action can be TransferOwnership, AcceptOwnership and RenounceOwnership.

Note: This is a cw_ownable message.

TransferOwnership

Propose to transfer the contract's ownership to another account, optionally with an expiry time. Can only be called by the contract's current owner. Any existing pending ownership transfer is overwritten.

{
  "update_ownership": {
    "transfer_ownership": {
      "new_owner": "mantra1...",
      "expiry": {
        "at_height": "424242424242"
      }
    }
  }
}

Key	Type	Description
new_owner	String	The new owner proposed,
expiry	Option<Expiration>	Optional expiration time parameter.

AcceptOwnership

Accept the pending ownership transfer. Can only be called by the pending owner.

{
  "update_ownership": {
    "accept_ownership": {}
  }
}

RenounceOwnership

Give up the contract's ownership and the possibility of appointing a new owner. Can only be invoked by the contract's current owner. Any existing pending ownership transfer is canceled.

{
  "update_ownership": {
    "renounce_ownership": {}
  }
}

QueryMsg

Config

Returns the configuration of the contract.

Query

{
  "config": {}
}

Response (ConfigResponse)

{
  "config": {
    "fee_collector_addr": "mantra1...",
    "farm_manager_addr": "mantra1...",
    "pool_creation_fee": {
      "denom": "uom",
      "amount": "1000000"
    },
    "feature_toggle": {
      "withdrawals_enabled": true,
      "deposits_enabled": true,
      "swaps_enabled": true
    }
  }
}

Key	Type	Description
config	Config	The contract configuration.

AssetDecimals

Retrieves the decimals for the given asset in a specific pool.

Query

{
  "asset_decimals": {
    "pool_identifier": "om-usdc-1",
    "denom": "uom"
  }
}

Key	Type	Description
pool_identifier	String	The pool identifier to do the query for.
denom	String	The queried denom in the given pool_identifier.

Response (AssetDecimalsResponse)

{
  "pool_identifier": "om-usdc-1",
  "denom": "uom",
  "decimals": 6
}

Key	Type	Description
pool_identifier	String	The pool identifier to do the query for.
denom	String	The queried denom in the given pool_identifier.
decimals	u8	The decimals for the requested denom.

Simulation

Simulates a swap.

Query

{
  "simulation": {
    "offer_asset": {
      "denom": "uom",
      "amount": "1000000"
    },
    "ask_asset_denom": "uusdc",
    "pool_identifier": "om-usdc-1"
  }
}

Key	Type	Description
offer_asset	Coin	The offer asset to swap.
ask_asset_denom	String	The ask asset denom to get.
pool_identifier	String	The pool identifier to swap in.

Response (SimulationResponse)

{
  "return_amount": "990000",
  "spread_amount": "5000",
  "swap_fee_amount": "3000",
  "protocol_fee_amount": "2000",
  "burn_fee_amount": "0",
  "extra_fees_amount": "0"
}

Key	Type	Description
return_amount	Uint128	The return amount of the ask asset given the offer amount.
spread_amount	Uint128	The spread amount of the swap.
swap_fee_amount	Uint128	The swap fee amount of the swap.
protocol_fee_amount	Uint128	The protocol fee amount of the swap.
burn_fee_amount	Uint128	The burn fee amount of the swap.
extra_fees_amount	Uint128	The extra fees amount of the swap.

ReverseSimulation

Simulates a reverse swap.

Query

{
  "reverse_simulation": {
    "ask_asset": {
      "denom": "uusdc",
      "amount": "990000"
    },
    "offer_asset_denom": "uom",
    "pool_identifier": "om-usdc-1"
  }
}

Key	Type	Description
ask_asset	Coin	The ask asset to get after the swap.
offer_asset_denom	String	The offer asset denom to input.
pool_identifier	String	The pool identifier to swap in.

Response (ReverseSimulationResponse)

{
  "offer_amount": "1000000",
  "spread_amount": "5000",
  "swap_fee_amount": "3000",
  "protocol_fee_amount": "2000",
  "burn_fee_amount": "0",
  "extra_fees_amount": "0"
}

Key	Type	Description
offer_amount	Uint128	The amount of the offer asset needed to get the ask amount.
spread_amount	Uint128	The spread amount of the swap.
swap_fee_amount	Uint128	The swap fee amount of the swap.
protocol_fee_amount	Uint128	The protocol fee amount of the swap.
burn_fee_amount	Uint128	The burn fee amount of the swap.
extra_fees_amount	Uint128	The extra fees amount of the swap.

SimulateSwapOperations

Simulates swap operations.

Query

{
  "simulate_swap_operations": {
    "offer_amount": "1000000",
    "operations": [
      {
        "mantra_swap": {
          "token_in_denom": "uom",
          "token_out_denom": "uusdc",
          "pool_identifier": "om-usdc-1"
        }
      },
      {
        "mantra_swap": {
          "token_in_denom": "uusdc",
          "token_out_denom": "uatom",
          "pool_identifier": "usdc-atom-1"
        }
      }
    ]
  }
}

Key	Type	Description
offer_amount	Uint128	The amount to swap.
operations	Vec<SwapOperation>	The operations to perform.

Response (SimulateSwapOperationsResponse)

{
  "return_amount": "980000",
  "spreads": [
    {
      "denom": "uusdc",
      "amount": "3"
    },
    {
      "denom": "uatom",
      "amount": "5"
    }
  ],
  "swap_fees": [
    {
      "denom": "uusdc",
      "amount": "500"
    },
    {
      "denom": "uatom",
      "amount": "100"
    }
  ],
  "protocol_fees": [
    {
      "denom": "uusdc",
      "amount": "100"
    },
    {
      "denom": "uatom",
      "amount": "50"
    }
  ],
  "burn_fees": [
    {
      "denom": "uusdc",
      "amount": "10"
    },
    {
      "denom": "uatom",
      "amount": "5"
    }
  ],
  "extra_fees": [
    {
      "denom": "uusdc",
      "amount": "5"
    },
    {
      "denom": "uatom",
      "amount": "5"
    }
  ]
}

Key	Type	Description
return_amount	Uint128	The return amount of the ask asset after the swap operations.
spreads	Vec<Coin>	The spreads of the swap.
swap_fees	Vec<Coin>	The swap fees of the swap.
protocol_fees	Vec<Coin>	The protocol fees of the swap.
burn_fees	Vec<Coin>	The burn fees of the swap.
extra_fees	Vec<Coin>	The extra fees of the swap.

ReverseSimulateSwapOperations

Simulates reverse swap operations.

Query

{
  "reverse_simulate_swap_operations": {
    "ask_amount": "980000",
    "operations": [
      {
        "mantra_swap": {
          "token_in_denom": "uom",
          "token_out_denom": "uusdc",
          "pool_identifier": "om-usdc-1"
        }
      },
      {
        "mantra_swap": {
          "token_in_denom": "uusdc",
          "token_out_denom": "uatom",
          "pool_identifier": "usdc-atom-1"
        }
      }
    ]
  }
}

Key	Type	Description
ask_amount	Uint128	The amount to get after the swap.
operations	Vec<SwapOperation>	The operations to perform.

Response (ReverseSimulateSwapOperationsResponse)

{
  "offer_amount": "1000000",
  "spreads": [
    {
      "denom": "uusdc",
      "amount": "3"
    },
    {
      "denom": "uatom",
      "amount": "5"
    }
  ],
  "swap_fees": [
    {
      "denom": "uusdc",
      "amount": "500"
    },
    {
      "denom": "uatom",
      "amount": "100"
    }
  ],
  "protocol_fees": [
    {
      "denom": "uusdc",
      "amount": "100"
    },
    {
      "denom": "uatom",
      "amount": "50"
    }
  ],
  "burn_fees": [
    {
      "denom": "uusdc",
      "amount": "10"
    },
    {
      "denom": "uatom",
      "amount": "5"
    }
  ],
  "extra_fees": [
    {
      "denom": "uusdc",
      "amount": "5"
    },
    {
      "denom": "uatom",
      "amount": "5"
    }
  ]
}

Key	Type	Description
offer_amount	Uint128	The amount of the initial token needed to get the final token after the swap operations.
spreads	Vec<Coin>	The spreads of the swap.
swap_fees	Vec<Coin>	The swap fees of the swap.
protocol_fees	Vec<Coin>	The protocol fees of the swap.
burn_fees	Vec<Coin>	The burn fees of the swap.
extra_fees	Vec<Coin>	The extra fees of the swap.

Pools

Retrieves the pool information for the given pool identifier or all pools.

Query

{
  "pools": {
    "pool_identifier": "om-usdc-1",
    "start_after": null,
    "limit": 10
  }
}

Key	Type	Description
pool_identifier	Option<String>	An optional parameter specifying the pool identifier to do the query for. If not provided, it will return all pools based on the pagination parameters.
start_after	Option<String>	An optional parameter specifying what pool (identifier) to start searching after.
limit	Option<u32>	The amount of pools to return. If unspecified, will default to a value specified by the contract.

Response (PoolsResponse)

{
  "pools": [
    {
      "pool_info": {
        "pool_identifier": "om-usdc-1",
        "asset_denoms": [
          "uom",
          "uusdc"
        ],
        "lp_denom": "uom_uusdc_lp",
        "asset_decimals": [
          6,
          6
        ],
        "assets": [
          {
            "denom": "uom",
            "amount": "1000000"
          },
          {
            "denom": "uusdc",
            "amount": "1000000"
          }
        ],
        "pool_type": {
          "constant_product": {}
        },
        "pool_fees": {
          "protocol_fee": "0.003",
          "swap_fee": "0.003",
          "burn_fee": "0.0"
        }
      },
      "total_share": {
        "denom": "uom_uusdc_lp",
        "amount": "1000000"
      }
    }
  ]
}

Key	Type	Description
pools	Vec<PoolInfoResponse>	The pools information responses.

Ownership

Returns the ownership of the contract.

Note: This is a cw_ownable query.

Query

{
  "ownership": {}
}

Response (::cw_ownable::Ownership<String>)

{
  "owner": "mantra1...",
  "pending_owner": "mantra1...",
  "pending_expiry": 424242424242
}

Key	Type	Description
owner	Option	The contract's current owner. None if the ownership has been renounced.
pending_owner	Option	The account who has been proposed to take over the ownership. None if there isn't a pending ownership transfer.
pending_expiry	Option	The deadline for the pending owner to accept the ownership. None if there isn't a pending ownership transfer, or if a transfer exists and it doesn't have a deadline.

MigrateMsg

Message to migrate the contract to a new code ID.

{}