Skip to content

Latest commit

 

History

History
708 lines (517 loc) · 21 KB

liquidity.md

File metadata and controls

708 lines (517 loc) · 21 KB
Title Description
Liquidity
A high-level overview of how the command-line interfaces (CLI) works for the liquidity module.

Liquidity Module

Synopsis

This document provides a high-level overview of how the command line (CLI) interface works for the liquidity module. To set up a local testing environment, it requires the latest Ignite CLI. If you don't have Ignite CLI set up in your local machine, see this guide to install it. Run this command under the project root directory $ ignite chain serve -c config-test.yml.

Note that jq is recommended to be installed as it is used to process JSON throughout the document.

Command Line Interfaces

Transaction

CreatePair

Create a pair (market) for trading.

A pair consists of a base coin and a quote coin and you can think of a pair in an order book. An orderer can request a limit or market order once a pair is created. Anyone can create a pair by paying a fee PairCreationFee (default is 1000000stake).

Usage

create-pair [base-coin-denom] [quote-coin-denom]
Argument Description
base-coin-denom denom of the base coin for the pair
quote-coin-deom denom of the quote coin for the pair

Example

# Create a pair ATOM/UST
squad tx liquidity create-pair uatom uusd \
--chain-id localnet \
--from alice \
--keyring-backend test \
--broadcast-mode block \
--yes \
--output json | jq

#
# Tips
#
# You can query pairs using the following command
squad q liquidity pairs -o json | jq

CreatePool

Create a liquidity pool in existing pair.

Pool(s) belong to a pair. Therefore, a pair must exist in order to create a pool. Anyone can create a pool by paying a fee PoolCreationFee (default is 1000000stake).

Usage

create-pool [pair-id] [deposit-coins]
Argument Description
pair-id pair id
deposit-coins deposit amount of base and quote coins

Example

# Create a pool 1000ATOM/3000UST
squad tx liquidity create-pool 1 1000000000uatom,3000000000uusd \
--chain-id localnet \
--from alice \
--keyring-backend test \
--broadcast-mode block \
--yes \
--output json | jq

#
# Tips
#
# You can query pools using the following command
squad q liquidity pools -o json | jq

CreateRangedPool

Create a ranged liquidity pool in existing pair.

Pool(s) belong to a pair. Therefore, a pair must exist in order to create a pool. Anyone can create a pool by paying a fee PoolCreationFee (default is 1000000stake).

Usage

create-ranged-pool [pair-id] [deposit-coins] [min-price] [max-price] [initial-price]
Argument Description
pair-id pair id
deposit-coins deposit amount of base and quote coins
min-price minimum price of the pool
max-price maximum price of the pool
initial-price initial pool price

Example

# Create a ranged pool with 1000ATOM/1000UST with price range of [2.5, 10.0],
# with initial price set to 3.0
squad tx liquidity create-ranged-pool 1 1000000000uatom,1000000000uusd 2.5 10.0 3.0 \
--chain-id localnet \
--from alice \
--keyring-backend test \
--broadcast-mode block \
--yes \
--output json | jq

#
# Tips
#
# You can query pools using the following command
squad q liquidity pools -o json | jq

Deposit

Deposit coins to a liquidity pool.

Deposit uses a batch execution methodology. Deposit requests are accumulated in a batch for a pre-defined period (default is 1 block) and they are executed at the end of the batch. A minimum deposit amount is 1000000 for each denomination.

Note that in an order book system, a pool is considered as an orderer. A liquidity in the pool places orders conservatively. What that means is that it places buy orders lower than the pool price and places sell orders higher than the pool price.

Usage

deposit [pool-id] [deposit-coins]
Argument Description
pool-id pool id
deposit-coins deposit amount of base and quote coins

Example

# Deposit 10ATOM/30UST to the pool
squad tx liquidity deposit 1 10000000uatom,30000000uusd \
--chain-id localnet \
--from alice \
--keyring-backend test \
--broadcast-mode block \
--yes \
--output json | jq

#
# Tips
#
# You can query deposit requests by using the following command
# You must query this right away to get the result
# Otherwise, it is removed as it is executed.
squad q liquidity deposit-requests 1 -o json | jq

Withdraw

Withdraw coins from the liquidity pool.

Withdraw uses a batch execution methodology. Withdraw requests are accumulated in a batch for a pre-defined period (default is 1 block) and they are executed at the end of the batch.

Usage

withdraw [pool-id] [pool-coin]
Argument Description
pool-id pool id
pool-coin amount of pool coin to withdraw

Example

# Withdraw pool coin from the pool
squad tx liquidity withdraw 1 500000000000pool1 \
--chain-id localnet \
--from alice \
--keyring-backend test \
--broadcast-mode block \
--yes \
--output json | jq

