thru-grpc-client

Use thru-grpc-client when you want direct Rust access to Thru’s generated protobuf messages and gRPC service clients.

Install

cargo add thru-grpc-client tonic
cargo add tokio --features macros,rt-multi-thread

Install the buf CLI before building this crate. thru-grpc-client generates bindings in build.rs, and local builds call buf build directly.

If cargo build fails with a missing buf error, install buf with the official instructions from buf.build.

When to use it

Choose this crate when you want to:

• Instantiate Thru protobuf messages directly in Rust.
• Call Query, Command, Debug, or Streaming services with tonic clients.
• Stay close to the wire format for custom middleware, testing, or low-level service integrations.
• Reuse the same generated service and message modules that higher-level Rust clients build on top of.

Choose another crate when

• You need keys, transaction builders, address parsing, or proof helpers: use thru-base.
• You want a more ergonomic Rust RPC client with helper methods like get_account_info, get_block_height, or execute_transaction: use a higher-level wrapper such as thru-client.

Entry points

The crate has one public root entrypoint: thru_grpc_client::thru.

Import path	What it provides
thru_grpc_client::thru::common::v1	Shared message types such as primitives, filters, pagination, and consensus-related definitions.
thru_grpc_client::thru::core::v1	Core chain types such as accounts, blocks, state, transactions, and related enums.
thru_grpc_client::thru::services::v1	Generated request and response types plus tonic clients including QueryServiceClient, CommandServiceClient, DebugServiceClient, and StreamingServiceClient.

Start here

Most direct integrations begin by creating a tonic transport channel, instantiating one of the generated service clients, and sending a generated request type.

use thru_grpc_client::thru::services::v1::{
    query_service_client::QueryServiceClient,
    GetVersionRequest,
};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let channel = tonic::transport::Channel::from_static("http://127.0.0.1:8472")
        .connect()
        .await?;

    let mut client = QueryServiceClient::new(channel);
    let response = client.get_version(GetVersionRequest {}).await?;

    println!("{:?}", response.into_inner().versions);
    Ok(())
}

Service groups

Service client	Useful for
QueryServiceClient	Read-side RPC calls such as account lookups, block and height queries, state roots, metrics, and version information.
CommandServiceClient	Write-side RPC calls such as transaction submission and proof-related command flows.
DebugServiceClient	Debug and re-execution workflows.
StreamingServiceClient	Subscription-style or continuous data flows over the Thru gRPC API.

Notes for agents

• This crate is intentionally low level. You will usually need to assemble tonic channels, metadata, timeouts, and request types yourself.
• The generated modules are namespaced under common::v1, core::v1, and services::v1, so start by locating the request type and service client in services::v1.
• In this repository, rpc/thru-client is the main example of how to layer ergonomic Rust APIs on top of thru-grpc-client.