chore: Merge pull request #158 from kogisin/kogisin/152-refactor-comm…

…ents

docs: add more clear and description comments

x/farming/client/cli/flags.go

@@ -14,6 +14,7 @@ const (
 	FlagAll              = "all"
 )
 
+// flagSetPlans returns the FlagSet used for farming plan related opertations.
 func flagSetPlans() *flag.FlagSet {
 	fs := flag.NewFlagSet("", flag.ContinueOnError)
 
@@ -25,6 +26,7 @@ func flagSetPlans() *flag.FlagSet {
 	return fs
 }
 
+// flagSetStakings returns the FlagSet used for farmer's staking coin denom.
 func flagSetStakings() *flag.FlagSet {
 	fs := flag.NewFlagSet("", flag.ContinueOnError)
 
@@ -33,6 +35,7 @@ func flagSetStakings() *flag.FlagSet {
 	return fs
 }
 
+// flagSetRewards returns the FlagSet used for farmer's rewards.
 func flagSetRewards() *flag.FlagSet {
 	fs := flag.NewFlagSet("", flag.ContinueOnError)
 
@@ -41,6 +44,7 @@ func flagSetRewards() *flag.FlagSet {
 	return fs
 }
 
+// flagSetHarvest returns the FlagSet used for harvest all staking coin denoms.
 func flagSetHarvest() *flag.FlagSet {
 	fs := flag.NewFlagSet("", flag.ContinueOnError)
 

x/farming/client/cli/query.go

@@ -39,10 +39,10 @@ func GetQueryCmd() *cobra.Command {
 		GetCmdQueryRewards(),
 		GetCmdQueryCurrentEpochDays(),
 	)
-
 	return farmingQueryCmd
 }
 
+// GetCmdQueryParams implements the query params command.
 func GetCmdQueryParams() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "params",
@@ -78,6 +78,7 @@ $ %s query %s params
 	return cmd
 }
 
+// GetCmdQueryPlans implements the query all plans command.
 func GetCmdQueryPlans() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "plans [optional flags]",
@@ -148,6 +149,7 @@ $ %s query %s plans --staking-coin-denom poolD35A0CC16EE598F90B044CE296A405BA9C3
 	return cmd
 }
 
+// GetCmdQueryPlan implements the query the particular plan command.
 func GetCmdQueryPlan() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "plan [plan-id]",
@@ -190,6 +192,7 @@ $ %s query %s plan
 	return cmd
 }
 
+// GetCmdQueryStakings implements the query all stakings command.
 func GetCmdQueryStakings() *cobra.Command {
 	bech32PrefixAccAddr := sdk.GetConfig().GetBech32AccountAddrPrefix()
 
@@ -242,6 +245,7 @@ $ %s query %s stakings %s1gghjut3ccd8ay0zduzj64hwre2fxs9ldmqhffj --staking-coin-
 	return cmd
 }
 
+// GetCmdQueryTotalStakings implements the query total staking amounts for a staking coin denom command.
 func GetCmdQueryTotalStakings() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "total-stakings [staking-coin-denom]",
@@ -284,6 +288,7 @@ $ %s query %s total-stakings poolD35A0CC16EE598F90B044CE296A405BA9C381E38837599D
 	return cmd
 }
 
+// GetCmdQueryRewards implements the query all rewards for a farmer command.
 func GetCmdQueryRewards() *cobra.Command {
 	bech32PrefixAccAddr := sdk.GetConfig().GetBech32AccountAddrPrefix()
 
@@ -336,6 +341,7 @@ $ %s query %s rewards %s1gghjut3ccd8ay0zduzj64hwre2fxs9ldmqhffj --staking-coin-d
 	return cmd
 }
 
+// GetCmdQueryCurrentEpochDays implements the query current epoch days command.
 func GetCmdQueryCurrentEpochDays() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "current-epoch-days",

x/farming/client/cli/tx.go

@@ -46,6 +46,7 @@ func GetTxCmd() *cobra.Command {
 	return farmingTxCmd
 }
 
+// NewCreateFixedAmountPlanCmd implements the create a fixed amount plan command handler.
 func NewCreateFixedAmountPlanCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "create-private-fixed-plan [plan-file]",