#
# Tips
#
# You can query withdraw requests by using the following command
# You must query this right away to get the result
# Otherwise, it is removed as it is executed.
squad q liquidity withdraw-requests 1 -o json | jq

LimitOrder

Make a limit order.

Buy limit order will be matched at lower than or equal to the defined order price whereas sell limit order will be matched at higher than or equal to the defined order price.

Order uses a batch execution methodology. Order requests are accumulated in a batch for a pre-defined period (default is 1 block) and they are executed at the end of the batch.

Usage

limit-order [pair-id] [direction] [offer-coin] [demand-coin-denom] [price] [amount]
Argument Description
pair-id pair id
direction swap direction; buy or sell
offer-coin amount of coin that the orderer offers to swap with; buy direction requires quote coin whereas sell direction requires base coin. For buy direction, quote coin amount must be greater than or equal to price * amount. For sell direction, base coin amount must be greater than or equal to the amount value.
demand-coin-denom demand coin denom that the orderer is willing to swap for
price order price; the exchange ratio is the amount of quote coin over the amount of base coin
amount amount of base coin that the orderer is willing to buy or sell

| Optional Flag | Description | | :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ | --- | --- | --- | --- | --- | | order-lifespan | duration that the order lives until it is expired; an order will be executed for at least one batch, even if the lifespan is 0; valid time units are ns | us | ms | s | m | h |

Example

# Make a limit order to swap
squad tx liquidity limit-order 1 sell 50000000uatom uusd 3.3 50000000 \
--chain-id localnet \
--from alice \
--keyring-backend test \
--broadcast-mode block \
--yes \
--output json | jq

# Make a limit order to swap with order-lifespan flag
squad tx liquidity limit-order 1 sell 50000000uatom uusd 3.3 50000000 \
--chain-id localnet \
--order-lifespan 30s \
--from alice \
--keyring-backend test \
--broadcast-mode block \
--yes \
--output json | jq

#
# Tips
#
# You can query order requests by using the following command
# You must query this right away to get the result
# Otherwise, it is removed as it is executed.
squad q liquidity orders cosmos1zaavvzxez0elundtn32qnk9lkm8kmcszzsv80v -o json | jq

MarketOrder

Make a market order.

Unlike a limit order, there is no need to input order price.

Buy market order uses MaxPriceLimitRatio of the last price, which is LastPrice * (1+MaxPriceLimitRatio).

Sell market order uses negative MaxPriceLimitRatio of the last price, which is LastPrice * (1-MaxPriceLimitRatio).

Order uses a batch execution methodology. Order requests are accumulated in a batch for a pre-defined period (default is 1 block) and they are executed at the end of the batch.

Usage

market-order [pair-id] [direction] [offer-coin] [demand-coin-denom] [amount]
Argument Description
pair-id pair id
direction swap direction; buy or sell
offer-coin amount of coin that the orderer offers to swap with; buy direction requires quote coin whereas sell direction requires base coin. For buy direction, quote coin amount must be greater than or equal to price * amount. For sell direction, base coin amount must be greater than or equal to the amount value.
demand-coin-denom demand coin denom that the orderer is willing to swap for
amount amount of base coin that the orderer is willing to buy or sell

| Optional Flag | Description | | :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ | --- | --- | --- | --- | --- | | order-lifespan | duration that the order lives until it is expired; an order will be executed for at least one batch, even if the lifespan is 0; valid time units are ns | us | ms | s | m | h |

Example

# Make a market order to swap
squad tx liquidity market-order 1 sell 100000000uatom uusd 100000000 \
--chain-id localnet \
--from alice \
--keyring-backend test \
--broadcast-mode block \
--yes \
--output json | jq

# Make a limit order to swap with order-lifespan flag
squad tx liquidity market-order 1 sell 100000000uatom uusd 100000000 \
--chain-id localnet \
--order-lifespan 30s \
--from alice \
--keyring-backend test \
--broadcast-mode block \
--yes \
--output json | jq

#
# Tips
#
# You can query order requests by using the following command
# You must query this right away to get the result
# Otherwise, it is removed as it is executed.
squad q liquidity orders cosmos1zaavvzxez0elundtn32qnk9lkm8kmcszzsv80v -o json | jq

MMOrder

Make an MM(market making) order. An MM order is a group of multiple buy/sell limit orders which are distributed evenly based on its parameters.

Usage

mm-order [pair-id] [max-sell-price] [min-sell-price] [sell-amount] [max-buy-price] [min-buy-price] [buy-amount]
Argument Description
pair-id pair id
max-sell-price maximum price of sell orders
min-sell-price minimum price of sell orders
sell-amount total amount of sell orders
max-buy-price maximum price of buy orders
min-buy-price minimum price of buy orders
buy-amount total amount of buy orders

