diff --git a/docs/api/amm.md b/docs/api/amm.md new file mode 100644 index 000000000..32a51f645 --- /dev/null +++ b/docs/api/amm.md @@ -0,0 +1,477 @@ +--- +Title: AMM +Description: A high-level overview of what gRPC-gateway REST routes are supported in the amm module. +--- + +# AMM Module + +## Synopsis + +This document provides a high-level overview of what gRPC-gateway REST routes are supported in the `amm` module. + +## gRPC-gateway REST Routes + + +++https://github.com/crescent-network/crescent/blob/main/proto/crescent/amm/v1beta1/query.proto (need check) + +- [Params](#Params) +- [AllPools](#AllPools) +- [Pool](#Pool) +- [AllPositions](#AllPositions) +- [Position](#Position) +- [AddLiquiditySimulation](#AddLiquiditySimulation) +- [RemoveLiquiditySimulation](#RemoveLiquiditySimulation) +- [CollectibleCoins](#CollectibleCoins) +- [AllTickInfos](#AllTickInfos) +- [TickInfo](#TickInfo) +- [AllFarmingPlans](#AllFarmingPlans) +- [FarmingPlan](#FarmingPlan) + +## Params + +Example Request + + +```bash +http://localhost:1317/crescent/amm/v1beta1/params +``` + +Example Response + +```json +{ + "params": { + "pool_creation_fee": [ + { + "denom": "stake", + "amount": "1000000" + } + ], + "default_tick_spacing": 50, + "private_farming_plan_creation_fee": [ + { + "denom": "stake", + "amount": "1000000" + } + ], + "max_num_private_farming_plans": 50, + "max_farming_block_time": "10s" + } +} +``` + +## AllPools + +Example Request + + +```bash +http://localhost:1317/crescent/amm/v1beta1/pools +http://localhost:1317/crescent/amm/v1beta1/pools?market_id=1 +``` + +Example Response + +```json +{ + "pools": [ + { + "id": "1", + "market_id": "1", + "balance0": { + "denom": "uatom", + "amount": "706867" + }, + "balance1": { + "denom": "uusd", + "amount": "12020740" + }, + "reserve_address": "cre1pf3w839s80c26z8dqccuzu4epyj58jrzglqv93yppqpj6yggu9qs8vpazr", + "rewards_pool": "cre1srphgsfqllr85ndknjme24txux8m0sz0hhpnnksn2339d3a788rs3ax6tu", + "tick_spacing": 50, + "min_order_quantity": "1.000000000000000000", + "min_order_quote": "1.000000000000000000", + "current_tick": 90208, + "current_price": "10.208470700277704312", + "current_liquidity": "61622776", + "total_liquidity": "61622776", + "fee_growth_global": [ + { + "denom": "uatom", + "amount": "2417937.160117551341731180" + }, + { + "denom": "uusd", + "amount": "8072226411.870831654841385269" + } + ], + "farming_rewards_growth_global": [ + { + "denom": "uatom", + "amount": "1363132.358723988675875290" + } + ] + } + ], + "pagination": { + "next_key": null, + "total": "1" + } +} +``` + +## Pool + +Example Request + + +```bash +http://localhost:1317/crescent/amm/v1beta1/pools/1 +``` + +Example Response + +```json +{ + "pool": { + "id": "1", + "market_id": "1", + "balance0": { + "denom": "uatom", + "amount": "706867" + }, + "balance1": { + "denom": "uusd", + "amount": "12020740" + }, + "reserve_address": "cre1pf3w839s80c26z8dqccuzu4epyj58jrzglqv93yppqpj6yggu9qs8vpazr", + "rewards_pool": "cre1srphgsfqllr85ndknjme24txux8m0sz0hhpnnksn2339d3a788rs3ax6tu", + "tick_spacing": 50, + "min_order_quantity": "1.000000000000000000", + "min_order_quote": "1.000000000000000000", + "current_tick": 90208, + "current_price": "10.208470700277704312", + "current_liquidity": "61622776", + "total_liquidity": "61622776", + "fee_growth_global": [ + { + "denom": "uatom", + "amount": "2417937.160117551341731180" + }, + { + "denom": "uusd", + "amount": "8072226411.870831654841385269" + } + ], + "farming_rewards_growth_global": [ + { + "denom": "uatom", + "amount": "6052956.783381521144065276" + } + ] + } +} +``` + +## AllPositions + +Example Request + + +```bash +http://localhost:1317/crescent/amm/v1beta1/positions +http://localhost:1317/crescent/amm/v1beta1/positions?pool_id=1 +http://localhost:1317/crescent/amm/v1beta1/positions?owner=cre1zaavvzxez0elundtn32qnk9lkm8kmcszxclz6p +``` + +Example Response + +```json +{ + "positions": [ + { + "id": "1", + "pool_id": "1", + "owner": "cre1zaavvzxez0elundtn32qnk9lkm8kmcszxclz6p", + "lower_price": "9.000000000000000000", + "upper_price": "11.000000000000000000", + "liquidity": "61622776", + "last_fee_growth_inside": [ + ], + "owed_fee": [ + ], + "last_farming_rewards_growth_inside": [ + ], + "owed_farming_rewards": [ + ] + } + ], + "pagination": { + "next_key": null, + "total": "1" + } +} +``` + +## Position + +Example Request + + +```bash +http://localhost:1317/crescent/amm/v1beta1/positions/1 +``` + +Example Response + +```json +{ + "position": { + "id": "1", + "pool_id": "1", + "owner": "cre1zaavvzxez0elundtn32qnk9lkm8kmcszxclz6p", + "lower_price": "9.000000000000000000", + "upper_price": "11.000000000000000000", + "liquidity": "61622776", + "last_fee_growth_inside": [ + ], + "owed_fee": [ + ], + "last_farming_rewards_growth_inside": [ + ], + "owed_farming_rewards": [ + ] + } +} +``` + +## AddLiquiditySimulation + +Example Request + + +```bash +http://localhost:1317/crescent/amm/v1beta1/simulation/add_liquidity?pool_id=1&lower_price=9&upper_price=11&desired_amount=100uatom,100uusd +``` + +Example Response + +```json +{ + "liquidity": "559", + "amount": [ + { + "denom": "uatom", + "amount": "8" + }, + { + "denom": "uusd", + "amount": "100" + } + ] +} +``` + +## RemoveLiquiditySimulation + +Example Request + + +```bash +http://localhost:1317/crescent/amm/v1beta1/simulation/remove_liquidity?position_id=1&liquidity=10000 +``` + +Example Response + +```json +{ + "amount": [ + { + "denom": "uatom", + "amount": "130" + }, + { + "denom": "uusd", + "amount": "1785" + } + ] +} +``` + +## CollectibleCoins + +Example Request + + +```bash +http://localhost:1317/crescent/amm/v1beta1/collectible_coins?owner=cre1zaavvzxez0elundtn32qnk9lkm8kmcszxclz6p +http://localhost:1317/crescent/amm/v1beta1/collectible_coins?position_id=1 +``` + +Example Response + +```json +{ + "fee": [ + { + "denom": "uatom", + "amount": "147" + }, + { + "denom": "uusd", + "amount": "2571" + } + ], + "farming_rewards": [ + { + "denom": "uatom", + "amount": "63407" + } + ] +} +``` + +## AllTickInfos + +Example Request + + +```bash +http://localhost:1317/crescent/amm/v1beta1/pools/1/tick_infos +``` + +Example Response + +```json +{ + "tick_infos": [ + { + "tick": 80000, + "gross_liquidity": "61622776", + "net_liquidity": "61622776", + "fee_growth_outside": [ + ], + "farming_rewards_growth_outside": [ + ] + }, + { + "tick": 91000, + "gross_liquidity": "61622776", + "net_liquidity": "-61622776", + "fee_growth_outside": [ + ], + "farming_rewards_growth_outside": [ + ] + } + ], + "pagination": { + "next_key": null, + "total": "2" + } +} +``` + +## TickInfo + +Example Request + + +```bash +http://localhost:1317/crescent/amm/v1beta1/pools/1/tick_infos/80000 +``` + +Example Response + +```json +{ + "tick_info": { + "tick": 80000, + "gross_liquidity": "61622776", + "net_liquidity": "61622776", + "fee_growth_outside": [ + ], + "farming_rewards_growth_outside": [ + ] + } +} +``` + +## AllFarmingPlans + +Example Request + + +```bash +http://localhost:1317/crescent/amm/v1beta1/farming_plans +``` + +Example Response + +```json +{ + "farming_plans": [ + { + "id": "1", + "description": "New farming plan", + "farming_pool_address": "cre1ll5dtdmug9n54fnhr9fpr8nmr840s72dstydd723ufgsxzrjg5qq9kzn3e", + "termination_address": "cre1zaavvzxez0elundtn32qnk9lkm8kmcszxclz6p", + "reward_allocations": [ + { + "pool_id": "1", + "rewards_per_day": [ + { + "denom": "uatom", + "amount": "1000000" + } + ] + } + ], + "start_time": "2023-01-01T00:00:00Z", + "end_time": "2024-01-01T00:00:00Z", + "is_private": true, + "is_terminated": false + } + ], + "pagination": { + "next_key": null, + "total": "1" + } +} +``` + +## FarmingPlan + +Example Request + + +```bash +http://localhost:1317/crescent/amm/v1beta1/farming_plans/1 +``` + +Example Response + +```json +{ + "farming_plan": { + "id": "1", + "description": "New farming plan", + "farming_pool_address": "cre1ll5dtdmug9n54fnhr9fpr8nmr840s72dstydd723ufgsxzrjg5qq9kzn3e", + "termination_address": "cre1zaavvzxez0elundtn32qnk9lkm8kmcszxclz6p", + "reward_allocations": [ + { + "pool_id": "1", + "rewards_per_day": [ + { + "denom": "uatom", + "amount": "1000000" + } + ] + } + ], + "start_time": "2023-01-01T00:00:00Z", + "end_time": "2024-01-01T00:00:00Z", + "is_private": true, + "is_terminated": false + } +} +``` diff --git a/docs/api/exchange.md b/docs/api/exchange.md new file mode 100644 index 000000000..bc5e117bf --- /dev/null +++ b/docs/api/exchange.md @@ -0,0 +1,273 @@ +--- +Title: Exchange +Description: A high-level overview of what gRPC-gateway REST routes are supported in the exchange module. +--- + +# Exchange Module + +## Synopsis + +This document provides a high-level overview of what gRPC-gateway REST routes are supported in the `exchange` module. + +## gRPC-gateway REST Routes + + +++https://github.com/crescent-network/crescent/blob/main/proto/crescent/exchange/v1beta1/query.proto (need check) + +- [Params](#Params) +- [AllMarkets](#AllMarkets) +- [Market](#Market) +- [AllOrders](#AllOrders) +- [Order](#Order) +- [BestSwapExactAmountInRoutes](#BestSwapExactAmountInRoutes) +- [OrderBook](#OrderBook) + +## Params + +Example Request + + +```bash +http://localhost:1317/crescent/exchange/v1beta1/params +``` + +Example Response + +```json +{ + "params": { + "market_creation_fee": [ + { + "denom": "stake", + "amount": "1000000" + } + ], + "fees": { + "default_maker_fee_rate": "0.001500000000000000", + "default_taker_fee_rate": "0.003000000000000000", + "default_order_source_fee_ratio": "0.500000000000000000" + }, + "max_order_lifespan": "86400s", + "max_order_price_ratio": "0.100000000000000000", + "max_swap_routes_len": 3, + "max_num_mm_orders": 15 + } +} +``` + +## AllMarkets + +Example Request + + +```bash +http://localhost:1317/crescent/exchange/v1beta1/markets +``` + +Example Response + +```json +{ + "markets": [ + { + "id": "1", + "base_denom": "uatom", + "quote_denom": "uusd", + "escrow_address": "cre1whhqyaxuv9vrmr00slaqa6zg9cf30nk4k6ltpqvp6ecn6vks5mfsttzq30", + "maker_fee_rate": "0.001500000000000000", + "taker_fee_rate": "0.003000000000000000", + "order_source_fee_ratio": "0.500000000000000000", + "last_price": "15.000000000000000000", + "last_matching_height": "6948" + } + ], + "pagination": { + "next_key": null, + "total": "1" + } +} +``` + +## Market + +Example Request + + +```bash +http://localhost:1317/crescent/exchange/v1beta1/markets/1 +``` + +Example Response + +```json +{ + "market": { + "id": "1", + "base_denom": "uatom", + "quote_denom": "uusd", + "escrow_address": "cre1whhqyaxuv9vrmr00slaqa6zg9cf30nk4k6ltpqvp6ecn6vks5mfsttzq30", + "maker_fee_rate": "0.001500000000000000", + "taker_fee_rate": "0.003000000000000000", + "order_source_fee_ratio": "0.500000000000000000", + "last_price": "15.000000000000000000", + "last_matching_height": "6948" + } +} +``` + +## AllOrders + +Example Request + + +```bash +http://localhost:1317/crescent/exchange/v1beta1/orders +``` + +Example Response + +```json +{ + "orders": [ + { + "id": "6", + "type": "ORDER_TYPE_MM", + "orderer": "cre1zaavvzxez0elundtn32qnk9lkm8kmcszxclz6p", + "market_id": "1", + "is_buy": true, + "price": "15.000000000000000000", + "quantity": "100000.000000000000000000", + "msg_height": "7213", + "open_quantity": "100000.000000000000000000", + "remaining_deposit": "1500000.000000000000000000", + "deadline": "2023-08-30T05:30:50.090404Z" + } + ], + "pagination": { + "next_key": null, + "total": "1" + } +} +``` + +## Order + +Example Request + + +```bash +http://localhost:1317/crescent/exchange/v1beta1/orders/1 +``` + +Example Response + +```json +{ + "order": { + "id": "1", + "type": "ORDER_TYPE_LIMIT", + "orderer": "cre1zaavvzxez0elundtn32qnk9lkm8kmcszxclz6p", + "market_id": "1", + "is_buy": true, + "price": "9.000000000000000000", + "quantity": "100000", + "msg_height": "6549", + "open_quantity": "100000", + "remaining_deposit": "900000", + "deadline": "2023-06-29T07:28:37.840415Z" + } +} +``` + +## BestSwapExactAmountInRoutes + +Example Request + + +```bash +http://localhost:1317/crescent/exchange/v1beta1/best_swap_exact_amount_in_routes?input=100uatom&output_denom=uusd +``` + +Example Response + +```json +{ + "routes": [ + "1" + ], + "output": { + "denom": "uusd", + "amount": "1016" + }, + "results": [ + { + "market_id": "1", + "input": { + "denom": "uatom", + "amount": "100" + }, + "output": { + "denom": "uusd", + "amount": "1016" + }, + "fee": { + "denom": "uusd", + "amount": "4" + } + } + ] +} +``` + + +## Orderbook + +Example Request + + +```bash +http://localhost:1317/crescent/exchange/v1beta1/markets/1/order_book +``` + +Example Response + +```json +{ + "order_books": [ + { + "price_interval": "0.001000000000000000", + "sells": [ + ], + "buys": [ + { + "p": "15.000000000000000000", + "q": "100000.000000000000000000" + } + ] + }, + { + "price_interval": "0.010000000000000000", + "sells": [ + ], + "buys": [ + { + "p": "15.000000000000000000", + "q": "100000.000000000000000000" + } + ] + }, + { + "price_interval": "0.100000000000000000", + "sells": [ + ], + "buys": [ + { + "p": "15.000000000000000000", + "q": "100000.000000000000000000" + } + ] + } + ] +} +``` + diff --git a/docs/api/liquidamm.md b/docs/api/liquidamm.md new file mode 100644 index 000000000..525997584 --- /dev/null +++ b/docs/api/liquidamm.md @@ -0,0 +1,243 @@ +--- +Title: Liquidamm +Description: A high-level overview of what gRPC-gateway REST routes are supported in the liquidamm module. +--- + +# liquidamm Module + +## Synopsis + +This document provides a high-level overview of what gRPC-gateway REST routes are supported in the `liquidamm` module. + +## gRPC-gateway REST Routes + + + +++https://github.com/crescent-network/crescent/blob/main/proto/crescent/liquidamm/v1beta1/query.proto + +- [Params](#Params) +- [PublicPositions](#PublicPositions) +- [PublicPosition](#PublicPosition) +- [RewardsAuctions](#Rewardsauctions) +- [RewardsAuction](#Rewardsauction) +- [Bids](#Bids) +- [Rewards](#Rewards) + +## Params + +Example Request + + + +```bash +http://localhost:1317/crescent/liquidamm/v1beta1/params +``` + +Example Response + +```json +{ + "params": { + "rewards_auction_duration": "3600s", + "max_num_recent_rewards_auctions": 10 + } +} +``` + +## PublicPositions + +Example Request + + + +```bash +http://localhost:1317/crescent/liquidamm/v1beta1/public_positions +``` + +Example Response + +```json +{ + "public_positions": [ + { + "id": "1", + "pool_id": "1", + "lower_tick": 35000, + "upper_tick": 45000, + "bid_reserve_address": "cre1rkln8d74uhfyc9qp3645xnwks0pd8rsterguf6uugd2g60m37dmqwcapvh", + "min_bid_amount": "100000", + "fee_rate": "0.003000000000000000", + "last_rewards_auction_id": "0", + "liquidity": "0", + "position_id": "0", + "total_share": { + "denom": "sb1", + "amount": "0" + } + } + ], + "pagination": { + "next_key": null, + "total": "1" + } +} +``` + +## PublicPosition + +Example Request + + + +```bash +http://localhost:1317/crescent/liquidamm/v1beta1/public_positions/1 +``` + +Example Response + +```json +{ + "public_position": { + "id": "1", + "pool_id": "1", + "lower_tick": 35000, + "upper_tick": 45000, + "bid_reserve_address": "cre1rkln8d74uhfyc9qp3645xnwks0pd8rsterguf6uugd2g60m37dmqwcapvh", + "min_bid_amount": "100000", + "fee_rate": "0.003000000000000000", + "last_rewards_auction_id": "0", + "liquidity": "0", + "position_id": "0", + "total_share": { + "denom": "sb1", + "amount": "0" + } + } +} +``` + +## RewardsAuctions + +Example Request + + + +```bash +http://localhost:1317/crescent/liquidamm/v1beta1/public_positions/1/rewards_auctions +http://localhost:1317/crescent/liquidamm/v1beta1/public_positions/1/rewards_auctions?status=AUCTION_STATUS_STARTED +http://localhost:1317/crescent/liquidamm/v1beta1/public_positions/1/rewards_auctions?status=AUCTION_STATUS_FINISHED +http://localhost:1317/crescent/liquidamm/v1beta1/public_positions/1/rewards_auctions?status=AUCTION_STATUS_SKIPPED +``` + +Example Response + +```json +{ + "rewards_auctions": [ + { + "public_position_id": "1", + "id": "1", + "start_time": "2023-07-05T01:59:28.180826Z", + "end_time": "2023-07-06T00:00:00Z", + "status": "AUCTION_STATUS_STARTED", + "winning_bid": null, + "rewards": [ + ], + "fees": [ + ] + } + ], + "pagination": { + "next_key": null, + "total": "1" + } +} +``` + +## RewardsAuction + +Example Request + + + +```bash +http://localhost:1317/crescent/liquidamm/v1beta1/public_positions/1/rewards_auctions/1 +``` + +Example Response + +```json +{ + "rewards_auction": { + "public_position_id": "1", + "id": "1", + "start_time": "2023-07-05T01:59:28.180826Z", + "end_time": "2023-07-06T00:00:00Z", + "status": "AUCTION_STATUS_STARTED", + "winning_bid": null, + "rewards": [ + ], + "fees": [ + ] + } +} +``` + +## Bids + +Example Request + + + +```bash +http://localhost:1317/crescent/liquidamm/v1beta1/public_positions/1/rewards_auctions/1/bids +``` + +Example Response + +```json +{ + "bids": [ + { + "public_position_id": "1", + "rewards_auction_id": "1", + "bidder": "cre1zaavvzxez0elundtn32qnk9lkm8kmcszxclz6p", + "share": { + "denom": "sb1", + "amount": "1000000" + } + } + ], + "pagination": { + "next_key": null, + "total": "1" + } +} +``` + +## Rewards + +Example Request + + + +```bash +http://localhost:1317/crescent/liquidamm/v1beta1/public_positions/1/rewards +``` + +Example Response + +```json +{ + "rewards": [ + { + "denom": "uatom", + "amount": "50456" + }, + { + "denom": "uusd", + "amount": "749866" + } + ] +} +``` diff --git a/docs/api/liquidfarming.md b/docs/api/liquidfarming.md deleted file mode 100644 index 08362a940..000000000 --- a/docs/api/liquidfarming.md +++ /dev/null @@ -1,264 +0,0 @@ ---- -Title: Liquidfarming -Description: A high-level overview of what gRPC-gateway REST routes are supported in the liquidfarming module. ---- - -# Liquidfarming Module - -## Synopsis - -This document provides a high-level overview of what gRPC-gateway REST routes are supported in the `liquidfarming` module. - -## gRPC-gateway REST Routes - - - -++https://github.com/crescent-network/crescent/blob/main/proto/crescent/liquidfarming/v1beta1/query.proto - -- [Params](#Params) -- [LiquidFarms](#Liquidfarms) -- [LiquidFarm](#Liquidfarm) -- [RewardsAuctions](#Rewardsauctions) -- [RewardsAuction](#Rewardsauction) -- [Bids](#Bids) -- [Rewards](#Rewards) -- [ExchangeRate](#ExchangeRate) - -## Params - -Example Request - - - -```bash -http://localhost:1317/crescent/liquidfarming/v1beta1/params -``` - -Example Response - -```json -{ - "params": { - "fee_collector": "cre1lsvtflq2gau8ha7zvlethfy85qus59eserphyhc3tumua7upx6eqckll2q", - "rewards_auction_duration": "120s", - "liquid_farms": [ - { - "pool_id": "1", - "min_farm_amount": "1", - "min_bid_amount": "1", - "fee_rate": "0.000000000000000000" - } - ] - } -} -``` - -## LiquidFarms - -Example Request - - - -```bash -http://localhost:1317/crescent/liquidfarming/v1beta1/liquidfarms -``` - -Example Response - -```json -{ - "liquid_farms": [ - { - "pool_id": "1", - "liquid_farm_reserve_address": "cre1zyyf855slxure4c8dr06p00qjnkem95d2lgv8wgvry2rt437x6ts363hdt", - "lf_coin_denom": "lf1", - "lf_coin_supply": "500000000000", - "pool_coin_denom": "pool1", - "pool_coin_farming_amount": "500000000000", - "min_farm_amount": "1", - "min_bid_amount": "1" - } - ] -} -``` - -## LiquidFarm - -Example Request - - - -```bash -http://localhost:1317/crescent/liquidfarming/v1beta1/liquidfarms/1 -``` - -Example Response - -```json -{ - "liquid_farm": { - "pool_id": "1", - "liquid_farm_reserve_address": "cre1zyyf855slxure4c8dr06p00qjnkem95d2lgv8wgvry2rt437x6ts363hdt", - "lf_coin_denom": "lf1", - "lf_coin_supply": "500000000000", - "pool_coin_denom": "pool1", - "pool_coin_farming_amount": "500000000000", - "min_farm_amount": "1", - "min_bid_amount": "1" - } -} -``` - -## RewardsAuctions - -Example Request - - - -```bash -http://localhost:1317/crescent/liquidfarming/v1beta1/liquidfarms/1/rewards_auctions -http://localhost:1317/crescent/liquidfarming/v1beta1/liquidfarms/1/rewards_auctions?status=AUCTION_STATUS_STARTED -http://localhost:1317/crescent/liquidfarming/v1beta1/liquidfarms/1/rewards_auctions?status=AUCTION_STATUS_FINISHED -http://localhost:1317/crescent/liquidfarming/v1beta1/liquidfarms/1/rewards_auctions?status=AUCTION_STATUS_SKIPPED -``` - -Example Response - -```json -{ - "rewards_auctions": [ - { - "id": "1", - "pool_id": "1", - "bidding_coin_denom": "pool1", - "paying_reserve_address": "cre1h72q3pkvsz537kj08hyv20tun3apampxhpgad97t3ls47nukgtxq4nw9fg", - "start_time": "2022-09-27T06:06:52.627872Z", - "end_time": "2022-09-27T06:08:52.627872Z", - "status": "AUCTION_STATUS_STARTED", - "winner": "", - "winning_amount": { - "denom": "", - "amount": "0" - }, - "rewards": [ - { - "denom": "stake", - "amount": "25369" - } - ], - "fees": [], - "fee_rate": "0.000000000000000000" - } - ] -} -``` - -## RewardsAuction - -Example Request - - - -```bash -http://localhost:1317/crescent/liquidfarming/v1beta1/liquidfarms/1/rewards_auctions/1 -``` - -Example Response - -```json -{ - "rewards_auction": { - "id": "1", - "pool_id": "1", - "bidding_coin_denom": "pool1", - "paying_reserve_address": "cre1h72q3pkvsz537kj08hyv20tun3apampxhpgad97t3ls47nukgtxq4nw9fg", - "start_time": "2022-08-05T08:56:22.237454Z", - "end_time": "2022-08-06T08:56:22.237454Z", - "status": "AUCTION_STATUS_FINISHED", - "winner": "", - "winning_amount": { - "denom": "", - "amount": "0" - }, - "rewards": [ - { - "denom": "stake", - "amount": "25369" - } - ], - "fees": [], - "fee_rate": "0.000000000000000000" - } -} -``` - -## Bids - -Example Request - - - -```bash -http://localhost:1317/crescent/liquidfarming/v1beta1/liquidfarms/1/bids -``` - -Example Response - -```json -{ - "bids": [ - { - "pool_id": "1", - "bidder": "cre1zaavvzxez0elundtn32qnk9lkm8kmcszxclz6p", - "amount": { - "denom": "pool1", - "amount": "1000000000" - } - } - ] -} -``` - -## Rewards - -Example Request - - - -```bash -http://localhost:1317/crescent/liquidfarming/v1beta1/liquidfarms/1/rewards -``` - -Example Response - -```json -{ - "rewards": [ - { - "denom": "stake", - "amount": "1903" - } - ] -} -``` - -## ExchangeRate - -Example Request - - - -```bash -http://localhost:1317/crescent/liquidfarming/v1beta1/liquidfarms/1/exchange_rate -``` - -Example Response - -```json -{ - "exchange_rate": { - "mint_rate": "1.000000000000000000", - "burn_rate": "1.000000000000000000" - } -} -``` diff --git a/docs/cli/amm.md b/docs/cli/amm.md new file mode 100644 index 000000000..da9b25464 --- /dev/null +++ b/docs/cli/amm.md @@ -0,0 +1,456 @@ +--- +Title: AMM +Description: A high-level overview of how the command-line interfaces (CLI) works for the amm module. +--- + +# AMM Module + +## Synopsis + +This document provides a high-level overview of how the command line (CLI) interface works for the `amm` module. + +Note that [jq](https://stedolan.github.io/jq/) is recommended to be installed as it is used to process JSON throughout the document. + +## Command Line Interfaces + +- [Transaction](#Transaction) + - [CreatePool](#CreatePool) + - [AddLiquidity](#AddLiquidity) + - [RemoveLiquidity](#RemoveLiquidity) + - [Collect](#Collect) + - [CreatePrivateFarmingPlan](#CreatePrivateFarmingPlan) + - [TerminatePrivateFarmingPlan](#TerminatePrivateFarmingPlan) +- [Query](#Query) + - [Params](#Params) + - [AllPools](#AllPools) + - [Pool](#Pool) + - [AllPositions](#AllPositions) + - [Position](#Position) + - [AddLiquiditySimulation](#AddLiquiditySimulation) + - [RemoveLiquiditySimulation](#RemoveLiquiditySimulation) + - [CollectibleCoins](#CollectibleCoins) + - [AllTickInfos](#AllTickInfos) + - [TickInfo](#TickInfo) + - [AllFarmingPlans](#AllFarmingPlans) + - [FarmingPlan](#FarmingPlan) + +# Transaction + +## CreatePool + +Create a pool to market for trading. + +A pool is tied to a single market and places orders to market based on the preset logic. Once a pool is created, liquidity providers can create positions. + +Usage + +```bash +create-pool [market-id] [price] +``` + +| **Argument** | **Description** | +| :--------------- | :----------------------------------------------------- | +| market-id | id of the market where the pool's order will be placed | +| price | initial pool price | + +Example + +```bash +# Create a pool +crescentd tx amm create-pool 1 10 \ +--chain-id localnet \ +--from alice + +# +# Tips +# +# You can query pools by using the following command +crescentd q amm pools -o json | jq +``` + +## AddLiquidity + +Add liquidity to existing position or make a new position. + +Position(s) belong to a pool. Therefore, a pool must exist in order to create a position. Anyone can create a position with custom range. + +Usage + +```bash +add-liquidity [pool-id] [lower-price] [upper-price] [desired-amount] +``` + +| **Argument** | **Description** | +| :------------ | :------------------------------------------------- | +| pool-id | pool id | +| lower-price | lower bound for price range of liquidity providing | +| upper-price | upper bound for price range of liquidity providing | +| desired-amount | deposit amounts of base and quote coins | + +Example + +```bash +# Create a position with 10ATOM/10USD which provide liquidity to price range [9,11] +crescentd tx amm add-liquidity 1 9 11 10000000uatom,10000000uusd \ +--chain-id localnet \ +--from alice + +# +# Tips +# +# You can query expected result of add-liquidity by using the following command +crescentd q amm add-liquidity-simulation 1 9 11 10000000uatom,10000000uusd -o json | jq +``` + +## RemoveLiquidity + +Withdraw coins from the liquidity providing position. + +Withdrawal requests are typically processed in the order they are received, rather than being delayed until the end of a batch. + +Usage + +```bash +remove-liquidity [position-id] [liquidity] +``` + +| **Argument** | **Description** | +| :------------ | :-------------------------------------------------- | +| position-id | position id | +| liquidity | amount of liquidity to be removed from the position | + +Example + +```bash +# Remove 10000 liquidity from position with id 1 +crescentd tx amm remove-liquidity 1 10000 \ +--chain-id localnet \ +--from alice + +# +# Tips +# +# You can query expected result of remove-liquidity by using the following command +crescentd q amm remove-liquidity-simulation 1 10000 -o json | jq +``` + +## Collect + +Collect rewards accumulated in a position. + +The reward consists of the swap fee and farming reward accumulated in the position. + +Usage + +```bash +collect [position-id] [amount] +``` + +| **Argument** | **Description** | +| :------------ | :-------------------------------- | +| position-id | position id | +| amount | amounts of reward to be withdrawn | + +Example + +```bash +# Withdraw 10uATOM and 10uUSD of reward from the positino +crescentd tx amm collect 1 10uatom,10uusd \ +--chain-id localnet \ +--from alice + +# +# Tips +# +# You can query collectible reward by using the following command +crescentd crescentd q amm collectible-coins --position-id 1 -o json | jq +``` + +## CreatePrivateFarmingPlan + +Create a new private farming plan. + +The newly created plan's farming pool address is automatically generated and will have no balances in the account initially. + +Manually send enough reward coins to the generated farming pool address to make sure that the rewards allocation happens. + +The plan's termination address is set to the plan creator. + +```bash +create-private-farming-plan [description] [termination-address] [start-time] [end-time] [reward-allocations...] +``` + +| **Argument** | **Description** | +| :-------------------- | :------------------------------------------------------------------------------------------------------ | +| description | a brief description of the plan | +| termination-address | address where the remaining farming rewards in the farming pool transferred when the plan is terminated | +| start-time | the time at which the plan begins, in RFC3339 format | +| end-time | the time at which the plan ends, in RFC3339 format | +| reward-allocations... | whitespace-separated list of the reward allocations | + +Example + +```bash +# Create private farming plan +crescentd tx amm create-private-farming-plan "New farming plan" cre1zaavvzxez0elundtn32qnk9lkm8kmcszxclz6p 2023-01-01T00:00:00Z 2024-01-01T00:00:00Z 1:1000000uatom \ +--chain-id localnet \ +--from alice \ + +# +# Tips +# +# You can query farming plans by using the following command +crescentd q amm farming-plans -o json | jq +``` + +## TerminatePrivateFarmingPlan + +Terminate a private farming plan. + +The plan's termination address must be same with the message sender. + +Usage + +```bash +terminate-private-farming-plan [farming-plan-id] +``` + +| **Argument** | **Description** | | +|:------------------|:--------------- | +| farming-plan-id | farming plan id | + +Example + +```bash +# Withdraw pool coin from the pool +crescentd tx amm terminate-private-farming-plan 1 \ +--chain-id localnet \ +--from alice \ + +# +# Tips +# +# You can query farming plans by using the following command +crescentd q amm farming-plans -o json | jq +``` + + +# Query + +## Params + +Query the current amm parameters information + +Usage + +```bash +params +``` + +Example + +```bash +crescentd q amm params -o json | jq +``` + +## AllPools + +Query for all pools + +Usage + +```bash +pools +``` + +Example + +```bash +crescentd q amm pools -o json | jq +```` + +## Pool + +Query details for the particular pool + +Usage + +```bash +pool [pool-id] +``` + +Example + +```bash +crescentd q amm pool 1 -o json | jq +``` + +## AllPositions + +Query for all positions + +Usage + +```bash +positions +``` + +Example + +```bash +# Query all positions +crescentd q amm positions -o json | jq + +# Query all positions that has the pool id +crescentd q amm positions --pool-id 1 -o json | jq + +# Query all positions of particular address +crescentd q amm position --owner cre1zaavvzxez0elundtn32qnk9lkm8kmcszxclz6p -o json | jq +``` + +## Position + +Query details for the particular position + +Usage + +```bash +position [position-id] +``` + +Example + +```bash +crescentd q amm position 1 -o json | jq +``` + +## AddLiquiditySimulation + +Query expected result for add-liquidity + +Usage + +```bash +add-liquidity-simulation [pool-id] [lower-price] [upper-price] [desired-amount] +``` + +Example + +```bash +crescentd q amm add-liquidity-simulation 1 9 11 10000000uatom,10000000uusd -o json | jq +``` + +## RemoveLiquiditySimulation + +Query expected result for remove-liquidity + +Usage + +```bash +remove-liquidity-simulation [position-id] [liquidity] +``` + +Example + +```bash +crescentd q amm remove-liquidity-simulation 1 10000 -o json | jq +``` + +## CollectibleCoins + +Query collectible coins(fees, rewards) in the position. + +Usage + +```bash +collectible-coins +``` + +Example + +```bash +# Query collectible coins with address +crescentd q amm collectible-coins --owner cre1zaavvzxez0elundtn32qnk9lkm8kmcszxclz6p -o json | jq + +# Query collectible coins with position id +crescentd q amm collectible-coins --position-id 1 -o json | jq +``` + +## AllTickInfos + +Query for information of all ticks in the particular pool + +Usage + +```bash +tick-infos [pool-id] +``` + +Example + +```bash +# Query all ticks in pool +crescentd q amm tick-infos 1 -o json | jq + +# Query all ticks above designated lower tick +crescentd q amm tick-infos 1 --lower-tick 10000 -o json | jq + +# Query all ticks below designated upper tick +crescentd q amm tick-infos 1 --upper-tick 10000 -o json | jq +``` + +## TickInfo + +Query details for the particular tick in the pool + +Usage + +```bash +tick-info [pool-id] [tick] +``` + +Example + +```bash +crescentd q amm tick-info 1 10000 -o json | jq +``` + + +## AllFarmingPlans + +Query for all farming plans + +Usage + +```bash +farming-plans +``` + +Example + +```bash +# Query all farming plans +crescentd q amm farming-plans -o json | jq + +# Query farming plans based on private status +crescentd q amm farming-plans --is-private true -o json | jq + +# Query farming plans based on private status +crescentd q amm farming-plans --is-terminated true -o json | jq +``` + +## FarmingPlan + +Query details for the particular farming plan + +Usage + +```bash +farming-plan [plan-id] +``` + +Example + +```bash +crescentd q amm farming-plan 1 -o json | jq +``` \ No newline at end of file diff --git a/docs/cli/exchange.md b/docs/cli/exchange.md new file mode 100644 index 000000000..8fbb0d51a --- /dev/null +++ b/docs/cli/exchange.md @@ -0,0 +1,452 @@ +--- +Title: Exchange +Description: A high-level overview of how the command-line interfaces (CLI) works for the exchange module. +--- + +# Exchange Module + +## Synopsis + +This document provides a high-level overview of how the command line (CLI) interface works for the `exchange` module. + +Note that [jq](https://stedolan.github.io/jq/) is recommended to be installed as it is used to process JSON throughout the document. + +## Command Line Interfaces + +- [Transaction](#Transaction) + - [CreateMarket](#CreateMarket) + - [PlaceLimitOrder](#PlaceLimitOrder) + - [PlaceBatchLimitOrder](#PlaceBatchLimitOrder) + - [PlaceMMLimitOrder](#PlaceMMLimitOrder) + - [PlaceMMBatchLimitOrder](#PlaceMMBatchLimitOrder) + - [PlaceMarketOrder](#PlaceMarketOrder) + - [CancelOrder](#CancelOrder) + - [CancelAllOrders](#CancelAllOrders) + - [SwapExactAmountIn](#SwapExactAmountIn) +- [Query](#Query) + - [Params](#Params) + - [AllMarkets](#AllMarkets) + - [Market](#Market) + - [AllOrders](#AllOrders) + - [Order](#Order) + - [BestSwapExactAmountInRoutes](#BestSwapExactAmountInRoutes) + - [OrderBook](#OrderBook) + +# Transaction + +## CreateMarket + +Create a market for trading assets. + +Usage + +```bash +create-market [base-denom] [quote-denom] +``` + +| **Argument** | **Description** | +| :------------ | :------------------------------------- | +| base-denom | denom of the base coin for the market | +| quote-denom | denom of the quote coin for the market | + +Example + +```bash +# Create a pool +crescentd tx exchange create-market uatom uusd \ +--chain-id localnet \ +--from alice + +# +# Tips +# +# You can query markets using the following command +crescentd q exchange markets -o json | jq +``` + +## PlaceLimitOrder + +Place a limit order to markets. This order will be placed in sequential matching stage. + +For buy orders, it allows orders up to 10% above the current price, and for sell orders, it allows orders up to 10% below the current price. This is to prevent users from incurring large financial losses due to simple mistakes. + +Usage + +```bash +place-limit-order [market-id] [is-buy] [price] [quantity] [lifespan] +``` + +| **Argument** | **Description** | +| :------------ | :--------------------------------------------------------------------------------------- | +| market-id | market id | +| is-buy | if this is true, the order is placed to buy base coin | +| price | order price; the exchange ratio is the amount of quote coin over the amount of base coin | +| quantity | amount of base coin that the orderer is willing to buy or sell | +| lifespan | duration that the order lives until it is expired | + +Example + +```bash +# Place a limit order +crescentd tx exchange place-limit-order 1 true 15 100000 1h \ +--chain-id localnet \ +--from alice + +# +# Tips +# +# You can query orders by using the following command +# Query all orders +crescentd q exchange orders -o json | jq + +# Query all orders in particular market +crescentd q exchange orders --makret-id 1 -o json | jq + +# Query all orders of particular orderer +crescentd q exchange orders --orderer cre1zaavvzxez0elundtn32qnk9lkm8kmcszxclz6p -o json | jq +``` + +## PlaceBatchLimitOrder + +Place a batch limit order. Batch orders are matched prior to normal orders in a batch matching stage. + +For buy orders, it allows orders up to 10% above the current price, and for sell orders, it allows orders up to 10% below the current price. This is to prevent users from incurring large financial losses due to simple mistakes. + +Usage + +```bash +place-batch-limit-order [market-id] [is-buy] [price] [quantity] [lifespan] +``` + +| **Argument** | **Description** | +| :------------ | :--------------------------------------------------------------------------------------- | +| market-id | market id | +| is-buy | if this is true, the order is placed to buy base coin | +| price | order price; the exchange ratio is the amount of quote coin over the amount of base coin | +| quantity | amount of base coin that the orderer is willing to buy or sell | +| lifespan | duration that the order lives until it is expired | + +Example + +```bash +# Place a batch limit order +crescentd tx exchange place-batch-limit-order 1 true 15 100000 1h \ +--chain-id localnet \ +--from alice + +# +# Tips +# +# You can query orders by using the following command +# Query all orders +crescentd q exchange orders -o json | jq + +# Query all orders in particular market +crescentd q exchange orders --makret-id 1 -o json | jq + +# Query all orders of particular orderer +crescentd q exchange orders --orderer cre1zaavvzxez0elundtn32qnk9lkm8kmcszxclz6p -o json | jq +``` + +## PlaceMMLimitOrder + +Place a market maker limit order. + +For buy orders, it allows orders up to 10% above the current price, and for sell orders, it allows orders up to 10% below the current price. This is to prevent users from incurring large financial losses due to simple mistakes. + +Usage + +```bash +place-mm-limit-order [market-id] [is-buy] [price] [quantity] [lifespan] +``` + +| **Argument** | **Description** | +| :------------ | :--------------------------------------------------------------------------------------- | +| market-id | market id | +| is-buy | if this is true, the order is placed to buy base coin | +| price | order price; the exchange ratio is the amount of quote coin over the amount of base coin | +| quantity | amount of base coin that the orderer is willing to buy or sell | +| lifespan | duration that the order lives until it is expired | + +Example + +```bash +# Place a market maker limit order +crescentd tx exchange place-mm-limit-order 1 true 15 100000 1h \ +--chain-id localnet \ +--from alice + +# +# Tips +# +# You can query orders by using the following command +# Query all orders +crescentd q exchange orders -o json | jq + +# Query all orders in particular market +crescentd q exchange orders --makret-id 1 -o json | jq + +# Query all orders of particular orderer +crescentd q exchange orders --orderer cre1zaavvzxez0elundtn32qnk9lkm8kmcszxclz6p -o json | jq +``` + +## PlaceMMBatchLimitOrder + +Place a market maker batch limit order. Batch orders are matched prior to normal orders in a batch matching stage. + +For buy orders, it allows orders up to 10% above the current price, and for sell orders, it allows orders up to 10% below the current price. This is to prevent users from incurring large financial losses due to simple mistakes. + +Usage +```bash +place-mm-batch-limit-order [market-id] [is-buy] [price] [quantity] [lifespan] +``` + +| **Argument** | **Description** | +| :------------ | :--------------------------------------------------------------------------------------- | +| market-id | market id | +| is-buy | if this is true, the order is placed to buy base coin | +| price | order price; the exchange ratio is the amount of quote coin over the amount of base coin | +| quantity | amount of base coin that the orderer is willing to buy or sell | +| lifespan | duration that the order lives until it is expired | + +Example + +```bash +# Place a market maker batch limit order +crescentd tx exchange place-mm-batch-limit-order 1 true 15 100000 1h \ +--chain-id localnet \ +--from alice + +# +# Tips +# +# You can query orders by using the following command +# Query all orders +crescentd q exchange orders -o json | jq + +# Query all orders in particular market +crescentd q exchange orders --makret-id 1 -o json | jq + +# Query all orders of particular orderer +crescentd q exchange orders --orderer cre1zaavvzxez0elundtn32qnk9lkm8kmcszxclz6p -o json | jq +``` + +## PlaceMarketOrder + +Place a market order. + +Usage + +```bash +place-market-order [market-id] [is-buy] [quantity] +``` + +| **Argument** | **Description** | +| :------------ | :--------------------------------------------------------------------------------------- | +| market-id | market id | +| is-buy | if this is true, the order is placed to buy base coin | +| quantity | amount of base coin that the orderer is willing to buy or sell | + +Example + +```bash +# Place a market order +crescentd tx exchange place-market-order 1 false 100000 \ +--chain-id localnet \ +--from alice +``` + +## CancelOrder + +Cancel an existing order. + +Usage + +```bash +cancel-order [order-id] +``` + +| **Argument** | **Description** | +| :------------ | :------------------ | +| order-id | order id | + +Example + +```bash +# Place a market order +crescentd tx exchange cancel-order 1 \ +--chain-id localnet \ +--from alice +``` + +## CancelAllOrders + +Cancel all orders in a market placed by the sender + +Usage + +```bash +cancel-all-orders [market-id] +``` + +| **Argument** | **Description** | +| :------------ | :------------------ | +| market-id | market id | + +Example + +```bash +# Place a market order +crescentd tx exchange cancel-all-orders 1 \ +--chain-id localnet \ +--from alice +``` + +## SwapExactAmountIn + +Swap with exact input amount. + +User need to specify swap routes from input to output. If the result of the swap falls short of user's desired output, the request will be reverted. + +Usage + +```bash +swap-exact-amount-in [routes] [input] [min-output] +``` + +| **Argument** | **Description** | +| :------------ | :-------------------------------------------------------------- | +| routes | sequential swap routes | +| input | input token denom and amount | +| min-output | The denom and minimum amount of the user's desired output token | + +Example + +```bash +# Place a market order +crescentd tx exchange swap-exact-amount-in 1,2,3 1000000uusd 98000uatom \ +--chain-id localnet \ +--from alice +``` + + +# Query + +## Params + +Query the current exchange parameters information + +Usage + +```bash +params +``` + +Example + +```bash +crescentd q exchange params -o json | jq +``` + +## AllMarkets + +Query for all markets + +Usage + +```bash +markets +``` + +Example + +```bash +crescentd q exchange markets -o json | jq +```` + +## Market + +Query details for the particular market + +Usage + +```bash +market [market-id] +``` + +Example + +```bash +crescentd q exchange market 1 -o json | jq +``` + +## AllOrders + +Query for all orders + +Usage + +```bash +orders +``` + +Example + +```bash +# Query all orders +crescentd q exchange orders -o json | jq + +# Query all orders in particular market +crescentd q exchange orders --makret-id 1 -o json | jq + +# Query all orders of particular orderer +crescentd q exchange orders --orderer cre1zaavvzxez0elundtn32qnk9lkm8kmcszxclz6p -o json | jq +``` + +## Order + +Query details for the particular order + +Usage + +```bash +order [order-id] +``` + +Example + +```bash +crescentd q exchange order 1 -o json | jq +``` + +## BestSwapExactAmountInRoutes + +Query for the route that can be swapped at the best price given the input token denom and volume, and the denom of the output token. + +Usage + +```bash +best-swap-exact-amount-in-routes [input] [output-denom] +``` + +Example + +```bash +crescentd q exchange best-swap-exact-amount-in-routes 1000000uusd uatom -o json | jq +``` + +## Orderbook + +Query orderbook of particular market from exisiting orders + +Usage + +```bash +order-book [market-id] +``` + +Example + +```bash +crescentd q exchange order-book 1 -o json | jq +``` diff --git a/docs/cli/liquidamm.md b/docs/cli/liquidamm.md new file mode 100644 index 000000000..057e87c42 --- /dev/null +++ b/docs/cli/liquidamm.md @@ -0,0 +1,258 @@ +--- +Title: LiquidAMM +Description: A high-level overview of how the command-line interfaces (CLI) works for the liquidamm module. +--- + +# LiquidAMM Module + +## Synopsis + +This document provides a high-level overview of how the command line (CLI) interface works for the `liquidamm` module. + +Note that [jq](https://stedolan.github.io/jq/) is recommended to be installed as it is used to process JSON throughout the document. + +## Command Line Interfaces + +- [Transaction](#Transaction) + - [MintShare](#MintShare) + - [BurnShare](#BurnShare) + - [PlaceBid](#PlaceBid) +- [Query](#Query) + - [Params](#Params) + - [PublicPositions](#PublicPositions) + - [PublicPosition](#PublicPosition) + - [RewardsAuctions](#RewardsAuctions) + - [RewardsAuction](#RewardsAuction) + - [Bids](#Bids) + - [Rewards](#Rewards) + +# Transaction + +## MintShare + +Mint public position share for auto compounding rewards. The module mints the corresponding amount of `sbCoin` and sends it to the sender when the execution is complete. + +Usage + +```bash +mint-share [public-position-id] [desired-amount] +``` + +| **Argument** | **Description** | +|:-------------------|:----------------------------------------| +| public-position-id | public position id | +| desired-amount | deposit amounts of base and quote coins | + +Example + +```bash +# In order to fully test the module in your local network, public positions must be set up by governance proposal. +# +# For example, + +crescentd tx gov submit-proposal public-position-create proposal.json --chain-id localnet --from alice + +Where proposal.json contains: +{ + "title": "Public Position Create Proposal", + "description": "Let's start new liquid amm", + "pool_id": "1", + "lower_price": "4.5", + "upper_price": "5.5", + "min_bid_amount": "100000000", + "fee_rate": "0.003" +} + +# mint share +crescentd tx liquidamm mint-share 1 100000000uatom,500000000uusd \ +--chain-id localnet \ +--from alice + +# +# Tips +# +# Query all the registered public position objects +crescentd q liquidamm public-positions -o json | jq +# +# Query account balances to see if Alice has sb coin. +crescentd q bank balances cre1zaavvzxez0elundtn32qnk9lkm8kmcszxclz6p -o json | jq +``` + +## BurnShare + +Burn liquid amm share to withdraw underlying tokens. + +Usage + +```bash +burn-share [public-position-id] [share] +``` + +| **Argument** | **Description** | +|:-------------------|:--------------------------------| +| public-position-id | public position id | +| share | desired amount of burning share | + +Example + +```bash +crescentd tx liquidamm burn-share 1 10000000000sb1 \ +--chain-id localnet \ +--from alice \ +# +# Tips +# +# Query account balances +crescentd q bank balances cre1zaavvzxez0elundtn32qnk9lkm8kmcszxclz6p -o json | jq +``` + +## PlaceBid + +Place a bid for a rewards auction. Bidders estimate how much rewards for the next epoch will be accumulated and place their bids accordingly with sb coin amount. + +Usage + +```bash +place-bid [public-position-id] [auction-id] [share] +``` + +| **Argument** | **Description** | +|:-------------------|:-----------------------| +| public-position-id | public position id | +| auction-id | auction id | +| share | bid amount for auction | + +Example + +```bash +crescentd tx liquidamm place-bid 1 1 10000000sb1 \ +--chain-id localnet \ +--from alice \ + +# +# Tips +# +crescentd q liquidamm bids 1 -o json | jq +``` + + +# Query + +## Params + +Query the current liquidamm parameters information. + +Usage + +```bash +params +``` + +Example + +```bash +crescentd query liquidamm params -o json | jq +``` + +## PublicPositions + +Query for all public positions. + +Usage + +```bash +public-positions +``` + +Example + +```bash +crescentd query liquidamm public-positions -o json | jq +``` + +## PublicPosition + +Query the specific public position with id. + +Usage + +```bash +public-position [public-position-id] +``` + +Example + +```bash +crescentd query liquidamm public-position 1 -o json | jq +``` + +## RewardsAuctions + +Query all rewards auctions for specific public position. + +Usage + +```bash +rewards-auctions [public-position-id] +``` + +Example + +```bash +# The "rewards_auction_duration" param is the duration that is used to create new rewards auction in begin blocker. +# You can adjust the value in config-test.yml file to make it faster or slower. +# By default, the value is set to 8 hours but for local testing purpose it is set to 120 seconds. +# If you wait 120 seconds (2 minutes) after starting a local network, the module automatically creates new rewards auction. +crescentd query liquidamm rewards-auctions 1 -o json | jq +crescentd query liquidamm rewards-auctions 1 --status AUCTION_STATUS_STARTED -o json | jq +crescentd query liquidamm rewards-auctions 1 --status AUCTION_STATUS_FINISHED -o json | jq +crescentd query liquidamm rewards-auctions 1 --status AUCTION_STATUS_SKIPPED -o json | jq +``` + +## RewardsAuction + +Query the specific reward auction + +Usage + +```bash +rewards-auction [public-position-id] [auction-id] +``` + +Example + +```bash +crescentd query liquidamm rewards-auction 1 1 -o json | jq +``` + +## Bids + +Query all bids for the rewards auction + +Usage + +```bash +bids [public-position-id] [auction-id] +``` + +Example + +```bash +crescentd query liquidamm bids 1 1 -o json | jq +``` + +## Rewards + +Query current rewards for the particular public position + +Usage + +```bash +rewards [public-position-id] +``` + +Example + +```bash +crescentd query liquidamm rewards 1 -o json | jq +``` diff --git a/docs/cli/liquidfarming.md b/docs/cli/liquidfarming.md deleted file mode 100644 index 1537214db..000000000 --- a/docs/cli/liquidfarming.md +++ /dev/null @@ -1,359 +0,0 @@ ---- -Title: LiquidFarming -Description: A high-level overview of how the command-line interfaces (CLI) works for the liquidfarming module. ---- - -# LiquidFarming Module - -## Synopsis - -This document provides a high-level overview of how the command line (CLI) interface works for the `liquidfarming` module. - -Note that [jq](https://stedolan.github.io/jq/) is recommended to be installed as it is used to process JSON throughout the document. - -## Command Line Interfaces - -- [Transaction](#Transaction) - - [LiquidFarm](#LiquidFarm) - - [LiquidUnfarm](#LiquidUnfarm) - - [PlaceBid](#PlaceBid) - - [RefundBid](#RefundBid) - - [AdvanceAuction](#AdvanceAuction) -- [Query](#Query) - - [Params](#Params) - - [LiquidFarms](#LiquidFarms) - - [LiquidFarm](#LiquidFarm) - - [RewardsAuctions](#RewardsAuctions) - - [RewardsAuction](#RewardsAuction) - - [Bids](#Bids) - - [Rewards](#Rewards) - - [ExchangeRate](#ExchangeRate) - -# Transaction - -## LiquidFarm - -Farm pool coin to make it liquid. The module mints the corresponding amount of `LFCoin` and sends it to the farmer when the execution is complete. - -Usage - -```bash -liquid-farm [pool-id] [amount] -``` - -| **Argument** | **Description** | -| :----------- | :--------------------------------- | -| pool-id | pool id for the liquid farm | -| amount | amount of pool coin to liquid farm | - -Example - -```bash -# In order to fully test the module in your local network, the following testing environments must be set up. -# -# 1. Register new LiquidFarm by param-change governance proposal -# - Unless you want to register new one, you do not have to do anything if you run a local network using `ignite` with config-test.yml. -# - LiquidFarm is already set up in config-test.yml file -# -# 2. Set up an account (e.g: alice) to have some pool coin -# - Create a new pool with X/Y coin -# - Send limit orders to set last price which needs to be set in order for the farm module to allocate rewards -# - Reference docs/cli/liquidity.md document for a detailed information -# -# 3. Create a Farm plan to participate RewardsAuction to place a bid for farming rewards -# - Create a new private farm plan to allocate rewards per day -# - Reference docs/cli/lpfarm.md document for a detailed information -# -# 4. Send some coins to the farming pool address that is generated when you create a farming plan -# - Farming pool address must have some coins to distribute farming rewards -crescentd tx liquidfarming liquid-farm 1 500000000000pool1 \ ---chain-id localnet \ ---from alice \ ---keyring-backend test \ ---gas 1000000 \ ---broadcast-mode block \ ---yes \ ---output json | jq - -# -# Tips -# -# Query all the registered LiquidFarm objects -crescentd q liquidfarming liquidfarms -o json | jq - -# Query account balances to see if Alice has lfcoin. -crescentd q bank balances cre1zaavvzxez0elundtn32qnk9lkm8kmcszxclz6p -o json | jq -``` - -## LiquidUnfarm - -Unfarm liquid farming coin to get the corresponding pool coin in return. - -Usage - -```bash -liquid-unfarm [pool-id] [amount] -``` - -| **Argument** | **Description** | -| :----------- | :-------------------------- | -| pool-id | pool id for the liquid farm | -| amount | amount of lf coin to unfarm | - -Example - -```bash -crescentd tx liquidfarming liquid-unfarm 1 300000000000lf1 \ ---chain-id localnet \ ---from alice \ ---keyring-backend test \ ---broadcast-mode block \ ---yes \ ---output json | jq - -# -# Tips -# -# Query account balances -crescentd q bank balances cre1zaavvzxez0elundtn32qnk9lkm8kmcszxclz6p -o json | jq -``` - -## PlaceBid - -Place a bid for a rewards auction. Bidders estimate how much rewards for the next epoch will be accumulated and place their bids accordingly with pool coin amount. - -Usage - -```bash -place-bid [auction-id] [pool-id] [amount] -``` - -| **Argument** | **Description** | -| :----------- | :------------------------------------------------- | -| auction-id | auction id for the liquid unfarm | -| pool-id | pool id for the liquid unfarm | -| amount | amount of pool coin to bid for the rewards auction | - -Example - -```bash -crescentd tx liquidfarming place-bid 1 1 1000000000pool1 \ ---chain-id localnet \ ---from alice \ ---keyring-backend test \ ---broadcast-mode block \ ---yes \ ---output json | jq - -# -# Tips -# -crescentd q liquidfarming bids 1 -o json | jq -``` - -## RefundBid - -Refund the placed bid for the rewards auction. Bidders use this transaction message to refund their bid; however, it is important to note that if the bid is currently winning bid, it can't be refunded. - -Usage - -```bash -refund-bid [auction-id] [pool-id] -``` - -| **Argument** | **Description** | -| :----------- | :----------------------------- | -| auction-id | auction id for the liquid farm | -| pool-id | pool id for the liquid farm | - -Example - -```bash -crescentd tx liquidfarming refund-bid 1 1 \ ---chain-id localnet \ ---from alice \ ---keyring-backend test \ ---broadcast-mode block \ ---yes \ ---output json | jq -``` - -## AdvanceAuction - -***This message is disabled by default, you have to build the binary with `make install-testing` to activate this message.*** - -Usage - -```bash -advance-auction -``` - -Example - -```bash -crescentd tx liquidfarming advance-auction \ ---chain-id localnet \ ---from alice \ ---keyring-backend test \ ---broadcast-mode block \ ---yes \ ---output json | jq -``` - -# Query - -## Params - -Query the current liquidfarming parameters information. - -Usage - -```bash -params -``` - -Example - -```bash -crescentd query liquidfarming params -o json | jq -``` - -## LiquidFarms - -Query for all liquidfarms. - -Usage - -```bash -liquidfarms -``` - -Example - -```bash -crescentd query liquidfarming liquidfarms -o json | jq -``` - -## LiquidFarm - -Query the specific liquidfarm with pool id. - -Usage - -```bash -liquidfarm [pool-id] -``` - -| **Argument** | **Description** | -| :----------- | :------------------------ | -| pool-id | pool id of the liquidfarm | - -Example - -```bash -crescentd query liquidfarming liquidfarm 1 -o json | jq -``` - -## RewardsAuctions - -Query all rewards auctions for the liquidfarm. - -Usage - -```bash -rewards-auctions -``` - -Example - -```bash -# The "rewards_auction_duration" param is the duration that is used to create new rewards auction in begin blocker. -# You can adjust the value in config-test.yml file to make it faster or slower. -# By default, the value is set to 8 hours but for local testing purpose it is set to 120 seconds. -# If you wait 120 seconds (2 minutes) after starting a local network, the module automatically creates new rewards auction. -crescentd query liquidfarming rewards-auctions 1 -o json | jq -crescentd query liquidfarming rewards-auctions 1 --status AUCTION_STATUS_STARTED -o json | jq -crescentd query liquidfarming rewards-auctions 1 --status AUCTION_STATUS_FINISHED -o json | jq -crescentd query liquidfarming rewards-auctions 1 --status AUCTION_STATUS_SKIPPED -o json | jq -``` - -## RewardsAuction - -Query the specific reward auction - -Usage - -```bash -rewards-auction [pool-id] [auction-id] -``` - -| **Argument** | **Description** | -| :----------- | :-------------------------------------------- | -| pool-id | pool id of the liquidfarm | -| auction-id | auction id of the liquidfarm with the pool id | - -Example - -```bash -crescentd query liquidfarming rewards-auction 1 1 -o json | jq -``` - -## Bids - -Query all bids for the rewards auction - -Usage - -```bash -bids [pool-id] -``` - -| **Argument** | **Description** | -| :----------- | :------------------------ | -| pool-id | pool id of the liquidfarm | - -Example - -```bash -crescentd query liquidfarming bids 1 -o json | jq -``` - -## Rewards - -Query current farming rewards for the particular liquid farm - -Usage - -```bash -rewards [pool-id] -``` - -| **Argument** | **Description** | -| :----------- | :------------------------ | -| pool-id | pool id of the liquidfarm | - -Example - -```bash -crescentd query liquidfarming rewards 1 -o json | jq -``` - -## ExchangeRate - -Query current exchange rate for mint and burn rates - -Usage - -```bash -exchange-rate [pool-id] -``` - -| **Argument** | **Description** | -| :----------- | :------------------------ | -| pool-id | pool id of the liquidfarm | - -Example - -```bash -crescentd query liquidfarming exchange-rate 1 -o json | jq -``` \ No newline at end of file diff --git a/x/amm/spec/02_state.md b/x/amm/spec/02_state.md index 965104d75..28d3f1514 100644 --- a/x/amm/spec/02_state.md +++ b/x/amm/spec/02_state.md @@ -4,26 +4,30 @@ ## Pool -* LastPoolId: `0x?? -> BigEndian(LastPoolId)` -* Pool: `0x?? | BigEndian(PoolId) -> ProtocolBuffer(Pool)` -* PoolByReserveAddressIndex: `0x?? | AddrLen (1 byte) | ReserveAddress -> BigEndian(PoolId)` -* PoolByMarketIndexKeyPrefix: `0x?? | BigEndian(MarketId) -> BigEndian(PoolId)` -* PoolState: `0x?? | BigEndian(PoolId) -> ProtocolBuffer(PoolState)` +* LastPoolId: `0x40 -> BigEndian(LastPoolId)` +* Pool: `0x42 | BigEndian(PoolId) -> ProtocolBuffer(Pool)` +* PoolState: `0x43 | BigEndian(PoolId) -> ProtocolBuffer(PoolState)` +* PoolByReserveAddressIndex: `0x44 | AddrLen (1 byte) | ReserveAddress -> BigEndian(PoolId)` +* PoolByMarketIndexKeyPrefix: `0x45 | BigEndian(MarketId) -> BigEndian(PoolId)` ```go type Pool struct { - Id uint64 - MarketId uint64 - Denom0 string - Denom1 string - TickSpacing uint32 - ReserveAddress string + Id uint64 + MarketId uint64 + Denom0 string + Denom1 string + ReserveAddress string + RewardsPool string + TickSpacing uint32 + MinOrderQuantity sdk.Dec + MinOrderQuote sdk.Dec } type PoolState struct { CurrentTick int32 CurrentPrice sdk.Dec CurrentLiquidity sdk.Int + TotalLiquidity sdk.Int FeeGrowthGlobal sdk.DecCoins FarmingRewardsGrowthGlobal sdk.DecCoins } @@ -31,10 +35,10 @@ type PoolState struct { ## Position -* LastPositionId: `0x?? -> BigEndian(LastPositionId)` -* Position: `0x?? | BigEndian(PositionId) -> ProtocoulBuffer(Position)` -* PositionByParamsIndex: `0x?? | BigEndian(PoolId) | AddrLen (1 byte) | Owner | Sign (1 byte) | BigEndian(LowerTick) | Sign (1 byte) | BigEndian(UpperTick) -> BigEndian(PositionId)` -* PositionsByPoolIndex: `0x?? | BigEndian(PoolId) | BigEndian(PositionId) -> nil` +* LastPositionId: `0x41 -> BigEndian(LastPositionId)` +* Position: `0x46 | BigEndian(PositionId) -> ProtocoulBuffer(Position)` +* PositionByParamsIndex: `0x47 | AddrLen (1 byte) | Owner | BigEndian(PoolId) | Sign (1 byte) | BigEndian(LowerTick) | Sign (1 byte) | BigEndian(UpperTick) -> BigEndian(PositionId)` +* PositionsByPoolIndex: `0x48 | BigEndian(PoolId) | BigEndian(PositionId) -> nil` ```go type Position struct { @@ -53,7 +57,7 @@ type Position struct { ## TickInfo -* TickInfo: `0x?? | BigEndian(PoolId) | Sign (1 byte) | BigEndian(Tick) -> ProtocolBuffer(TickInfo)` +* TickInfo: `0x49 | BigEndian(PoolId) | Sign (1 byte) | BigEndian(Tick) -> ProtocolBuffer(TickInfo)` ```go type TickInfo struct { @@ -66,9 +70,9 @@ type TickInfo struct { ## FarmingPlan -* LastFarmingPlanId: `0x?? -> BigEndian(LastFarmingPlanId)` -* FarmingPlan: `0x?? | BigEndian(FarmingPlanId) -> ProtocolBuffer(FarmingPlan)` -* NumPrivateFarmingPlans: `0x?? -> BigEndian(NumPrivateFarmingPlans)` +* LastFarmingPlanId: `0x4a -> BigEndian(LastFarmingPlanId)` +* FarmingPlan: `0x4b | BigEndian(FarmingPlanId) -> ProtocolBuffer(FarmingPlan)` +* NumPrivateFarmingPlans: `0x4c -> BigEndian(NumPrivateFarmingPlans)` ```go type FarmingPlan struct { diff --git a/x/amm/spec/06_params.md b/x/amm/spec/06_params.md index 98faab393..6cf0310d5 100644 --- a/x/amm/spec/06_params.md +++ b/x/amm/spec/06_params.md @@ -4,10 +4,12 @@ The amm module contains the following parameters: -| Key | Type | Example | -|-------------------------------|-----------------------|----------------------------------------| -| PoolCreationFee | array (sdk.Coins) | [{"denom":"stake","amount":"1000000"}] | -| DefaultTickSpacing | uint32 | 25 | -| PrivateFarmingPlanCreationFee | array (sdk.Coins) | [{"denom":"stake","amount":"1000000"}] | -| MaxNumPrivateFarmingPlans | uint32 | 50 | -| MaxFarmingBlockTime | int64 (time.Duration) | 10s | +| Key | Type | Example | +|-------------------------------|-----------------------|---------------------------------------| +| PoolCreationFee | array (sdk.Coins) | [{"denom":"ucre","amount":"1000000"}] | +| DefaultTickSpacing | uint32 | 25 | +| DefaultMinOrderQuantity | sdk.Dec | "10000.000000000000000000" | +| DefaultMinOrderQuote | sdk.Dec | "10000.000000000000000000" | +| PrivateFarmingPlanCreationFee | array (sdk.Coins) | [{"denom":"ucre","amount":"1000000"}] | +| MaxNumPrivateFarmingPlans | uint32 | 50 | +| MaxFarmingBlockTime | int64 (time.Duration) | 10s | diff --git a/x/amm/spec/README.md b/x/amm/spec/README.md index 68b13be4a..c468a73a2 100644 --- a/x/amm/spec/README.md +++ b/x/amm/spec/README.md @@ -23,6 +23,7 @@ parent: * [MsgRemoveLiquidity](03_messages.md#msgremoveliquidity) * [MsgCollect](03_messages.md#msgcollect) * [MsgCreatePrivateFarmingPlan](03_messages.md#msgcreateprivatefarmingplan) + * [MsgTerminatePrivateFarmingPlan](03_messages.md#msgterminateprivatefarmingplan) 4. [Begin-Block](04_begin_block.md) 5. [Events](05_events.md) * [Begin-Block](05_events.md#begin-block) diff --git a/x/exchange/spec/02_state.md b/x/exchange/spec/02_state.md index a279fbed0..37b92a590 100644 --- a/x/exchange/spec/02_state.md +++ b/x/exchange/spec/02_state.md @@ -4,19 +4,20 @@ ## Market -* LastMarketId: `0x?? -> BigEndian(LastMarketId)` -* Market: `0x?? | BigEndian(MarketId) -> ProtocolBuffer(Market)` -* MarketState: `0x?? | BigEndian(MarketId) -> ProtocolBuffer(Market)` -* MarketByDenomsIndex: `0x?? | DenomLen (1 byte) | BaseDenom | QuoteDenom -> BigEndian(MarketId)` +* LastMarketId: `0x60 -> BigEndian(LastMarketId)` +* Market: `0x62 | BigEndian(MarketId) -> ProtocolBuffer(Market)` +* MarketState: `0x63 | BigEndian(MarketId) -> ProtocolBuffer(Market)` +* MarketByDenomsIndex: `0x64 | DenomLen (1 byte) | BaseDenom | QuoteDenom -> BigEndian(MarketId)` ```go type Market struct { - Id uint64 - BaseDenom string - QuoteDenom string - EscrowAddress string - MakerFeeRate sdk.Dec - TakerFeeRate sdk.Dec + Id uint64 + BaseDenom string + QuoteDenom string + EscrowAddress string + MakerFeeRate sdk.Dec + TakerFeeRate sdk.Dec + OrderSourceFeeRatio sdk.Dec } type MarketState struct { @@ -27,9 +28,11 @@ type MarketState struct { ## Order -* LastOrderId: `0x?? -> BigEndian(LastOrderId)` -* OrderKey: `0x?? | BigEndian(OrderId) -> ProtocoulBuffer(Order)` -* OrderBookOrderIndex: `0x?? | BigEndian(MarketId) | IsBuy | SortableDecBytes(Price) | BigEndian(OrderId) -> BigEndian(OrderId)` +* LastOrderId: `0x61 -> BigEndian(LastOrderId)` +* OrderKey: `0x65 | BigEndian(OrderId) -> ProtocoulBuffer(Order)` +* OrderBookOrderIndex: `0x66 | BigEndian(MarketId) | IsBuy | SortableDecBytes(Price) | BigEndian(OrderId) -> BigEndian(OrderId)` +* OrdersByOrdererIndex: `0x67 | AddrLen (1 byte) | Orderer | BigEndian(MarketId) | BigEndian(OrderId) -> nil` +* NumMMOrders: `0x68 | AddrLen (1 byte) | Orderer | BigEndian(MarketId) -> BigEndian(NumMMOrders)` ```go type Order struct { @@ -39,10 +42,10 @@ type Order struct { MarketId uint64 IsBuy bool Price sdk.Dec - Quantity sdk.Int + Quantity sdk.Dec MsgHeight int64 - OpenQuantity sdk.Int - RemainingDeposit sdk.Int + OpenQuantity sdk.Dec + RemainingDeposit sdk.Dec Deadline time.Time } @@ -54,7 +57,3 @@ const ( OrderTypeMM OrderType = 2 ) ``` - -## Transient Balance Difference - -* TransientBalance: `0x?? | AddrLen (1 byte) | Address | Denom -> ProtocolBuffer(Amount)` diff --git a/x/exchange/spec/03_messages.md b/x/exchange/spec/03_messages.md index 9a3a13118..b373f0be4 100644 --- a/x/exchange/spec/03_messages.md +++ b/x/exchange/spec/03_messages.md @@ -20,7 +20,7 @@ type MsgPlaceLimitOrder struct { MarketId uint64 IsBuy bool Price sdk.Dec - Quantity sdk.Int + Quantity sdk.Dec Lifespan time.Duration } ``` @@ -33,7 +33,7 @@ type MsgPlaceBatchLimitOrder struct { MarketId uint64 IsBuy bool Price sdk.Dec - Quantity sdk.Int + Quantity sdk.Dec Lifespan time.Duration } ``` @@ -46,7 +46,7 @@ type MsgPlaceMMLimitOrder struct { MarketId uint64 IsBuy bool Price sdk.Dec - Quantity sdk.Int + Quantity sdk.Dec Lifespan time.Duration } ``` @@ -59,7 +59,7 @@ type MsgPlaceMMBatchLimitOrder struct { MarketId uint64 IsBuy bool Price sdk.Dec - Quantity sdk.Int + Quantity sdk.Dec Lifespan time.Duration } ``` @@ -71,7 +71,7 @@ type MsgPlaceMarketOrder struct { Sender string MarketId uint64 IsBuy bool - Quantity sdk.Int + Quantity sdk.Dec } ``` @@ -99,7 +99,7 @@ type MsgCancelAllOrders struct { type MsgSwapExactAmountIn struct { Sender string Routes []uint64 - Input types.Coin - MinOutput types.Coin + Input types.DecCoin + MinOutput types.DecCoin } ``` diff --git a/x/exchange/spec/06_params.md b/x/exchange/spec/06_params.md index 2b777b63e..4ea20d88a 100644 --- a/x/exchange/spec/06_params.md +++ b/x/exchange/spec/06_params.md @@ -4,10 +4,21 @@ The amm module contains the following parameters: -| Key | Type | Example | -|---------------------|-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Fees | Fees | `{"market_creation_fee":[{"denom":"stake","amount":"1000000"}],"default_maker_fee_rate":"-0.001500000000000000","default_taker_fee_rate":"0.003000000000000000"}` | -| MaxOrderLifespan | int64 (time.Duration) | 168h | -| MaxOrderPriceRatio | sdk.Dec | "0.100000000000000000" | -| MaxSwapRoutesLen | uint32 | 3 | -| MaxNumMMOrders | uint32 | 15 | +| Key | Type | Example | +|--------------------|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------| +| MarketCreationFee | sdk.Coins | `[{"denom":"ucre","amount":"100000000"}]` | +| Fees | Fees | `{"default_maker_fee_rate":"-0.001500000000000000","default_taker_fee_rate":"0.003000000000000000","default_order_source_fee_ratio":"0.800000000000000000"}` | +| MaxOrderLifespan | int64 (time.Duration) | 168h | +| MaxOrderPriceRatio | sdk.Dec | "0.100000000000000000" | +| MaxSwapRoutesLen | uint32 | 3 | +| MaxNumMMOrders | uint32 | 15 | + +## Fees + +```go +type Fees struct { + DefaultMakerFeeRate sdk.Dec + DefaultTakerFeeRate sdk.Dec + DefaultOrderSourceFeeRatio sdk.Dec +} +``` diff --git a/x/exchange/spec/README.md b/x/exchange/spec/README.md index 25750fbd5..6731483b4 100644 --- a/x/exchange/spec/README.md +++ b/x/exchange/spec/README.md @@ -18,8 +18,12 @@ parent: 3. [Messages](03_messages.md) * [MsgCreateMarket](03_messages.md#msgcreatemarket) * [MsgPlaceLimitOrder](03_messages.md#msgplacelimitorder) + * [MsgPlaceBatchLimitOrder](03_messages.md#msgplacebatchlimitorder) + * [MsgPlaceMMLimitOrder](03_messages.md#msgplacemmlimitorder) + * [MsgPlaceMMBatchLimitOrder](03_messages.md#msgplacemmbatchlimitorder) * [MsgPlaceMarketOrder](03_messages.md#msgplacemarketorder) * [MsgCancelOrder](03_messages.md#msgcancelorder) + * [MsgCancelAllOrders](03_messages.md#msgcancelallorders) * [MsgSwapExactAmountIn](03_messages.md#msgswapexactamountin) 4. [Begin-Block](04_begin_block.md) 5. [Events](05_events.md) diff --git a/x/liquidamm/spec/01_concepts.md b/x/liquidamm/spec/01_concepts.md index 083f99987..1c39bc932 100644 --- a/x/liquidamm/spec/01_concepts.md +++ b/x/liquidamm/spec/01_concepts.md @@ -2,67 +2,4 @@ # Concepts -This is the concept for `Liquidfarming` module in Crescent Network. - -## LiquidFarming Module - -The `liquidfarming` module provides a functionality for farmers to have another option to use with their liquidity pool coins in Crescent Network. - -The module allows farmers to farm their pool coin and mint a synthetic version of the pool coin called LFCoin. -Farmers can use the LFCoin to take a full advantage of Crescent functionality, such as Boost. -On behalf of farmers, the module stakes their pool coin to the `lpfarm` module and receives farming rewards for every block. -The module provides auto-compounding of the rewards by going through an auction process, which results in the exchange of the farming rewards coin(s) into the pool coin. - -## Registration of Liquidfarm - -A `liquidFarm` corresponds to one unique pool id. A `liquidFarm` stakes and unstakes the pool coins as users’ requests. When the rewards are allocated by staking the pool coins, the `liquidFarm` creates and manages an auction in order to exchange the rewards to pool coins to be staked additionally. - -A `liquidFarm` can be registered to the parameter `liquidFarms` by governance for activating the liquid farming of a pool. -When the `liquidFarm` is registered to the parameter, users can request to farm their pool coins. - -A `liquidFarm` can be removed in the parameter `liquidFarms` by governance for deactivating the liquid farming of a pool. -When the `liquidFarm` is removed, the module unstakes all pool coins in the module, users cannot request to farm their pool coins, but users can still request to unfarm LF coins. -In this case, the ongoing rewards auction becomes finished, all bids are refunded, and a new auction is not started. - -## Liquid Farm - -Once a user farms their pool coin, the user receives LFCoin instantly minted. -The following formula is used for an exchange rate of `LFCoinMint` when a user farms with `LPCoinFarm`. - -$$LF Coin Mint = \frac{LF Coin Supply}{LP Coin Farming Amount} \times LP Coin Farm,$$ - -where `LFCoinSupply` is not zero. -If `LF Coin Supply` is zero, then the following formula is applied: - -$$LF Coin Mint = LP Coin Farm.$$ - -## Liquid Unfarm - -When a user unfarms their LFCoin, the module burns the LFCoin and releases the corresponding amount of pool coin. -The following formula is used for an exchange rate of `LFCoinBurn` to receive `LPCoinUnfarm`: - -$$LP Coin Unfarm = \frac{LP Coin Farming Amount - Compounding Rewards}{LF Coin Supply} \times LF Coin Burn,$$ - -if $$LFCoinBurn < LF Coin Supply$$, where `CompoundingRewards` is the amount of pool coins obtained from the last rewards auction. -If $$LFCoinBurn = LF Coin Supply$$, the following formula is used: - -$$LP Coin Unfarm = \frac{LP Coin Farming Amount}{LF Coin Supply} \times LF Coin Burn.$$ - -If the `liquidfarm` is not registered in the governance parameter, the `LiquidFarming` module unstakes all LP coin, and the following formula is used an exchange rate of `LFCoinBurn`: - -$$LP Coin Unfarm = \frac{LP Coin In Module}{LF Coin Supply} \times LF Coin Burn.$$ - -## Farming Rewards and Auction - -On behalf of users, the module stakes their pool coins and claims farming rewards. -In order to exchange the rewards coin(s) into the pool coin to be additionally staked for farming, the module creates an auction to sell the rewards that will be received at the end of the auction period. -Note that the exact amount of the rewards being auctioned is not determined when the auction is created, but will be determined when the auction ends. -The amount of the rewards depends on the total amount of staked pool coins and the `liquidfarming` module’s staked pool coin, which can be varied during the auction period. -Therefore, a bidder to place a bid for the auction should be aware of this uncertainty of the rewards amount. - -## Bidding for Auction and Winning Bid - -A bidder can place a bid with the pool coin, which is the paying coin of the auction. -A bidder only can place a single bid per auction of a liquid farm. -The bid amount of the pool coin must be higher than the current winning bid amount that is the highest bid amount of the auction at the moment. -The bidder placing the bid with the highest amount of the pool coin becomes the winner of the auction and will takes all the accumulated rewards amount at the end of the auction. +## LiquidAMM diff --git a/x/liquidamm/spec/02_state.md b/x/liquidamm/spec/02_state.md index c9dd196ef..e4d48253d 100644 --- a/x/liquidamm/spec/02_state.md +++ b/x/liquidamm/spec/02_state.md @@ -2,88 +2,62 @@ # State -The `liquidfarming` module keeps track of the states of pool coins and LFCoins. +## PublicPosition -## LiquidFarm +* LastPublicPositionId: `0x81 -> BigEndian(LastPublicPositionId)` +* PublicPosition: `0x83 | BigEndian(PublicPositionId) -> ProtocolBuffer(PublicPosition)` +* PublicPositionsByPoolIndex: `0x84 | BigEndian(PoolId) | BigEndian(PublicPositionId) -> nil` +* PublicPositionByParamsIndex: `0x85 | AddrLen (1 byte) | Owner | BigEndian(PoolId) | Sign (1 byte) | BigEndian(LowerTick) | Sign (1 byte) | BigEndian(UpperTick) -> nil` ```go -// LiquidFarms tracks the list of the activated LiquidFarms -type LiquidFarms struct { - liquidfarms []LiquidFarm -} - -// LiquidFarm defines liquid farm. -type LiquidFarm struct { - PoolId uint64 // the pool id - MinFarmAmount sdk.Int // the minimum farm amount; it allows zero value - MinBidAmount sdk.Int // the minimum bid amount; it allows zero value - FeeRate sdk.Dec // the fee rate for the liquidfarm which deducts from auction winner's rewards +type PublicPosition struct { + Id uint64 + PoolId uint64 + LowerTick int32 + UpperTick int32 + BidReserveAddress string + MinBidAmount sdk.Int + FeeRate sdk.Dec + LastRewardsAuctionId uint64 } ``` ## RewardsAuction +* LastRewardsAuctionEndTime: `0x82 -> FormatTimeBytes(LastRewardsAuctionEndTime)` +* RewardsAuction: `0x86 | BigEndian(PublicPositionId) | BigEndian(AuctionId) -> ProtocolBuffer(RewardsAuction)` + ```go -// AuctionStatus enumerates the valid status of an auction. type AuctionStatus int32 const ( - AuctionStatusNil AuctionStatus = 0 - AuctionStatusStarted AuctionStatus = 1 - AuctionStatusFinished AuctionStatus = 2 - AuctionStatusSkipped AuctionStatus = 3 + AuctionStatusNil AuctionStatus = 0 + AuctionStatusStarted AuctionStatus = 1 + AuctionStatusFinished AuctionStatus = 2 + AuctionStatusSkipped AuctionStatus = 3 ) -// RewardsAuction defines rewards auction information. type RewardsAuction struct { - Id uint64 // rewards auction id - PoolId uint64 // corresponding pool id of the target liquid farm - BiddingCoinDenom string // corresponding pool coin denom - PayingReserveAddress string // the paying reserve address that collects bidding coin placed by bidders - StartTime time.Time // the auction start time - EndTime time.Time // the auction end time - Status AuctionStatus // the auction status - Winner string // the bidder who won the auction - WinningAmount sdk.Coin // the winning amount placed by the winner - Rewards sdk.Coins // the farming rewards for are accumulated every block - Fees sdk.Coins // the fees for the rewards by the fee rate - FeeRate sdk.Dec // the fee rate for the liquid farm -} -``` - -## CompoundingRewards - -```go -// CompoundingRewards records the amount of farming rewards -type CompoundingRewards struct { - Amount sdk.Int + PublicPositionId uint64 + Id uint64 + StartTime time.Time + EndTime time.Time + Status AuctionStatus + WinningBid *Bid + Rewards sdk.Coins + Fees sdk.Coins } ``` ## Bid +* Bid: `0x87 | BigEndian(PublicPositionId) | BigEndian(AuctionId) | Bidder -> ProtocolBuffer(Bid)` + ```go -// Bid defines a standard bid for an auction. type Bid struct { - PoolId uint64 - Bidder string - Amount sdk.Coin + PublicPositionId uint64 + RewardsAuctionId uint64 + Bidder string + Share sdk.Coin } ``` - -## Parameter - -- ModuleName: `liquidfarming` -- RouterKey: `liquidfarming` -- StoreKey: `liquidfarming` -- QuerierRoute: `liquidfarming` - -## Store - -- LastRewardsAuctionEndTimeKey: `[]byte{0xe1} -> Timestamp(time.Time)` -- LastRewardsAuctionIdKey: `[]byte{0xe2} | PoolId -> Uint64Value(uint64)` -- LiquidFarmKey: `[]byte{0xe3} | PoolId -> ProtocolBuffer(LiquidFarm)` -- CompoundingRewardsKey: `[]byte{0xe4} | PoolId -> ProtocolBuffer(CompoundingRewards)` -- RewardsAuctionKey: `[]byte{0xe5} | AuctionId | PoolId -> ProtocolBuffer(RewardsAuction)` -- BidKey: `[]byte{0xe6} | PoolId | BidderAddressLen (1 byte) | BidderAddress -> ProtocolBuffer(Bid)` -- WinningBidKey: `[]byte{0xe7} | AuctionId | PoolId -> ProtocolBuffer(Bid)` diff --git a/x/liquidamm/spec/03_state_transitions.md b/x/liquidamm/spec/03_state_transitions.md index 141d0e796..fa778b3cd 100644 --- a/x/liquidamm/spec/03_state_transitions.md +++ b/x/liquidamm/spec/03_state_transitions.md @@ -1,49 +1,3 @@ # State Transitions - -This document describes the state transaction operations in the `liquidfarming` module. - -## Parameter Change for Activated Liquid Farms - -### Activation of a Liquid Farm - -When a new `liquidFarm` with a given pool id is registered to the parameter `LiquidFarms` by governance, the `liquidFarm` with the pool id is added to the state `LiquidFarms`. - -### Deactivation of a Liquid Farm - -When a `liquidFarm` with a given pool id in the parameter `LiquidFarms` is removed by governance, the `liquidFarm` is deleted in the state `LiquidFarms`. -When the `liquidFarm` is deleted in the state `LiquidFarms`, the module unstakes all pool coins for the `liquidFarm`. - -## Coin Escrow for Liquidfarming Module Messages - -The following messages cause state transition on the `bank`, `liquidty`, and `lpfarm` modules. - -### MsgLiquidFarm - -- A farmer farms in the `liquidfarming` module with their pool coins. -- The module sends that the pool coin to the reserve account. -- The reserve account farms their pool coin to the `lpfarm` module and start generating farming rewards. -- The `LFCoin` is minted and sends it to the farmer. - -### MsgLiquidUnfarm - -- A farmer unfarms in the `liquidfarming` module with their liquid farming coin (LFCoin). -- The module calculates the corresponding pool coin by the burn rate and sends the pool coin back to the farmer. -- The module burns the unfarmed `LFCoin`. - -### MsgLiquidUnfarmWithdraw - -- A farmer unfarms in the `liquidfarming` module with their liquid farming coin (LFCoin). -- The module calculates the corresponding pool coin by the burn rate and calls to withdraw the pool coin in the `liquidity` module. -- The module burns the unfarmed `LFCoin`. -- The corresponding two kinds of withdrawn coins are sent back to the farmer. - -### MsgPlaceBid - -- Bidding coins are sent to the `PayingReserveAddress` of an auction. -- If a bidder who already placed a bid in the liquidfarm places another bid with higher bidding amount, then the previous bidding coins is refunded and the new bidding coins are sent to the `PayingReserveAddress` of an auction. - -### MsgRefundBid - -- Bidding coins are sent to a bidder account from the `PayingReserveAddress` of an auction. diff --git a/x/liquidamm/spec/04_messages.md b/x/liquidamm/spec/04_messages.md index 88e09875d..0969eb5e9 100644 --- a/x/liquidamm/spec/04_messages.md +++ b/x/liquidamm/spec/04_messages.md @@ -2,120 +2,33 @@ # Messages -Messages (Msg) are objects that trigger state transitions. Msgs are wrapped in transactions (Txs) that clients submit to the network. -The Cosmos SDK wraps and unwraps `liquidfarming` module messages from transactions. - -## MsgLiquidFarm - -Farm coin to liquid farm. Farming coins are the pool coin that starts with pool prefix, which is a pool coin of a corresponding pool. -It is important to note that a farmer is not receiving a synthetic version of the farming coins right away. -It are expected to receive the synthetic version of the farming coins after one epoch at the current mint rate. -A synthetic version of the farming coin is called as LFCoin in the module and the terminology is used throughout the documentation and codebase. +## MsgMintShare ```go -type MsgLiquidFarm struct { - PoolId uint64 // target pool id - Farmer string // the bech32-encoded address that farms coin - FarmingCoin sdk.Coin // farming amount of pool coin +type MsgMintShare struct { +Sender string +PublicPositionId uint64 +DesiredAmount sdk.Coins } ``` -Validity checks are performed for `MsgLiquidFarm` message. The transaction that is triggered with the `MsgLiquidFarm` message fails if: - -- The target liquid farm with the pool id does not exist -- The amount of farming coin is not positive -- The amount of farming coin is less than `MinimumFarmAmount` -- The farming coin denom is not the same as the pool coin denom of the pool with `PoolId` -- The farmer has insufficient spendable balances of the pool coin amount - -## MsgLiquidUnfarm - -Unfarm LFCoin to liquid unfarm. -The module burns LFCoin amounts and releases the corresponding amount of pool coins to a farmer at the current burn rate. +## MsgBurnShare ```go -type MsgLiquidUnfarm struct { - PoolId uint64 // target deposit request id - Farmer string // the bech32-encoded address that unfarms liquid farm coin - UnfarmingCoin sdk.Coin // withdrawing amount of LF coin +type MsgBurnShare struct { +Sender string +PublicPositionId uint64 +Share sdk.Coin } ``` -Validity checks are performed for `MsgLiquidUnfarm` message. The transaction that is triggered with the `MsgLiquidUnfarm` message fails if: - -- The target liquid farm with the pool id does not exist -- The amount of LF coins is not positive -- The unfarming coin denom is not the same as the pool coin denom of the pool with `PoolId` -- The farmer has insufficient spendable balances for the unfarming LF coin amount - -## MsgLiquidUnfarmAndWithdraw - -Unfarm LFCoin to liquid unfarm and withdraw the pool coin from the pool. -The module burns LFCoin amounts at the current burn rate, withdraw the corresponding amount of pool coins from the pool, and then the withdrawn coins are sent back to the farmer. - -```go -type MsgLiquidUnfarmAndWithdraw struct { - PoolId uint64 // target pool id - Farmer string // the bech32-encoded address that unfarms liquid farm coin and withdraws - UnfarmingCoin sdk.Coin // withdrawing amount of LF coin -} -``` - -Validity checks are performed for `MsgLiquidUnfarmAndWithdraw` message. The transaction that is triggered with the `MsgLiquidUnfarmAndWithdraw` message fails if: - -- The target liquid farm with the pool id does not exist -- The amount of LF coins is not positive -- The unfarming coin denom is not the same as the pool coin denom of the pool with `PoolId` -- The farmer has insufficient spendable balances for the unfarming LF coin amount - ## MsgPlaceBid -Place a bid for a rewards auction. -Anyone can place a bid for an auction where the bidder placing with the highest bid amount takes all the rewards. - ```go type MsgPlaceBid struct { - AuctionId uint64 // auction id - PoolId uint64 // target pool id - Bidder string // the bech32-encoded address that places a bid - BiddingCoin sdk.Coin // bidding amount of pool coin -} -``` - -Validity checks are performed for `MsgPlaceBid` message. The transaction that is triggered with the `MsgPlaceBid` message fails if: - -- The target liquid farm with the pool id does not exist -- The target auction status is in invalid status -- The bidding coin amount is less than that of the current winning bidding coin amount - -## MsgRefundBid - -Refund the bid that is not winning for the auction. - -```go -type MsgRefundBid struct { - AuctionId uint64 // auction id - PoolId uint64 // target pool id - Bidder string // the bech32-encoded address that refunds a bid -} -``` - -Validity checks are performed for `MsgRefundBid` message. The transaction that is triggered with the `MsgRefundBid` message fails if: - -- The target liquid farm with the pool id does not exist -- The target auction status is in invalid status -- The bid by the bidder in the auction of the liquid farm with the pool id does not exist - -## MsgAdvanceAuction - -**_This message is disabled by default, you have to build the binary with `make install-testing` to activate this message._** - -For testing purposes only, this custom message is used to advance auction. - -When you send the `MsgAdvanceAuction` message to the network, finish the ongoing rewards auction and create the next one. - -```go -type MsgAdvanceAuction struct { - Requester string // requester defines the bech32-encoded address of the requester +Sender string +PublicPositionId uint64 +RewardsAuctionId uint64 +Share sdk.Coin } ``` diff --git a/x/liquidamm/spec/05_begin_block.md b/x/liquidamm/spec/05_begin_block.md index fd3691dab..c58d450a2 100644 --- a/x/liquidamm/spec/05_begin_block.md +++ b/x/liquidamm/spec/05_begin_block.md @@ -1,11 +1,3 @@ # Begin-Block - -At each BeginBlock, the following operations occur in the `liquidfarming` module: - -- Synchronizes `LiquidFarms` registered in params with the ones stored in KVStore. When a new `LiquidFarm` is added by governance proposal, the `LiquidFarm` is stored in KVStore and a rewards auction will be started at 00:00UTC in the next day. - -- When an existing `LiquidFarm` is removed by the governance proposal, it first calls `Unfarm` function in the `lpfarm` module with the reserve module account to unfarm all farming coin to prevent from having farming rewards accumulated and handle the ongoing `RewardsAuction`. It refunds all placed bids and change the auction status to `AuctionStatusFinished`. Lastly, it deletes the `LiquidFarm` in the store. - -- Iterates all existing `LiquidFarms` in KVStore and create `RewardsAuction` for every `LiquidFarm` if it is not created before. It there is an ongoing `RewardsAuction` for the `LiquidFarm`, then it finishes by selecting the winning bid to give them the accumulated farming rewards and calls `Farm` function in the `lpfarm` module to farm the coin of the winning bid. This action is regarded as auto compounding rewards functionality for farmers. diff --git a/x/liquidamm/spec/06_events.md b/x/liquidamm/spec/06_events.md index 0e117e77b..9a1ed9379 100644 --- a/x/liquidamm/spec/06_events.md +++ b/x/liquidamm/spec/06_events.md @@ -1,65 +1,3 @@ # Events - -The `liquidfarming` module emits the following events: - -## Handlers - -### MsgLiquidFarm - -| Type | Attribute Key | Attribute Value | -| ----------- | ----------------- | ---------------- | -| liquid_farm | pool_id | {poolId} | -| liquid_farm | farmer | {farmer} | -| liquid_farm | farming_coin | {farmingCoin} | -| liquid_farm | minted_coin | {mintingCoin} | -| message | module | {liquidfarming} | -| message | action | {farm} | -| message | farmer | {farmerAddress} | - -### MsgLiquidUnfarm - -| Type | Attribute Key | Attribute Value | -| ------------- | ----------------- | ---------------- | -| liquid_unfarm | pool_id | {poolId} | -| liquid_unfarm | farmer | {farmer} | -| liquid_unfarm | unfarming_coin | {unfarmingCoin} | -| liquid_unfarm | unfarmed_coin | {unfarmedCoin} | -| message | module | {liquidfarming} | -| message | action | {unfarm} | -| message | farmer | {farmerAddress} | - -### MsgLiquidUnfarmAndWithdraw - -| Type | Attribute Key | Attribute Value | -| -------------------------- | ------------------| ----------------- | -| liquid_unfarm_and_withdraw | pool_id | {poolId} | -| liquid_unfarm_and_withdraw | farmer | {farmer} | -| liquid_unfarm_and_withdraw | unfarming_coin | {unfarmingCoin} | -| liquid_unfarm_and_withdraw | unfarmed_coin | {unfarmedCoin} | -| message | module | liquidfarming | -| message | action | unfarmandwithdraw | -| message | farmer | {farmerAddress} | - -### MsgPlaceBid - -| Type | Attribute Key | Attribute Value | -| --------- | ------------- | ----------------- | -| place_bid | auction_id | {auctionId} | -| place_bid | bidder | {bidder} | -| place_bid | bidding_coin | {biddingCoin} | -| message | module | {liquidfarming} | -| message | action | {deposit} | -| message | bidder | {bidderAddress} | - -### MsgRefundBid - -| Type | Attribute Key | Attribute Value | -| ---------- | ------------- | --------------- | -| refund_bid | auction_id | {auctionId} | -| refund_bid | bidder | {bidder} | -| refund_bid | refund_coin | {bidAmount} | -| message | module | {liquidfarming} | -| message | action | {deposit} | -| message | bidder | {bidderAddress} | diff --git a/x/liquidamm/spec/07_params.md b/x/liquidamm/spec/07_params.md index 891b759f5..d43063c26 100644 --- a/x/liquidamm/spec/07_params.md +++ b/x/liquidamm/spec/07_params.md @@ -2,28 +2,9 @@ # Parameters -The `liquidfarming` module contains the following parameters: +The liquidamm module contains the following parameters: -| Key | Type | Example | -| ---------------------- | ---------------- | -------------------------------------------------------------- | -| LiquidFarms | []LiquidFarm | []LiquidFarm{} | -| RewardsAuctionDuration | string (time ns) | 43200000000000 (12 hours) | -| FeeCollector | string | cre1lsvtflq2gau8ha7zvlethfy85qus59eserphyhc3tumua7upx6eqckll2q | - -## LiquidFarms - -`LiquidFarms` is a list of `LiquidFarm`, where a `LiquidFarm` is corresponding to a specific pool with `PoolId`. - -```go -type LiquidFarm struct { - PoolId uint64 // the pool id - MinFarmAmount sdk.Int // the minimum farm amount; it allows zero value - MinBidAmount sdk.Int // the minimum bid amount; it allows zero value - FeeRate sdk.Dec // the fee rate that deducts from auction winner's rewards; default value is 0 -} -``` - -## RewardsAuctionDuration - -`RewardsAuctionDuration` is the duration that triggers the module to create new `RewardsAuction`. -If there is an ongoing `RewardsAuction`, then it finishes it and it creates next one. +| Key | Type | Example | +|-----------------------------|---------------|---------| +| RewardsAuctionDuration | time.Duration | 10s | +| MaxNumRecentRewardsAuctions | uint32 | 10 | diff --git a/x/liquidamm/spec/README.md b/x/liquidamm/spec/README.md index 8d1c40199..7e39a267c 100644 --- a/x/liquidamm/spec/README.md +++ b/x/liquidamm/spec/README.md @@ -1,11 +1,9 @@ - + -# `liquidfarming` +# `liquidamm` ## Abstract -This document specifies the `liquidfarming` module that provides a functionality for farmers to have another option to use with their liquidity pool coins in Crescent Network. - ## Contents 1. **[Concepts](01_concepts.md)**