Skip to main content
Version: Next

Query Lifecycle

Synopsis

This document describes the lifecycle of a query in a Cosmos SDK application, from the user interface to application stores and back. The query is referred to as MyQuery.

Pre-requisite Readings

Query Creation​

A query is a request for information made by end-users of applications through an interface and processed by a full-node. Users can query information about the network, the application itself, and application state directly from the application's stores or modules. Note that queries are different from transactions (view the lifecycle here), particularly in that they do not require consensus to be processed (as they do not trigger state-transitions); they can be fully handled by one full-node.

For the purpose of explaining the query lifecycle, let's say the query, MyQuery, is requesting a list of delegations made by a certain delegator address in the application called simapp. As is to be expected, the staking module handles this query. But first, there are a few ways MyQuery can be created by users.

CLI​

The main interface for an application is the command-line interface. Users connect to a full-node and run the CLI directly from their machines - the CLI interacts directly with the full-node. To create MyQuery from their terminal, users type the following command:

simd query staking delegations <delegatorAddress>

This query command was defined by the staking module developer and added to the list of subcommands by the application developer when creating the CLI.

Note that the general format is as follows:

simd query [moduleName] [command] <arguments> --flag <flagArg>

To provide values such as --node (the full-node the CLI connects to), the user can use the app.toml config file to set them or provide them as flags.

The CLI understands a specific set of commands, defined in a hierarchical structure by the application developer: from the root command (simd), the type of command (Myquery), the module that contains the command (staking), and command itself (delegations). Thus, the CLI knows exactly which module handles this command and directly passes the call there.

gRPC​

Another interface through which users can make queries is gRPC requests to a gRPC server. The endpoints are defined as Protocol Buffers service methods inside .proto files, written in Protobuf's own language-agnostic interface definition language (IDL). The Protobuf ecosystem developed tools for code-generation from *.proto files into various languages. These tools allow to build gRPC clients easily.

One such tool is grpcurl, and a gRPC request for MyQuery using this client looks like:

grpcurl \
    -plaintext                                           # We want results in plain text
    -import-path ./proto \                               # Import these .proto files
    -proto ./proto/cosmos/staking/v1beta1/query.proto \  # Look into this .proto file for the Query protobuf service
    -d '{"address":"$MY_DELEGATOR"}' \                   # Query arguments
    localhost:9090 \                                     # gRPC server endpoint
    cosmos.staking.v1beta1.Query/Delegations             # Fully-qualified service method name

REST​

Another interface through which users can make queries is through HTTP Requests to a REST server. The REST server is fully auto-generated from Protobuf services, using gRPC-gateway.

An example HTTP request for MyQuery looks like:

GET http://localhost:1317/cosmos/staking/v1beta1/delegators/{delegatorAddr}/delegations

How Queries are Handled by the CLI​

The preceding examples show how an external user can interact with a node by querying its state. To understand in more detail the exact lifecycle of a query, let's dig into how the CLI prepares the query, and how the node handles it. The interactions from the users' perspective are a bit different, but the underlying functions are almost identical because they are implementations of the same command defined by the module developer. This step of processing happens within the CLI, gRPC, or REST server, and heavily involves a client.Context.

Context​

The first thing that is created in the execution of a CLI command is a client.Context. A client.Context is an object that stores all the data needed to process a request on the user side. In particular, a client.Context stores the following:

  • Codec: The encoder/decoder used by the application, used to marshal the parameters and query before making the CometBFT RPC request and unmarshal the returned response into a JSON object. The default codec used by the CLI is Protobuf.
  • Account Decoder: The account decoder from the auth module, which translates []bytes into accounts.
  • RPC Client: The CometBFT RPC Client, or node, to which requests are relayed.
  • Keyring: A Key Manager used to sign transactions and handle other operations with keys.
  • Output Writer: A Writer used to output the response.
  • Configurations: The flags configured by the user for this command, including --height, specifying the height of the blockchain to query, and --indent, which indicates to add an indent to the JSON response.

