chore: review feedback improvements

proto/poktroll/migration/legacy.proto

@@ -17,7 +17,7 @@ option go_package = "github.com/pokt-network/poktroll/x/migration/types";
 option (gogoproto.stable_marshaler_all) = true;
 
 // MorseStateExport is the data structure that is serialized and output when running
-// `pocket utils export-genesis-for-reset`.
+// `pocket util export-genesis-for-reset`.
 // See: https://editor.swagger.io/?url=https://raw.githubusercontent.com/pokt-network/pocket-core/staging/doc/specs/rpc-spec.yaml#operations-query-post_query_state
 message MorseStateExport {
   // app_hash is the Morse tendermint state hash.

proto/poktroll/migration/query.proto

@@ -21,7 +21,7 @@ service Query {
 
   }
 
-  // Queries a MorseAccountState by index.
+  // Queries the MorseAccountState.
   rpc MorseAccountState (QueryGetMorseAccountStateRequest) returns (QueryGetMorseAccountStateResponse) {
     option (google.api.http).get = "/pokt-network/poktroll/migration/morse_account_state";
 
@@ -37,8 +37,10 @@ message QueryParamsResponse {
   Params params = 1 [(gogoproto.nullable) = false, (amino.dont_omitempty) = true];
 }
 
+// Queries the MorseAccountState which was created with MsgCreateMorseAccountState.
 message QueryGetMorseAccountStateRequest {}
 
+// Returns the MorseAccountState. If it has not yet been created, an error is returned.
 message QueryGetMorseAccountStateResponse {
   MorseAccountState MorseAccountState = 1 [(gogoproto.nullable) = false];
 }

proto/poktroll/migration/tx.proto

@@ -39,15 +39,29 @@ message MsgUpdateParams {
 // MsgUpdateParams message.
 message MsgUpdateParamsResponse {}
 
+// MsgCreateMorseAccountState is used to create the on-chain MorseAccountState ONLY ONCE (per network / re-genesis).
 message MsgCreateMorseAccountState {
   option (cosmos.msg.v1.signer) = "authority";
 
   // authority is the address that controls the module (defaults to x/gov unless overwritten).
   string authority  = 1 [(cosmos_proto.scalar) = "cosmos.AddressString"];
+  // the account state derived from the Morse state export and the `poktrolld migrate collect-morse-accounts` command.
   MorseAccountState morse_account_state = 2 [(gogoproto.jsontag) = "morse_account_state", (gogoproto.nullable) = false];
+  // expected sha256 hash of the morse_account_state. If this hash does not match the on-chain
+  // computation, the transaction will fail. Social consensus regarding the correctness of
+  // morse_account_state should have be achieved off-chain and can be verified on-chain by
+  // comparing this hash with that of a locally derived Morse state export:
+  // E.g., `poktrolld migrate collect-morse-accounts $<(pocket util export-genesis-for-reset)`.
+  // See: `pocket util export-genesis-for-migration --help` & `poktrolld migrate collect-morse-accounts --help`
+  // for more details.
+  bytes morse_account_state_hash = 3 [(gogoproto.jsontag) = "morse_account_state_hash"];
 }
 
+// MsgCreateMorseAccountStateResponse represents an on-chain summary of the result of the corresponding MsgCreateMorseAccountState.
 message MsgCreateMorseAccountStateResponse {
+  // On-chain computed sha256 hash of the morse_account_state provided in the corresponding MsgCreateMorseAccountState.
   bytes state_hash = 1 [(gogoproto.jsontag) = "state_hash"];
+  // Number of accounts (EOAs) which were collected from the Morse state export, which may be claimed.
+  // NOTE: Application and supplier actor stakes are consolidated into their corresponding account balances.
   uint64 num_accounts = 2 [(gogoproto.jsontag) = "num_accounts"];
 }

x/migration/keeper/morse_account_state.go

@@ -9,26 +9,26 @@ import (
 	"github.com/pokt-network/poktroll/x/migration/types"
 )
 
-// SetMorseAccountState set morseAccountState in the store
+// SetMorseAccountState sets morseAccountState in the store
 func (k Keeper) SetMorseAccountState(ctx context.Context, morseAccountState types.MorseAccountState) {
 	storeAdapter := runtime.KVStoreAdapter(k.storeService.OpenKVStore(ctx))
 	store := prefix.NewStore(storeAdapter, types.KeyPrefix(types.MorseAccountStateKey))
-	b := k.cdc.MustMarshal(&morseAccountState)
-	store.Set([]byte{0}, b)
+	morseAccountStateBz := k.cdc.MustMarshal(&morseAccountState)
+	store.Set([]byte{0}, morseAccountStateBz)
 }
 
 // GetMorseAccountState returns morseAccountState
-func (k Keeper) GetMorseAccountState(ctx context.Context) (val types.MorseAccountState, found bool) {
+func (k Keeper) GetMorseAccountState(ctx context.Context) (morseAccountState types.MorseAccountState, found bool) {
 	storeAdapter := runtime.KVStoreAdapter(k.storeService.OpenKVStore(ctx))
 	store := prefix.NewStore(storeAdapter, types.KeyPrefix(types.MorseAccountStateKey))
 
-	b := store.Get([]byte{0})
-	if b == nil {
-		return val, false
+	morseAccountStateBz := store.Get([]byte{0})
+	if morseAccountStateBz == nil {
+		return morseAccountState, false
 	}
 
-	k.cdc.MustUnmarshal(b, &val)
-	return val, true
+	k.cdc.MustUnmarshal(morseAccountStateBz, &morseAccountState)
+	return morseAccountState, true
 }
 
 // RemoveMorseAccountState removes morseAccountState from the store

x/migration/keeper/msg_server_morse_account_state.go

@@ -10,6 +10,7 @@ import (
 	"github.com/pokt-network/poktroll/x/migration/types"
 )
 
+// CreateMorseAccountState creates the on-chain MorseAccountState ONLY ONCE (per network / re-genesis).
 func (k msgServer) CreateMorseAccountState(goCtx context.Context, msg *types.MsgCreateMorseAccountState) (*types.MsgCreateMorseAccountStateResponse, error) {
 	ctx := sdk.UnwrapSDKContext(goCtx)
 
@@ -19,6 +20,10 @@ func (k msgServer) CreateMorseAccountState(goCtx context.Context, msg *types.Msg
 		return nil, errorsmod.Wrap(sdkerrors.ErrInvalidRequest, "already set")
 	}
 
+	if err := msg.ValidateBasic(); err != nil {
+		return nil, err
+	}
+
 	k.SetMorseAccountState(
 		ctx,
 		msg.MorseAccountState,

x/migration/keeper/query_morse_account_state.go

@@ -10,16 +10,18 @@ import (
 	"github.com/pokt-network/poktroll/x/migration/types"
 )
 
+// MorseAccountState returns the morseAccountState, if one has been created;
+// otherwise, an error is returned.
 func (k Keeper) MorseAccountState(goCtx context.Context, req *types.QueryGetMorseAccountStateRequest) (*types.QueryGetMorseAccountStateResponse, error) {
 	if req == nil {
 		return nil, status.Error(codes.InvalidArgument, "invalid request")
 	}
 	ctx := sdk.UnwrapSDKContext(goCtx)
 
-	val, found := k.GetMorseAccountState(ctx)
-	if !found {
+	morseAccountState, isFound := k.GetMorseAccountState(ctx)
+	if !isFound {
 		return nil, status.Error(codes.NotFound, "not found")
 	}
 
-	return &types.QueryGetMorseAccountStateResponse{MorseAccountState: val}, nil
+	return &types.QueryGetMorseAccountStateResponse{MorseAccountState: morseAccountState}, nil
 }

x/migration/types/messages_morse_account_state.go

@@ -1,7 +1,9 @@
 package types
 
 import (
-	errorsmod "cosmossdk.io/errors"
+	"bytes"
+
+	"cosmossdk.io/store/types"
 	sdk "github.com/cosmos/cosmos-sdk/types"
 	sdkerrors "github.com/cosmos/cosmos-sdk/types/errors"
 )
@@ -16,9 +18,22 @@ func NewMsgCreateMorseAccountState(authority string, morseAccountState MorseAcco
 }
 
 func (msg *MsgCreateMorseAccountState) ValidateBasic() error {
-	_, err := sdk.AccAddressFromBech32(msg.Authority)
+	if _, err := sdk.AccAddressFromBech32(msg.Authority); err != nil {
+		return sdkerrors.ErrInvalidAddress.Wrapf("invalid authority address (%s)", err)
+	}
+
+	actualHash, err := msg.MorseAccountState.GetHash()
 	if err != nil {
-		return errorsmod.Wrapf(sdkerrors.ErrInvalidAddress, "invalid creator address (%s)", err)
+		return err
 	}
-	return nil
+
+	expectedHash := msg.GetMorseAccountStateHash()
+	if bytes.Equal(actualHash, expectedHash) {
+		return nil
+	}
+
+	return types.ErrInvalidRequest.Wrapf(
+		"Morse account state hash (%s) doesn't match expected: (%s)",
+		actualHash, expectedHash,
+	)
 }