Struct GraphQLClient 

pub struct GraphQLClient { /* private fields */ }

The GraphQL client for interacting with the IOTA blockchain. By default, it uses the reqwest crate as the HTTP client.

Implementations

impl GraphQLClient

pub fn balance(&self, address: Address) -> GetBalanceQuery

Get the balance of all the coins owned by address.

impl GraphQLClient

pub fn checkpoint(&self) -> GetCheckpointQuery

Get the CheckpointSummary of the last known checkpoint.

pub fn checkpoint_by_digest( &self, digest: CheckpointDigest, ) -> GetCheckpointQuery

Get the CheckpointSummary for the given checkpoint digest.

pub fn checkpoint_by_sequence_number( &self, sequence_number: u64, ) -> GetCheckpointQuery

Get the CheckpointSummary for the given checkpoint sequence number.

pub fn checkpoints(&self) -> ListCheckpointsQuery

Get a page of CheckpointSummary.

pub fn latest_checkpoint_sequence_number( &self, ) -> GetLatestCheckpointSequenceNumberQuery

Return the sequence number of the latest checkpoint that has been executed.

pub fn total_transaction_blocks_by_digest( &self, digest: CheckpointDigest, ) -> GetTotalTransactionBlocksQuery

The total number of transaction blocks in the network by the end of the provided checkpoint digest.

pub fn total_transaction_blocks_by_sequence_number( &self, sequence_number: u64, ) -> GetTotalTransactionBlocksQuery

The total number of transaction blocks in the network by the end of the provided checkpoint sequence number.

pub fn total_transaction_blocks(&self) -> GetTotalTransactionBlocksQuery

The total number of transaction blocks in the network by the end of the last known checkpoint.

impl GraphQLClient

pub fn coins(&self, owner: Address) -> ListCoinsQuery

Get the list of coins for the specified address. For IOTA coins, set the coin type to 0x2::iota::IOTA.

pub fn gas_coins(&self, owner: Address) -> ListGasCoinsQuery

Get the list of gas coins for the specified address.

pub fn coin_metadata(&self, coin_type: StructTag) -> GetCoinMetadataQuery

Get the coin metadata for the coin type.

pub fn total_supply(&self, coin_type: StructTag) -> GetTotalSupplyQuery

Get total supply for the coin type.

impl GraphQLClient

pub fn dry_run_transaction( &self, transaction: &Transaction, ) -> DryRunTransactionQuery

Dry run a Transaction and return the transaction effects and dry run error (if any).

pub fn dry_run_transaction_kind( &self, transaction_kind: &TransactionKind, ) -> DryRunTransactionKindQuery

Dry run a TransactionKind and return the transaction effects and dry run error (if any).

impl GraphQLClient

pub fn dynamic_field( &self, address: Address, type_tag: TypeTag, name: impl Into<NameValue>, ) -> GetDynamicFieldQuery

Access a dynamic field on an object using its name. Names are arbitrary Move values whose type have copy, drop, and store, and are specified using their type, and their BCS contents, Base64 encoded.

The name argument can be either a BcsName for passing raw bcs bytes or a type that implements Serialize.

This returns DynamicFieldOutput which contains the name, the value as json, and object.

Example

 
let client = iota_graphql_client::GraphQLClient::new_testnet().unwrap();
let address = ObjectId::system().into();
let df = client.dynamic_field_with_name(address, "u64", 2u64).await.unwrap();

let bcs = base64ct::Base64::decode_vec("AgAAAAAAAAA=").unwrap();
let df = client.dynamic_field(address, "u64", BcsName(bcs)).await.unwrap();

pub fn dynamic_object_field( &self, address: Address, type_tag: TypeTag, name: impl Into<NameValue>, ) -> GetDynamicObjectFieldQuery

Access a dynamic object field on an object using its name. Names are arbitrary Move values whose type have copy, drop, and store, and are specified using their type, and their BCS contents, Base64 encoded.

The name argument can be either a BcsName for passing raw bcs bytes or a type that implements Serialize.

