docs: improve documentation for audit release

.github/PULL_REQUEST_TEMPLATE.md

@@ -32,6 +32,6 @@ write a little note why.
 - [ ] Code follows the [module structure standards](https://github.com/cosmos/cosmos-sdk/blob/master/docs/building-modules/structure.md).
 - [ ] Wrote unit and integration
 - [ ] Updated relevant documentation (`docs/`) or specification (`x/<module>/spec/`)
-- [ ] Added relevant `godoc` [comments](https://blog.golang.org/godoc-documenting-go-code).
+- [ ] Added relevant `godoc` [comments](https://go.dev/blog/godoc).
 - [ ] Re-reviewed `Files changed` in the Github PR explorer
 - [ ] Review `Codecov Report` in the comment section below once CI passes

README.md

@@ -3,12 +3,13 @@
 
 # Farming Module
 
-A farming module is a Cosmos SDK module that implements farming functionality, which provides farming rewards to participants called farmers. One use case is to use this module to provide incentives for liquidity pool investors for their pool participation. 
+A farming module is a Cosmos SDK module that implements farming functionality, which provides farming rewards to participants called farmers. A primary use case is to use this module to provide incentives for liquidity pool investors for their pool participation. 
 
-⚠ **Farming module v1 is in active development - see "master" branch for the v1 mainnet version** ⚠
+⚠ **Farming module v1 is in active development** ⚠ 
+- see the [master](https://github.com/tendermint/farming/tree/master) branch for the latest 
+- see [releases](https://github.com/tendermint/farming/releases) for the latest release
 
-## Installation
-### Requirements
+## Dependencies
 
 If you haven't already, install Golang by following the [official docs](https://golang.org/doc/install). Make sure that your `GOPATH` and `GOBIN` environment variables are properly set up.
 
@@ -17,32 +18,30 @@ Requirement | Notes
 Go version  | Go1.16 or higher
 Cosmos SDK  | v0.44.2 or higher
 
-### Get Farming Module source code
+## Installation
 
 ```bash
+# Use git to clone farming module source code and install `farmingd`
 git clone https://github.com/tendermint/farming.git
 cd farming
 make install
 ```
 
-## Development
+## Getting Started
 
-### Test
+To get started to the project, visit the [TECHNICAL-SETUP.md](./TECHNICAL-SETUP.md) docs.
 
-```bash
-make test-all
-```
+## Documentation
 
-### Setup local testnet using script
+The farming module documentation is available in [docs](./docs) folder and technical specification is available in [specs](https://github.com/tendermint/farming/blob/master/x/farming/spec/README.md) folder. 
 
-```bash
-# This script bootstraps a single local testnet.
-# Note that config, data, and keys are created in the ./data/localnet folder and
-# RPC, GRPC, and REST ports are all open.
-$ make localnet
-```
+These are some of the documents that help you to quickly get you on board with the farming module.
+
+- [How to bootstrap a local network with farming module](./docs/Tutorials/localnet)
+- [How to use Command Line Interfaces](./docs/How-To/cli)
+- [How to use gRPC-gateway REST Routes](./docs/How-To)
+- [Demo for how to budget and farming modules](./docs/Tutorials/demo/budget_with_farming.md)
 
-## Resources
+## Contributing
 
-- [Documentation about Command-line and REST API Interfaces](./docs/How-To)
-- [Demo](./docs/Tutorials/demo)
+We welcome contributions from everyone. The [master](https://github.com/tendermint/farming/tree/master) branch contains the development version of the code. You can branch of from master and create a pull request, or maintain your own fork and submit a cross-repository pull request. If you're not sure where to start check out [CONTRIBUTING.md](./CONTRIBUTING.md) for our guidelines & policies for how we develop farming module. Thank you to all those who have contributed to farming module!

TECHNICAL-SETUP.md

@@ -1,6 +1,6 @@
 # Technical Setup
 
-To ensure you have a successful experience working with our farming module, Tendermint recommends this technical setup.
+To ensure you have a successful experience working with our farming module, we recommend this technical setup.
 
 ## Github Integration
 
@@ -54,15 +54,15 @@ For cross-builds use the standard `GOOS` and `GOARCH` env vars. i.e. to build fo
 GOOS=windows GOARCH=amd64 make build
 ```
 
+## Installation
+
+To install the node client on your machine, run `make install` command from the project's root folder. 
+
+> 💡 you can also use the default `go` command to build the project, check the content of the [Makefile](https://github.com/tendermint/farming/blob/master/Makefile#L90) for reference
 
 ## Testing
 
 Run `make test-all` command to run tests.
 
 > 💡 you can also use the default `go` command to build the project, check the content of the [Makefile](https://github.com/tendermint/farming/blob/master/Makefile#L145) for reference
 
-## Installation
-
-To install the node client on your machine, run `make install` command from the project's root folder. 
-
-> 💡 you can also use the default `go` command to build the project, check the content of the [Makefile](https://github.com/tendermint/farming/blob/master/Makefile#L90) for reference

x/farming/spec/01_concepts.md

@@ -3,7 +3,7 @@
  # Concepts
 ## Farming Module
 
-`x/farming` is a Cosmos SDK module that implements farming functionality that keeps track of the staking and provides farming rewards to farmers. One use case is to use this module to provide incentives for liquidity pool investors for their pool participation. 
+`x/farming` is a Cosmos SDK module that implements farming functionality that keeps track of the staking and provides farming rewards to farmers. A primary use case is to use this module to provide incentives for liquidity pool investors for their pool participation. 
 
 ## Plans
 
@@ -27,3 +27,16 @@ A `FixedAmountPlan` distributes fixed amount of coins to farmers for every epoch
 
 A `RatioPlan` distributes to farmers by ratio distribution for every epoch day. If the plan creators `FarmingPoolAddress` is depleted with distributing coins, then there is no more coins to distribute unless it is filled up with more coins.
 
+## Accumulated Reward Calculation
+
+- Accumulated Unit Reward : AUR represents accumulated rewards(for each staking coin) of a staking position with amount 1.
+- AUR for each staking coin for each epoch can be calculated as below
+  - ![](https://latex.codecogs.com/svg.latex?\Large&space;\sum_{i=0}^{now}\frac{TR_i}{TS_i})
+    - ![](https://latex.codecogs.com/svg.latex?\Large&space;i) : each `EpochId`
+    - ![](https://latex.codecogs.com/svg.latex?\Large&space;now) : current `EpochId`
+    - ![](https://latex.codecogs.com/svg.latex?\Large&space;TS_i) : total staking amount of the staking coin for epoch i
+    - ![](https://latex.codecogs.com/svg.latex?\Large&space;TR_i) : total reward amount of the staking coin for epoch i
+- Accumulated rewards from any staking position can be calculated from AUR and the staking amount of the position as below
+  - ![](https://latex.codecogs.com/svg.latex?\Large&space;x*\(\sum_{i=0}^{now}\frac{TR_i}{TS_i}-\sum_{i=0}^{start}\frac{TR_i}{TS_i}\))
+    - assuming constant staking amount for the staking epochs
+    - ![](https://latex.codecogs.com/svg.latex?\Large&space;x) : staking amount for the staking period

x/farming/spec/03_state_transitions.md

@@ -25,52 +25,57 @@ const (
 - Staking Coins for Farming
   - Each `farmingPlan` predefines list of `stakingCoinWeights` using `sdk.DecCoins`
   - `weight` mean that each group of stakers with each coin `denom` will receive each predefined `weight` of the total rewards
+
 - Multiple Farming Coins within a `farmingPoolAddress`
   - If `farmingPoolAddress` has multiple kinds of coins, then all coins are identically distributed following the given `farmingPlan`
+
 - Time Parameters
   - Each `farmingPlan` has its own `startTime` and `endTime`
+
 - Distribution Method
   - `FixedAmountPlan`
     - fixed amount of coins are distributed per `CurrentEpochDays`
     - `epochAmount` is `sdk.Coins`
   - `RatioPlan`
     - ratio of total assets in `farmingPoolAddress` is distributed per `CurrentEpochDays`
     - `epochRatio` is in percentage
+
 - Termination Address
   - When the plan ends after the `endTime`, transfer the balance of `farmingPoolAddress` to `terminationAddress`.
 
-## Staking
-
-- New `Staking` object is created when a farmer creates a staking, and when the farmer does not have existing `Staking`.
-- When a farmer add/remove stakings to/from existing `Staking`, `StakedCoins` and `QueuedCoins` are updated in the corresponding `Staking`.
-- `QueuedCoins` : newly staked coins are in this status until end of current epoch, and then migrated to `StakedCoins` at the end of current epoch.
-- When a farmer unstakes, `QueuedCoins` are unstaked first, and then `StakedCoins`.
-
-## Reward Withdrawal
-
-To assume constant staking amount for reward withdrawal, automatic withdrawal is designed as below:
-- Add staking position : When there exists `QueuedCoins` in `Staking` at the end of current epoch
-  - accumulated rewards until current epoch are automatically withdrawn
-  - `StartEpochId` is modified to the `EpochId` of the next epoch
-  - `QueuedCoins` is migrated to `StakedCoins`
-- Remove staking position : When a farmer remove stakings from `StakedCoins`
-  - accumulated rewards until last epoch are immediately withdrawn
-  - `StartEpochId` is modified to the `EpochId` of the current epoch
-  - unstake executed immediately and `StakedCoins` are reduced accordingly
-- Manual reward withdrawal : When a farmer request a reward withdrawal
-  - accumulated rewards until last epoch are immediately withdrawn
-  - `StartEpochId` is modified to the `EpochId` of the current epoch
-
-## Accumulated Reward Calculation
-
-- Accumulated Unit Reward : AUR represents accumulated rewards(for each staking coin) of a staking position with amount 1.
-- AUR for each staking coin for each epoch can be calculated as below
-  - ![](https://latex.codecogs.com/svg.latex?\Large&space;\sum_{i=0}^{now}\frac{TR_i}{TS_i})
-    - ![](https://latex.codecogs.com/svg.latex?\Large&space;i) : each `EpochId`
-    - ![](https://latex.codecogs.com/svg.latex?\Large&space;now) : current `EpochId`
-    - ![](https://latex.codecogs.com/svg.latex?\Large&space;TS_i) : total staking amount of the staking coin for epoch i
-    - ![](https://latex.codecogs.com/svg.latex?\Large&space;TR_i) : total reward amount of the staking coin for epoch i
-- Accumulated rewards from any staking position can be calculated from AUR and the staking amount of the position as below
-  - ![](https://latex.codecogs.com/svg.latex?\Large&space;x*\(\sum_{i=0}^{now}\frac{TR_i}{TS_i}-\sum_{i=0}^{start}\frac{TR_i}{TS_i}\))
-    - assuming constant staking amount for the staking epochs
-    - ![](https://latex.codecogs.com/svg.latex?\Large&space;x) : staking amount for the staking period
+## Stake
+
+When a farmer stakes an amount of coins, the following state transitions occur:
+
+- it reserves the amount of coins to the staking reserve pool account `StakingReservePoolAcc` 
+- it creates `QueuedStaking` object and stores the staking coins in `QueueStaking`, which are waiting in a queue until the end of epoch to move to `Staking` object
+- it imposes more gas if the farmer already has `Staking` with the same coin denom
+
+## Unstake
+
+When a farmer unstakes an amount of coins, the following state transitions occur:
+
+- it adds `Staking` and `QueueStaking` amounts to see if the unstaking amount is sufficient
+- it automatically withdraws rewards for the coin denom which are accumulated over the last epochs
+- it substracts the unstaking amount of coins from `QueueStaking` first and if it is not sufficient then it substracts from `Staking`
+- it releases the unstaking amount of coins to the farmer
+
+## Harvest (Reward Withdrawal)
+
+- it calculates `CumulativeUnitRewards` in `HistoricalRewards` object in order to get the rewards for the staking coin denom which are accumulated over the last epochs for the farmer
+- it releases the accumulated rewards to the farmer if it is not zero and decreases the `OutstandingRewards`
+- it sets `StartingEpoch` in `Staking` object
+
+## Reward Allocation
+
+Each abci end block call, the operations to update rewards allocation are to execute:
+
+++ https://github.com/tendermint/farming/blob/69db071ce30b99617b8ba9bb6efac76e74cd100b/x/farming/keeper/reward.go#L363-L426
+
+- it calculates rewards allocation information for the end of the current epoch depending on plan type `FixedAmountPlan` or `RatioPlan`
+- it distributes total allocated coins from each plan’s farming pool address `FarmingPoolAddress` to the rewards reserve pool account `RewardsReserveAcc`
+- it calculates staking coin weight for each denom in each plan and gets the unit rewards by denom
+- it updates `HistoricalRewards` and `CurrentEpoch` based on the allocation information
+- it automatically withdraws the accumulated rewards to the farmer with the given staking coin denom if `Staking` position exists
+- it deletes `QueueStaking` object after moving `QueueCoins` to `StakedCoins` in `Staking` object
+- it increases `TotalStakings` for the staking coin denom

x/farming/spec/05_end_block.md

@@ -1,15 +1,6 @@
 <!-- order: 6 -->
+# End-Block
 
- # End-Block
+++ https://github.com/tendermint/farming/blob/69db071ce3/x/farming/abci.go#L13-L46
 
-- Termination of Farming Plan
-    - Private Plan
-        - distribution stops
-        - remove plan states
-        - keep stake, reward states for unstakable stakes and claimable rewards each farmers
-        - rest of the fund in `farmingPoolAddress` sent to `terminationAddress`, in Private Plan case, `terminationAddress` is plan creator
-    - Public Plan
-        - distribution stops
-        - remove plan states
-        - keep stake, reward states for unstakable stakes and claimable rewards each farmers
-        - rest of the fund in `farmingPoolAddress` sent to `terminationAddress`
+At the end of each block, it terminates plans that their end time has passed over the current block time. It sends all remaining coins in the plan's farming pool account `FarmingPoolAddress` to the termination address `TerminationAddress` and mark the plan as terminated by making `Terminated` false. A global parameter `NextEpochDays` is there but the farming module uses an internal state `CurrentEpochDays` to prevent from a case where it may affect the rewards allocation. Suppose `NextEpochDays` is 7 and it is proposed to change the value to 1 through governance proposal. Although the proposal is passed, rewards allocation should continue to proceed with 7, not 1. The [test code](https://github.com/tendermint/farming/blob/69db071ce3/x/farming/abci_test.go#L12-L64) is available for you if you want to understand it in more detail. Then it allocates farming rewards, processes `QueueCoins` to `StakedCoins`, and sets `LastEpochTime` to keep in track in case of the chain upgrdae.