iota_sdk_grpc_client/
lib.rs

1// Copyright (c) 2026 IOTA Stiftung
2// SPDX-License-Identifier: Apache-2.0
3
4//! gRPC client for IOTA node operations.
5//!
6//! This crate provides a high-level client for interacting with IOTA nodes
7//! via gRPC. It wraps the low-level proto types and provides ergonomic APIs
8//! using SDK types from `iota_types`.
9//!
10//! # Example
11//!
12//! ```no_run
13//! use iota_sdk_grpc_client::{
14//!     Client,
15//!     read_mask_fields::{ObjectReadMask, TransactionReadMask},
16//! };
17//! use iota_types::{ObjectId, TransactionDigest};
18//!
19//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
20//! let client = Client::new_localnet()?;
21//!
22//! // Get a transaction with the default field mask.
23//! // The batched reads return one result per request, so a transaction the
24//! // node cannot serve fails only its own slot.
25//! let digest: TransactionDigest = todo!();
26//! let txs = client
27//!     .get_transactions([digest], TransactionReadMask::default())
28//!     .await?;
29//! for tx in txs.body() {
30//!     match tx {
31//!         Ok(tx) => println!("Transaction digest: {:?}", tx.transaction()?.digest()?),
32//!         Err(e) => eprintln!("could not read transaction: {e}"),
33//!     }
34//! }
35//!
36//! // Get an object with the default field mask.
37//! let object_id: ObjectId = "0x2".parse()?;
38//! let objects = client
39//!     .get_objects([object_id], ObjectReadMask::default())
40//!     .await?;
41//! for object in objects.body() {
42//!     match object {
43//!         Ok(object) => println!("Object version: {:?}", object.object_reference()?.version()),
44//!         Err(e) => eprintln!("could not read object: {e}"),
45//!     }
46//! }
47//! # Ok(())
48//! # }
49//! ```
50
51pub mod api;
52mod transaction_builder_client;
53
54// Re-export all read mask constants (per-method fields)
55pub use api::{
56    // CheckpointResponse per-method masks
57    CHECKPOINT_CONTENTS_BCS,
58    CHECKPOINT_CONTENTS_DIGEST,
59    CHECKPOINT_RESPONSE_CHECKPOINT_DATA,
60    CHECKPOINT_RESPONSE_CONTENTS,
61    CHECKPOINT_RESPONSE_EVENTS,
62    CHECKPOINT_RESPONSE_EXECUTED_TRANSACTIONS,
63    CHECKPOINT_RESPONSE_SIGNATURE,
64    CHECKPOINT_RESPONSE_SIGNED_SUMMARY,
65    CHECKPOINT_RESPONSE_SUMMARY,
66    CHECKPOINT_SUMMARY_BCS,
67    CHECKPOINT_SUMMARY_DIGEST,
68    // Event per-method masks
69    EVENT_BCS,
70    EVENT_BCS_CONTENTS,
71    EVENT_JSON_CONTENTS,
72    EVENT_MODULE,
73    EVENT_PACKAGE_ID,
74    EVENT_SENDER,
75    EVENT_TYPE,
76    // ExecutedTransaction per-method masks
77    EXECUTED_TRANSACTION_CHECKPOINT,
78    EXECUTED_TRANSACTION_EFFECTS,
79    EXECUTED_TRANSACTION_EVENTS,
80    EXECUTED_TRANSACTION_INPUT_OBJECTS,
81    EXECUTED_TRANSACTION_OUTPUT_OBJECTS,
82    EXECUTED_TRANSACTION_SIGNATURES,
83    EXECUTED_TRANSACTION_TIMESTAMP,
84    EXECUTED_TRANSACTION_TRANSACTION,
85    // ExecutionError sub-fields
86    EXECUTION_ERROR_BCS_KIND,
87    EXECUTION_ERROR_COMMAND_INDEX,
88    EXECUTION_ERROR_SOURCE,
89    // Object per-method masks
90    OBJECT_BCS,
91    OBJECT_REFERENCE,
92    // SimulatedTransaction per-method masks
93    SIMULATED_TRANSACTION_EXECUTED_TRANSACTION,
94    SIMULATED_TRANSACTION_EXECUTION_RESULT,
95    SIMULATED_TRANSACTION_SUGGESTED_GAS_PRICE,
96    // Transaction / Effects / Events sub-fields
97    TRANSACTION_BCS,
98    TRANSACTION_DIGEST,
99    TRANSACTION_EFFECTS_BCS,
100    TRANSACTION_EFFECTS_DIGEST,
101    TRANSACTION_EVENTS_BCS,
102    TRANSACTION_EVENTS_DIGEST,
103};
104// Re-export types for convenience
105pub use api::{
106    CheckpointResponse, CheckpointStreamError, CheckpointStreamItem, Error, MetadataEnvelope, Page,
107    ProtocolError, ReadMask, Result, RpcStatus, execution::simulate::SimulateTransactionInput,
108};
109// Re-export all read mask constants (endpoint defaults)
110pub use api::{
111    // Endpoint defaults
112    EXECUTE_TRANSACTIONS_READ_MASK,
113    GET_CHECKPOINT_READ_MASK,
114    GET_EPOCH_READ_MASK,
115    GET_OBJECTS_READ_MASK,
116    GET_SERVICE_INFO_READ_MASK,
117    GET_TRANSACTIONS_READ_MASK,
118    LIST_DYNAMIC_FIELDS_READ_MASK,
119    LIST_OWNED_OBJECTS_READ_MASK,
120    SIMULATE_TRANSACTIONS_READ_MASK,
121};
122// Re-export query builders for convenience
123pub use api::{
124    move_package::package_versions::ListPackageVersionsQuery,
125    state::{
126        coins::GetCoinsQuery, dynamic_fields::ListDynamicFieldsQuery,
127        owned_objects::ListOwnedObjectsQuery,
128    },
129};
130// Re-export typed read mask field enums
131pub use iota_grpc_types::read_mask_fields;
132
133mod client;
134pub use client::{Client, InterceptedChannel};
135
136mod response_ext;
137pub use response_ext::ResponseExt;
138
139mod interceptors;
140pub use interceptors::HeadersInterceptor;
iota_sdk_grpc_client/lib.rs

iota_sdk_grpc_client/
lib.rs
