Interacting with InitiaDEX

Overview

InitiaDEX stands as a pivotal component of the Initia blockchain, functioning as a native decentralized exchange (DEX) constructed on Layer 1 using the Move programming language. As an essential part of the Omnitia ecosystem, InitiaDEX not only facilitates trading but also significantly enhances liquidity and interoperability between Layer 1 and various Layer 2 networks. For more information about InitiaDEX, please refer to this section.

Interacting with InitiaDEX

Create a Trading Pair

InitiaDEX allows anyone to create a custom trading pair. The Move Function Interface is as follows:

public entry fun create_pair_script(
    creator: &signer,
    name: String,
    symbol: String,
    swap_fee_rate: Decimal128,
    coin_a_weight: Decimal128,
    coin_b_weight: Decimal128,
    coin_a_metadata: Object<Metadata>,
    coin_b_metadata: Object<Metadata>,
    coin_a_amount: u64,
    coin_b_amount: u64,
)

• name: Name of the trading pair and the corresponding LP Token.

• symbol: Symbol for the LP Token.

• swap_fee_rate: Fee rate applied to swaps.

• coin_a_weight and coin_b_weight: Balancer weights for the respective coins.

• coin_a_metadata and coin_b_metadata: Metadata for each coin in the pair.

• coin_a_amount and coin_b_amount: Initial amounts for each coin.

For more information on metadata, please refer to obtaining metadata.

Example Usage:

CLI

initiad tx move execute 0x1 dex create_pair_script \
  --args "string:name string:symbol decimal128:0.001 decimal128:0.8 decimal128:0.2 object:0x... object:0x... u64:100 u64:100" \
  --from [key-name] \
  --gas auto --gas-adjustment 1.5 --gas-prices 0.15uinit \
  --node [rpc-url]:[rpc-port] --chain-id [chain-id]

initia.js

import {
  bcs,
  LCDClient,
  MnemonicKey,
  MsgExecute,
  Wallet,
} from '@initia/initia.js';

async function main() {
  const lcd = new LCDClient('[rest-url]', {
    gasPrices: '0.15uinit',
    gasAdjustment: '1.5',
  });

  const key = new MnemonicKey({
    mnemonic: 'beauty sniff protect ...',
  });
  const wallet = new Wallet(lcd, key);

  const msgs = [
    new MsgExecute(
      key.accAddress,
      '0x1',
      'dex',
      'create_pair_script',
      [],
      [
        bcs.string().serialize('name'), // name
        bcs.string().serialize('symbol'), // symbol
        bcs.decimal128().serialize('0.003'), // swap fee
        bcs.decimal128().serialize('0.2'), // coin a weight
        bcs.decimal128().serialize('0.8'), // coin b weight
        bcs.object().serialize('0x...'), // coin a
        bcs.object().serialize('0x...'), // coin b
        bcs.u64().serialize(7500000000000), // coin a amount
        bcs.u64().serialize(3000000000000), // coin b amount
      ].map(v => v.toBase64())
    ),
  ];

  // sign tx
  const signedTx = await wallet.createAndSignTx({ msgs });
  // send(broadcast) tx
  lcd.tx.broadcastSync(signedTx).then(res => console.log(res));
  // {
  //   height: 0,
  //   txhash: '0F2B255EE75FBA407267BB57A6FF3E3349522DA6DBB31C0356DB588CC3933F37',
  //   raw_log: '[]'
  // }
}

main();

Provide Liquidity

provide_liquidity allows the users to provide liquidity of both coin_a and coin_b in the said pair. In order to maximize liquidity, the user should provide in resonation with the current ratio. The Move module interface is as follows:

public entry fun provide_liquidity_script(
    account: &signer,
    pair: Object<Config>,
    coin_a_amount_in: u64,
    coin_b_amount_in: u64,
    min_liquidity: Option<u64>
)

• pair: The metadata or object address of pair.

• coin_a_amount_in and coin_b_amount_in: Amount of token provided for coin_a and coin_b

• min_liquidity: Minimum amout of liquidity token to receive. In case that the actual value is smaller than min_liquidity, the transaction will fail.

Example Usage:

CLI

initiad tx move execute 0x1 dex provide_liquidity_script \
  --args "object:0x... u64:100 u64:100 option<u64>:100" \
  --from [key-name] \
  --gas auto --gas-adjustment 1.5 --gas-prices 0.15uinit \
  --node [rpc-url]:[rpc-port] --chain-id [chain-id]

initia.js

import {
  bcs,
  LCDClient,
  MnemonicKey,
  MsgExecute,
  Wallet,
} from '@initia/initia.js';