This returns DynamicFieldOutput which contains the name, the value as json, and object.

pub fn dynamic_fields(&self, address: Address) -> ListDynamicFieldsQuery

Get a page of dynamic fields for the provided address. Note that this will also fetch dynamic fields on wrapped objects.

impl GraphQLClient

pub fn epoch(&self) -> GetEpochQuery

Return the epoch information. Defaults to the last known epoch.

pub fn epoch_total_checkpoints(&self) -> GetEpochTotalCheckpointsQuery

Return the number of checkpoints in an epoch. Resolves to None if the epoch requested is not available in the GraphQL service (e.g., due to pruning).

pub fn epoch_total_transaction_blocks( &self, ) -> GetEpochTotalTransactionBlocksQuery

Return the number of transaction blocks in an epoch. Resolves to None if the epoch requested is not available in the GraphQL service (e.g., due to pruning).

impl GraphQLClient

pub fn events(&self) -> ListEventsQuery

Return a page of events.

impl GraphQLClient

pub fn iota_names_lookup(&self, name: Name) -> GetIotaNamesLookupQuery

Return the resolved address for the given name.

pub fn iota_names_registrations( &self, address: Address, ) -> ListIotaNamesRegistrationsQuery

Find all registration NFTs for the given address.

pub fn iota_names_default_name( &self, address: Address, ) -> GetIotaNamesDefaultNameQuery

Get the default name pointing to this address, if one exists.

impl GraphQLClient

pub fn move_objects<T: MoveObject>(&self) -> ListMoveObjectsQuery<T>

Available on crate feature move-types only.

Return a page of objects of the Move type T, decoded into T and paired with their object references.

The type filter is derived from T, so unlike GraphQLClient::objects this needs no type string and no separate decode step.

Errors

Returns an error if any object in the page fails to decode. The query filters on T’s exact type, so a failure means the on-chain type has moved out from under the mirror rather than that one object is odd — yielding the rest of the page would hide that.

Example

let staked: Page<OwnedMoveObject<StakedIota>> = client
    .move_objects()
    .filter(MoveObjectFilter::default().with_owner(address))
    .await?;

impl GraphQLClient

pub fn move_view_call_json( &self, package: impl Into<ObjectId>, module: impl Into<String>, function: impl Into<String>, ) -> MoveViewCallJsonQuery

Execute a Move View Function with raw JSON arguments.

This is an alternative to GraphQLClient::move_view_call that accepts raw JSON values instead of typed arguments.

A View Function is a function in a Move module with a return type that does not alter the state of the ledger. When using this interface, no transactions are submitted to the network for inclusion into the ledger.

The function is function in the module module of the package package. Set its type arguments with type_arguments and its JSON arguments with arguments.

Resolves to a MoveViewResult containing either execution results (return values) or an error.

pub fn move_view_call( &self, package: impl Into<ObjectId>, module: impl Into<String>, function: impl Into<String>, ) -> MoveViewCallQuery

Execute a Move View Function.

A View Function is a function in a Move module with a return type that does not alter the state of the ledger. When using this interface, no transactions are submitted to the network for inclusion into the ledger.

This method allows calling nearly any Move function with a return type and any arguments. The function’s result values are provided and decoded using the appropriate Move type, then formatted in JSON.

The use of this interface does not require signature checks (even for functions that take Owned Objects as input) or gas coins, as it does not alter ledger state. Spam attacks are dealt with at the RPC level rather than execution level.

The function is function in the module module of the package package. Set its typed arguments with arguments and its type arguments with type_arguments.

Example

// The `view_demo` package published on testnet, and the shared
// `view_demo::shop::Shop` created when it was published.
let package = ObjectId::from_str(
    "0x533074f8e22e8ce1330d7e9d67c18966abb5a3d58dc2e2deea50e50bea4e87f4",
)?;
let shop = ObjectId::from_str(
    "0x9d5ce0da7531d56ffecced5efb7e19ccad0e191071041267cc8134a3e5a6cd20",
)?;

