🧱Astroport Factory

Contract used to create new Astroport pairs

1. Overview

The factory contract can create new Astroport pair contracts which are tracked in a registry. Right now, the only available pair types are constant product, stableswap, and non-boosted constant product pairs.

The factory contract code can be found here.

2. Variables & Functions

Constants

Name
Description

CONTRACT_NAME

The factory contract name

CONTRACT_VERSION

The current factory version

INSTANTIATE_PAIR_REPLY_ID

A reply call code ID used in a sub-message

TMP_PAIR_INFO

Mapping that saves pair info key

CONFIG

Struct that stores general contract params

PAIRS

Array that stores created pairs, in the order they were created

PAIR_CONFIGS

Mapping that stores configurations for each pair type

MAX_LIMIT

The maximum amount of pairs that can be retrieved at once when querying for data

DEFAULT_LIMIT

The default amount of pairs that are retrieved when querying for data

OWNERSHIP_PROPOSAL

Struct that stores the latest ownership transfer proposal

Structs

Name
Description
Contains

InstantiateMsg

This struct holds data used to instantiate the factory contract

  • pair_configs - Initial pair type configurations available in the factory

  • token_code_id - The code ID of the token implementation used in Astroport pairs (CW20)

  • fee_address - The Maker contract address

  • generator_address - The Generator contract address

  • owner - The address of the contract owner

  • whitelist_code_id - CW1 w

Config

This struct holds general contract parameters

  • owner - The current contract owner

  • token_code_id - The code ID of the token implementation used in Astroport pairs (CW20)

  • generator_address - The Generator contract address

  • fee_address - The Maker contract address

  • whitelist_code_id - CW1 whitelist contract code id used to store 3rd party rewards for staking Astroport LP tokens

TmpPairInfo

This is an intermediate struct for storing a pair's key. It is used in a sub-message response.

  • pair_key - The key (uint8) associated with a pair in the factory

UpdateConfig

This struct holds newly proposed config parameters used to update values in the factory contract.

  • token_code_id - The code ID of the token implementation used in Astroport pairs (CW20)

  • fee_address - The Maker contract address

  • generator_address - The Generator contract address

  • whitelist_code_id - CW1 whitelist contract code id used to store 3rd party rewards for staking Astroport LP tokens

PairConfig

This struct holds data about a pair type's configuration.

  • code_id - The code ID used to instantiate pairs of this type

  • pair_type - The pair type (XYK, stableswap etc)

  • total_fee_bps - The total amount of fees charged on a swap (e.g if set to 30, it means 30 bps)

  • maker_fee_bps - The amount of fees (out of total fees) that go to governance (e.g if set to 3333, 33.33% of the fees go to governance; max possible is 10,000 which is 100%)

  • is_disabled - Whether the pair type is disabled which means no more pairs of this type can be created

ConfigResponse

This struct holds parameters returned when someone queries the contract configuration.

  • owner - the current contract owner

  • pair_configs - The current available pair type configurations

  • token_code_id - The code ID of the token implementation used in Astroport pairs (CW20)

  • fee_address - The Maker contract address

  • generator_address - The Generator contract address

  • whitelist_code_id - CW1 whitelist contract code id used to store 3rd party rewards for staking Astroport LP tokens

MigrateMsg

This struct holds parameters used in a contract migration.

  • whitelist_code_id - CW1 whitelist contract code id used to store 3rd party staking rewards for Astroport LP tokens

PairsResponse

This struct is used to return an array of PairInfo structs.

  • pairs - The array of pairs being returned

FeeInfoResponse

This struct holds returns the fee configuration for a specific pair type.

  • fee_address - The Maker contract address

  • total_fee_bps - The total amount of fees charged on a swap (e.g if set to 30, it means 30 bps)

  • maker_fee_bps - The amount of fees (out of total fees) that go to governance (e.g if set to 3333, 33.33% of the fees go to governance; max possible is 10,000 which is 100%)

ConfigV100

This struct holds general contract parameters.

  • owner - the current contract owner

  • token_code_id - The code ID of the token implementation used in Astroport pairs (CW20)

  • generator_address - The Generator contract address

  • fee_address - The Maker contract address

Struct Logic

Name
Description

PairConfig

The implementation checks if total_fee_bps and maker_fee_bps are both lower than or equal to 10,000

