From 4342601b042c58b35fc77c0b9966a28d5593ebdd Mon Sep 17 00:00:00 2001 From: Jeongho Yeo <83253362+jeonghoyeo7@users.noreply.github.com> Date: Thu, 11 Aug 2022 13:54:35 +0900 Subject: [PATCH] docs: add drafts of specs for liquidfarming module (#343) * add docs * docs: draft specs for liquidfarming module * docs: update specs * docs: update specs * docs: update specs * docs: update spec * docs: update spec * docs: update docs * docs: update cli/api docs * docs: updates * docs: update API/CLI * docs: updated docs for deactivation of liquidFarms * Revert "docs: updated docs for deactivation of liquidFarms" This reverts commit 2a0545d6ad738a6a98c04b267c2cbdb1df891d6c. * Revert "Revert "docs: updated docs for deactivation of liquidFarms"" This reverts commit 07a063dc31a8e92af9153ac752e4cfdd727f6ecb. * docs: update liquidfarming spec * docs: update spec docs * docs: updates * docs: update spec/api/cli --- docs/api/liquidfarming.md | 219 +++++++++++++++++++ docs/api/liquidity.md | 33 +-- docs/api/liquidstaking.md | 11 +- docs/cli/liquidfarming.md | 213 ++++++++++++++++++ x/farming/spec/09_hooks.md | 9 + x/liquidfarming/spec/01_concepts.md | 73 ++++++- x/liquidfarming/spec/02_state.md | 54 +++-- x/liquidfarming/spec/03_state_transitions.md | 57 +++++ x/liquidfarming/spec/04_messages.md | 93 ++++++-- x/liquidfarming/spec/05_begin_block.md | 16 ++ x/liquidfarming/spec/05_end_block.md | 9 - x/liquidfarming/spec/06_events.md | 27 +-- x/liquidfarming/spec/07_params.md | 12 +- x/liquidfarming/spec/08_hooks.md | 21 ++ x/liquidfarming/spec/README.md | 6 +- 15 files changed, 749 insertions(+), 104 deletions(-) create mode 100644 docs/api/liquidfarming.md create mode 100644 docs/cli/liquidfarming.md create mode 100644 x/liquidfarming/spec/05_begin_block.md delete mode 100644 x/liquidfarming/spec/05_end_block.md create mode 100644 x/liquidfarming/spec/08_hooks.md diff --git a/docs/api/liquidfarming.md b/docs/api/liquidfarming.md new file mode 100644 index 000000000..106a158fb --- /dev/null +++ b/docs/api/liquidfarming.md @@ -0,0 +1,219 @@ +--- +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/cosmosquad-labs/squad/blob/main/proto/squad/liquidfarming/v1beta1/query.proto + +- [Liquidfarming Module](#liquidfarming-module) + - [Synopsis](#synopsis) + - [gRPC-gateway REST Routes](#grpc-gateway-rest-routes) + - [Params](#params) + - [LiquidFarms](#liquidfarms) + - [LiquidFarm](#liquidfarm) + - [RewardsAuctions](#rewardsauctions) + - [RewardsAuction](#rewardsauction) + - [Bids](#bids) + +## Params + +Example Request + + +```bash +http://localhost:1317/squad/liquidfarming/v1beta1/params +``` + +Example Response + +```json +{ + "params": { + "liquid_farms": [ + { + "pool_id": "1", + "minimum_farm_amount": "1", + "minimum_bid_amount": "1" + }, + { + "pool_id": "2", + "minimum_farm_amount": "1", + "minimum_bid_amount": "1" + } + ], + } +} +``` + +## LiquidFarms + +Example Request + + +```bash +http://localhost:1317/squad/liquidfarming/v1beta1/liquidfarms +``` + +Example Response + +```json +{ + "liquid_farms": [ + { + "pool_id": "1", + "liquid_farm_reserve_address": "cosmos1zyyf855slxure4c8dr06p00qjnkem95d2lgv8wgvry2rt437x6tsaf9tcf", + "lf_coin_denom": "lf1", + "minimum_farm_amount": "1", + "minimum_bid_amount": "1", + "staked_coin": { + "denom": "pool1", + "amount": "0" + }, + "queued_coin": { + "denom": "pool1", + "amount": "500000000000" + } + } + ] +} +``` + +## LiquidFarm + +Example Request + + +```bash +http://localhost:1317/squad/liquidfarming/v1beta1/liquidfarms/1 +``` + +Example Response + +```json +{ + "liquid_farm": { + "pool_id": "1", + "liquid_farm_reserve_address": "cosmos1zyyf855slxure4c8dr06p00qjnkem95d2lgv8wgvry2rt437x6tsaf9tcf", + "lf_coin_denom": "lf1", + "minimum_farm_amount": "1", + "minimum_bid_amount": "1", + "staked_coin": { + "denom": "pool1", + "amount": "0" + }, + "queued_coin": { + "denom": "pool1", + "amount": "500000000000" + } + } +} +``` + +## RewardsAuctions + +Example Request + + +```bash +http://localhost:1317/squad/liquidfarming/v1beta1/pools/1/rewards_auctions +``` + +Example Response + +```json +{ + "reward_auctions": [ + { + "id": "2", + "pool_id": "1", + "bidding_coin_denom": "pool1", + "paying_reserve_address": "cosmos1h72q3pkvsz537kj08hyv20tun3apampxhpgad97t3ls47nukgtxqeq6eu2", + "start_time": "2022-08-05T08:56:55.820787Z", + "end_time": "2022-08-06T08:56:55.820787Z", + "status": "AUCTION_STATUS_STARTED", + "winner": "", + "rewards": [ + + ] + }, + { + "id": "1", + "pool_id": "1", + "bidding_coin_denom": "pool1", + "paying_reserve_address": "cosmos1h72q3pkvsz537kj08hyv20tun3apampxhpgad97t3ls47nukgtxqeq6eu2", + "start_time": "2022-08-05T08:56:22.237454Z", + "end_time": "2022-08-06T08:56:22.237454Z", + "status": "AUCTION_STATUS_FINISHED", + "winner": "", + "rewards": [ + + ] + } + ], +} +``` + +## RewardsAuction + +Example Request + + +```bash +http://localhost:1317/squad/liquidfarming/v1beta1/pools/1/rewards_auctions/1 +``` + +Example Response + +```json +{ + "reward_auction": { + "id": "1", + "pool_id": "1", + "bidding_coin_denom": "pool1", + "paying_reserve_address": "cosmos1h72q3pkvsz537kj08hyv20tun3apampxhpgad97t3ls47nukgtxqeq6eu2", + "start_time": "2022-08-05T08:56:22.237454Z", + "end_time": "2022-08-06T08:56:22.237454Z", + "status": "AUCTION_STATUS_FINISHED", + "winner": "", + "rewards": [ + + ] + } +} +``` + + +## Bids + +Example Request + + +```bash +http://localhost:1317/squad/liquidfarming/v1beta1/pools/1/bids +``` + +Example Response + +```json +{ + "bids": [ + { + "pool_id": "1", + "bidder": "cosmos1zaavvzxez0elundtn32qnk9lkm8kmcszzsv80v", + "amount": { + "denom": "pool1", + "amount": "10000000" + } + } + ], +} +``` \ No newline at end of file diff --git a/docs/api/liquidity.md b/docs/api/liquidity.md index c1fd5cc0f..890a8b384 100644 --- a/docs/api/liquidity.md +++ b/docs/api/liquidity.md @@ -14,21 +14,24 @@ This document provides a high-level overview of what gRPC-gateway REST routes ar ++https://github.com/cosmosquad-labs/squad/blob/main/proto/squad/liquidity/v1beta1/query.proto -- [Params](#Params) -- [Pairs](#Pairs) -- [Pair](#Pair) -- [Pools](#Pools) -- [Pool](#Pool) -- [PoolByReserveAddress](#PoolByReserveAddress) -- [PoolByPoolCoinDenom](#PoolByPoolCoinDenom) -- [DepositRequests](#DepositRequests) -- [DepositRequest](#DepositRequest) -- [WithdrawRequests](#WithdrawRequests) -- [WithdrawRequest](#WithdrawRequest) -- [Orders](#Orders) -- [Order](#Order) -- [OrdersByOrderer](#OrdersByOrderer) -- [OrderBooks](#OrderBooks) +- [Liquidity Module](#liquidity-module) + - [Synopsis](#synopsis) + - [gRPC-gateway REST Routes](#grpc-gateway-rest-routes) + - [Params](#params) + - [Pairs](#pairs) + - [Pair](#pair) + - [Pools](#pools) + - [Pool](#pool) + - [PoolByReserveAddress](#poolbyreserveaddress) + - [PoolByPoolCoinDenom](#poolbypoolcoindenom) + - [DepositRequests](#depositrequests) + - [DepositRequest](#depositrequest) + - [WithdrawRequests](#withdrawrequests) + - [WithdrawRequest](#withdrawrequest) + - [Orders](#orders) + - [Order](#order) + - [OrdersByOrderer](#ordersbyorderer) + - [OrderBooks](#orderbooks) ## Params diff --git a/docs/api/liquidstaking.md b/docs/api/liquidstaking.md index 820e7958d..a81ee823b 100644 --- a/docs/api/liquidstaking.md +++ b/docs/api/liquidstaking.md @@ -14,10 +14,13 @@ This document provides a high-level overview of what gRPC-gateway REST routes ar ++https://github.com/cosmosquad-labs/squad/blob/main/proto/squad/liquidstaking/v1beta1/query.proto -- [Params](#Params) -- [Validators](#Validators) -- [VotingPower](#VotingPower) -- [States](#States) +- [Liquidstaking Module](#liquidstaking-module) + - [Synopsis](#synopsis) + - [gRPC-gateway REST Routes](#grpc-gateway-rest-routes) + - [Params](#params) + - [Validators](#validators) + - [VotingPower](#votingpower) + - [States](#states) ## Params diff --git a/docs/cli/liquidfarming.md b/docs/cli/liquidfarming.md new file mode 100644 index 000000000..d4e60d207 --- /dev/null +++ b/docs/cli/liquidfarming.md @@ -0,0 +1,213 @@ +--- +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. +To set up a local testing environment, it requires the latest [Ignite CLI](https://docs.ignite.com/). +If you don't have Ignite CLI set up in your local machine, see [this guide](https://docs.ignite.com/guide/install.html) to install it. +Run this command under the project root directory `$ ignite chain serve -c config-test.yml`. + +Note that [jq](https://stedolan.github.io/jq/) is recommended to be installed as it is used to process JSON throughout the document. + +- [LiquidFarming Module](#liquidfarming-module) + - [Synopsis](#synopsis) +- [Transaction](#transaction) + - [Farm](#farm) + - [Unfarm](#unfarm) +- [Query](#query) + - [Params](#params) + - [Liquidfarms](#liquidfarms) + - [Liquidfarm](#liquidfarm) + - [Rewards-Auctions](#rewards-auctions) + - [Rewards-Auction](#rewards-auction) + - [Bids](#bids) + +# Transaction + +## Farm + +Farm pool coin for liquid farming. +It is important to note that the farmer receives corresponding LFCoin after 1 epoch is passed. +It is because their pool coin is reserved in liquid farm reserve account and it stakes the amount in the farming module for them. +When an epoch is passed, the module mints the LFCoin and send them to the farmer. + +Usage + +```bash +farm [pool-id] [amount] +``` + +| **Argument** | **Description** | +| :----------- | :-------------------------------------------------------- | +| pool-id | target pool id of the liquid farm | +| amount | amount of pool coin of the target pool to liquid farm | + +Example + +```bash +squad tx liquidfarming farm 1 500000000000pool1 \ +--chain-id localnet \ +--from bob \ +--keyring-backend test \ +--gas 1000000 \ +--broadcast-mode block \ +--yes \ +--output json | jq + +# +# Tips +# +# Query account balances +# Notice the newly minted bToken +squad q liquidfarming queued-farmings 1 -o json | jq +``` + +## Unfarm + +Unfarm liquid farming coin to receive the corresponding pool coin. + +Usage + +```bash +unfarm [pool-id] [amount] +``` + +| **Argument** | **Description** | +| :------------ | :---------------------------------------------------- | +| pool-id | target pool id of the liquid unfarm | +| amount | amount of lf coin to liquid unfarm | + +Example + +```bash +squad tx liquidfarming unfarm 1 300000000000lf1 \ +--chain-id localnet \ +--from alice \ +--keyring-backend test \ +--broadcast-mode block \ +--yes \ +--output json | jq + +# +# Tips +# +# Query account balances +# Notice the newly minted bToken +squad q bank balances cosmos1mzgucqnfr2l8cj5apvdpllhzt4zeuh2cshz5xu -o json | jq +``` + +# Query + +## Params + +Query the current liquidfarming parameters information. + +Usage + +```bash +params +``` + +Example + +```bash +squad query liquidfarming params -o json | jq +``` + +## Liquidfarms + + Query for all liquidfarms. + +Usage + +```bash +liquidfarms +``` + +Example + +```bash +squad query liquidfarming liquidfarms -o json | jq +``` + +## Liquidfarm + +Query the specific liquidfarm with pool id. + +Usage + +```bash +liquidfarm [pool-id] +``` + +| **Argument** | **Description** | +| :------------ | :---------------------------------------------------- | +| pool-id | target pool id of the liquidfarm | + +Example + +```bash +squad query liquidfarming liquidfarm 1 -o json | jq +``` + +## Rewards-Auctions + +Query all rewards auctions for the liquidfarm + +Usage + +```bash +rewards-auctions +``` + +Example + +```bash +squad query liquidfarming rewards-auctions -o json | jq +``` + +## Rewards-Auction + +Query the specific reward auction + +Usage + +```bash +rewards-auction [pool-id] [auction-id] +``` + +| **Argument** | **Description** | +| :------------ | :---------------------------------------------------- | +| pool-id | target pool id of the liquidfarm | +| auction-id | target auction id of the liquidfarm with the pool id | + +Example + +```bash +squad 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 | target pool id of the liquidfarm | + +Example + +```bash +squad query liquidfarming bids 1 -o json | jq +``` diff --git a/x/farming/spec/09_hooks.md b/x/farming/spec/09_hooks.md index fc55e565f..dc6809c39 100644 --- a/x/farming/spec/09_hooks.md +++ b/x/farming/spec/09_hooks.md @@ -8,4 +8,13 @@ The following hooks can be registered: ```go AfterAllocateRewards(ctx sdk.Context) +``` + +```go +AfterStaked( + ctx sdk.Context, + farmer sdk.AccAddress, + stakingCoinDenom string, + stakingAmt sdk.Int, +) ``` \ No newline at end of file diff --git a/x/liquidfarming/spec/01_concepts.md b/x/liquidfarming/spec/01_concepts.md index 7150efe16..9c9e9310f 100644 --- a/x/liquidfarming/spec/01_concepts.md +++ b/x/liquidfarming/spec/01_concepts.md @@ -1,14 +1,77 @@ - # Concepts +This is the concept for `Liquidfarming` module in Crescent Network. + ## LiquidFarming Module -## Deposit +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 `farming` module and receives farming rewards for every epoch. +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. + +## Liquid Farm + +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 activated by being added to the parameter `liquidFarms` by governance. When the `liquidFarm` is activated, users can request to farm their pool coins. + +A `liquidFarm` can be deactivated by being removed to the parameter `liquidFarms` by governance. When the `liquidFarm` is deactivated, the module unstakes all pool coins in the module, users cannot request to farm their pool coins, but users can request to unfarm LF coins. + +## 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`. + +$$LFCoinMint = \frac{LFCoinTotalSupply}{LPCoinTotalStaked+LPCoinTotalQueued} \times LPCoinFarm,$$ + +where `LFCoinTotalSupply` is not zero. +`LPCoinTotalQueued` is the amount of pool coins in `FarmQueued` by the `liquidfarming` module. +If `LFCoinTotalSupply` is zero, then the following formula is applied: + +$$LFCoinMint = LPCoinFarm.$$ + +## Unfarm + +When a user unfarms their LFCoin, the module burns the LFCoin and releases the corresponding amount of pool coin. +Unlike minting LFCoin that happens after a certain period from farming, burning the LFCoin occurs instantly when unfarming. +The following formula is used for an exchange rate of `LFCoinUnfarm`: + +$$LPCoinUnfarm = \frac{LPCoinTotalStaked+LPCoinTotalQueued-CompoundingRewards}{LFCoinTotalSupply} \times LFCoinBurn,$$ + +if $$LFCoinBurn < LFCoinTotalSupply$$, where `CompoundingRewards` is the amount of pool coins obtained from the last rewards auction, which is in `FarmQueued`. +If $$LFCoinBurn = LFCoinTotalSupply$$, the following formula is used: + +$$LPCoinUnfarm = \frac{LPCoinTotalStaked+LPCoinTotalQueued}{LFCoinTotalSupply} \times LFCoinBurn.$$ + +If the `liquidfarm` is deactivated, the following formula is used an exchange rate of `LFCoinUnfarm`: + +$$LPCoinUnfarm = \frac{LPCoinTotalQueued}{LFCoinTotalSupply} \times LFCoinBurn.$$ + +## Farming Rewards and Auction + +On behalf of users, the module stakes their pool coins and claims farming rewards for every epoch. +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 epoch. 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 epoch. +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. 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. + +## Activation of LiquidFarm -## Withdraw +A `liquidFarm` is activated by addition of `liquidFarm` in the parameter by governance. +When a `liquidFarm` is activated, users can request to farm their pool coins and the `liquidfarming` module stakes the pool coins. -## Farming Rewards +## Deactivation of LiquidFarm -## RewardsAuction +A `liquidFarm` is deactivated by deletion of `liquidFarm` in the parameter by governance. +When a `liquidFarm` is deactivated, the `liquidfarming` module unstakes all pool coins from the farming module with the reserve module account. +The users cannot request to farm their pool coins, but users can still request to unfarm LF coins. +If a user has the request as `QueuedFarming`, the user needs to cancel the request to get the pool coins back. +In this case, the ongoing rewards auction becomes finished, all bids are refunded, and a new auction is not started. diff --git a/x/liquidfarming/spec/02_state.md b/x/liquidfarming/spec/02_state.md index d03691a64..c9f26288f 100644 --- a/x/liquidfarming/spec/02_state.md +++ b/x/liquidfarming/spec/02_state.md @@ -4,15 +4,11 @@ The `liquidfarming` module keeps track of the states of pool coins and LFCoins. -## QueuedFarming +## LiquidFarms ```go -type QueuedFarming struct { - PoolId uint64 - Id uint64 - Farmer string - FarmingCoin sdk.Coin -} +// LiquidFarms tracks the list of the activated LiquidFarms +type LiquidFarms []LiquidFarm ``` ## RewardsAuction @@ -28,16 +24,25 @@ const ( ) type RewardsAuction struct { - Id uint64 - PoolId uint64 - SellingRewards sdk.Coins - BiddingCoinDenom string // pool coin denom - SellingReserverAddress string - PayingReserveAddress string - StartTime time.Time - EndTime time.Time - Status AuctionStatus - WinnerBidId uint64 + Id uint64 + PoolId uint64 // Corresponding pool id of the target liquid farm + BiddingCoinDenom string // corresponding pool coin denom + PayingReserveAddress string + StartTime time.Time + EndTime time.Time + Status AuctionStatus + Winner string // winner's account address + Rewards sdk.Coins +} +``` + +## CompoundingRewards + +```go +// RewardsQueued records the amount of pool coins in `FarmQueued` status +// that was converted from the rewards coins by the auction. +type RewardsQueued struct { + Amount sdk.Int } ``` @@ -46,11 +51,9 @@ type RewardsAuction struct { ```go // Bid defines a standard bid for an auction. type Bid struct { - Id uint64 - AuctionId uint64 - Bidder string - Amount sdk.Coin - IsWinner bool + PoolId uint64 + Bidder string + BiddingCoin sdk.Coin } ``` @@ -63,4 +66,9 @@ type Bid struct { ## Store -... \ No newline at end of file +- LastRewardsAuctionIdKey: `[]byte{0xe1} | PoolId -> Uint64Value(uint64)` +- LiquidFarmKey: `[]byte{0xe3} | PoolId -> ProtocolBuffer(LiquidFarm)` +- CompoundingRewardsKey: `[]byte{0xe6} | PoolId -> ProtocolBuffer(CompoundingRewards)` +- RewardsAuctionKey: `[]byte{0xe7} | PoolId | AuctionId -> ProtocolBuffer(RewardsAuction)` +- BidKey: `[]byte{0xea} | PoolId | BidderAddressLen (1 byte) | BidderAddress -> ProtocolBuffer(Bid)` +- WinningBidKey: `[]byte{0xeb} | PoolId | AuctionId -> ProtocolBuffer(WinningBid)` \ No newline at end of file diff --git a/x/liquidfarming/spec/03_state_transitions.md b/x/liquidfarming/spec/03_state_transitions.md index 8439b2fa5..7ff2f854a 100644 --- a/x/liquidfarming/spec/03_state_transitions.md +++ b/x/liquidfarming/spec/03_state_transitions.md @@ -3,3 +3,60 @@ # 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 added to the parameter `LiquidFarms` by governance, the `liquidFarm` with the pool id becomes activated and 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` becomes deactivated and deleted in the state `LiquidFarms`. +When the `liquidFarm` becomes deactivated, 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 `farming` modules. + +### MsgFarm + +- Pool coins are sent to a reserve address of a liquid farm. +- The `liquidfarming` module stakes the pool coins to the `farming` module. +- LF coins are minted and sent to the farmer. + +### MsgUnfarm + +- LF coins are sent to the `liquidfarm` module account, and the LF coins are burnt. +- The `liquidfarming` module unstakes pool coins from the `farming` module. +- The pool coins are sent from a reserve address of a liquid farm to a farmer. + +### MsgUnfarmWithdraw + +- LF coins are sent to the `liquidfarm` module account, and the LF coins are burnt. +- The `liquidfarming` module unstakes pool coins from the `farming` module. +- The pool coins are sent from a reserve account of a liquid farm to a farmer. +- The pool coins are sent to a reserve account in `liquidity` module, and the corresponding coins are withdrawn to the farmer. + +### MsgPlaceBid + +- 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. + + +## State transition by hooks from other module +The following events triggered by hooks cause state transition on the `bank`, `liquidty`, and `farming` modules. + +### AfterAllocateRewards hook from `farming` module + +When `AfterAllocateRewards` hook is delivered, the following operations are performed. +- If the auction currently going on exists, the current auction becomes finished. And, + - the winner is chosen, + - the rewards is harvested and sent to the winner, + - the pool coins from the winner in the paying reserve address is sent to the module account, + - the module stakes the pool coins from the auction, the amount of these pool coins is saved to `CompoundingRewards` + - the pool coins from the others not winner in the paying reserve address is refunded to each bidder’s account. +- A new auction is created. diff --git a/x/liquidfarming/spec/04_messages.md b/x/liquidfarming/spec/04_messages.md index f7e2eb913..221a4f42d 100644 --- a/x/liquidfarming/spec/04_messages.md +++ b/x/liquidfarming/spec/04_messages.md @@ -2,58 +2,103 @@ # 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. - -## MsgCreate - -Creating new `LiquidFarm` is not possible by transaction message. It is expected to be created through governance proposal. +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. ## MsgFarm +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. + ```go type MsgFarm struct { - PoolId uint64 - Farmer string - FarmingCoin sdk.Coin + PoolId uint64 // target pool id + Farmer string // the bech32-encoded address that farms coin + FarmingCoin sdk.Coin // farming amount of pool coin } ``` -## MsgCancelQueuedFarming +Validity checks are performed for `MsgFarm` message. The transaction that is triggered with the `MsgFarm` 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 for the farming coin amount + +## MsgUnfarm + +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. ```go -type MsgCancelQueuedFarming struct { - Depositor string - PoolId uint64 - QueuedFarmingId uint64 +type MsgUnfarm 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 } ``` -## MsgUnfarm +Validity checks are performed for `MsgUnfarm` message. The transaction that is triggered with the `MsgUnfarm` 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 amount + +## MsgUnfarmAndWithdraw + +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 releases the withdrawn coins to a farmer. ```go -type MsgUnfarm struct { - PoolId uint64 - Farmer string - LFCoin sdk.Coin +type MsgUnfarmAndWithdraw 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 `MsgUnfarmAndWithdraw` message. The transaction that is triggered with the `MsgUnfarmAndWithdraw` 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 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 - Bidder string - Amount sdk.Coin + 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 + ## MsgRefundBid +Refund the bid that is not winning for the auction. + ```go type MsgRefundBid struct { - AuctionId uint64 - BidId string - Bidder sdk.Coin + BidId uint64 // target bid 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 \ No newline at end of file diff --git a/x/liquidfarming/spec/05_begin_block.md b/x/liquidfarming/spec/05_begin_block.md new file mode 100644 index 000000000..f475f0bed --- /dev/null +++ b/x/liquidfarming/spec/05_begin_block.md @@ -0,0 +1,16 @@ + + +# Begin-Block + +Begin block operations for the liquidfarming module synchronizes `liquidFarms` of the parameter and state. + +## Addition of new liquidFarm + +When a new liquidFarm is added in the parameter `LiquidFarms`, the new liquidFarm is also added in the state `LiquidFarms`. + +## Deletion of liquidFarm + +When a liquidFarm is deleted in the parameter `LiquidFarms`, the following opertions are done. +- Unstake all pool coins from the farming module with the reserve module account +- The ongoing auction status is set to `AUCTION_STATUS_FINISHED`. +- The new liquidFarm is also deleted in the state `LiquidFarms`. \ No newline at end of file diff --git a/x/liquidfarming/spec/05_end_block.md b/x/liquidfarming/spec/05_end_block.md deleted file mode 100644 index 9d46fcbfe..000000000 --- a/x/liquidfarming/spec/05_end_block.md +++ /dev/null @@ -1,9 +0,0 @@ - - -# End-Block - -At each end-block call, the `liquidfarming` module operations are specified to execute. - -At the end of each block: - -... \ No newline at end of file diff --git a/x/liquidfarming/spec/06_events.md b/x/liquidfarming/spec/06_events.md index 0a2a96ada..ee849996f 100644 --- a/x/liquidfarming/spec/06_events.md +++ b/x/liquidfarming/spec/06_events.md @@ -13,33 +13,34 @@ The `liquidfarming` module emits the following events: | farm | pool_id | {poolId} | | farm | farmer | {farmer} | | farm | farming_coin | {farmingCoin} | +| farm | farm_coin | {farmCoin} | | message | module | liquidfarming | | message | action | farm | | message | farmer | {farmerAddress} | -### MsgCancelQueuedFarming - -| Type | Attribute Key | Attribute Value | -| --------------------- | -------------------- | ---------------------- | -| cancel_queued_farming | pool_id | {poolId} | -| cancel_queued_farming | queued_farming_id | {queuedFarmingId} | -| cancel_queued_farming | farmer | {farmer} | -| message | module | liquidfarming | -| message | action | cancel_queued_farming | -| message | farmer   | {farmerAddress} | - ### MsgUnfarm | Type | Attribute Key | Attribute Value | | ---------- | ------------------ | ---------------------- | | unfarm | pool_id | {poolId} | | unfarm | farmer | {farmer} | -| unfarm | farming_coin | {farmingCoin} | -| unfarm | farmed_coin | {farmedCoin} | +| unfarm | unfarming_coin | {unfarmingCoin} | +| unfarm | unfarm_coin | {unfarmCoin} | | message | module | liquidfarming | | message | action | unfarm | | message | farmer | {farmerAddress} | +### MsgUnfarmAndWithdraw + +| Type | Attribute Key | Attribute Value | +| ---------- | ------------------ | ---------------------- | +| unfarm | pool_id | {poolId} | +| unfarm | farmer | {farmer} | +| unfarm | unfarming_coin | {unfarmingCoin} | +| message | module | liquidfarming | +| message | action | unfarmandwithdraw | +| message | farmer | {farmerAddress} | + ### MsgPlaceBid | Type | Attribute Key | Attribute Value | diff --git a/x/liquidfarming/spec/07_params.md b/x/liquidfarming/spec/07_params.md index 36bcec205..1037c4e8d 100644 --- a/x/liquidfarming/spec/07_params.md +++ b/x/liquidfarming/spec/07_params.md @@ -6,22 +6,18 @@ The `liquidfarming` module contains the following parameters: | Key | Type | Example | | -------------------------- | ------------ | ---------------------------------------------- | -| LiquidFarmCreationFee | sdk.Coins | [{"denom":"stake","amount":"100000000"}] | | LiquidFarms | []LiquidFarm | TBD | - -## LiquidFarmCreationFee - -`LiquidFarmCreationFee` ... - ## LiquidFarms -`LiquidFarms` is a list of `LiquidFarm` ... +`LiquidFarms` is a list of `LiquidFarm`, where a `LiquidFarm` is corresponding to a specific pool with `PoolId`. +A single `LiquidFarm` can exist for a given pool. + ```go type LiquidFarm struct { PoolId uint64 - MinimumDepositAmount sdk.Int + MinimumFarmAmount sdk.Int MinimumBidAmount sdk.Int } ``` diff --git a/x/liquidfarming/spec/08_hooks.md b/x/liquidfarming/spec/08_hooks.md new file mode 100644 index 000000000..6ed466b84 --- /dev/null +++ b/x/liquidfarming/spec/08_hooks.md @@ -0,0 +1,21 @@ + + +# Hooks + +The `Liquidfarming` module uses the following hooks registered in `farming` module. + +## AfterAllocateRewards Hook + +```go +AfterAllocateRewards(ctx sdk.Context) +``` + +When `AfterAllocateRewards` hook is delivered, the following operations are performed. +- If the auction currently going on exists, the current auction becomes closed. And, + - the winner is chosen, + - the rewards is harvested and sent to the winner, + - the pool coins from the winner in the paying reserve address is sent to the module account, + - these pool coins are staked via `Farming` module + - the amount of these pool coins are saved in `RewardsQueued` + - the pool coins from the others not winner in the paying reserve address is refunded to each bidder’s account. +- A new auction is created. diff --git a/x/liquidfarming/spec/README.md b/x/liquidfarming/spec/README.md index 4cc1b19da..86fe3afa7 100644 --- a/x/liquidfarming/spec/README.md +++ b/x/liquidfarming/spec/README.md @@ -12,6 +12,6 @@ This document specifies the `liquidfarming` module that provides a functionality 2. **[State](02_state.md)** 3. **[State Transitions](03_state_transitions.md)** 4. **[Messages](04_messages.md)** -5. **[End-Block](05_end_block.md)** -6. **[Events](06_events.md)** -7. **[Parameters](07_params.md)** +5. **[Events](05_events.md)** +6. **[Parameters](06_params.md)** +7. **[Hooks](07_hooks.md)**