# Messages and Queries
# Pre-requisite Readings
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
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.
messages is the responsibility of module developers. Typically, they are defined in a
./internal/types/msgs.go file inside the module's folder. The
message's type 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
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 [
It contains the following methods:
Route() string: Name of the route for this message. Typically all
messages 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-specific
string, typically the denomination of the message itself.
ValidateBasic() Error: This method is called by
baseappvery early in the processing of the
DeliverTx), 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 the
amountis 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 each
messagecontained 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
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
queryrouter so that it can be processed by the module's
querier. For a deeper look at the lifecycle of a
query, click here.
messages, there is usually no specific
query object defined by module developers. Instead, the SDK takes the simpler approach of using a simple
path to define each
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:
queryCategoryis the category of the
customfor module queries. It is used to differentiate between different kinds of queries within
queryRouteis used by
queryRouterto map the
queryto its module. Usually,
queryRouteshould be the name of the module.
queryTypeis used by the module's
querierto map the
queryto the appropriate
querier functionwithin the module.
argsare the actual arguments needed to process the
query. They are filled out by the end-user. Note that for bigger queries, you might prefer passing arguments in the
Datafield of the request
reqinstead of 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:
querier, to process the
queryonce it has been routed to the module.
- Query commands in the module's CLI file, where the
queryreturn types. Typically defined in a file
internal/types/querier.go, they specify the result type of each of the module's
queries. These custom types must implement the
fmt.Stringer(opens new window).
See an example of
query return types from the