Functions

Name
Params
Description

pair_key

(asset_infos: &[AssetInfo; 2]) -> Vec<u8>

Retrieve the key for a specific pair. AssetInfo is imported from the asset file

read_pairs

(deps: Deps, start_after: Option<[AssetInfo; 2]>, limit: Option<u32>) -> Vec<Addr>

Return an array of pair addresses; start to read pair addresses from the pair that has the assets specified in start_after. AssetInfo is imported from the asset file

query_pair_info

(deps: Deps, pair_contract: &Addr) -> StdResult<PairInfo>

Return the information about a specific pair by passing a reference to a pair contract address. PairInfo is imported from the asset file

instantiate

(deps: DepsMut, _env: Env, _info: MessageInfo, msg: InstantiateMsg) -> Result<Response, ContractError>

Instantiate the factory contract

execute

(deps: DepsMut, env: Env, info: MessageInfo, msg: ExecuteMsg) -> Result<Response, ContractError>

Execute a function from the contract

execute_update_config

(deps: DepsMut, _env: Env, info: MessageInfo, param: UpdateConfig) -> Result<Response, ContractError>

Update the general contract configuration. Only the owner can call this

execute_update_pair_config

(deps: DepsMut, info: MessageInfo, pair_config: PairConfig) -> Result<Response, ContractError>

Update the configuration for a pair type. Only the owner can call this

execute_create_pair

(deps: DepsMut, env: Env, pair_type: PairType, asset_infos: [AssetInfo; 2], init_params: Option<Binary>)

create a new Astroport pair. Anyone can call this function. A pair can only be created if the assets mentioned in asset_infos don't already have a pair. AssetInfo is imported from the asset file

deregister

(deps: DepsMut, info: MessageInfo, asset_infos: [AssetInfo; 2]) -> Result<Response, ContractError>

Deregister a pair from the factory. Someone else can create a new pair for the assets in asset_infos. AssetInfo is imported from the asset file

query

(deps: Deps, _env: Env, msg: QueryMsg) -> StdResult<Binary>

Access point for all contract queries

query

(deps: Deps, _env: Env, msg: QueryMsg) -> StdResult<ConfigResponse>

Return the contract configuration

query_pair

(deps: Deps, asset_infos: [AssetInfo; 2]) -> StdResult<PairInfo>

Retrieve information about a specific pair. PairInfo and AssetInfo are imported from the asset file

query_pairs

(deps: Deps, start_after: Option<[AssetInfo; 2]>, limit: Option<u32>) -> StdResult<PairsResponse>

Return information about multiple pairs. AssetInfo is imported from the asset file

query_fee_info

(deps: Deps, pair_type: PairType) -> StdResult<FeeInfoResponse>

Return the fee configuration for a specific pair type

migrate

(deps: DepsMut, _env: Env, msg: MigrateMsg) -> Result<Response, ContractError>

Migrate the contract to a new implementation

3. Pool Creation & Querying Walkthrough

The following are examples and descriptions of core functions that can be called by anyone to create and query Astroport pairs.

Each pool within an AMM system may use a different algorithm for swapping tokens and determining token prices based on the ratio of the two tokens in the pool — thus, we say that these different algorithms define different "pool types".

Different tokens have different properties and characteristics; therefore, different pool types can be more or less appropriate for a particular token. Choosing the appropriate pool type for a given token can increase efficiency for both traders and LPs. Right now, the Factory contract stores the following pool types:

  • Constant Product Pools - Good choice for pairs with high volatility (e.g. mBTC-UST), as they facilitate trading at all possible prices, even during large, sudden market moves.

  • Stableswap Pools - Most suitable for ‘stable’ pairs, where each token is meant to represent the same underlying value.

  • Non-Boosted Constant Product Pools - Works just like Astroport’s standard constant product pools. However, they send a much larger percentage of their fees to LPs but in return, they are not eligible for ASTRO emissions. Altering the fee structure for these long-tail pools will make Astroport competitive with other Terra DEXs where fees go entirely to LPs.

Total fee and reward details for different pool types are listed below:

Pool Type
Total Fee
Fee Split
Eligible for ASTRO Emissions

Constant Product

0.3% / 30bps

0.2% -> LPs 0.1% -> ASTRO Stakers

