feat(gRPC)!: improve client ergonomics & read-mask discoverability#1147
Open
DaughterOfMars wants to merge 18 commits into
Open
feat(gRPC)!: improve client ergonomics & read-mask discoverability#1147DaughterOfMars wants to merge 18 commits into
DaughterOfMars wants to merge 18 commits into
Conversation
Thoralf-M
reviewed
Jun 1, 2026
Thoralf-M
reviewed
Jun 1, 2026
Thoralf-M
reviewed
Jun 1, 2026
Thoralf-M
reviewed
Jun 1, 2026
Thoralf-M
reviewed
Jun 1, 2026
Thoralf-M
reviewed
Jun 1, 2026
Member
|
Overall not sure if this PR is really worth it, just providing |
Contributor
Author
I think it's a pretty big usability increase, if not for the extra helper fns than definitely for the read mask discoverability. Before you basically had no way to know what read masks to use other than reading the doc. Now it's implicit. |
Thoralf-M
approved these changes
Jun 4, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Follow-up to the initial gRPC client landing (#1062). This PR sharpens the
high-level Rust gRPC API around two recurring rough edges — every read method
having to take an
Option<ReadMask>, and callers having to know by conventionwhich
XFieldnamespace pairs with which method — and adds a handful ofexamples that exercise the result.
Summary
_maskedvariant.
client.get_objects(refs)uses the canonical default mask;client.get_objects_masked(refs, mask)takes a mask directly (noOption, no wrapper). Applied to all 17 masked methods acrossget_objects/get_objects_with_versions/get_transactions/get_service_info/get_epoch/get_checkpoint_*/stream_checkpoints*/
list_owned_objects/list_dynamic_fields/get_coins/simulate_transaction(s)/execute_transaction(s).XField(e.g.ObjectField,TransactionField,EpochField, …) is now a typedCow<'static, str>newtype instead of a bag of&strconsts, and eachmasked endpoint accepts a paired
XReadMask(ObjectReadMask,TransactionReadMask, …) viaimpl Into<…>. Call sites become:ReadMask::from(…)wrapper. PassingTransactionField::EFFECTStoget_objects_maskedis now a compile error. Pre-computed mask constantsin
read_masks::*still flow through viaFrom<&'static str>/From<String>escape hatches on each scoped mask.Client::get_coins(_masked)plusGetCoinsQuerybuilder instate/coins.rs— paginated coin listing with optionalStructTagfilter, returning
iota_types::framework::Coinitems (protoObject→SDK
Coinconversion happens internally).CheckpointResponseaccessors refactored to return SDK types directly.response.summary()/.signature()/.contents()now yield thedeserialized SDK types; the proto variants are renamed to
_grpc(
summary_grpc, etc.). Same pattern as theexecuted_transactions/executed_transactions_grpcsplit.Client:Client::new_localnet(),new_devnet(),new_testnet(),new_mainnet()plus pub-crate hostconstants.
iota-sdk'sgrpcfeature. Previouslyenabling
iota-sdk/grpcpulled iniota-grpc-clientwithdefault-features = false, soClient::new_testnet()failed at runtimewith
"HTTPS requires the tls-ring feature". Thegrpcfeature nowforwards
tls-ring+tls-native-roots.crates/iota-sdk/examples/:chain_id_grpc,get_object_grpc,owned_objects_grpc,stream_checkpoints_grpc— the last has no GraphQL counterpart andexists specifically to showcase the streaming RPC.
Migration
This is a breaking change to the gRPC client surface. The mechanical
rewrite at call sites:
get_objects(refs, None)get_objects(refs)get_objects(refs, Some(ReadMask::from(ObjectField::BCS)))get_objects_masked(refs, ObjectField::BCS)get_objects(refs, Some(ReadMask::from(&[ObjectField::BCS, ObjectField::REFERENCE])))get_objects_masked(refs, [ObjectField::BCS, ObjectField::REFERENCE])cp.summary()?.summary()?cp.summary()?cp.signature()?.signature()?cp.signature()?cp.contents()?.contents()?cp.contents()?XField::Yused to evaluate to&'static str; it's now anXFieldstruct. Use
.as_str()if you need the underlying path string.ReadMask<'_>is retained as a low-level string holder for advancedcomposition but is no longer accepted by client methods directly — pass a
scoped mask (or a
&strfor the escape hatch) instead.