| Optional Flag | Description | | :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ | --- | --- | --- | --- | --- | | order-lifespan | duration that the order lives until it is expired; an order will be executed for at least one batch, even if the lifespan is 0; valid time units are ns | us | ms | s | m | h |

Example

# Make a market making order in pair 1 with following parameters:
# Sell: total 1000000 with price range from 102 to 101
# Buy: total 1000000 with price range from 100 to 99
squad tx liquidity mm-order 1 102 101 1000000 100 99 1000000  \
--chain-id localnet \
--from alice \
--keyring-backend test \
--broadcast-mode block \
--yes \
--output json | jq

# Make the same order with order-lifespan flag
squad tx liquidity mm-order 1 102 101 1000000 100 99 1000000  \
--order-lifespan 30s \
--chain-id localnet \
--from alice \
--keyring-backend test \
--broadcast-mode block \
--yes \
--output json | jq

CancelOrder

Cancel an order.

Usage

cancel-order [pair-id] [order-id]
Argument Description
pair-id pair id
order-id order id

Example

squad tx liquidity cancel-order 1 1 \
--chain-id localnet \
--from alice \
--keyring-backend=test \
--broadcast-mode block \
--yes \
--output json | jq

CancelAllOrders

Cancel all orders.

This command provides a convenient way to cancel all orders.

Usage

cancel-all-orders [pair-ids]
Argument Description
pool-id pool id
pool-coin amount of pool coin to withdraw

Example

squad tx liquidity cancel-all-orders 1,2,3 \
--chain-id localnet \
--from alice \
--keyring-backend=test \
--broadcast-mode block \
--yes \
--output json | jq

CancelMMOrder

Cancel a market making order in a pair. This will cancel all limit orders in the pair made by the mm order.

Usage

cancel-mm-order [pair-id]
Argument Description
pair-id pair id

Example

squad tx liquidity cancel-mm-order 1 \
--chain-id localnet \
--from alice \
--keyring-backend=test \
--broadcast-mode block \
--yes \
--output json | jq

Query

Params

Query the current liquidity parameters information

Usage

params

Example

squad q liquidity params -o json | jq

Pairs

Query for all pairs

Usage

pairs

Example

# Query all pairs
squad q liquidity pairs -o json | jq

# Query all pairs that has the defined denom
squad q liquidity pairs --denoms=uatom -o json | jq

# Query all pairs that has the defined denoms
squad q liquidity pairs --denoms=uatom,uusd -o json | jq

Pair

Query details for the particular pair

Usage

pair [pair-id]

Example

squad q liquidity pair 1 -o json | jq

Pools

Query for all pools

Usage

pools

Example

# Query all pools
squad q liquidity pools -o json | jq

# Query all pools that has the pair id
squad q liquidity pools -o json --pair-id=1 | jq

# Query all pools with disabled flag
squad q liquidity pools -o json --disabled=false | jq

Pool

Query details for the particular pool

Usage

pool [pool-id]

Example

# Query the specific pool
squad q liquidity pool 1 -o json | jq

# Query the specific pool that has the defined pool coin denom
squad q liquidity pool --pool-coin-denom=pool1 -o json | jq

DepositRequests

Query for all deposit requests in the pool

Usage

deposit-requests [pool-id]

Example

squad q liquidity deposit-requests 1 -o json | jq

DepositRequest

Query details for the particular deposit request in the pool

Usage

deposit-request [pool-id] [id]

Example

squad q liquidity deposit-request 1 1 -o json | jq

WithdrawRequests

Query for all withdraw requests in the pool

Usage

withdraw-requests [pool-id]

Example

squad q liquidity withdraw-requests 1 -o json | jq

WithdrawRequest

Query details for the particular withdraw request in the pool

Usage

withdraw-request [pool-id] [id]

Example

squad q liquidity withdraw-request 1 1 -o json | jq

Orders

Query for all orders made by an orderer or in the pair.

Usage

orders

Example

squad q liquidity orders cosmos1zaavvzxez0elundtn32qnk9lkm8kmcszzsv80v \
-o json | jq

squad q liquidity orders cosmos1zaavvzxez0elundtn32qnk9lkm8kmcszzsv80v \
--pair-id=1 \
-o json | jq

squad q liquidity orders \
--pair-id=1 \
-o json | jq

Order

Query details for the particular order

Usage

order [pair-id] [id]

Example

squad q liquidity order 1 1

OrderBooks

Query order books for given pairs and tick precisions.

Usage

order-books [pair-ids] [tick-precisions]

Example

squad order-books 1 --num-ticks=10

squad order-books 1,2,3