// Single argument: wrap in a list or tuple
let result = client
    .move_view_call(package, "shop", "total_revenue")
    .arguments((shop,))
    .await?;

// Or append it
let result = client
    .move_view_call(package, "shop", "total_revenue")
    .argument(shop)
    .await?;

Resolves to a MoveViewResult containing either execution results (return values) or an error.

impl GraphQLClient

pub fn chain_id(&self) -> GetChainIdQuery

Get the chain identifier.

pub fn reference_gas_price(&self) -> GetReferenceGasPriceQuery

Get the reference gas price. Defaults to the last known epoch.

This will resolve to Ok(None) if the epoch requested is not available in the GraphQL service (e.g., due to pruning).

pub fn protocol_config(&self) -> GetProtocolConfigQuery

Get the protocol configuration. Defaults to the latest version.

pub fn active_validators(&self) -> ListActiveValidatorsQuery

Get the list of active validators, including related metadata.

impl GraphQLClient

pub fn object(&self, object_id: ObjectId) -> GetObjectQuery

Return an object based on the provided Address.

If the object does not exist (e.g., due to pruning), this will resolve to Ok(None). Similarly, if this is not an object but an address, it will resolve to Ok(None).

pub fn objects(&self) -> ListObjectsQuery

Return a page of objects.

Use ListObjectsQuery::filter together with ObjectFilter::with_owner to get the objects owned by an address.

Example

let filter = ObjectFilter::default().with_owner(Address::from_str("test").unwrap());

let owned_objects = client.objects().filter(filter).await;

pub fn object_bcs(&self, object_id: ObjectId) -> GetObjectBcsQuery

Return the object’s bcs content Vec<u8> based on the provided Address.

pub fn move_object_contents( &self, object_id: ObjectId, ) -> GetMoveObjectContentsQuery

Return the contents JSON of an object that is a Move object.

If the object does not exist (e.g., due to pruning), this will resolve to Ok(None). Similarly, if this is not an object but an address, it will resolve to Ok(None).

pub fn move_object_contents_bcs( &self, object_id: ObjectId, ) -> GetMoveObjectContentsBcsQuery

Return the BCS of an object that is a Move object.

If the object does not exist (e.g., due to pruning), this will resolve to Ok(None). Similarly, if this is not an object but an address, it will resolve to Ok(None).

impl GraphQLClient

pub fn package(&self, address: Address) -> GetPackageQuery

The package corresponding to the given address (at the optionally given version). When no version is given, the package is loaded directly from the address given. Otherwise, the address is translated before loading to point to the package whose original ID matches the package at address, but whose version is version. For non-system packages, this might result in a different address than address because different versions of a package, introduced by upgrades, exist at distinct addresses.

Note that this interpretation of version is different from a historical object read (the interpretation of version for the object query).

pub fn package_versions(&self, address: Address) -> ListPackageVersionsQuery

Fetch all versions of package at address (packages that share this package’s original ID), optionally bounding the versions exclusively with ListPackageVersionsQuery::after_version and ListPackageVersionsQuery::before_version.

pub fn package_latest(&self, address: Address) -> GetPackageLatestQuery

Fetch the latest version of the package at address. This corresponds to the package with the highest version that shares its original ID with the package at address.

pub fn packages(&self) -> ListPackagesQuery

The Move packages that exist in the network, optionally bounded exclusively with ListPackagesQuery::after_checkpoint and ListPackagesQuery::before_checkpoint.

This query returns all versions of a given user package that appear between the specified checkpoints, but only records the latest versions of system packages.

pub fn normalized_move_function( &self, package: Address, module: impl Into<String>, function: impl Into<String>, ) -> GetNormalizedMoveFunctionQuery

Return the normalized Move function data for the provided package, module, and function.

pub fn normalized_move_module( &self, package: Address, module: impl Into<String>, ) -> GetNormalizedMoveModuleQuery

Return the normalized Move module data for the provided module.

