🧱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

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": {}
}

{
  "owner": "terra1c7m6j8ya58a2fkkptn8fgudx8sqjqvc8azq0ex",
  "pair_configs": [
    {
      "code_id": 1793,
      "pair_type": {
        "custom": "XYK-2BPS"
      },
      "total_fee_bps": 30,
      "maker_fee_bps": 667,
      "is_disabled": false
    },
    {
      "code_id": 2264,
      "pair_type": {
        "stable": {}
      },
      "total_fee_bps": 5,
      "maker_fee_bps": 5000,
      "is_disabled": false
    },
    {
      "code_id": 1793,
      "pair_type": {
        "xyk": {}
      },
      "total_fee_bps": 30,
      "maker_fee_bps": 3333,
      "is_disabled": null
    }
  ],
  "token_code_id": 1796,
  "fee_address": "terra12u7hcmpltazmmnq0fvyl225usn3fy6qqlp05w0",
  "generator_address": "terra1zgrx9jjqrfye8swykfgmd6hpde60j0nszzupp9"
}

`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": {}
}

{
  "pairs": {
    "start_after": [
      {
        "token": {
          "contract_addr": "terra..."
        }
      },
      {
        "native_token": {
          "denom": "uusd"
        }
      }
    ],
    "limit": 10
  }
}

{
  "pairs": [
    {
      "asset_infos": [
        {
          "token": {
            "contract_addr": "terra100yeqvww74h4yaejj6h733thgcafdaukjtw397"
          }
        },
        {
          "native_token": {
            "denom": "uusd"
          }
        }
      ],
      "contract_addr": "terra1zpnhtf9h5s7ze2ewlqyer83sr4043qcq64zfc4",
      "liquidity_token": "terra1zuktmswe9zjck0xdpw2k79t0crjk86fljv2rm0",
      "pair_type": {
        "xyk": {}
      }
    },
    {
      "asset_infos": [
        {
          "token": {
            "contract_addr": "terra12897djskt9rge8dtmm86w654g7kzckkd698608"
          }
        },
        {
          "token": {
            "contract_addr": "terra10f2mt82kjnkxqj2gepgwl637u2w4ue2z5nhz5j"
          }
        }
      ],
      "contract_addr": "terra10lv5wz84kpwxys7jeqkfxx299drs3vnw0lj8mz",
      "liquidity_token": "terra1t53c8p0zwvj5xx7sxh3qtse0fq5765dltjrg33",
      "pair_type": {
        "xyk": {}
      }
    },
    {
      "asset_infos": [
        {
          "token": {
            "contract_addr": "terra1pepwcav40nvj3kh60qqgrk8k07ydmc00xyat06"
          }
        },
        {
          "token": {
            "contract_addr": "terra10f2mt82kjnkxqj2gepgwl637u2w4ue2z5nhz5j"
          }
        }
      ],
      "contract_addr": "terra1t59ywlkkmvy7rmkdmdpy0z7wdqez5tne9mrd0r",
      "liquidity_token": "terra1jxhmcjh3ymd32v7e8f5uar92pg3e05yts8z6lf",
      "pair_type": {
        "stable": {}
      }
    },
    {
      "asset_infos": [
        {
          "token": {
            "contract_addr": "terra12897djskt9rge8dtmm86w654g7kzckkd698608"
          }
        },
        {
          "token": {
            "contract_addr": "terra178v546c407pdnx5rer3hu8s2c0fc924k74ymnn"
          }
        }
      ],
      "contract_addr": "terra18hjdxnnkv8ewqlaqj3zpn0vsfpzdt3d0y2ufdz",
      "liquidity_token": "terra1pjfqacx7k6dg63v2h5q96zjg7w5q25093wnkjc",
      "pair_type": {
        "xyk": {}
      }
    },
    {
      "asset_infos": [
        {
          "token": {
            "contract_addr": "terra12897djskt9rge8dtmm86w654g7kzckkd698608"
          }
        },
        {
          "native_token": {
            "denom": "uusd"
          }
        }
      ],
      "contract_addr": "terra1v5ct2tuhfqd0tf8z0wwengh4fg77kaczgf6gtx",
      "liquidity_token": "terra1cspx9menzglmn7xt3tcn8v8lg6gu9r50d7lnve",
      "pair_type": {
        "xyk": {}
      }
    },
    {
      "asset_infos": [
        {
          "token": {
            "contract_addr": "terra12flsr4mk5sxmu8yk7m8zc5f44tfx00yjvzj7v4"
          }
        },
        {
          "native_token": {
            "denom": "uusd"
          }
        }
      ],
      "contract_addr": "terra1vfpfncl2wcxjhatl08mt0j8ppx5vzr6eek0wj2",
      "liquidity_token": "terra1ggz8vxgngjc8atv8z70kdfhmlg534gg0zevfcf",
      "pair_type": {
        "xyk": {}
      }
    },
    {
      "asset_infos": [
        {
          "token": {
            "contract_addr": "terra133chr09wu8sakfte5v7vd8qzq9vghtkv4tn0ur"
          }
        },
        {
          "native_token": {
            "denom": "uusd"
          }
        }
      ],
      "contract_addr": "terra1edurrzv6hhd8u48engmydwhvz8qzmhhuakhwj3",
      "liquidity_token": "terra1qz4cv5lsfw4k2266q52z9rtz64n58paxy9d476",
      "pair_type": {
        "xyk": {}
      }
    },
    {
      "asset_infos": [
        {
          "token": {
            "contract_addr": "terra13xujxcrc9dqft4p9a8ls0w3j0xnzm6y2uvve8n"
          }
        },
        {
          "native_token": {
            "denom": "uusd"
          }
        }
      ],
      "contract_addr": "terra1m95udvvdame93kl6j2mk8d03kc982wqgr75jsr",
      "liquidity_token": "terra14p4srhzd5zng8vghly5artly0s53dmryvg3qc6",
      "pair_type": {
        "xyk": {}
      }
    },
    {
      "asset_infos": [
        {
          "token": {
            "contract_addr": "terra14ec8v4c5dnwu2pq9plfquaffutu59tq9hld77e"
          }
        },
        {
          "native_token": {
            "denom": "uusd"
          }
        }
      ],
      "contract_addr": "terra10k05ec24u8nrd3889c6zydr8tlv73cyhaufs4t",
      "liquidity_token": "terra1y0l4ghzlrrelwawxzgrsgz0xdd0az2h9tvf3hg",
      "pair_type": {
        "xyk": {}
      }
    },
    {
      "asset_infos": [
        {
          "token": {
            "contract_addr": "terra14tl83xcwqjy0ken9peu4pjjuu755lrry2uy25r"
          }
        },
        {
          "native_token": {
            "denom": "uluna"
          }
        }
      ],
      "contract_addr": "terra1m32zs8725j9jzvva7zmytzasj392wpss63j2v0",
      "liquidity_token": "terra1lmlv43teqcty6xldtg4f40sghnd2f8ehjz0qpk",
      "pair_type": {
        "xyk": {}
      }
    }
  ]
}

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"
        }
      }
    ]
  }
}

{
  "create_pair": {
    "pair_type": {
      "stable": {}
    },
    "asset_infos": [
      {
        "token": {
          "contract_addr": "terra..."
        }
      },
      {
        "native_token": {
          "denom": "uusd"
        }
      }
    ],
    "init_params": "<base64_encoded_json_string: Optional binary serialised parameters for custom pool types>"
  }
}

{
  "create_pair": {
    "pair_type": {
      "custom": "XYK-2BPS"
    },
    "asset_infos": [
      {
        "token": {
          "contract_addr": "terra..."
        }
      },
      {
        "native_token": {
          "denom": "uusd"
        }
      }
    ],
    "init_params": "<base64_encoded_json_string: Optional binary serialised parameters for custom pool types>"
  }
}

{
  "create_pair": {
    "pair_type": {
      "xyk": {}
    },
    "asset_infos": [
      {
        "token": {
          "contract_addr": "terra..."
        }
      },
      {
        "token": {
          "contract_addr": "terra..."
        }
      }
    ],
    "init_params": "<base64_encoded_json_string: Optional binary serialised parameters for custom pool types>"
  }
}

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"
        }
      }
    ]
  }
}

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

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": {}
}

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

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": {}
}

{
  "assets": [
    {
      "info": {
        "token": {
          "contract_addr": "terra..."
        }
      },
      "amount": "..."
    },
    {
      "info": {
        "native_token": {
          "denom": "uusd"
        }
      },
      "amount": "..."
    }
  ],
  "total_share": "..."
}

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": {}
}

PreviousAsset NextSwap Pairs

Last updated 3 years ago

hashtag1. Overview

hashtag2. Variables & Functions

hashtagConstants

hashtagStructs

hashtagStruct Logic

hashtagFunctions

hashtag3. Pool Creation & Querying Walkthrough

hashtagFactory Contract Queries

hashtagfee_info

hashtagpairs

hashtagCreate a Pool

hashtagcreate_pair

hashtagDeregister a Pool

hashtagderegister

hashtagAstroport Pair and Liquidity Token Contracts

hashtagAstroport Pair Contract (contract_addr)

hashtagLiquidity Token Contract (liquidity_token)

1. Overview

2. Variables & Functions

Constants

Structs

Struct Logic

Functions

3. Pool Creation & Querying Walkthrough

Factory Contract Queries

`fee_info`

`pairs`

Create a Pool

`create_pair`

Deregister a Pool

`deregister`

Astroport Pair and Liquidity Token Contracts

Astroport Pair Contract (`contract_addr`)

Liquidity Token Contract (`liquidity_token`)