[docs]: update building modules section to reflect ADR31

docs/basics/app-anatomy.md

@@ -158,7 +158,7 @@ Each module should also implement the `RegisterServices` method as part of the [
 
 #### Handlers
 
-The [handler](../building-modules/handler.md) refers to the part of the module responsible for processing the `Msg` after it is routed by `baseapp`. Handler functions of modules are only executed if the transaction is relayed from Tendermint by the `DeliverTx` ABCI message. If the transaction is relayed by `CheckTx`, only stateless checks and fee-related stateful checks are performed. To better understand the difference between `DeliverTx`and `CheckTx`, as well as the difference between stateful and stateless checks, click [here](./tx-lifecycle.md).
+The [handler](../building-modules/msg-services.md#handler-type) refers to the part of the module responsible for processing the `Msg` after it is routed by `baseapp`. Handler functions of modules are only executed if the transaction is relayed from Tendermint by the `DeliverTx` ABCI message. If the transaction is relayed by `CheckTx`, only stateless checks and fee-related stateful checks are performed. To better understand the difference between `DeliverTx`and `CheckTx`, as well as the difference between stateful and stateless checks, click [here](./tx-lifecycle.md).
 
 The `handler` of a module is generally defined in a file called `handler.go` and consists of:
 

docs/basics/gas-fees.md

@@ -44,7 +44,7 @@ By default, the Cosmos SDK makes use of two different gas meters, the [main gas
 
 `ctx.GasMeter()` is the main gas meter of the application. The main gas meter is initialized in `BeginBlock` via `setDeliverState`, and then tracks gas consumption during execution sequences that lead to state-transitions, i.e. those originally triggered by [`BeginBlock`](../core/baseapp.md#beginblock), [`DeliverTx`](../core/baseapp.md#delivertx) and [`EndBlock`](../core/baseapp.md#endblock). At the beginning of each `DeliverTx`, the main gas meter **must be set to 0** in the [`AnteHandler`](#antehandler), so that it can track gas consumption per-transaction. 
 
-Gas consumption can be done manually, generally by the module developer in the [`BeginBlocker`, `EndBlocker`](../building-modules/beginblock-endblock.md) or [`handler`](../building-modules/handler.md), but most of the time it is done automatically whenever there is a read or write to the store. This automatic gas consumption logic is implemented in a special store called [`GasKv`](../core/store.md#gaskv-store). 
+Gas consumption can be done manually, generally by the module developer in the [`BeginBlocker`, `EndBlocker`](../building-modules/beginblock-endblock.md) or [`Msg` service](../building-modules/msg-services.md), but most of the time it is done automatically whenever there is a read or write to the store. This automatic gas consumption logic is implemented in a special store called [`GasKv`](../core/store.md#gaskv-store). 
 
 ### Block Gas Meter
 

docs/basics/tx-lifecycle.md

@@ -179,7 +179,7 @@ explicitly ordered in the block proposal.
 
 ### DeliverTx
 
-The `DeliverTx` ABCI function defined in [`baseapp`](../core/baseapp.md) does the bulk of the
+The `DeliverTx` ABCI function defined in [`BaseApp`](../core/baseapp.md) does the bulk of the
 state transitions: it is run for each transaction in the block in sequential order as committed
 to during consensus. Under the hood, `DeliverTx` is almost identical to `CheckTx` but calls the
 [`runTx`](../core/baseapp.md#runtx) function in deliver mode instead of check mode.
@@ -194,15 +194,15 @@ Instead of using their `checkState`, full-nodes use `deliverState`:
   `AnteHandler` will not compare `gas-prices` to the node's `min-gas-prices` since that value is local
   to each node - differing values across nodes would yield nondeterministic results.
 
-- **Route and Handler:** While `CheckTx` would have exited, `DeliverTx` continues to run
+- **`MsgServiceRouter`:** While `CheckTx` would have exited, `DeliverTx` continues to run
   [`runMsgs`](../core/baseapp.md#runtx-and-runmsgs) to fully execute each `Msg` within the transaction.
-  Since the transaction may have messages from different modules, `baseapp` needs to know which module
-  to find the appropriate Handler. Thus, the `route` function is called via the [module manager](../building-modules/module-manager.md) to
-  retrieve the route name and find the [`Handler`](../building-modules/handler.md) within the module.
+  Since the transaction may have messages from different modules, `BaseApp` needs to know which module
+  to find the appropriate handler. This is achieved using `BaseApp`'s `MsgServiceRouter` so that it can be processed by the module's [`Msg` service](../building-modules/msg-services.md).
+	For legacy `Msg` routing, the `Route` function is called via the [module manager](../building-modules/module-manager.md) to retrieve the route name and find the legacy [`Handler`](../building-modules/msg-services.md#handler-type) within the module.
 
-- **Handler:** The `handler`, a step up from `AnteHandler`, is responsible for executing each
+- **`Msg` service:** The `Msg` service, a step up from `AnteHandler`, is responsible for executing each
   message in the `Tx` and causes state transitions to persist in `deliverTxState`. It is defined
-  within a `Msg`'s module and writes to the appropriate stores within the module.
+  within a module `Msg` protobuf service and writes to the appropriate stores within the module.
 
 - **Gas:** While a `Tx` is being delivered, a `GasMeter` is used to keep track of how much
   gas is being used; if execution completes, `GasUsed` is set and returned in the

docs/building-modules/README.md

@@ -11,7 +11,7 @@ This repository contains documentation on concepts developers need to know in or
 1. [Introduction to Cosmos SDK Modules](./intro.md)
 2. [`AppModule` Interface and Module Manager](./module-manager.md)
 3. [Messages and Queries](./messages-and-queries.md)
-4. [`Handler`s - Processing Messages](./handler.md)
+4. [`Msg` services - Processing Messages](./msg-services.md)
 5. [Query Services - Processing Queries](./query-services.md)
 6. [BeginBlocker and EndBlocker](./beginblock-endblock.md)
 7. [`Keeper`s](./keeper.md)

docs/building-modules/beginblock-endblock.md

@@ -16,7 +16,7 @@ order: 6
 
 When needed, `BeginBlocker` and `EndBlocker` are implemented as part of the [`AppModule` interface](./module-manager.md#appmodule). The `BeginBlock` and `EndBlock` methods of the interface implemented in `module.go` generally defer to `BeginBlocker` and `EndBlocker` methods respectively, which are usually implemented in a **`abci.go`** file. 
 
-The actual implementation of `BeginBlocker` and `EndBlocker` in `./abci.go` are very similar to that of a [`handler`](./handler.md):
+The actual implementation of `BeginBlocker` and `EndBlocker` in `./abci.go` are very similar to that of a [`Msg` service](./msg-services.md):
 
 - They generally use the [`keeper`](./keeper.md) and [`ctx`](../core/context.md) to retrieve information about the latest state. 
 - If needed, they use the `keeper` and `ctx` to trigger state-transitions. 

docs/building-modules/intro.md

@@ -17,7 +17,7 @@ The Cosmos SDK can be thought as the Ruby-on-Rails of blockchain development. It
 
 On top of this core, the Cosmos SDK enables developers to build modules that implement the business logic of their application. In other words, SDK modules implement the bulk of the logic of applications, while the core does the wiring and enables modules to be composed together. The end goal is to build a robust ecosystem of open-source SDK modules, making it increasingly easier to build complex blockchain applications. 
 
-SDK Modules can be seen as little state-machines within the state-machine. They generally define a subset of the state using one ore multiple `KVStore` in the [main multistore](../core/store.md), as well as a subset of [`message` types](./messages-and-queries.md#messages). These `message`s are routed by one of the main component of SDK core, [`baseapp`](../core/baseapp.md), to the [`handler`](./handler.md) of the module that define them. 
+SDK Modules can be seen as little state-machines within the state-machine. They generally define a subset of the state using one or more `KVStore`s in the [main multistore](../core/store.md), as well as a subset of [message types](./messages-and-queries.md#messages). These messages are routed by one of the main component of SDK core, [`BaseApp`](../core/baseapp.md), to the [`Msg` service](./msg-services.md) of the module that define them. 
 
 ```
                                       +
@@ -76,12 +76,11 @@ While there is no definitive guidelines for writing modules, here are some impor
 
 ## Main Components of SDK Modules
 
-Modules are by convention defined in the `.x/` subfolder (e.g. the `bank` module will be defined in the `./x/bank` folder). They generally share the same core components:
+Modules are by convention defined in the `./x/` subfolder (e.g. the `bank` module will be defined in the `./x/bank` folder). They generally share the same core components:
 
-- Custom [`message` types](./messages-and-queries.md#messages) to trigger state-transitions. 
-- A [`handler`](./handler.md) used to process messages when they are routed to the module by [`baseapp`](../core/baseapp.md#message-routing). 
-- A  [`keeper`](./keeper.md), used to access the module's store(s) and update the state. 
-- A [query service](./query-services.md), used to process user queries when they are routed to the module by [`baseapp`](../core/baseapp.md#query-routing).
+- A  [`keeper`](./keeper.md), used to access the module's store(s) and update the state.
+- A [`Msg` service](./messages-and-queries.md#messages) used to process messages when they are routed to the module by [`BaseApp`](../core/baseapp.md#message-routing) and trigger state-transitions.
+- A [query service](./query-services.md), used to process user queries when they are routed to the module by [`BaseApp`](../core/baseapp.md#query-routing).
 - Interfaces, for end users to query the subset of the state defined by the module and create `message`s of the custom types defined in the module.
 
 In addition to these components, modules implement the `AppModule` interface in order to be managed by the [`module manager`](./module-manager.md). 

docs/building-modules/keeper.md

@@ -46,7 +46,7 @@ Of course, it is possible to define different types of internal `keeper`s for th
 
 ## Implementing Methods 
 
-`Keeper`s primarily expose getter and setter methods for the store(s) managed by their module. These methods should remain as simple as possible and strictly be limited to getting or setting the requested value, as validity checks should have already been performed via the `ValidateBasic()` method of the [`message`](./messages-and-queries.md#messages) and the [`handler`](./handler.md) when `keeper`s' methods are called. 
+`Keeper`s primarily expose getter and setter methods for the store(s) managed by their module. These methods should remain as simple as possible and strictly be limited to getting or setting the requested value, as validity checks should have already been performed via the `ValidateBasic()` method of the [`message`](./messages-and-queries.md#messages) and the [`Msg` server](./msg-services.md) when `keeper`s' methods are called. 
 
 Typically, a *getter* method will present with the following signature