impl GraphQLClient

pub fn transaction(&self, digest: TransactionDigest) -> GetTransactionQuery

Get a transaction by its digest.

pub fn transactions(&self) -> ListTransactionsQuery

Get a page of transactions.

pub fn address_transactions( &self, address: Address, ) -> ListAddressTransactionsQuery

Get a page of transactions related to the given address.

pub fn transaction_effects( &self, digest: TransactionDigest, ) -> GetTransactionEffectsQuery

Get a transaction’s effects by its digest.

pub fn transactions_effects(&self) -> ListTransactionsEffectsQuery

Get a page of transactions’ effects.

pub fn transaction_data_effects( &self, digest: TransactionDigest, ) -> GetTransactionDataEffectsQuery

Get a transaction’s data and effects by its digest.

pub fn transactions_data_effects(&self) -> ListTransactionsDataEffectsQuery

Get a page of transactions’ data and effects.

pub fn execute_transaction( &self, signatures: &[UserSignature], transaction: &Transaction, ) -> ExecuteTransactionQuery

Execute a transaction.

pub fn is_transaction_indexed_on_node( &self, digest: TransactionDigest, ) -> IsTransactionIndexedOnNodeQuery

Returns whether the transaction for the given digest has been indexed on the node. This means that it can be queried by its digest and its effects will be usable for subsequent transactions. To check for full finalization, use Self::is_transaction_finalized.

pub fn is_transaction_finalized( &self, digest: TransactionDigest, ) -> IsTransactionFinalizedQuery

Returns whether the transaction for the given digest has been included in a checkpoint (finalized).

pub fn wait_for_transaction( &self, digest: TransactionDigest, wait_for: WaitForTransaction, ) -> WaitForTransactionQuery

Wait for the indexing or finalization of a transaction by its digest. Resolves to an error if it takes longer than the timeout, 60s unless set with timeout.

impl GraphQLClient

pub fn new(server: &str) -> GraphQLResult<Self>

Create a new GraphQL client with the provided server address.

The HTTP client is built for you, trusting the platform store plus the bundled Mozilla roots. Use Self::new_with_reqwest_client to supply your own.

An https or wss address is rejected on a build without a crypto provider, since no request to it could succeed. See the crate README.

pub fn builder(server: &str) -> GraphQLClientBuilder

Start building a client for server from this crate’s default HTTP client, keeping its user agent and trust anchors while letting you set timeouts and headers.

pub fn new_with_reqwest_client( server: &str, client: Client, ) -> GraphQLResult<Self>

Create a new GraphQL client that issues its requests through the supplied reqwest::Client.

This is the way to choose your own trust anchors, TLS backend, proxies or timeouts.

Note that on a build with tls-ring or tls-aws-lc, reqwest has no crypto provider to fall back on, so building the client panics unless one has been installed for the process. See the crate README.

The client is used as given: the SDK does not set its user agent, so callers who want to be identifiable should apply USER_AGENT themselves.

pub fn new_mainnet() -> GraphQLResult<Self>

Create a new GraphQL client connected to the mainnet GraphQL server: {MAINNET_HOST}.

pub fn new_testnet() -> GraphQLResult<Self>

Create a new GraphQL client connected to the testnet GraphQL server: {TESTNET_HOST}.

pub fn new_devnet() -> GraphQLResult<Self>

Create a new GraphQL client connected to the devnet GraphQL server: {DEVNET_HOST}.

pub fn new_localnet() -> GraphQLResult<Self>

Create a new GraphQL client connected to a localnet GraphQL server: {LOCAL_HOST}.

pub async fn service_config(&self) -> GraphQLResult<&ServiceConfig>

Get the GraphQL service configuration, including complexity limits, read and mutation limits, supported versions, and others.

pub async fn run_query<T, V>( &self, operation: &Operation<T, V>, ) -> GraphQLResult<T>

where T: DeserializeOwned, V: Serialize,

Run a query on the GraphQL server and return the response. This method returns cynic::GraphQlResponse over the query type T, and it is intended to be used with custom queries.