Yes

Stableswap

0.05% / 5bps

0.025% -> LPs 0.025% -> ASTRO Stakers

Yes

Non-Boosted Constant Product

0.3% / 30bps

0.28% -> LPs 0.02% -> ASTRO Stakers

No

Factory Contract Queries

query_config

The factory contract can be queried for data about each pool type. Calling the query_config function will return:

  • the owner of the contract. After the initial bootstrapping of Astroport contracts, ownership will be transferred from the Astroport Multisig to the Astral Assembly Contract.

  • the different pair_types ("xyk", "stable", and "XYK-2BPS")

  • the total_fee_bps for each pool (30bps for "xyk" / "XYK-2BPS" pools and 5bps for "stable"pools)

  • the maker_fee_bps for each pool (50%, 33.3%, and 6.67% for "stable", "xyk", and "XYK-2BPS"pools respectively)

  • the fee_address (Maker Contract)

{
  "config": {}
}

fee_info

The Factory contract also allows queries for the fee_info for individual pair_types. These queries return the fee_address, the total_fee_bps, and the maker_fee_bps for each. 

{
  "fee_info": {
    "pair_type": {
        "xyk": {}
      }
  }
}

pairs

The Factory contract can be queried for paginated information about multiple pairs, including their contract_addr and liquidity_token. The query accepts a limit for the number of pairs to return and a timestamp to start_after (pools that were created after start_after are taken into consideration). 

{
  "pairs": {}
}

Create a Pool

create_pair

When an address executes the CreatePair operation, it creates an Astroport Pair contract and an associated Liquidity Token contract. It also creates a PairInfo struct with information about the newly created pair.

The CreatePair operation takes in a pair_type and asset_infos for each of the two tokens in the pool. asset_infos for each token can include a CW-20 contract_addr or a native_token denomination. init_params accepts binary serialized parameters for custom pool types.

{
  "create_pair": {
    "pair_type": {
      "xyk": {}
    },
    "asset_infos": [
      {
        "token": {
          "contract_addr": "terra..."
        }
      },
      {
        "native_token": {
          "denom": "uusd"
        }
      }
    ]
  }
}

Deregister a Pool

deregister

An address can execute the deregister operation to deregister an already registered pair (deletes a pair from the factory). Deregistering is subject to a governance decision.

The deregister operation takes inasset_info for each of the two tokens in the pool. asset_info for each token can include a CW-20 contract_addr or a native_token denomination. 

{
  "deregister": {
    "asset_infos": [
      {
        "token": {
          "contract_addr": "terra..."
        }
      },
      {
        "native_token": {
          "denom": "uusd"
        }
      }
    ]
  }
}

Astroport Pair and Liquidity Token Contracts

pair

After executing the CreatePair operation, the factory contract can be queried to reveal an Astroport pair's contract_addr and liquidity token. The pair query takes in asset_infos for each of the two tokens in a given pool and returns information about the specific pair. asset_infos for each token can include a CW-20 contract_addr or a native_token denomination. 

{
  "pair": {
    "asset_infos": [
        {
          "token": {
            "contract_addr": "terra..."
        }
        },
        {
          "native_token": {
            "denom": "uusd"
        }
      }
    ]
  }
}

Astroport Pair Contract (contract_addr)

pair

The contract_addr for an Astroport pair can also be queried to confirm the same information returned in the Factory pair query.

{
  "pair": {}
}

pool

The contract_addr for an Astroport pair can be queried for general information regarding the pool, including the amount of tokens deposited into the pair and the total_share which is the total amount of LP tokens currently issued. 

{
  "pool": {}
}

Liquidity Token Contract (liquidity_token)

balance

The liquidity_token contract for an Astroport pair can be queried to return a balance, or the amount of LP tokens a specific address has. 

{
  "balance": {
    "address": "terra..."
  }
}

token_info

The liquidity_token contract for an Astroport pair can be queried to return token_info, including the name of the LP token, its symbol and the total_supply. 

{
  "token_info": {}
}

minter

The liquidity_token contract can be queried to return the minter address. The minter address should be the same as the contract_addr, which is a pool created by the Factory contract. 

{
  "minter": {}
}
PreviousAssetNextSwap Pairs

Last updated

Was this helpful?