async function main() {
  const lcd = new LCDClient('[rest-url]', {
    gasPrices: '0.15uinit',
    gasAdjustment: '1.5',
  });

  const key = new MnemonicKey({
    mnemonic: 'beauty sniff protect ...',
  });
  const wallet = new Wallet(lcd, key);

  const msgs = [
    new MsgExecute(
      key.accAddress,
      '0x1',
      'dex',
      'provide_liquidity_script',
      [],
      [
        bcs.object().serialize('0x...'), // pair object
        bcs.u64().serialize(7500000000000), // coin a amount
        bcs.u64().serialize(3000000000000), // coin b amount
        bcs.option(bcs.u64()).serialize(100000000), // min liquidity amount
      ].map(v => v.toBase64())
    ),
  ];

  // sign tx
  const signedTx = await wallet.createAndSignTx({ msgs });
  // send(broadcast) tx
  lcd.tx.broadcastSync(signedTx).then(res => console.log(res));
  // {
  //   height: 0,
  //   txhash: '0F2B255EE75FBA407267BB57A6FF3E3349522DA6DBB31C0356DB588CC3933F37',
  //   raw_log: '[]'
  // }
}

main();

Single Asset Provide Liquidity

Instead of creating a pair, the user can provide a pool of only one token. Internally, the token will be swapped to another token and provide liquidity, so there can be fee and slippage in occurance. The Move function interface is as follows:

public entry fun single_asset_provide_liquidity_script(
    account: &signer,
    pair: Object<Config>,
    provide_coin: Object<Metadata>,
    amount_in: u64,
    min_liquidity: Option<u64>
)

• pair: The metadata or object address of pair.

• provide_coin: The metadata of the provided coin.

• amount_in: The amount of provided coin.

• min_liquidity: Minimum amout of liquidity token to receive. In case that the actual value is smaller than min_liquidity, the transaction will fail.

CLI

initiad tx move execute 0x1 dex single_asset_provide_liquidity_script \
  --args "object:0x... object:0x.. u64:100 option<u64>:100" \
  --from [key-name] \
  --gas auto --gas-adjustment 1.5 --gas-prices 0.15uinit \
  --node [rpc-url]:[rpc-port] --chain-id [chain-id]

initia.js

import {
  bcs,
  LCDClient,
  MnemonicKey,
  MsgExecute,
  Wallet,
} from '@initia/initia.js';

async function main() {
  const lcd = new LCDClient('[rest-url]', {
    gasPrices: '0.15uinit',
    gasAdjustment: '1.5',
  });

  const key = new MnemonicKey({
    mnemonic: 'beauty sniff protect ...',
  });
  const wallet = new Wallet(lcd, key);

  const msgs = [
    new MsgExecute(
      key.accAddress,
      '0x1',
      'dex',
      'single_asset_provide_liquidity_script',
      [],
      [
        bcs.object().serialize('0x...'), // pair object
        bcs.object().serialize('0x...'), // provide asset metadata
        bcs.u64().serialize(3000000000000), // provide amount
        bcs.option(bcs.u64()).serialize(100000000), // min liquidity amount
      ].map(v => v.toBase64())
    ),
  ];

  // sign tx
  const signedTx = await wallet.createAndSignTx({ msgs });
  // send(broadcast) tx
  lcd.tx.broadcastSync(signedTx).then(res => console.log(res));
  // {
  //   height: 0,
  //   txhash: '0F2B255EE75FBA407267BB57A6FF3E3349522DA6DBB31C0356DB588CC3933F37',
  //   raw_log: '[]'
  // }
}

main();

Withdraw Liquidity

withdraw_liquidity allows users to provide liquidity tokens and receive coin_a and coin_b. The Move module interface is as follows:

public entry fun withdraw_liquidity_script(
    account: &signer,
    pair: Object<Config>,
    liquidity: u64,
    min_coin_a_amount: Option<u64>,
    min_coin_b_amount: Option<u64>,
)

• pair: The metadata or object address of pair.

• liquidity: Amount of liquidity token.

• min_coin_a_amount and min_coin_b_amount : Minimum amout of coin_a or coin_b to receive. In case that the actual value is smaller than min_coin_a_amount or min_coin_b_amount, the transaction will fail.

cli

initiad tx move execute 0x1 dex withdraw_liquidity_script \
  --args "object:0x... u64:100 option<u64>:100 option<u64>:100" \
  --from [key-name] \
  --gas auto --gas-adjustment 1.5 --gas-prices 0.15uinit \
  --node [rpc-url]:[rpc-port] --chain-id [chain-id]

initia.js

import {
  bcs,
  LCDClient,
  MnemonicKey,
  MsgExecute,
  Wallet,
} from '@initia/initia.js';

async function main() {
  const lcd = new LCDClient('[rest-url]', {
    gasPrices: '0.15uinit',
    gasAdjustment: '1.5',
  });

  const key = new MnemonicKey({
    mnemonic: 'beauty sniff protect ...',
  });
  const wallet = new Wallet(lcd, key);

  const msgs = [
    new MsgExecute(
      key.accAddress,
      '0x1',
      'dex',
      'withdraw_liquidity_script',
      [],
      [
        bcs.object().serialize('0x...'), // pair object
        bcs.u64().serialize(100000000), // liquidity
        bcs.option(bcs.u64()).serialize(100000000), // min coin a amount
        bcs.option(bcs.u64()).serialize(100000000), // min coin b amount
      ].map(v => v.toBase64())
    ),
  ];

  // sign tx
  const signedTx = await wallet.createAndSignTx({ msgs });
  // send(broadcast) tx
  lcd.tx.broadcastSync(signedTx).then(res => console.log(res));
  // {
  //   height: 0,
  //   txhash: '0F2B255EE75FBA407267BB57A6FF3E3349522DA6DBB31C0356DB588CC3933F37',
  //   raw_log: '[]'
  // }
}