@@ -118,6 +119,7 @@ Description for the parameters:
 	return cmd
 }
 
+// NewCreateRatioPlanCmd implements the create a ratio plan command handler.
 func NewCreateRatioPlanCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "create-private-ratio-plan [plan-file]",
@@ -185,6 +187,7 @@ Description for the parameters:
 	return cmd
 }
 
+// NewStakeCmd implements the stake coin(s) command handler.
 func NewStakeCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "stake [amount]",
@@ -227,6 +230,7 @@ $ %s tx %s stake 500poolD35A0CC16EE598F90B044CE296A405BA9C381E38837599D96F2F70C2
 	return cmd
 }
 
+// NewUnstakeCmd implements the unstake coin(s) command handler.
 func NewUnstakeCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "unstake [amount]",
@@ -269,6 +273,7 @@ $ %s tx %s unstake 500poolD35A0CC16EE598F90B044CE296A405BA9C381E38837599D96F2F70
 	return cmd
 }
 
+// NewHarvestCmd implements the harvest rewards command handler.
 func NewHarvestCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "harvest [staking-coin-denoms]",
@@ -334,6 +339,7 @@ $ %s tx %s harvest --all --from mykey
 	return cmd
 }
 
+// NewAdvanceEpochCmd implements the advance epoch by 1 command handler.
 func NewAdvanceEpochCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "advance-epoch",
@@ -368,7 +374,7 @@ $ %s tx %s advance-epoch --from mykey
 	return cmd
 }
 
-// GetCmdSubmitPublicPlanProposal implements a command handler for submitting a public farming plan transaction to create, update, and delete plan.
+// GetCmdSubmitPublicPlanProposal implements the create/update/delete public farming plan command handler.
 func GetCmdSubmitPublicPlanProposal() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "public-farming-plan [proposal-file] [flags]",

x/farming/client/cli/utils.go

@@ -77,6 +77,7 @@ func ParsePublicPlanProposal(cdc codec.JSONCodec, proposalFile string) (types.Pu
 	return proposal, nil
 }
 
