github.com/fibonacci-chain/fbc@v0.0.0-20231124064014-c7636198c1e9/libs/cosmos-sdk/docs/building-modules/handler.md (about)

     1  <!--
     2  order: 4
     3  synopsis: "A `Handler` designates a function that processes [`message`s](./messages-and-queries.md#messages). `Handler`s are specific to the module in which they are defined, and only process `message`s defined within the said module. They are called from `baseapp` during [`DeliverTx`](../core/baseapp.md#delivertx)."
     4  -->
     5  
     6  # Handlers
     7  
     8  ## Pre-requisite Readings {hide}
     9  
    10  - [Module Manager](./module-manager.md) {prereq}
    11  - [Messages and Queries](./messages-and-queries.md) {prereq}
    12  
    13  ## `handler` type
    14  
    15  The `handler` type defined in the Cosmos SDK specifies the typical structure of a `handler` function.
    16  
    17  +++ https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/types/handler.go#L4
    18  
    19  Let us break it down:
    20  
    21  - The [`Msg`](./messages-and-queries.md#messages) is the actual object being processed. 
    22  - The [`Context`](../core/context.md) contains all the necessary information needed to process the `msg`, as well as a cache-wrapped copy of the latest state. If the `msg` is succesfully processed, the modified version of the temporary state contained in the `ctx` will be written to the main state.
    23  - The [`Result`] returned to `baseapp`, which contains (among other things) information on the execution of the `handler`, [`gas`](../basics/gas-fees.md) consumption and [`events`](../core/events.md).
    24  	+++ https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/types/result.go#L15-L40
    25  
    26  ## Implementation of a module `handler`s
    27  
    28  Module `handler`s are typically implemented in a `./handler.go` file inside the module's folder. The
    29  [module manager](./module-manager.md) is used to add the module's `handler`s to the
    30  [application's `router`](../core/baseapp.md#message-routing) via the `NewHandler()` method. Typically,
    31  the manager's `NewHandler()` method simply calls a `NewHandler()` method defined in `handler.go`,
    32  which looks like the following:
    33  
    34  ```go
    35  func NewHandler(keeper Keeper) sdk.Handler {
    36  	return func(ctx sdk.Context, msg sdk.Msg) (*sdk.Result, error) {
    37  		switch msg := msg.(type) {
    38  		case MsgType1:
    39  			return handleMsgType1(ctx, keeper, msg)
    40  
    41  		case MsgType2:
    42  			return handleMsgType2(ctx, keeper, msg)
    43  
    44  		default:
    45  			return nil, sdkerrors.Wrapf(sdkerrors.ErrUnknownRequest, "unrecognized %s message type: %T", ModuleName, msg)
    46  		}
    47  	}
    48  }
    49  ```
    50  
    51  This simple switch returns a `handler` function specific to the type of the received `message`. These `handler` functions are the ones that actually process `message`s, and usually follow the following 2 steps:
    52  
    53  - First, they perform *stateful* checks to make sure the `message` is valid. At this stage, the `message`'s `ValidateBasic()` method has already been called, meaning *stateless* checks on the message (like making sure parameters are correctly formatted) have already been performed. Checks performed in the `handler` can be more expensive and require access to the state. For example, a `handler` for a `transfer` message might check that the sending account has enough funds to actually perform the transfer. To access the state, the `handler` needs to call the [`keeper`'s](./keeper.md) getter functions. 
    54  - Then, if the checks are successfull, the `handler` calls the [`keeper`'s](./keeper.md) setter functions to actually perform the state transition. 
    55  
    56  Before returning, `handler` functions generally emit one or multiple [`events`](../core/events.md) via the `EventManager` held in the `ctx`:
    57  
    58  ```go
    59  ctx.EventManager().EmitEvent(
    60  		sdk.NewEvent(
    61  			eventType,  // e.g. sdk.EventTypeMessage for a message, types.CustomEventType for a custom event defined in the module
    62  			sdk.NewAttribute(attributeKey, attributeValue),
    63  		),
    64      )
    65  ```
    66  
    67  These `events` are relayed back to the underlying consensus engine and can be used by service providers to implement services around the application. Click [here](../core/events.md) to learn more about `events`. 
    68  
    69  Finally, the `handler` function returns a `sdk.Result` which contains the aforementioned `events` and an optional `Data` field. 
    70  
    71  +++ https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/types/result.go#L15-L40
    72  
    73  Next is an example of how to return a `Result` from the `gov` module:
    74  
    75  +++ https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/x/gov/handler.go#L59-L62
    76  
    77  For a deeper look at `handler`s, see this [example implementation of a `handler` function](https://github.com/cosmos/sdk-application-tutorial/blob/c6754a1e313eb1ed973c5c91dcc606f2fd288811/x/nameservice/handler.go) from the nameservice tutorial. 
    78  
    79  ## Next {hide}
    80  
    81  Learn about [queriers](./querier.md) {hide}