The client.Context also contains various functions such as Query(), which retrieves the RPC Client and makes an ABCI call to relay a query to a full-node.

https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/client/context.go#L29-L86

The client.Context's primary role is to store data used during interactions with the end-user and provide methods to interact with this data - it is used before and after the query is processed by the full-node. Specifically, in handling MyQuery, the client.Context is utilized to encode the query parameters, retrieve the full-node, and write the output. Prior to being relayed to a full-node, the query needs to be encoded into a []byte form, as full-nodes are application-agnostic and do not understand specific types. The full-node (RPC Client) itself is retrieved using the client.Context, which knows which node the user CLI is connected to. The query is relayed to this full-node to be processed. Finally, the client.Context contains a Writer to write output when the response is returned. These steps are further described in later sections.

Arguments and Route Creation​

At this point in the lifecycle, the user has created a CLI command with all of the data they wish to include in their query. A client.Context exists to assist in the rest of the MyQuery's journey. Now, the next steps are to parse the command or request, extract the arguments, and encode everything. These steps all happen on the user side within the interface they are interacting with.

Encoding​

In our case (querying an address's delegations), MyQuery contains an address delegatorAddress as its only argument. However, the request can only contain []bytes, as it is ultimately relayed to a consensus engine (e.g. CometBFT) of a full-node that has no inherent knowledge of the application types. Thus, the codec of client.Context is used to marshal the address.

Here is what the code looks like for the CLI command:

https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/client/grpc_query.go#L64-L68

gRPC Query Client Creation​

The Cosmos SDK uses Protobuf-generated services for queries. The staking module's MyQuery service generates a queryClient used by the CLI.

With the introduction of AutoCLI, query client creation is now automated and integrated into the module's setup. This approach simplifies the process of exposing module queries through the CLI.

https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/x/staking/autocli.go#L73-L81

The client.Context still contains a Query() function to retrieve the pre-configured node and relay queries. It takes the fully-qualified service method name as a path (e.g. /cosmos.staking.v1beta1.Query/Delegations) and arguments as parameters. The function retrieves the RPC Client, creates ABCIQueryOptions, and makes the ABCI call using ABCIQueryWithOptions().

Here is what the code looks like:

https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/client/query.go#L64-L98

RPC​

With a call to ABCIQueryWithOptions(), MyQuery is received by a full-node which then processes the request. Note that, while the RPC is made to the consensus engine (e.g. CometBFT) of a full-node, queries are not part of consensus and so are not broadcasted to the rest of the network, as they do not require anything the network needs to agree upon.

Read more about ABCI Clients and CometBFT RPC in the CometBFT documentation.

Application Query Handling​

When a query is received by the full-node after it has been relayed from the underlying consensus engine, it is at that point being handled within an environment that understands application-specific types and has a copy of the state. baseapp implements the ABCI Query() function and handles gRPC queries. The query route is parsed, and it matches the fully-qualified service method name of an existing service method (most likely in one of the modules), then baseapp relays the request to the relevant module.

Since MyQuery has a Protobuf fully-qualified service method name from the staking module (recall /cosmos.staking.v1beta1.Query/Delegations), baseapp first parses the path, then uses its own internal GRPCQueryRouter to retrieve the corresponding gRPC handler, and routes the query to the module. The gRPC handler is responsible for recognizing this query, retrieving the appropriate values from the application's stores, and returning a response. Read more about query services here.

Once a result is received from the querier, baseapp begins the process of returning a response to the user.

Response​

Since Query() is an ABCI function, baseapp returns the response as an abci.QueryResponse type. The client.Context Query() routine receives the response.

CLI Response​

The application codec is used to unmarshal the response to a JSON and the client.Context prints the output to the command line, applying any configurations such as the output type (text, JSON or YAML).

https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/client/context.go#L391-L398

And that's a wrap! The result of the query is outputted to the console by the CLI.