# Liquidity Module

The liquidity module, known on the Cosmos Hub as Gravity DEX, enables users to create liquidity pools and swap tokens.

# Use Liquidity Pools to Trade Tokens

When using your Cosmos SDK-based blockchains, you want to enable users to trade tokens. You can have multiple tokens on your blockchain or have tokens from external blockchains sent to your blocking using inter-blockchain communication protocol (IBC).

The liquidity module allows users to use pools to trade those tokens on your blockchain. Each pool represents a token pair and allows the user to swap from one token to the other token.

In this tutorial, you create your own blockchain, send tokens to another blockchain, create a pool, deposit to a pool, withdraw from a pool, and swap tokens.

You can follow the code with us session (opens new window) for hands-on experience

Important In the code examples throughout this tutorial, when you see username be sure to substitute your username.

You will learn how to:

  • Create a blockchain with Starport
  • Create your own token on your blockchain
  • Connect your blockchain to the testnet
  • Send your own token with IBC to the testnet
  • Create a pool with your token
  • Use the pool with your token

# Requirements

Before you start the tutorial, install the prerequisite software.

  • Install Starport v0.16.2

    Important This tutorial uses Starport (opens new window) v0.16.2. The tutorial is based on this specific version of Starport and is not supported for other versions.

  • Install the Gravity DEX binary

    • Clone the repo:
    Copy git clone https://github.com/b-harvest/gravity-dex.git
    • Move into the directory and install software to the right location:
    Copy cd gravity-dex && make install
    • Verify the gaiad version:
    Copy gaiad version

    The output of gaiad version prints something like:

    Copy gravity-dex-fa647b0fefe5508e9c975b3d4f095db2d3d20a13

# Create the Blockchain

Scaffold a new blockchain called myblockchain:

Copy starport app github.com/username/myblockchain

Change to the blockchain directory:

Copy cd myblockchain

# Add Your Token in the Configuration

Navigate to the top-level folder of your app directory myblockchain and use any text editor to edit the config.yml file.

For the accounts parameter, add your username and your new token:

Copy accounts: - name: username coins: ["10000token", "50000000stake", "1000000000000mytoken"]

Tip To add your coins, use a list of strings for the initial coins with denominations. You can follow the .yml syntax for the auto-generated users alice and bob.

The minimum reserve coin amount for a pool in the liquidity module is 1,000,000. Make sure you create enough tokens for your liquidity pools. This entry creates enough tokens to create 10 liquidity pools (1000000000000).

# Start Your Blockchain

To start your blockchain, run this command in your local terminal:

Copy starport serve

You see output similar to the following output, but with different account passphrases and addresses:

Copy Cosmos SDK's version is: Stargate v0.40.0 (or later) πŸ”„ Resetting the app state... πŸ› οΈ Building proto... πŸ“¦ Installing dependencies... πŸ› οΈ Building the blockchain... πŸ’Ώ Initializing the app... πŸ™‚ Created account "alice" with address "cosmos1qur6tvu7p4khtr5zzcx0uk5fq06hfk5xflw83e" with mnemonic: "tank film icon helmet myth devote velvet rib behind exhaust move pass endless combine bag congress pool bean shoulder issue trouble banner best nice" πŸ™‚ Created account "bob" with address "cosmos1w8w3t8rhv5zpvdscy9332wp4tugkg0ezskf95u" with mnemonic: "attract shoulder person upset dream category finish detect country track edge planet crack gloom soldier together hockey arena panel horn rapid zero common marriage" πŸ™‚ Created account "username" with address "cosmos1mr3ss57xexzg7j377vfd24d3vv3vy0e3mpuj6y" with mnemonic: "parent butter piece picnic north thumb knife denial toy silk juice diary cruise idle pink repair radar brisk decide sugar gap joke palm day" Genesis transaction written to "/Users/joy20/.myblockchaind/config/gentx/gentx-2e8a6a680b4f9adaecfafbc6ecad8b96ef8b9157.json" 🌍 Tendermint node: http://0.0.0.0:26657 🌍 Blockchain API: http://0.0.0.0:1317 🌍 Token faucet: http://0.0.0.0:4500