main();

Swap

The Move module interface for swap function is as follows:

public entry fun swap_script(
    account: &signer,
    pair: Object<Config>,
    offer_coin: Object<Metadata>,
    offer_coin_amount: u64,
    min_return: Option<u64>,
)

• pair: The metadata or object address of pair.

• offer_coin: Metadata of offered coin.

• offer_coin_amount: Amount of offered coin.

• min_return: Minimum return amount of coin. In case that the actual value is smaller than min_return, the transaction will fail.

cli

initiad tx move execute 0x1 dex swap_script \
  --args "object:0x... object:0x... u64:100 option<u64>:100" \
  --from [key-name] \
  --gas auto --gas-adjustment 1.5 --gas-prices 0.15uinit \
  --node [rpc-url]:[rpc-port] --chain-id [chain-id]

initia.js

import {
  bcs,
  LCDClient,
  MnemonicKey,
  MsgExecute,
  Wallet,
} from '@initia/initia.js';

async function main() {
  const lcd = new LCDClient('[rest-url]', {
    gasPrices: '0.15uinit',
    gasAdjustment: '1.5',
  });

  const key = new MnemonicKey({
    mnemonic: 'beauty sniff protect ...',
  });
  const wallet = new Wallet(lcd, key);

  const msgs = [
    new MsgExecute(
      key.accAddress,
      '0x1',
      'dex',
      'swap_script',
      [],
      [
        bcs.object().serialize('0x...'), // pair object
        bcs.object().serialize('0x...'), // offer asset metadata
        bcs.u64().serialize(100000000), // offer amount
        bcs.option(bcs.u64()).serialize(100000000), // min return amount
      ].map(v => v.toBase64())
    ),
  ];

  // sign tx
  const signedTx = await wallet.createAndSignTx({ msgs });
  // send(broadcast) tx
  lcd.tx.broadcastSync(signedTx).then(res => console.log(res));
  // {
  //   height: 0,
  //   txhash: '0F2B255EE75FBA407267BB57A6FF3E3349522DA6DBB31C0356DB588CC3933F37',
  //   raw_log: '[]'
  // }
}

main();

Swap simulation

swap_simulation is a view function to estimate the return value of said swap.

#[view]
/// Return swap simulation result
public fun get_swap_simulation(
    pair: Object<Config>,
    offer_metadata: Object<Metadata>,
    offer_amount: u64,
): u64 // return amount

• pair: The metadata or object address of pair.

• offer_metadata: Metadata of offered coin.

• offer_amount: Amount of offered coin.

curl

curl -X POST "[LCD_URI]/initia/move/v1/accounts/0x1/modules/dex/view_functions/get_swap_simulation" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -d "{ \"args\": [ \"[BCS_ENCODED_OBJECT, BCS_ENCODED_OBJECT, BCS_ENCODED_OFFER_AMOUNT]\" ]}"

  
#{
#  "data": "\"100\"",
#  "events": [],
#  "gas_used": "5699"
#}

CLI

> initiad query move view 0x1 dex get_swap_simulation \
  --args "object:0x... object:0x... u64:123" \
  --node [rpc-url]:[rpc-port]
  
# data: '"123"'
# events: []
# gas_used: "5699"

initia.js

import { LCDClient, bcs } from '@initia/initia.js';

const lcdUri = 'https://....';
const lcd = new LCDClient(lcdUri);

lcd.move
  .view(
    '0x1',
    'dex',
    'get_swap_simulation',
    [],
    [
      bcs.object().serialize('0x...').toBase64(),
      bcs.object().serialize('0x...').toBase64(),
      bcs.u64().serialize(100).toBase64(),
    ]
  )
  .then(console.log);

// { data: '"100"', events: [], gas_used: '21371' }

Conclusion

The provided examples illustrate the practical steps necessary to interact with InitiaDEX, demonstrating its versatility and user-friendliness within the Initia blockchain ecosystem. By detailing how to create trading pairs, provide liquidity, and perform transactions like swaps and withdrawals, users are equipped with the tools needed to effectively engage with the decentralized exchange. The use of the Move programming language ensures secure and efficient execution of these operations, reflecting the platform’s commitment to fostering a reliable and scalable trading environment. For developers and traders alike, understanding and utilizing these examples can significantly enhance their ability to customize and optimize their interactions with InitiaDEX, leveraging the full potential of decentralized finance on this innovative platform.