Creating a Pair
Overview
The Factory creates new pool contracts and keeps a registry of them. Anyone can create a pool for a new asset pair with create_pair, as long as the pool type is not permissioned or disabled. The factory registers one pool per asset pair: if a pool for the pair already exists, whatever its type, create_pair fails with Pair was already created.
| Chain | Factory |
|---|---|
| Terra | terra14x9fr055x5hvr48hzy2t4q7kvjvfttsvxusa4xsdcy702mnzsvuqprer8r |
| Neutron | neutron1hptk0k5kng7hjy35vmh009qd5m6l33609nypgf2yc6nqnewduqasxplt4e |
Pool types anyone can create on both chains:
pair_type | Pool | Swap fee | Notes |
|---|---|---|---|
{"xyk": {}} | Constant product | 0.30% | No init_params needed |
{"stable": {}} | Stableswap | 0.05% | init_params with amp |
{"custom": "concentrated"} | PCL | Dynamic, set in the pool parameters | init_params with the PCL parameters |
On Neutron the factory also offers {"custom": "concentrated_duality_orderbook"}. Transmuter pools are permissioned. The live list, with fees and flags, is the factory's config query (pair_configs). The Maker's share of the swap fee goes to the protocol (see Maker); the rest stays in the pool for liquidity providers.
Stableswap and PCL pools need the decimals of every native asset in the pool. They read them from the native coin registry (Terra terra1zuf8fla02926nhpfvk09k2pg6qv9aayflp0qt4a0msppu2h4exqs6af275, Neutron neutron1jzzv6r5uckwd64n6qan3suzker0kct5w565f6529zjyumfcx96kqtcswn3). Check a denom with {"native_token": {"denom": "..."}}. If it isn't registered, anyone can register it with {"register": {"native_coins": [["<denom>", 6]]}}, sending a small amount of each listed coin with the message; the coins are returned.
Constant Product Pools
create_pair takes the pair_type and the two assets as AssetInfo values. This example creates an xyk pool for a new tokenfactory token against NTRN on Neutron:
_19{_19 "create_pair": {_19 "pair_type": {_19 "xyk": {}_19 },_19 "asset_infos": [_19 {_19 "native_token": {_19 "denom": "factory/neutron1...creator/mytoken"_19 }_19 },_19 {_19 "native_token": {_19 "denom": "untrn"_19 }_19 }_19 ]_19 }_19}
With CosmJS (see Swapping for the client setup):
_15const factory = "neutron1hptk0k5kng7hjy35vmh009qd5m6l33609nypgf2yc6nqnewduqasxplt4e";_15_15const assetInfos = [_15 { native_token: { denom: "factory/neutron1...creator/mytoken" } },_15 { native_token: { denom: "untrn" } },_15];_15_15const result = await signingClient.execute(_15 sender,_15 factory,_15 { create_pair: { pair_type: { xyk: {} }, asset_infos: assetInfos } },_15 "auto"_15);_15_15console.log(result.transactionHash);
For a CW20 asset, use {"token": {"contract_addr": "..."}} instead of native_token.
Stableswap Pools
Stableswap pools take a base64-encoded init_params with the amplification amp:
_20{_20 "create_pair": {_20 "pair_type": {_20 "stable": {}_20 },_20 "asset_infos": [_20 {_20 "native_token": {_20 "denom": "ibc/...stable-a"_20 }_20 },_20 {_20 "native_token": {_20 "denom": "ibc/...stable-b"_20 }_20 }_20 ],_20 "init_params": "eyJhbXAiOjEwfQ=="_20 }_20}
eyJhbXAiOjEwfQ== is the base64 encoding of {"amp":10}. With CosmJS, toBinary does the encoding:
_17import { toBinary } from "@cosmjs/cosmwasm-stargate";_17_17const result = await signingClient.execute(_17 sender,_17 factory,_17 {_17 create_pair: {_17 pair_type: { stable: {} },_17 asset_infos: [_17 { native_token: { denom: "ibc/...stable-a" } },_17 { native_token: { denom: "ibc/...stable-b" } },_17 ],_17 init_params: toBinary({ amp: 10 }),_17 },_17 },_17 "auto"_17);
PCL Pools
PCL pools use {"custom": "concentrated"} and a base64-encoded ConcentratedPoolParams as init_params (amplification, gamma, fees, initial price scale and more). The parameters and their meaning are documented on the PCL pool page. Pick parameters from an existing pool with similar assets (query its config) unless you know what you need.
Finding the Pool Address
After the transaction, look up the new pool with the factory's pair query. The order of asset_infos doesn't matter.
_16{_16 "pair": {_16 "asset_infos": [_16 {_16 "native_token": {_16 "denom": "factory/neutron1...creator/mytoken"_16 }_16 },_16 {_16 "native_token": {_16 "denom": "untrn"_16 }_16 }_16 ]_16 }_16}
The response is a PairInfo:
_19{_19 "asset_infos": [_19 {_19 "native_token": {_19 "denom": "factory/neutron1...creator/mytoken"_19 }_19 },_19 {_19 "native_token": {_19 "denom": "untrn"_19 }_19 }_19 ],_19 "contract_addr": "neutron1...pool",_19 "liquidity_token": "factory/neutron1...pool/astroport/share",_19 "pair_type": {_19 "xyk": {}_19 }_19}
liquidity_token is the pool's LP token. Pools created on Neutron today mint a native tokenfactory LP token (factory/<pool address>/astroport/share). The pool codes the Terra factory uses mint a CW20 LP token, so liquidity_token is a terra1... contract address. Older pools on both chains may use CW20 LP tokens. The LP token type decides how you withdraw liquidity and stake in Incentives: see Providing/Withdrawing Liquidity and Staking/Unstaking LP Tokens.
Links
- Factory contract
- Creating and Seeding a Pool: an end-to-end CosmJS script
- Contract Addresses