iota_grpc_types/
read_masks.rs

1// Copyright (c) 2025 IOTA Stiftung
2// SPDX-License-Identifier: Apache-2.0
3
4//! Read mask constants for the gRPC API.
5//!
6//! This module provides two categories of constants:
7//!
8//! ## Endpoint defaults
9//!
10//! Constants like [`GET_CHECKPOINT_READ_MASK`] are the canonical defaults used
11//! by both the server (as fallback when no mask is provided) and the client
12//! (when `None` is passed as the mask).
13//!
14//! ## Per-method field constants
15//!
16//! Constants like [`CHECKPOINT_RESPONSE_SUMMARY`] or
17//! [`EXECUTED_TRANSACTION_EFFECTS`] represent the read mask field(s) required
18//! by a specific accessor method on a response type. Pass one or more of these
19//! to the endpoint's `read_mask` parameter to ensure the accessor will succeed.
20//!
21//! ### Context-dependent paths
22//!
23//! [`ExecutedTransaction`](crate::v1::transaction::ExecutedTransaction) appears
24//! in multiple endpoints with different field-path prefixes:
25//!
26//! | Endpoint | Prefix |
27//! |---|---|
28//! | `get_transactions` / `execute_transactions` | *(none — direct)* |
29//! | Checkpoint queries | `transactions.` |
30//! | `simulate_transactions` | `executed_transaction.` |
31//!
32//! The `EXECUTED_TRANSACTION_*` constants use the **direct** (unprefixed)
33//! paths. For checkpoint or simulate contexts, prepend the appropriate prefix.
34//! The `CHECKPOINT_RESPONSE_*` constants already include the `transactions.`
35//! or `checkpoint.` prefix for convenience.
36//!
37//! Individual fields can be requested using dot notation. Pass a custom mask
38//! to narrow or widen the response; the endpoint defaults serve as a baseline
39//! that covers the most commonly needed fields.
40
41use crate::field_mask;
42
43// ---------------------------------------------------------------------------
44// Endpoint defaults
45// ---------------------------------------------------------------------------
46
47/// Default read mask for `get_service_info`.
48pub const GET_SERVICE_INFO_READ_MASK: &str = field_mask!(
49    "chain_id",
50    "epoch",
51    "executed_checkpoint_height",
52    "executed_checkpoint_timestamp",
53    "lowest_available_checkpoint",
54    "lowest_available_checkpoint_objects",
55);
56
57/// Default read mask for `get_epoch`.
58pub const GET_EPOCH_READ_MASK: &str = field_mask!(
59    "epoch",
60    "first_checkpoint",
61    "last_checkpoint",
62    "start",
63    "end",
64    "reference_gas_price",
65    "protocol_config.protocol_version",
66);
67
68/// Default read mask for `get_transactions`.
69pub const GET_TRANSACTIONS_READ_MASK: &str =
70    field_mask!("transaction", "signatures", "checkpoint", "timestamp",);
71
72/// Default read mask for `get_objects`.
73pub const GET_OBJECTS_READ_MASK: &str = field_mask!("reference", "bcs");
74
75/// Default read mask for `get_checkpoint` / `stream_checkpoints`.
76pub const GET_CHECKPOINT_READ_MASK: &str = field_mask!("checkpoint.summary");
77
78/// Default read mask for `list_dynamic_fields`.
79pub const LIST_DYNAMIC_FIELDS_READ_MASK: &str = field_mask!("parent", "field_id");
80
81/// Default read mask for `list_owned_objects`.
82pub const LIST_OWNED_OBJECTS_READ_MASK: &str = field_mask!("reference", "bcs");
83
84/// Default read mask for `execute_transactions`.
85///
86/// These paths apply to each `ExecutedTransaction` within the
87/// `transaction_results` of the response.
88pub const EXECUTE_TRANSACTIONS_READ_MASK: &str = field_mask!(
89    "transaction.digest",
90    "effects",
91    "events",
92    "input_objects",
93    "output_objects",
94);
95
96/// Default read mask for `simulate_transactions`.
97pub const SIMULATE_TRANSACTIONS_READ_MASK: &str = field_mask!(
98    "executed_transaction.transaction",
99    "executed_transaction.effects",
100    "executed_transaction.events",
101    "executed_transaction.input_objects",
102    "executed_transaction.output_objects",
103    "suggested_gas_price",
104    "execution_result",
105);
106
107// ---------------------------------------------------------------------------
108// CheckpointResponse — per-method field constants
109//
110// These use the full paths expected by the checkpoint endpoints
111// (get_checkpoint_*, stream_checkpoints).
112// ---------------------------------------------------------------------------
113
114/// Read mask for `CheckpointResponse::summary()`.
115///
116/// Includes the checkpoint summary (digest + BCS).
117pub const CHECKPOINT_RESPONSE_SUMMARY: &str = field_mask!("checkpoint.summary");
118
119/// Read mask for `CheckpointResponse::signature()`.
120///
121/// Includes the validator aggregated signature for the checkpoint.
122pub const CHECKPOINT_RESPONSE_SIGNATURE: &str = field_mask!("checkpoint.signature");
123
124/// Read mask for `CheckpointResponse::contents()`.
125///
126/// Includes the checkpoint contents (digest + BCS).
127pub const CHECKPOINT_RESPONSE_CONTENTS: &str = field_mask!("checkpoint.contents");
128
129/// Read mask for `CheckpointResponse::executed_transactions()`.
130///
131/// Includes all fields of every executed transaction in the checkpoint.
132pub const CHECKPOINT_RESPONSE_EXECUTED_TRANSACTIONS: &str = field_mask!("transactions");
133
134/// Read mask for `CheckpointResponse::events()`.
135///
136/// Includes all top-level event fields for the checkpoint.
137pub const CHECKPOINT_RESPONSE_EVENTS: &str = field_mask!("events");
138
139/// Read mask for `CheckpointResponse::signed_summary()`.
140///
141/// Contains the minimum fields required to build a
142/// `SignedCheckpointSummary`: checkpoint summary BCS and validator
143/// signature.
144pub const CHECKPOINT_RESPONSE_SIGNED_SUMMARY: &str =
145    field_mask!("checkpoint.summary.bcs", "checkpoint.signature",);
146
147/// Read mask for `CheckpointResponse::checkpoint_data()`.
148///
149/// Contains the minimum set of fields required to build a full
150/// `CheckpointData`: checkpoint summary/signature/contents BCS and
151/// per-transaction BCS for the transaction, signatures, effects,
152/// events, and input/output objects.
153pub const CHECKPOINT_RESPONSE_CHECKPOINT_DATA: &str = field_mask!(
154    "checkpoint.summary.bcs",
155    "checkpoint.signature",
156    "checkpoint.contents.bcs",
157    "transactions.transaction.bcs",
158    "transactions.signatures",
159    "transactions.effects.bcs",
160    "transactions.events.events.bcs",
161    "transactions.input_objects.bcs",
162    "transactions.output_objects.bcs",
163);
164
165// ---------------------------------------------------------------------------
166// CheckpointSummary / CheckpointContents — sub-field constants
167//
168// Full paths from the checkpoint endpoint root.
169// ---------------------------------------------------------------------------
170
171/// Read mask for
172/// [`CheckpointSummary::digest()`](crate::v1::checkpoint::CheckpointSummary::digest).
173pub const CHECKPOINT_SUMMARY_DIGEST: &str = "checkpoint.summary.digest";
174
175/// Read mask for
176/// [`CheckpointSummary::summary()`](crate::v1::checkpoint::CheckpointSummary::summary).
177pub const CHECKPOINT_SUMMARY_BCS: &str = "checkpoint.summary.bcs";
178
179/// Read mask for
180/// [`CheckpointContents::digest()`](crate::v1::checkpoint::CheckpointContents::digest).
181pub const CHECKPOINT_CONTENTS_DIGEST: &str = "checkpoint.contents.digest";
182
183/// Read mask for
184/// [`CheckpointContents::contents()`](crate::v1::checkpoint::CheckpointContents::contents).
185pub const CHECKPOINT_CONTENTS_BCS: &str = "checkpoint.contents.bcs";
186
187// ---------------------------------------------------------------------------
188// ExecutedTransaction — per-method field constants
189//
190// Direct (unprefixed) paths, usable with get_transactions and
191// execute_transactions. For checkpoint context prefix with "transactions.",
192// for simulate_transactions prefix with "executed_transaction.".
193// ---------------------------------------------------------------------------
194
195/// Read mask for
196/// [`ExecutedTransaction::transaction()`](crate::v1::transaction::ExecutedTransaction::transaction).
197///
198/// Includes the transaction digest and BCS.
199pub const EXECUTED_TRANSACTION_TRANSACTION: &str = "transaction";
200
201/// Read mask for
202/// [`ExecutedTransaction::signatures()`](crate::v1::transaction::ExecutedTransaction::signatures).
203pub const EXECUTED_TRANSACTION_SIGNATURES: &str = "signatures";
204
205/// Read mask for
206/// [`ExecutedTransaction::effects()`](crate::v1::transaction::ExecutedTransaction::effects).
207///
208/// Includes the effects digest and BCS.
209pub const EXECUTED_TRANSACTION_EFFECTS: &str = "effects";
210
211/// Read mask for
212/// [`ExecutedTransaction::events()`](crate::v1::transaction::ExecutedTransaction::events).
213///
214/// Includes the events digest and all individual event fields.
215pub const EXECUTED_TRANSACTION_EVENTS: &str = "events";
216
217/// Read mask for
218/// [`ExecutedTransaction::checkpoint_sequence_number()`](crate::v1::transaction::ExecutedTransaction::checkpoint_sequence_number).
219pub const EXECUTED_TRANSACTION_CHECKPOINT: &str = "checkpoint";
220
221/// Read mask for
222/// [`ExecutedTransaction::timestamp_ms()`](crate::v1::transaction::ExecutedTransaction::timestamp_ms).
223pub const EXECUTED_TRANSACTION_TIMESTAMP: &str = "timestamp";
224
225/// Read mask for
226/// [`ExecutedTransaction::input_objects()`](crate::v1::transaction::ExecutedTransaction::input_objects).
227///
228/// Includes object references and BCS for all input objects.
229pub const EXECUTED_TRANSACTION_INPUT_OBJECTS: &str = "input_objects";
230
231/// Read mask for
232/// [`ExecutedTransaction::output_objects()`](crate::v1::transaction::ExecutedTransaction::output_objects).
233///
234/// Includes object references and BCS for all output objects.
235pub const EXECUTED_TRANSACTION_OUTPUT_OBJECTS: &str = "output_objects";
236
237// ---------------------------------------------------------------------------
238// Transaction — sub-field constants (relative to ExecutedTransaction)
239// ---------------------------------------------------------------------------
240
241/// Read mask for
242/// [`Transaction::digest()`](crate::v1::transaction::Transaction::digest).
243pub const TRANSACTION_DIGEST: &str = "transaction.digest";
244
245/// Read mask for
246/// [`Transaction::transaction()`](crate::v1::transaction::Transaction::transaction)
247/// (BCS deserialization).
248pub const TRANSACTION_BCS: &str = "transaction.bcs";
249
250// ---------------------------------------------------------------------------
251// TransactionEffects — sub-field constants (relative to ExecutedTransaction)
252// ---------------------------------------------------------------------------
253
254/// Read mask for
255/// [`TransactionEffects::digest()`](crate::v1::transaction::TransactionEffects::digest).
256pub const TRANSACTION_EFFECTS_DIGEST: &str = "effects.digest";
257
258/// Read mask for
259/// [`TransactionEffects::effects()`](crate::v1::transaction::TransactionEffects::effects)
260/// (BCS deserialization).
261pub const TRANSACTION_EFFECTS_BCS: &str = "effects.bcs";
262
263// ---------------------------------------------------------------------------
264// TransactionEvents — sub-field constants (relative to ExecutedTransaction)
265// ---------------------------------------------------------------------------
266
267/// Read mask for
268/// [`TransactionEvents::digest()`](crate::v1::transaction::TransactionEvents::digest).
269pub const TRANSACTION_EVENTS_DIGEST: &str = "events.digest";
270
271/// Read mask for
272/// [`TransactionEvents::events()`](crate::v1::transaction::TransactionEvents::events)
273/// (BCS deserialization of all events).
274pub const TRANSACTION_EVENTS_BCS: &str = "events.events.bcs";
275
276// ---------------------------------------------------------------------------
277// Event — per-method field constants
278//
279// Relative paths. The full path depends on context:
280// - Checkpoint top-level events: prefix with "events."
281// - Transaction events (get_transactions): prefix with "events.events."
282// - Checkpoint transaction events: prefix with "transactions.events.events."
283// ---------------------------------------------------------------------------
284
285/// Read mask for
286/// [`Event::event()`](crate::v1::event::Event::event)
287/// (full BCS deserialization).
288pub const EVENT_BCS: &str = "bcs";
289
290/// Read mask for
291/// [`Event::package_id()`](crate::v1::event::Event::package_id).
292pub const EVENT_PACKAGE_ID: &str = "package_id";
293
294/// Read mask for
295/// [`Event::module_name()`](crate::v1::event::Event::module_name).
296pub const EVENT_MODULE: &str = "module";
297
298/// Read mask for
299/// [`Event::sender()`](crate::v1::event::Event::sender).
300pub const EVENT_SENDER: &str = "sender";
301
302/// Read mask for
303/// [`Event::type_name()`](crate::v1::event::Event::type_name).
304pub const EVENT_TYPE: &str = "event_type";
305
306/// Read mask for
307/// [`Event::bcs_contents()`](crate::v1::event::Event::bcs_contents).
308pub const EVENT_BCS_CONTENTS: &str = "bcs_contents";
309
310/// Read mask for
311/// [`Event::json_contents()`](crate::v1::event::Event::json_contents).
312pub const EVENT_JSON_CONTENTS: &str = "json_contents";
313
314// ---------------------------------------------------------------------------
315// Object — per-method field constants (for get_objects)
316// ---------------------------------------------------------------------------
317
318/// Read mask for
319/// [`Object::object_reference()`](crate::v1::object::Object::object_reference).
320///
321/// Includes object_id, version, and digest.
322pub const OBJECT_REFERENCE: &str = "reference";
323
324/// Read mask for
325/// [`Object::object()`](crate::v1::object::Object::object)
326/// (BCS deserialization).
327pub const OBJECT_BCS: &str = "bcs";
328
329// ---------------------------------------------------------------------------
330// SimulatedTransaction — per-method field constants
331// ---------------------------------------------------------------------------
332
333/// Read mask for
334/// [`SimulatedTransaction::executed_transaction()`](crate::v1::transaction_execution_service::SimulatedTransaction::executed_transaction).
335///
336/// Includes all ExecutedTransaction sub-fields. To request specific
337/// sub-fields, use paths like `"executed_transaction.effects"`.
338pub const SIMULATED_TRANSACTION_EXECUTED_TRANSACTION: &str = "executed_transaction";
339
340/// Read mask for
341/// [`SimulatedTransaction::gas_price_suggested()`](crate::v1::transaction_execution_service::SimulatedTransaction::gas_price_suggested).
342pub const SIMULATED_TRANSACTION_SUGGESTED_GAS_PRICE: &str = "suggested_gas_price";
343
344/// Read mask for
345/// [`SimulatedTransaction::execution_result()`](crate::v1::transaction_execution_service::SimulatedTransaction::execution_result),
346/// [`SimulatedTransaction::command_results()`](crate::v1::transaction_execution_service::SimulatedTransaction::command_results),
347/// and
348/// [`SimulatedTransaction::execution_error()`](crate::v1::transaction_execution_service::SimulatedTransaction::execution_error).
349pub const SIMULATED_TRANSACTION_EXECUTION_RESULT: &str = "execution_result";
350
351// ---------------------------------------------------------------------------
352// ExecutionError — sub-field constants (relative to simulate_transactions)
353// ---------------------------------------------------------------------------
354
355/// Read mask for
356/// [`ExecutionError::error_kind()`](crate::v1::transaction_execution_service::ExecutionError::error_kind).
357pub const EXECUTION_ERROR_BCS_KIND: &str = "execution_result.execution_error.bcs_kind";
358
359/// Read mask for
360/// [`ExecutionError::error_source()`](crate::v1::transaction_execution_service::ExecutionError::error_source).
361pub const EXECUTION_ERROR_SOURCE: &str = "execution_result.execution_error.source";
362
363/// Read mask for
364/// [`ExecutionError::error_command_index()`](crate::v1::transaction_execution_service::ExecutionError::error_command_index).
365pub const EXECUTION_ERROR_COMMAND_INDEX: &str = "execution_result.execution_error.command_index";
iota_grpc_types/read_masks.rs

iota_grpc_types/
read_masks.rs