Be patient, using the starport serve command is powerful and takes a few minutes. You are starting your sovereign application-specific blockchain in development and this command is doing all the work for you. Everything you need is being scaffolded so you can focus on business logic.

# Configure the Relayer

A relayer is software to connect two blockchains. Configure the relayer with your endpoints to create a connection between your blockchain and the testnet. After the connection is established, you can send tokens from one blockchain to the other blockchain.

# Remove Existing Relayer and Starport Configurations

If you previously used the relayer, follow these steps to remove exiting relayer and Starport configurations:

  • Delete previous configuration files:

    Copy rm -r $HOME/.starport/*

If existing configurations do not exist, the command returns no matches found and no action is taken.

# Create Your Connection

Configure the relayer to create a connection between your local chain and the chain you want to connect to. In this example, the chain you want to connect to is the Gravity DEX testnet.

Copy starport relayer configure

When everything runs successfully, you see the following output with a different account address:

Copy πŸ” Account on "source" is "cosmos174n26d8n223aje53dznlfahpv54np970wr3ae7" |Β· received coins from a faucet |Β· (balance: 100000stake,5token) πŸ” Account on "target" is "cosmos174n26d8n223aje53dznlfahpv54np970wr3ae7" |Β· received coins from a faucet |Β· (balance: 10000000stake,10000000uphoton) β›“ Configured chains: myblockchain-cosmoshub-testnet

Connect the chains:

Copy starport relayer connect

It will start to connect your two blockchains, you will see an output while it does

Copy β—£ Linking paths between chains...

When successful, your output will be

Copy --------------------------------------------- Linking chains --------------------------------------------- βœ“ Linked chains with 1 paths. - myblockchain-cosmoshub-testnet Continuing with 1 paths... --------------------------------------------- Chains by paths --------------------------------------------- myblockchain-cosmoshub-testnet: myblockchain > (port: transfer) (channel: channel-0) cosmoshub-testnet > (port: transfer) (channel: channel-9) --------------------------------------------- Listening and relaying packets between chains... ---------------------------------------------

# Get Token From the Faucet

From the terminal output that starport serve created for you, use the username accounts address and claim tokens from the faucet. Make sure to add your account address into the address field. Replace cosmosxxxxx with the address you saw in your user account on running starport serve.

Copy curl -X POST -d '{"address": "cosmosxxxxx"}' https://faucet.testnet.cosmos.network

After you see a success message, you can check your balance. Make sure to replace cosmosxxxxx with your address from the previous step.

See your balance at https://api.testnet.cosmos.network/cosmos/bank/v1beta1/balances/ (opens new window).

# Send Your Own Token to the Testnet

Now that your account on testnet is funded with testnet tokens, you can send your own token to the testnet.

At your local terminal, enter the IBC module command to transfer your token to the testnet. Make sure to replace cosmosxxxxx with your address, mytoken with your token name, username with your username and channel-0 with channel

Note: Make sure to use channel as shown in terminal when you run starport relayer connect

Copy myblockchaind tx ibc-transfer transfer transfer channel-0 cosmosxxxxx "15000000mytoken" --from username

After your transaction is complete, check your balance on the Gravity DEX testnet to confirm your token transfer.

Make sure to replace cosmosxxxxx with your address.

Tip: Sometimes transactions don't go through on the first try. Make sure you check the terminal window that shows the relayer process and verify that you see output similar to the following output:

Copy Relay 1 packets from myblockchain => cosmoshub-testnet Relay 1 packets from myblockchain => cosmoshub-testnet Relay 1 acks from cosmoshub-testnet => myblockchain Relay 1 acks from cosmoshub-testnet => myblockchain

See your balance at https://api.testnet.cosmos.network/cosmos/bank/v1beta1/balances/ (opens new window).

Take a closer look at the ibc/denomhash denominator. When you create a new pool, this will be the denom you need to input to make a pair with one of the existing native token, on our testnet we will create a pair with uphoton.

# Create a Pool with My Token

With the liquidity module and gaiad binary installed, use these links to explore your app:

# Verify Your Token Supply

You can get all available tokens. Your token is now listed. Check the following resources to get an overview of the activity on the testnet and find your token.

  • https://api.testnet.cosmos.network/cosmos/bank/v1beta1/supply

  • https://api.testnet.cosmos.network/ibc/applications/transfer/v1beta1/denom_traces

# Add your Starport blockchain account to gaiad

To access Starport username account on gaiad, add it to the keychain.

Copy gaiad keys add username --recover

It will ask you for the passphrase, that you see in the terminal window of running starport serve on your myblockchaind

Copy > Enter your bip39 mnemonic

Add usernames mnemonic passphrase and hit enter. You will see something similar to the following output

Copy - name: username type: local address: cosmos1780t4erzwrvr9x6jvqjxduwkuk3ex3fnhqzza5 pubkey: cosmospub1addwnpepqfs05yqcjghqzct5y39r33r5ew47pjqkvcj7ezngufazy0eqsyx65vtut0h mnemonic: "" threshold: 0 pubkeys: []

# Create a Liquidity Pool

To create a liquidity pool, enter the following command: Make sure to replace longibchash with the hash denom you received on the previous step. Replace username with your account username.

Copy gaiad tx liquidity create-pool 1 1100000uphoton,1500000ibc/longibchash --from username --chain-id cosmoshub-testnet --gas-prices "0.025stake" --node https://rpc.testnet.cosmos.network:443 --gas 2000000 -y

Optional: Add -y flag to bypass confirmation prompt

Confirm the pool has been created. See:

https://api.testnet.cosmos.network/tendermint/liquidity/v1beta1/pools (opens new window)

# Swap Token

You are ready to swap tokens! You now have uphoton token in your account and want to swap for the new IBC coin:

Copy gaiad tx liquidity swap 1 1 100000uphoton ibc/longibchash 0.1 0.003 --from username --chain-id cosmoshub-testnet --gas-prices "0.025stake" --node https://rpc.testnet.cosmos.network:443 -y

Optional: Add -y flag to bypass confirmation prompt

Check the balance on the new account that made the trade:

https://api.testnet.cosmos.network/cosmos/bank/v1beta1/balances/cosmosxxx (opens new window)

Make sure to replace cosmosxxxxx with your address.

# Deposit Token

You can Deposit tokens to the pool you have created.

Copy gaiad tx liquidity deposit 1 100uphoton,100ibc/longibchash --from username --chain-id cosmoshub-testnet --gas-prices "0.025stake" --node https://rpc.testnet.cosmos.network:443 -y

Optional: Add -y flag to bypass confirmation prompt

Note: Deposits must be the same coin denoms as the reserve coins.

Check the balance on the new deposit that you have made:

https://api.testnet.cosmos.network/cosmos/bank/v1beta1/balances/cosmosxxx (opens new window)

# Withdraw Token

You can also withdraw tokens from the pool you have created.

Copy gaiad tx liquidity withdraw 1 100pool-id --from username --chain-id cosmoshub-testnet --gas-prices "0.025stake" --node https://rpc.testnet.cosmos.network:443

Note: Make sure to replace pool-id found here (opens new window)

Check the balance on the new withdrawal that you have made:

https://api.testnet.cosmos.network/cosmos/bank/v1beta1/balances/cosmosxxx (opens new window)

# πŸŽ‰ Congratulations πŸŽ‰

By completing this tutorial you have learned how to use liquidity module.

Here’s what you accomplished in this tutorial:

  • Creating a Blockchain with Starport and connecting to testnet
  • Creating a new liquidity pool with IBC token
  • Swap tokens within the pool
  • Deposit tokens to the pool
  • Withdraw tokens from the pool