Query Services
A Protobuf Query service processes queries
. Query services are specific to the module in which they are defined, and only process queries
defined within said module. They are called from BaseApp
's Query
method.
Pre-requisite Readings
Implementation of a module query service
gRPC Service
When defining a Protobuf Query
service, a QueryServer
interface is generated for each module with all the service methods:
type QueryServer interface {
QueryBalance(context.Context, *QueryBalanceParams) (*types.Coin, error)
QueryAllBalances(context.Context, *QueryAllBalancesParams) (*QueryAllBalancesResponse, error)
}
These custom queries methods should be implemented by a module's keeper, typically in ./keeper/grpc_query.go
. The first parameter of these methods is a generic context.Context
. Therefore, the Cosmos SDK provides a function sdk.UnwrapSDKContext
to retrieve the sdk.Context
from the provided
context.Context
.
Here's an example implementation for the bank module:
package keeper
import (
"context"
"cosmossdk.io/math"
gogotypes "github.com/cosmos/gogoproto/types"
"google.golang.org/grpc/codes"
"google.golang.org/grpc/status"
"github.com/cosmos/cosmos-sdk/store/prefix"
sdk "github.com/cosmos/cosmos-sdk/types"
"github.com/cosmos/cosmos-sdk/types/query"
"github.com/cosmos/cosmos-sdk/x/bank/types"
)
var _ types.QueryServer = BaseKeeper{}
// Balance implements the Query/Balance gRPC method
func (k BaseKeeper) Balance(ctx context.Context, req *types.QueryBalanceRequest) (*types.QueryBalanceResponse, error) {
if req == nil {
return nil, status.Error(codes.InvalidArgument, "empty request")
}
if err := sdk.ValidateDenom(req.Denom); err != nil {
return nil, status.Error(codes.InvalidArgument, err.Error())
}
sdkCtx := sdk.UnwrapSDKContext(ctx)
address, err := sdk.AccAddressFromBech32(req.Address)
if err != nil {
return nil, status.Errorf(codes.InvalidArgument, "invalid address: %s", err.Error())
}
balance := k.GetBalance(sdkCtx, address, req.Denom)
return &types.QueryBalanceResponse{Balance: &balance}, nil
}
// AllBalances implements the Query/AllBalances gRPC method
func (k BaseKeeper) AllBalances(ctx context.Context, req *types.QueryAllBalancesRequest) (*types.QueryAllBalancesResponse, error) {
if req == nil {
return nil, status.Error(codes.InvalidArgument, "empty request")
}
addr, err := sdk.AccAddressFromBech32(req.Address)
if err != nil {
return nil, status.Errorf(codes.InvalidArgument, "invalid address: %s", err.Error())
}
sdkCtx := sdk.UnwrapSDKContext(ctx)
balances := sdk.NewCoins()
accountStore := k.getAccountStore(sdkCtx, addr)
pageRes, err := query.Paginate(accountStore, req.Pagination, func(key, value []byte) error {
denom := string(key)
balance, err := UnmarshalBalanceCompat(k.cdc, value, denom)
if err != nil {
return err
}
balances = append(balances, balance)
return nil
})
if err != nil {
return nil, status.Errorf(codes.InvalidArgument, "paginate: %v", err)
}
return &types.QueryAllBalancesResponse{Balances: balances, Pagination: pageRes}, nil
}
// SpendableBalances implements a gRPC query handler for retrieving an account's
// spendable balances.
func (k BaseKeeper) SpendableBalances(ctx context.Context, req *types.QuerySpendableBalancesRequest) (*types.QuerySpendableBalancesResponse, error) {
if req == nil {
return nil, status.Error(codes.InvalidArgument, "empty request")
}
addr, err := sdk.AccAddressFromBech32(req.Address)
if err != nil {
return nil, status.Errorf(codes.InvalidArgument, "invalid address: %s", err.Error())
}
sdkCtx := sdk.UnwrapSDKContext(ctx)
balances := sdk.NewCoins()
accountStore := k.getAccountStore(sdkCtx, addr)
zeroAmt := math.ZeroInt()
pageRes, err := query.Paginate(accountStore, req.Pagination, func(key, _ []byte) error {
balances = append(balances, sdk.NewCoin(string(key), zeroAmt))
return nil
})
if err != nil {
return nil, status.Errorf(codes.InvalidArgument, "paginate: %v", err)
}
result := sdk.NewCoins()
spendable := k.SpendableCoins(sdkCtx, addr)
for _, c := range balances {
result = append(result, sdk.NewCoin(c.Denom, spendable.AmountOf(c.Denom)))
}
return &types.QuerySpendableBalancesResponse{Balances: result, Pagination: pageRes}, nil
}
// SpendableBalanceByDenom implements a gRPC query handler for retrieving an account's
// spendable balance for a specific denom.
func (k BaseKeeper) SpendableBalanceByDenom(ctx context.Context, req *types.QuerySpendableBalanceByDenomRequest) (*types.QuerySpendableBalanceByDenomResponse, error) {
if req == nil {
return nil, status.Error(codes.InvalidArgument, "empty request")
}
addr, err := sdk.AccAddressFromBech32(req.Address)
if err != nil {
return nil, status.Errorf(codes.InvalidArgument, "invalid address: %s", err.Error())
}
if err := sdk.ValidateDenom(req.Denom); err != nil {
return nil, status.Error(codes.InvalidArgument, err.Error())
}
sdkCtx := sdk.UnwrapSDKContext(ctx)
spendable := k.SpendableCoin(sdkCtx, addr, req.Denom)
return &types.QuerySpendableBalanceByDenomResponse{Balance: &spendable}, nil
}
// TotalSupply implements the Query/TotalSupply gRPC method
func (k BaseKeeper) TotalSupply(ctx context.Context, req *types.QueryTotalSupplyRequest) (*types.QueryTotalSupplyResponse, error) {
sdkCtx := sdk.UnwrapSDKContext(ctx)
totalSupply, pageRes, err := k.GetPaginatedTotalSupply(sdkCtx, req.Pagination)
if err != nil {
return nil, status.Error(codes.Internal, err.Error())
}
return &types.QueryTotalSupplyResponse{Supply: totalSupply, Pagination: pageRes}, nil
}
// SupplyOf implements the Query/SupplyOf gRPC method
func (k BaseKeeper) SupplyOf(c context.Context, req *types.QuerySupplyOfRequest) (*types.QuerySupplyOfResponse, error) {
if req == nil {
return nil, status.Error(codes.InvalidArgument, "empty request")
}
if err := sdk.ValidateDenom(req.Denom); err != nil {
return nil, status.Error(codes.InvalidArgument, err.Error())
}
ctx := sdk.UnwrapSDKContext(c)
supply := k.GetSupply(ctx, req.Denom)
return &types.QuerySupplyOfResponse{Amount: sdk.NewCoin(req.Denom, supply.Amount)}, nil
}
// Params implements the gRPC service handler for querying x/bank parameters.
func (k BaseKeeper) Params(ctx context.Context, req *types.QueryParamsRequest) (*types.QueryParamsResponse, error) {
if req == nil {
return nil, status.Errorf(codes.InvalidArgument, "empty request")
}
sdkCtx := sdk.UnwrapSDKContext(ctx)
params := k.GetParams(sdkCtx)
return &types.QueryParamsResponse{Params: params}, nil
}
// DenomsMetadata implements Query/DenomsMetadata gRPC method.
func (k BaseKeeper) DenomsMetadata(c context.Context, req *types.QueryDenomsMetadataRequest) (*types.QueryDenomsMetadataResponse, error) {
if req == nil {
return nil, status.Errorf(codes.InvalidArgument, "empty request")
}
ctx := sdk.UnwrapSDKContext(c)
store := prefix.NewStore(ctx.KVStore(k.storeKey), types.DenomMetadataPrefix)
metadatas := []types.Metadata{}
pageRes, err := query.Paginate(store, req.Pagination, func(_, value []byte) error {
var metadata types.Metadata
k.cdc.MustUnmarshal(value, &metadata)
metadatas = append(metadatas, metadata)
return nil
})
if err != nil {
return nil, status.Error(codes.Internal, err.Error())
}
return &types.QueryDenomsMetadataResponse{
Metadatas: metadatas,
Pagination: pageRes,
}, nil
}
// DenomMetadata implements Query/DenomMetadata gRPC method.
func (k BaseKeeper) DenomMetadata(c context.Context, req *types.QueryDenomMetadataRequest) (*types.QueryDenomMetadataResponse, error) {
if req == nil {
return nil, status.Errorf(codes.InvalidArgument, "empty request")
}
if err := sdk.ValidateDenom(req.Denom); err != nil {
return nil, status.Error(codes.InvalidArgument, err.Error())
}
ctx := sdk.UnwrapSDKContext(c)
metadata, found := k.GetDenomMetaData(ctx, req.Denom)
if !found {
return nil, status.Errorf(codes.NotFound, "client metadata for denom %s", req.Denom)
}
return &types.QueryDenomMetadataResponse{
Metadata: metadata,
}, nil
}
func (k BaseKeeper) DenomOwners(
goCtx context.Context,
req *types.QueryDenomOwnersRequest,
) (*types.QueryDenomOwnersResponse, error) {
if req == nil {
return nil, status.Errorf(codes.InvalidArgument, "empty request")
}
if err := sdk.ValidateDenom(req.Denom); err != nil {
return nil, status.Error(codes.InvalidArgument, err.Error())
}
ctx := sdk.UnwrapSDKContext(goCtx)
denomPrefixStore := k.getDenomAddressPrefixStore(ctx, req.Denom)
var denomOwners []*types.DenomOwner
pageRes, err := query.FilteredPaginate(
denomPrefixStore,
req.Pagination,
func(key []byte, _ []byte, accumulate bool) (bool, error) {
if accumulate {
address, _, err := types.AddressAndDenomFromBalancesStore(key)
if err != nil {
return false, err
}
denomOwners = append(
denomOwners,
&types.DenomOwner{
Address: address.String(),
Balance: k.GetBalance(ctx, address, req.Denom),
},
)
}
return true, nil
},
)
if err != nil {
return nil, status.Error(codes.Internal, err.Error())
}
return &types.QueryDenomOwnersResponse{DenomOwners: denomOwners, Pagination: pageRes}, nil
}
func (k BaseKeeper) SendEnabled(goCtx context.Context, req *types.QuerySendEnabledRequest) (*types.QuerySendEnabledResponse, error) {
if req == nil {
return nil, status.Errorf(codes.InvalidArgument, "empty request")
}
ctx := sdk.UnwrapSDKContext(goCtx)
resp := &types.QuerySendEnabledResponse{}
if len(req.Denoms) > 0 {
store := ctx.KVStore(k.storeKey)
for _, denom := range req.Denoms {
if se, ok := k.getSendEnabled(store, denom); ok {
resp.SendEnabled = append(resp.SendEnabled, types.NewSendEnabled(denom, se))
}
}
} else {
store := k.getSendEnabledPrefixStore(ctx)
var err error
resp.Pagination, err = query.FilteredPaginate(
store,
req.Pagination,
func(key []byte, value []byte, accumulate bool) (bool, error) {
if accumulate {
var enabled gogotypes.BoolValue
k.cdc.MustUnmarshal(value, &enabled)
resp.SendEnabled = append(resp.SendEnabled, types.NewSendEnabled(string(key), enabled.Value))
}
return true, nil
},
)
if err != nil {
return nil, status.Error(codes.Internal, err.Error())
}
}
return resp, nil
}
Calling queries from the State Machine
The Cosmos SDK v0.47 introduces a new cosmos.query.v1.module_query_safe
Protobuf annotation which is used to state that a query that is safe to be called from within the state machine, for example:
- a Keeper's query function can be called from another module's Keeper,
- ADR-033 intermodule query calls,
- CosmWasm contracts can also directly interact with these queries.
If the module_query_safe
annotation set to true
, it means:
- The query is deterministic: given a block height it will return the same response upon multiple calls, and doesn't introduce any state-machine breaking changes across SDK patch versions.
- Gas consumption never fluctuates across calls and across patch versions.
If you are a module developer and want to use module_query_safe
annotation for your own query, you have to ensure the following things:
- the query is deterministic and won't introduce state-machine-breaking changes without coordinated upgrades
- it has its gas tracked, to avoid the attack vector where no gas is accounted for on potentially high-computation queries.