pub async fn run_query_from_json( &self, json: Map<String, Value>, ) -> GraphQLResult<Value>

Run a JSON query on the GraphQL server and return the response data. This method expects a JSON map holding the GraphQL query string and matching GraphQL variables. Any GraphQL error in the response is returned as an error, even if partial data is present. In general, it is recommended to use run_query which guarantees valid GraphQL query syntax and returns a proper response type.

pub async fn pagination_filter( &self, pagination_filter: PaginationFilter, ) -> PaginationFilterResponse

Handle pagination filters and return the appropriate values. If limit is omitted, it will use the max page size from the service config.

pub fn max_page_size(&self) -> GetMaxPageSizeQuery

Lazily fetch the max page size

impl GraphQLClient

pub fn events_subscription(&self) -> EventsSubscriptionBuilder

Subscribe to a live stream of events.

Note: subscriptions are served over a WebSocket, which the node has to have enabled: serviceConfig.enabledFeatures includes SUBSCRIPTIONS when it is available.

pub fn transactions_subscription(&self) -> TransactionsSubscriptionBuilder

Subscribe to a live stream of transactions.

Note: subscriptions are served over a WebSocket, which the node has to have enabled: serviceConfig.enabledFeatures includes SUBSCRIPTIONS when it is available.

impl GraphQLClient

pub fn transaction_builder(&self, sender: Address) -> TransactionBuilder<&Self>

Create a new TransactionBuilder with the given sender address.

Trait Implementations

impl Clone for GraphQLClient

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for GraphQLClient

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl TransactionBuilderClientBase for GraphQLClient

type Error = GraphQLError

The error type for this client.

impl TransactionBuilderExecutionClient for GraphQLClient

async fn execute_transaction( &self, signatures: &[UserSignature], transaction: &Transaction, wait_for: impl Into<Option<WaitForTransaction>>, ) -> Result<TransactionEffects, Self::Error>

Execute a transaction

async fn wait_for_transaction( &self, digest: TransactionDigest, wait_for: WaitForTransaction, ) -> Result<(), Self::Error>

Wait for the indexing or finalization of a transaction by its digest.

async fn transaction_effects( &self, digest: TransactionDigest, ) -> Result<Option<TransactionEffects>, Self::Error>

Fetch the effects of an executed transaction

impl TransactionBuilderLedgerClient for GraphQLClient

async fn object( &self, object_id: ObjectId, version: impl Into<Option<Version>>, ) -> Result<Option<Object>, Self::Error>

Fetch an object

async fn objects( &self, struct_tag: Option<StructTag>, owner: Address, cursor: Option<Vec<u8>>, limit: Option<usize>, ) -> Result<ObjectsPage, Self::Error>

Fetch one page of objects matching the filter, returning the page contents and a continuation cursor (when more pages exist).

async fn protocol_config(&self) -> Result<ProtocolConfig, Self::Error>

Fetch the chain’s protocol configuration.

async fn reference_gas_price( &self, epoch: impl Into<Option<u64>>, ) -> Result<Option<u64>, Self::Error>

Get the reference gas price

fn objects_by_id( &self, object_ids: &[(ObjectId, Option<Version>)], ) -> impl Future<Output = Result<Vec<Option<Object>>, Self::Error>>

Fetch several objects at once, returning them in the order they were requested with None in place of any object that does not exist.

impl TransactionBuilderSimulationClient for GraphQLClient

type DryRunResult = DryRunResult

The result of a dry run.

async fn estimate_transaction_budget( &self, transaction: &Transaction, ) -> Result<Option<u64>, Self::Error>

Estimate the gas budget needed for a transaction, typically by simulating it and reading the gas cost from the result. Ok(None) means no estimate is available; finish then fails unless a budget was set explicitly.

async fn dry_run_transaction( &self, transaction: &Transaction, skip_checks: bool, ) -> Result<Self::DryRunResult, Self::Error>

Dry run a transaction