gRPCurl

Interacting with grpcurl

grpcurl is like curl but for gRPC. It is also available as a Go library, but we will use it only as a CLI command for debugging and testing purposes. Follow the instructions in the previous link to install it.

Assuming you already installed terpd with the installer, you should be able to run the following command to list the Protobuf services available (you can replace grpc-terp.zenchainlabs.io:9000 by the gRPC server endpoint of another node such as the testnet, another provider or your own node.

Listing all the methods from the mainnet

grpcurl -plaintext grpc-terp.zenchainlabs.io:9090 list

Output will look like:

cosmos.auth.v1beta1.Query
cosmos.authz.v1beta1.Query
cosmos.bank.v1beta1.Query
cosmos.base.reflection.v1beta1.ReflectionService
cosmos.base.reflection.v2alpha1.ReflectionService
cosmos.base.tendermint.v1beta1.Service
cosmos.distribution.v1beta1.Query
cosmos.evidence.v1beta1.Query
cosmos.gov.v1beta1.Query
cosmos.params.v1beta1.Query
cosmos.slashing.v1beta1.Query
cosmos.staking.v1beta1.Query
cosmos.tx.v1beta1.Service
cosmos.upgrade.v1beta1.Query
cosmwasm.wasm.v1.Query
grpc.reflection.v1alpha.ServerReflection
ibc.applications.interchain_accounts.host.v1.Query
ibc.applications.transfer.v1.Query
ibc.core.channel.v1.Query
ibc.core.client.v1.Query
ibc.core.connection.v1.Query
testdata.Query

You should see a list of gRPC services, like cosmos.bank.v1beta1.Query. This is called reflection, which is a Protobuf endpoint returning a description of all available endpoints. Each of these represents a different Protobuf service, and each service exposes multiple RPC methods you can query against.

In order to get a description of the service you can run the following command:

grpcurl  -plaintext \
    grpc-terp.zenchainlabs.io:9090 \
    describe cosmos.staking.v1beta1.Query           

It's also possible to execute an RPC call to query the node for information:

grpcurl -plaintext grpc-terp.zenchainlabs.io:443 cosmos.staking.v1beta1.Query

The list of all available gRPC query endpoints and API exploration is possible with the help of buf studio.

Query for historical state using grpcurl

You may also query for historical data by passing some gRPC metadata to the query: the x-cosmos-block-height metadata should contain the block to query. Using grpcurl as above, the command looks like:

grpcurl \
    -plaintext \
    -H "x-cosmos-block-height: 6312618" \
    -d '{"address":"terp19a7pmytd9vk26l57q8chacuprsmx05g23mg6yc"}' \
    grpc-terp.zenchainlabs.io:9090 \
    cosmos.bank.v1beta1.Query/AllBalances

Note: This endpoint might change to grpc-terp.zenchainlabs.io:443 in the near future.

Assuming the state at that block has not yet been pruned by the node, this query should return a non-empty response.