Skip to main content

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.

ChainFactory
Terraterra14x9fr055x5hvr48hzy2t4q7kvjvfttsvxusa4xsdcy702mnzsvuqprer8r
Neutronneutron1hptk0k5kng7hjy35vmh009qd5m6l33609nypgf2yc6nqnewduqasxplt4e

Pool types anyone can create on both chains:

pair_typePoolSwap feeNotes
{"xyk": {}}Constant product0.30%No init_params needed
{"stable": {}}Stableswap0.05%init_params with amp
{"custom": "concentrated"}PCLDynamic, set in the pool parametersinit_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.

NOTE

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):


_15
const factory = "neutron1hptk0k5kng7hjy35vmh009qd5m6l33609nypgf2yc6nqnewduqasxplt4e";
_15
_15
const assetInfos = [
_15
{ native_token: { denom: "factory/neutron1...creator/mytoken" } },
_15
{ native_token: { denom: "untrn" } },
_15
];
_15
_15
const result = await signingClient.execute(
_15
sender,
_15
factory,
_15
{ create_pair: { pair_type: { xyk: {} }, asset_infos: assetInfos } },
_15
"auto"
_15
);
_15
_15
console.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:


_17
import { toBinary } from "@cosmjs/cosmwasm-stargate";
_17
_17
const 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.