Messages and Queries are the two primary objects handled by modules. Most of the core components defined in a module, like handlers, keepers and queriers, exist to process messages and queries. {synopsis}
- Introduction to SDK Modules {prereq}
Messages are objects whose end-goal is to trigger state-transitions. They are wrapped in transactions, which may contain one or multiple of them.
When a transaction is relayed from the underlying consensus engine to the SDK application, it is first decoded by baseapp. Then, each message contained in the transaction is extracted and routed to the appropriate module via baseapp's router so that it can be processed by the module's handler. For a more detailed explanation of the lifecycle of a transaction, click here.
Defining messages is the responsibility of module developers. Typically, they are defined as protobuf messages in a proto/ directory (see more info about conventions and naming). The message's definition usually includes a list of parameters needed to process the message that will be provided by end-users when they want to create a new transaction containing said message.
Here's an example of a protobuf message definition:
The Msg is typically accompanied by a standard constructor function, that is called from one of the module's interface. messages also need to implement the [Msg] interface:
It extends proto.Message and contains the following methods:
Route() string: Name of the route for this message. Typically allmessages in a module have the same route, which is most often the module's name.Type() string: Type of the message, used primarly in events. This should return a message-specificstring, typically the denomination of the message itself.ValidateBasic() error: This method is called bybaseappvery early in the processing of themessage(in bothCheckTxandDeliverTx), in order to discard obviously invalid messages.ValidateBasicshould only include stateless checks, i.e. checks that do not require access to the state. This usually consists in checking that the message's parameters are correctly formatted and valid (i.e. that theamountis strictly positive for a transfer).GetSignBytes() []byte: Return the canonical byte representation of the message. Used to generate a signature.GetSigners() []AccAddress: Return the list of signers. The SDK will make sure that eachmessagecontained in a transaction is signed by all the signers listed in the list returned by this method.
See an example implementation of a message from the gov module:
+++ https://github.com/cosmos/cosmos-sdk/blob/master/x/gov/types/msgs.go#L94-L136
A query is a request for information made by end-users of applications through an interface and processed by a full-node. A query is received by a full-node through its consensus engine and relayed to the application via the ABCI. It is then routed to the appropriate module via baseapp's queryrouter so that it can be processed by the module's query service (./query-services.md). For a deeper look at the lifecycle of a query, click here.
Starting from v0.40, the prefered way to define queries is by using Protobuf services. A Query service should be created per module in query.proto. This service lists endpoints starting with rpc.
Here's an example of such a Query service definition:
As proto.Messages, generated Response types implement by default String() method of fmt.Stringer.
A RegisterQueryServer method is also generated and should be used to register the module's query server in RegisterQueryService method from the AppModule interface.
Before the introduction of Protobuf and gRPC in the SDK, there was usually no specific query object defined by module developers, contrary to messages. Instead, the SDK took the simpler approach of using a simple path to define each query. The path contains the query type and all the arguments needed in order to process it. For most module queries, the path should look like the following:
queryCategory/queryRoute/queryType/arg1/arg2/...
where:
queryCategoryis the category of thequery, typicallycustomfor module queries. It is used to differentiate between different kinds of queries withinbaseapp'sQuerymethod.queryRouteis used bybaseapp'squeryRouterto map thequeryto its module. Usually,queryRouteshould be the name of the module.queryTypeis used by the module'squerierto map thequeryto the appropriatequerier functionwithin the module.argsare the actual arguments needed to process thequery. They are filled out by the end-user. Note that for bigger queries, you might prefer passing arguments in theDatafield of the requestreqinstead of thepath.
The path for each query must be defined by the module developer in the module's command-line interface file.Overall, there are 3 mains components module developers need to implement in order to make the subset of the state defined by their module queryable:
- A
querier, to process thequeryonce it has been routed to the module. - Query commands in the module's CLI file, where the
pathfor eachqueryis specified. queryreturn types. Typically defined in a filetypes/querier.go, they specify the result type of each of the module'squeries. These custom types must implement theString()method offmt.Stringer.
Store queries query directly for store keys. They use clientCtx.QueryABCI(req abci.RequestQuery) to return the full abci.ResponseQuery with inclusion Merkle proofs.
See following examples:
Learn about handlers {hide}