docs: add drafts of specs for liquidfarming module

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,
+)
 ```

x/liquidfarming/keeper/liquidfarm_test.go

@@ -1,6 +1,9 @@
 package keeper_test
 
 import (
+	"fmt"
+	"math/rand"
+
 	sdk "github.com/cosmos/cosmos-sdk/types"
 	sdkerrors "github.com/cosmos/cosmos-sdk/types/errors"
 
@@ -271,3 +274,18 @@ func (s *KeeperTestSuite) TestUnfarm_All() {
 	supply := s.app.BankKeeper.GetSupply(s.ctx, lfCoinDenom)
 	s.Require().Equal(sdk.ZeroInt(), supply.Amount)
 }
+
+func (s *KeeperTestSuite) TestMintingCal() {
+	for idx := 0; idx < 100000000; idx++ {
+		fmt.Println(idx)
+		lfCoinTotalSupply := sdk.NewInt(int64(rand.Intn(100000000000)))
+		queuedFarmingAmt := sdk.NewInt(int64(rand.Intn(100000000000)))
+		lpCoinTotalStaked := sdk.NewInt(int64(rand.Intn(100000000000)))
+
+		t1 := lfCoinTotalSupply.ToDec().Mul(queuedFarmingAmt.ToDec()).QuoTruncate(lpCoinTotalStaked.ToDec()).TruncateInt()
+		t2 := lfCoinTotalSupply.Mul(queuedFarmingAmt).Quo(lpCoinTotalStaked)
+		fmt.Println("t1: ", t1)
+		fmt.Println("t2: ", t2)
+		s.Require().Equal(t1, t2)
+	}
+}

x/liquidfarming/spec/01_concepts.md

@@ -1,14 +1,51 @@
 <!-- order: 1 -->
-
 # 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.
+
+
+## Farm
+
+Once a user farms their pool coin, the user will receive LFCoin after a configurable queueing period.
+The farm queueing period is configured as 1 day in Crescent Network. 
+The following formula is used for an exchange rate of `LFCoinMint` when a user farms with `LPCoinFarm`.
+
+$$LFCoinMint = \frac{LFCoinTotalSupply}{LPCoinTotalStaked} \times LPCoinFarm,$$
+
+where `LFCoinTotalSupply` is not zero.
+If `LFCoinTotalSupply` is zero, then the following formula is applied:
+
+$$LFCoinMint = LPCoinFarm.$$
+
+Note that the farm request can be cancelled by the user as long as minting LFCoin hasn’t occurred.
+
+## 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}{LFCoinTotalSupply} \times LFCoinBurn \times (1-fee).$$
 
-## Withdraw
+## Farming Rewards and Auction
 
-## Farming Rewards
+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.
 
-## RewardsAuction
+## 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.

x/liquidfarming/spec/02_state.md

@@ -8,10 +8,8 @@ The `liquidfarming` module keeps track of the states of pool coins and LFCoins.
 
 ```go
 type QueuedFarming struct {
-	PoolId      uint64
-	Id          uint64
-	Farmer      string
-	FarmingCoin sdk.Coin
+	PoolId      uint64  // Corresponding pool id of the target liquid farm
+	Amount 		sdk.Int // amount to liquid farm
 }
 ```
 
@@ -29,15 +27,13 @@ const (
 
 type RewardsAuction struct {
 	Id                     uint64
-	PoolId                 uint64
-	SellingRewards         sdk.Coins
-	BiddingCoinDenom       string // pool coin denom
-	SellingReserverAddress string
+	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
-	WinnerBidId            uint64
+	WinnerBidId            uint64 // id of winning bid of the auction
 }
 ```
 
@@ -46,11 +42,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
 }
 ```
 
@@ -62,5 +56,9 @@ type Bid struct {
 - QuerierRoute: `liquidfarming`
 
 ## Store
-
-...
+- `LastDepositRequestIdKeyPrefix: []byte{0xe1} PoolId → Uint64Value(uint64)`
+- `LastBidIdKeyPrefix: []byte{0xe2} AuctionId → Uint64Value(BidId)`
+- `LastRewardsAuctionIdKey: []byte{0xe3} → Uint64Value(uint64)`
+- `DepositRequestKey: []byte{0xe4} | PoolId | DepositRequestId -> ProtocolBuffer(DepositRequest)`
+- `DepositRequestIndexKey: []byte{0xe5} | DepositorAddressLen (1 byte) | DepositorAddress | PoolId | DepositRequestId -> nil`
+- `AuctionKey: []byte{0xe8} | LiquidFarmId | AuctionId -> ProtocolBuffer(AuctionState)`

x/liquidfarming/spec/03_state_transitions.md

@@ -3,3 +3,45 @@
 # State Transitions
 
 This document describes the state transaction operations in the `liquidfarming` module.
+
+## Liquid farm creation
+
+
+
+## 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.
+
+### MsgCancelQueuedFarming
+
+- 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.
+
+### 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.
+
+
+The following events triggered by hooks cause state transition on the `bank`, `liquidty`, and `farming` modules.

x/liquidfarming/spec/04_messages.md

@@ -2,58 +2,122 @@
 
 # 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
 }
 ```
 
+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
+
 ## MsgCancelQueuedFarming
 
+Cancel the farming coins before being staked. 
+A farmer is allowed to cancel their farming coin amount before they are staked to the farming module.
+
 ```go
 type MsgCancelQueuedFarming struct {
-	Depositor       string
-	PoolId          uint64
-	QueuedFarmingId uint64
+	PoolId           uint64 	// target pool id
+	Farmer           string		// the bech32-encoded address that cancels queued farming
+	UnfarmingCoin    sdk.Coin	// cancel amount of pool coin
 }
 ```
 
+Validity checks are performed for `MsgCancelQueuedFarming` message. The transaction that is triggered with the `MsgCancelQueuedFarming` message fails if:
+
+- The target liquid farm with the pool id does not exist
+- The unfarming coin denom is not the same as the pool coin denom of the pool with `PoolId`
+- The unfarming coin amount is less than the amount of the queued amount of farming coin of the farmer.
+
 ## 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 MsgUnfarm struct {
-	PoolId uint64
-	Farmer string
-	LFCoin sdk.Coin
+	PoolId     uint64   // target deposit request id
+	Farmer     string   // the bech32-encoded address that unfarms liquid farm coin
+	LFCoin     sdk.Coin // withdrawing amount of LF coin
 }
 ```
 
+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
+
+## MsgUnfarmWithdraw
+
+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 MsgUnfarmWithdraw struct {
+	PoolId     uint64   // target pool id
+	Farmer     string   // the bech32-encoded address that unfarms liquid farm coin and withdraws 
+	LFCoin     sdk.Coin // withdrawing amount of LF coin
+}
+```
+
+Validity checks are performed for `MsgUnfarmWithdraw` message. The transaction that is triggered with the `MsgUnfarmWithdraw` 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
 }
 ```
+
+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

x/liquidfarming/spec/06_events.md → x/liquidfarming/spec/05_events.md

@@ -1,4 +1,4 @@
-<!-- order: 6 -->
+<!-- order: 5 -->
 
 # Events
 

x/liquidfarming/spec/07_params.md → x/liquidfarming/spec/06_params.md

@@ -1,4 +1,4 @@
-<!-- order: 7 -->
+<!-- order: 6 -->
 
 # Parameters