+// String returns a human readable string representation of the request.
 func (req PrivateFixedPlanRequest) String() string {
 	result, err := json.Marshal(&req)
 	if err != nil {
@@ -85,6 +86,7 @@ func (req PrivateFixedPlanRequest) String() string {
 	return string(result)
 }
 
+// String returns a human readable string representation of the request.
 func (req PrivateRatioPlanRequest) String() string {
 	result, err := json.Marshal(&req)
 	if err != nil {

x/farming/client/proposal_handler.go

@@ -7,7 +7,8 @@ import (
 	"github.com/tendermint/farming/x/farming/client/rest"
 )
 
-// ProposalHandler is the public plan creation handler.
+// ProposalHandler is the public plan command handler.
+// Note that rest.ProposalRESTHandler will be deprecated in the future.
 var (
 	ProposalHandler = govclient.NewProposalHandler(cli.GetCmdSubmitPublicPlanProposal, rest.ProposalRESTHandler)
 )

x/farming/client/rest/rest.go

@@ -7,9 +7,6 @@ import (
 	govrest "github.com/cosmos/cosmos-sdk/x/gov/client/rest"
 )
 
-// TODO: not implemented yet;
-// although this legacy REST API may not be needed, it needs for ProposalHandler; otherwise it throws panic when starting the chain
-
 // ProposalRESTHandler returns a ProposalRESTHandler that exposes the farming plan proposal (add/update/delete) REST handler with a given sub-route.
 func ProposalRESTHandler(clientCtx client.Context) govrest.ProposalRESTHandler {
 	return govrest.ProposalRESTHandler{

x/farming/keeper/epoch.go

@@ -10,21 +10,25 @@ import (
 	"github.com/tendermint/farming/x/farming/types"
 )
 
-func (k Keeper) GetLastEpochTime(ctx sdk.Context) (time.Time, bool) {
+// GetLastEpochTime returns the last time the epoch ended.
+func (k Keeper) GetLastEpochTime(ctx sdk.Context) (t time.Time, found bool) {
 	store := ctx.KVStore(k.storeKey)
 	bz := store.Get(types.LastEpochTimeKey)
 	if bz == nil {
-		return time.Time{}, false
+		return
 	}
 	var ts gogotypes.Timestamp
 	k.cdc.MustUnmarshal(bz, &ts)
-	t, err := gogotypes.TimestampFromProto(&ts)
+	var err error
+	t, err = gogotypes.TimestampFromProto(&ts)
 	if err != nil {
 		panic(err)
 	}
-	return t, true
+	found = true
+	return
 }
 
+// SetLastEpochTime sets the last time the epoch ended.
 func (k Keeper) SetLastEpochTime(ctx sdk.Context, t time.Time) {
 	store := ctx.KVStore(k.storeKey)
 	ts, err := gogotypes.TimestampProto(t)
@@ -35,6 +39,8 @@ func (k Keeper) SetLastEpochTime(ctx sdk.Context, t time.Time) {
 	store.Set(types.LastEpochTimeKey, bz)
 }
 
+// AdvanceEpoch ends the current epoch. When an epoch ends, rewards
+// are distributed and queued staking coins become staked.
 func (k Keeper) AdvanceEpoch(ctx sdk.Context) error {
 	if err := k.AllocateRewards(ctx); err != nil {
 		return err
@@ -45,7 +51,7 @@ func (k Keeper) AdvanceEpoch(ctx sdk.Context) error {
 	return nil
 }
 
-// GetCurrentEpochDays returns the  current epoch days.
+// GetCurrentEpochDays returns the current epoch days(period).
 func (k Keeper) GetCurrentEpochDays(ctx sdk.Context) uint32 {
 	var epochDays uint32
 	store := ctx.KVStore(k.storeKey)
@@ -63,7 +69,7 @@ func (k Keeper) GetCurrentEpochDays(ctx sdk.Context) uint32 {
 	return epochDays
 }
 
-// SetCurrentEpochDays sets the  current epoch days.
+// SetCurrentEpochDays sets the current epoch days(period).
 func (k Keeper) SetCurrentEpochDays(ctx sdk.Context, epochDays uint32) {
 	store := ctx.KVStore(k.storeKey)
 	bz := k.cdc.MustMarshal(&gogotypes.UInt32Value{Value: epochDays})

x/farming/keeper/epoch_test.go

@@ -24,12 +24,11 @@ func (suite *KeeperTestSuite) TestLastEpochTime() {
 
 func (suite *KeeperTestSuite) TestFirstEpoch() {
 	// The first epoch may run very quickly depending on when
-	// the farming module is deployed,
+	// the farming module was activated,
 	// meaning that (block time) - (last epoch time) may be smaller
-	// than epoch_days parameter on the first epoch.
+	// than the current epoch_days for the first epoch.
 
-	params := suite.keeper.GetParams(suite.ctx)
-	suite.Require().Equal(uint32(1), params.NextEpochDays)
+	suite.Require().Equal(uint32(1), suite.keeper.GetCurrentEpochDays(suite.ctx))
 
 	suite.ctx = suite.ctx.WithBlockTime(types.ParseTime("2021-08-11T23:59:59Z"))
 	farming.EndBlocker(suite.ctx, suite.keeper)
@@ -39,7 +38,7 @@ func (suite *KeeperTestSuite) TestFirstEpoch() {
 	suite.ctx = suite.ctx.WithBlockTime(types.ParseTime("2021-08-12T00:00:00Z"))
 	farming.EndBlocker(suite.ctx, suite.keeper)
 	t, _ := suite.keeper.GetLastEpochTime(suite.ctx)
-	suite.Require().True(t.After(lastEpochTime)) // Indicating that the epoch advanced.
+	suite.Require().True(t.After(lastEpochTime)) // Indicating that the epoch ended.
 }
 
 func (suite *KeeperTestSuite) TestEpochDays() {

x/farming/keeper/grpc_query.go

@@ -77,7 +77,7 @@ func (k Querier) Plans(c context.Context, req *types.QueryPlansRequest) (*types.
 		if err != nil {
 			return false, err
 		}
-		any, err := codectypes.NewAnyWithValue(plan)
+		planAny, err := types.PackPlan(plan)
 		if err != nil {
 			return false, err
 		}
@@ -114,7 +114,7 @@ func (k Querier) Plans(c context.Context, req *types.QueryPlansRequest) (*types.
 		}
 
 		if accumulate {
-			plans = append(plans, any)
+			plans = append(plans, planAny)
 		}
 
 		return true, nil
@@ -138,14 +138,15 @@ func (k Querier) Plan(c context.Context, req *types.QueryPlanRequest) (*types.Qu
 		return nil, status.Errorf(codes.NotFound, "plan %d not found", req.PlanId)
 	}
 
-	any, err := codectypes.NewAnyWithValue(plan)
+	planAny, err := types.PackPlan(plan)
 	if err != nil {
 		return nil, status.Error(codes.Internal, err.Error())
 	}
 
-	return &types.QueryPlanResponse{Plan: any}, nil
+	return &types.QueryPlanResponse{Plan: planAny}, nil
 }
 
+// Stakings queries stakings for a farmer.
 func (k Querier) Stakings(c context.Context, req *types.QueryStakingsRequest) (*types.QueryStakingsResponse, error) {
 	if req == nil {
 		return nil, status.Error(codes.InvalidArgument, "empty request")
@@ -191,6 +192,7 @@ func (k Querier) Stakings(c context.Context, req *types.QueryStakingsRequest) (*
 	return resp, nil
 }
 
+// TotalStakings queries total staking coin amount for a specific staking coin denom.
 func (k Querier) TotalStakings(c context.Context, req *types.QueryTotalStakingsRequest) (*types.QueryTotalStakingsResponse, error) {
 	if req == nil {
 		return nil, status.Error(codes.InvalidArgument, "empty request")
@@ -212,6 +214,7 @@ func (k Querier) TotalStakings(c context.Context, req *types.QueryTotalStakingsR
 	}, nil
 }
 
+// Rewards queries accumulated rewards for a farmer.
 func (k Querier) Rewards(c context.Context, req *types.QueryRewardsRequest) (*types.QueryRewardsResponse, error) {
 	if req == nil {
 		return nil, status.Error(codes.InvalidArgument, "empty request")

x/farming/keeper/keeper.go

@@ -14,7 +14,10 @@ import (
 )
 
 var (
-	enableAdvanceEpoch = "false" // set it to "true" using build flags to enable AdvanceEpoch msg handling.
+	enableAdvanceEpoch = "false" // Set this to "true" using build flags to enable AdvanceEpoch msg handling.
+
+	// EnableAdvanceEpoch indicates whether msgServer accepts MsgAdvanceEpoch or not.
+	// Never set this to true in production mode. Doing that will expose serious attack vector.
 	EnableAdvanceEpoch = false
 )
 
@@ -71,7 +74,7 @@ func (k Keeper) Logger(ctx sdk.Context) log.Logger {
 	return ctx.Logger().With("module", "x/"+types.ModuleName)
 }
 
-// GetParams gets the parameters for the farming module.
+// GetParams returns the parameters for the farming module.
 func (k Keeper) GetParams(ctx sdk.Context) (params types.Params) {
 	k.paramSpace.GetParamSet(ctx, &params)
 	return params
@@ -82,15 +85,15 @@ func (k Keeper) SetParams(ctx sdk.Context, params types.Params) {
 	k.paramSpace.SetParamSet(ctx, &params)
 }
 
-// GetCodec return codec.Codec object used by the keeper
+// GetCodec returns codec.Codec object used by the keeper>
 func (k Keeper) GetCodec() codec.BinaryCodec { return k.cdc }
 
-// GetStakingReservePoolAcc returns module account for Staking Reserve Pool account
+// GetStakingReservePoolAcc returns module account for the staking reserve pool account.
 func (k Keeper) GetStakingReservePoolAcc(ctx sdk.Context) sdk.AccAddress { // nolint:interfacer
 	return types.StakingReserveAcc
 }
 
-// GetRewardsReservePoolAcc returns temporary module account for Reward coins Reserve Pool account
+// GetRewardsReservePoolAcc returns module account for the rewards reserve pool account.
 func (k Keeper) GetRewardsReservePoolAcc(ctx sdk.Context) sdk.AccAddress { // nolint:interfacer
 	return types.RewardsReserveAcc
 }