Crate sui_graphql

Expand description

GraphQL client for the Sui blockchain.

This crate provides a typed GraphQL client for Sui’s GraphQL API with automatic BCS deserialization and pagination support.

§Quick Start

use sui_graphql::Client;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new(Client::MAINNET)?;

    // Chain info
    let chain_id = client.chain_identifier().await?;
    println!("Chain: {chain_id}");

    // Fetch objects, transactions, checkpoints
    let obj = client.get_object("0x5".parse()?).await?;
    let tx = client.get_transaction("digest...").await?;
    let cp = client.get_checkpoint(None).await?; // latest

    Ok(())
}

§Streaming

List methods return async streams with automatic pagination:

use futures::StreamExt;
use std::pin::pin;
use sui_graphql::Client;
use sui_sdk_types::Address;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new(Client::MAINNET)?;
    let owner: Address = "0x123...".parse()?;

    let mut stream = pin!(client.list_objects(owner));
    while let Some(obj) = stream.next().await {
        let obj = obj?;
        println!("Object version: {}", obj.version());
    }
    Ok(())
}

§Custom Queries

For queries beyond the built-in methods, use Client::query with a response type that implements serde::de::DeserializeOwned. The sui-graphql-macros crate provides #[derive(Response)] which generates the deserialization code from declarative field paths, with compile-time validation against the Sui GraphQL schema.

use sui_graphql::Client;
use sui_graphql_macros::Response;

// Define a response type with field paths into the GraphQL response JSON.
// Paths are validated against the schema at compile time — typos like
// "epoch.epochIdd" will produce a compile error with a "Did you mean?" suggestion.
#[derive(Response)]
struct MyResponse {
    #[field(path = "epoch.epochId")]
    epoch_id: u64,
    // Use `[]` to extract items from a list field
    #[field(path = "epoch.checkpoints.nodes[].digest")]
    checkpoint_digests: Vec<String>,
    // Use `?` to mark nullable fields — null returns Ok(None) instead of an error.
    // Without `?`, a null value at that segment is a runtime error.
    #[field(path = "epoch.referenceGasPrice?")]
    gas_price: Option<u64>,
}

#[tokio::main]
async fn main() -> Result<(), sui_graphql::Error> {
    let client = Client::new(Client::MAINNET)?;

    let query = r#"
        query($epoch_id: UInt53) {
            epoch(id: $epoch_id) {
                epochId
                checkpoints { nodes { digest } }
                referenceGasPrice
            }
        }
    "#;
    let variables = serde_json::json!({ "epoch_id": 100 });

    let response = client.query::<MyResponse>(query, variables).await?;

    // GraphQL supports partial success — data and errors can coexist
    for err in response.errors() {
        eprintln!("GraphQL error: {}", err.message());
    }
    if let Some(data) = response.data() {
        println!("Epoch: {}", data.epoch_id);
        println!("Checkpoints: {:?}", data.checkpoint_digests);
        println!("Gas price: {:?}", data.gas_price);
    }
    Ok(())
}

For the full path syntax reference (?, [], aliases, enums), see the sui-graphql-macros documentation.

See Client for the full list of available methods.

Modules§

scalars: GraphQL scalar types for Sui.

Structs§

Balance: Balance information for a coin type.
Bcs: A wrapper for BCS-encoded values.
BcsBytes: Raw BCS bytes that can be deserialized into any type.
CheckpointResponse: A checkpoint response containing the summary and contents.
Client: GraphQL client for Sui blockchain.
DynamicField: A dynamic field entry with its name and value.
DynamicFieldRequest: Builder for fetching a single dynamic field by name.
DynamicFieldsRequest: Builder for listing dynamic fields on an object.
Epoch: Information about an epoch.
ExecutionResult: The result of executing a transaction on chain.
GraphQLError: A single GraphQL error.
Location: Location in the GraphQL query where an error occurred.
MoveObject: A Move object with its address and contents.
MoveValue: A Move value with type information and optional JSON/BCS representations.
Page: A page of results from a paginated GraphQL query.
PageInfo: GraphQL PageInfo from Connection responses.
Response: A GraphQL response containing data and/or errors.
TransactionResponse: A transaction response containing the transaction data and its effects.

Enums§

DynamicFieldValue: The value of a dynamic field, dispatched by __typename.
Error: Error type for GraphQL client operations.
Format: The format to fetch for Move values.
PathFragment: A segment in an error path - either a field name or array index.

Functions§

paginate: Creates a paginated stream from a fetch function.
paginate_backward: Creates a backward paginated stream from a fetch function.