Add comment on x/auth hacky migration script

x/auth/legacy/v043/store.go

@@ -1,3 +1,20 @@
+// Package v043 creates in-place store migrations for fixing tracking
+// delegations with vesting accounts.
+// ref: https://github.com/cosmos/cosmos-sdk/issues/8601
+// ref: https://github.com/cosmos/cosmos-sdk/issues/8812
+//
+// The migration script modifies x/auth state, hence lives in the `x/auth/legacy`
+// folder. However, it needs access to staking and bank state. To avoid
+// cyclic dependencies, we cannot import those 2 keepers in this file. To solve
+// this, we use the baseapp router to do inter-module querying, by importing
+// the `baseapp.QueryRouter grpc.Server`. This is really hacky.
+//
+// PLEASE DO NOT REPLICATE THIS PATTERN IN YOUR OWN APP.
+//
+// Proposals to refactor this file have been made in:
+// https://github.com/cosmos/cosmos-sdk/issues/9070
+// The preferred solution is to use inter-module communication (ADR-033), and
+// this file will be refactored to use ADR-033 once it's ready.
 package v043
 
 import (
@@ -27,6 +44,8 @@ const (
 	balancesPath                      = "/cosmos.bank.v1beta1.Query/AllBalances"
 )
 
+// We use the baseapp.QueryRouter here to do inter-module state querying.
+// PLEASE DO NOT REPLICATE THIS PATTERN IN YOUR OWN APP.
 func migrateVestingAccounts(ctx sdk.Context, account types.AccountI, queryServer grpc.Server) (types.AccountI, error) {
 	bondDenom, err := getBondDenom(ctx, queryServer)
 
@@ -111,6 +130,8 @@ func resetVestingDelegatedBalances(evacct exported.VestingAccount) (exported.Ves
 	}
 }
 
+// We use the baseapp.QueryRouter here to do inter-module state querying.
+// PLEASE DO NOT REPLICATE THIS PATTERN IN YOUR OWN APP.
 func getDelegatorDelegationsSum(ctx sdk.Context, address string, queryServer grpc.Server) (sdk.Coins, error) {
 	querier, ok := queryServer.(*baseapp.GRPCQueryRouter)
 	if !ok {
@@ -153,6 +174,8 @@ func getDelegatorDelegationsSum(ctx sdk.Context, address string, queryServer grp
 	return res, nil
 }
 
+// We use the baseapp.QueryRouter here to do inter-module state querying.
+// PLEASE DO NOT REPLICATE THIS PATTERN IN YOUR OWN APP.
 func getDelegatorUnbondingDelegationsSum(ctx sdk.Context, address, bondDenom string, queryServer grpc.Server) (sdk.Coins, error) {
 	querier, ok := queryServer.(*baseapp.GRPCQueryRouter)
 	if !ok {
@@ -197,6 +220,8 @@ func getDelegatorUnbondingDelegationsSum(ctx sdk.Context, address, bondDenom str
 	return res, nil
 }
 
+// We use the baseapp.QueryRouter here to do inter-module state querying.
+// PLEASE DO NOT REPLICATE THIS PATTERN IN YOUR OWN APP.
 func getBalance(ctx sdk.Context, address string, queryServer grpc.Server) (sdk.Coins, error) {
 	querier, ok := queryServer.(*baseapp.GRPCQueryRouter)
 	if !ok {
@@ -229,6 +254,8 @@ func getBalance(ctx sdk.Context, address string, queryServer grpc.Server) (sdk.C
 	return balance.Balances, nil
 }
 
+// We use the baseapp.QueryRouter here to do inter-module state querying.
+// PLEASE DO NOT REPLICATE THIS PATTERN IN YOUR OWN APP.
 func getBondDenom(ctx sdk.Context, queryServer grpc.Server) (string, error) {
 	querier, ok := queryServer.(*baseapp.GRPCQueryRouter)
 	if !ok {
@@ -264,6 +291,9 @@ func getBondDenom(ctx sdk.Context, queryServer grpc.Server) (string, error) {
 // MigrateAccount migrates vesting account to make the DelegatedVesting and DelegatedFree fields correctly
 // track delegations.
 // References: https://github.com/cosmos/cosmos-sdk/issues/8601, https://github.com/cosmos/cosmos-sdk/issues/8812
+//
+// We use the baseapp.QueryRouter here to do inter-module state querying.
+// PLEASE DO NOT REPLICATE THIS PATTERN IN YOUR OWN APP.
 func MigrateAccount(ctx sdk.Context, account types.AccountI, queryServer grpc.Server) (types.AccountI, error) {
 	return migrateVestingAccounts(ctx, account, queryServer)
 }