Struct Client 

pub struct Client { /* private fields */ }

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

Implementations

impl Client

pub fn set_rpc_server(&mut self, server: &str) -> Result<()>

Set the server address for the GraphQL GraphQL client. It should be a valid URL with a host and optionally a port number.

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

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

pub fn coins_stream( &self, address: Address, coin_type: impl Into<Option<StructTag>>, streaming_direction: Direction, ) -> impl Stream<Item = Result<Coin>> + '_

Get the list of coins for the specified address as a stream.

If coin_type is not provided, all coins will be returned. For IOTA coins, pass in the coin type: 0x2::iota::IOTA.

pub fn gas_coins_stream( &self, address: Address, streaming_direction: Direction, ) -> impl Stream<Item = Result<Coin>> + '_

Get the list of gas coins for the specified address as a stream.

pub fn checkpoints_stream( &self, streaming_direction: Direction, ) -> impl Stream<Item = Result<CheckpointSummary>> + '_

Get a stream of CheckpointSummary. Note that this will fetch all checkpoints which may trigger a lot of requests.

pub fn dynamic_fields_stream( &self, address: Address, streaming_direction: Direction, ) -> impl Stream<Item = Result<DynamicFieldOutput>> + '_

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

pub fn events_stream( &self, filter: impl Into<Option<EventFilter>>, streaming_direction: Direction, ) -> impl Stream<Item = Result<Event>> + '_

Return a stream of events based on the (optional) event filter.

pub fn objects_stream( &self, filter: impl Into<Option<ObjectFilter>>, streaming_direction: Direction, ) -> impl Stream<Item = Result<Object>> + '_

Return a stream of objects based on the (optional) object filter.

pub async fn dry_run_tx( &self, tx: &Transaction, skip_checks: bool, ) -> Result<DryRunResult>

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

The skip_checks flag disables the usual verification checks that prevent access to objects that are owned by addresses other than the sender, and calling non-public, non-entry functions, and some other checks.

pub async fn dry_run_tx_kind( &self, tx_kind: &TransactionKind, skip_checks: bool, tx_meta: TransactionMetadata, ) -> Result<DryRunResult>

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

skipChecks optional flag disables the usual verification checks that prevent access to objects that are owned by addresses other than the sender, and calling non-public, non-entry functions, and some other checks. Defaults to false.

tx_meta is the transaction metadata.

pub fn transactions_stream( &self, filter: impl Into<Option<TransactionsFilter>>, streaming_direction: Direction, ) -> impl Stream<Item = Result<SignedTransaction>> + '_

Get a stream of transactions based on the (optional) transaction filter.

pub fn transactions_effects_stream( &self, filter: impl Into<Option<TransactionsFilter>>, streaming_direction: Direction, ) -> impl Stream<Item = Result<TransactionEffects>> + '_

Get a stream of transactions’ effects based on the (optional) transaction filter.

pub async fn run_query<T, V>(&self, operation: &Operation<T, V>) -> Result<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>, ) -> Result<GraphQlResponse<Value>>

Run a JSON query on the GraphQL server and return the response. This method expects a JSON map holding the GraphQL query string and matching GraphQL variables. It returns a cynic::GraphQlResponse wrapping a serde_json::Value. In general, it is recommended to use run_query which guarantees valid GraphQL query syntax and returns a proper response type.

pub async fn balance( &self, address: Address, coin_type: impl Into<Option<String>>, ) -> Result<Option<u64>>

Get the balance of all the coins owned by address for the provided coin type. Coin type will default to 0x2::coin::Coin<0x2::iota::IOTA> if not provided.

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

Create a new GraphQL client with the provided server address.

pub fn new_mainnet() -> Self

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

pub fn new_testnet() -> Self

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

pub fn new_devnet() -> Self

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

pub fn new_localnet() -> Self

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

pub async fn chain_id(&self) -> Result<String>

Get the chain identifier.

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 async fn max_page_size(&self) -> Result<i32>

Lazily fetch the max page size

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

Get the reference gas price for the provided epoch or the last known one if no epoch is provided.

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

pub async fn protocol_config( &self, version: impl Into<Option<u64>>, ) -> Result<ProtocolConfigs>

Get the protocol configuration.

pub async fn active_validators( &self, epoch: impl Into<Option<u64>>, pagination_filter: PaginationFilter, ) -> Result<Page<Validator>>

Get the list of active validators for the provided epoch, including related metadata. If no epoch is provided, it will return the active validators for the current epoch.

pub async fn total_transaction_blocks_by_digest( &self, digest: Digest, ) -> Result<Option<u64>>

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

pub async fn total_transaction_blocks_by_seq_num( &self, seq_num: u64, ) -> Result<Option<u64>>

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

pub async fn total_transaction_blocks(&self) -> Result<Option<u64>>

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

pub async fn coins( &self, owner: Address, coin_type: impl Into<Option<StructTag>>, pagination_filter: PaginationFilter, ) -> Result<Page<Coin>>

Get the list of coins for the specified address.

If coin_type is not provided, all coins will be returned. For IOTA coins, pass in the coin type: 0x2::iota::IOTA.

pub async fn gas_coins( &self, owner: Address, pagination_filter: PaginationFilter, ) -> Result<Page<Coin>>

Get the list of gas coins for the specified address.

pub async fn coin_metadata( &self, coin_type: &str, ) -> Result<Option<CoinMetadata>>

Get the coin metadata for the coin type.

pub async fn total_supply(&self, coin_type: &str) -> Result<Option<u64>>

Get total supply for the coin type.

pub async fn checkpoint( &self, digest: impl Into<Option<Digest>>, seq_num: impl Into<Option<u64>>, ) -> Result<Option<CheckpointSummary>>

Get the CheckpointSummary for a given checkpoint digest or checkpoint id. If none is provided, it will use the last known checkpoint id.

pub async fn checkpoints( &self, pagination_filter: PaginationFilter, ) -> Result<Page<CheckpointSummary>>

Get a page of CheckpointSummary for the provided parameters.

pub async fn latest_checkpoint_sequence_number( &self, ) -> Result<Option<CheckpointSequenceNumber>>

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

pub async fn epoch( &self, epoch: impl Into<Option<u64>>, ) -> Result<Option<Epoch>>

Return the epoch information for the provided epoch. If no epoch is provided, it will return the last known epoch.

pub async fn epoch_total_checkpoints( &self, epoch: impl Into<Option<u64>>, ) -> Result<Option<u64>>

Return the number of checkpoints in this epoch. This will return Ok(None) if the epoch requested is not available in the GraphQL service (e.g., due to pruning).

pub async fn epoch_total_transaction_blocks( &self, epoch: impl Into<Option<u64>>, ) -> Result<Option<u64>>

Return the number of transaction blocks in this epoch. This will return Ok(None) if the epoch requested is not available in the GraphQL service (e.g., due to pruning).

pub async fn events( &self, filter: impl Into<Option<EventFilter>>, pagination_filter: PaginationFilter, ) -> Result<Page<Event>>

Return a page of events based on the (optional) event filter.

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

Return an object based on the provided Address.

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

pub async fn objects( &self, filter: impl Into<Option<ObjectFilter>>, pagination_filter: PaginationFilter, ) -> Result<Page<Object>>

Return a page of objects based on the provided parameters.

Use this function together with the ObjectFilter::owner to get the objects owned by an address.

Example

let filter = ObjectFilter {
    type_: None,
    owner: Some(Address::from_str("test").unwrap().into()),
    object_ids: None,
};

let owned_objects = client.objects(None, None, Some(filter), None, None).await;

pub async fn object_bcs(&self, object_id: ObjectId) -> Result<Option<Vec<u8>>>

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

pub async fn move_object_contents_bcs( &self, object_id: ObjectId, version: impl Into<Option<u64>>, ) -> Result<Option<Vec<u8>>>

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

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

pub async fn package( &self, address: Address, version: impl Into<Option<u64>>, ) -> Result<Option<MovePackage>>

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 async fn package_versions( &self, address: Address, pagination_filter: PaginationFilter, after_version: impl Into<Option<u64>>, before_version: impl Into<Option<u64>>, ) -> Result<Page<MovePackage>>

Fetch all versions of package at address (packages that share this package’s original ID), optionally bounding the versions exclusively from below with afterVersion, or from above with beforeVersion.

pub async fn package_latest( &self, address: Address, ) -> Result<Option<MovePackage>>

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 async fn packages( &self, pagination_filter: PaginationFilter, after_checkpoint: impl Into<Option<u64>>, before_checkpoint: impl Into<Option<u64>>, ) -> Result<Page<MovePackage>>

The Move packages that exist in the network, optionally filtered to be strictly before beforeCheckpoint and/or strictly after afterCheckpoint.

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 async fn transaction( &self, digest: Digest, ) -> Result<Option<SignedTransaction>>

Get a transaction by its digest.

pub async fn transaction_effects( &self, digest: Digest, ) -> Result<Option<TransactionEffects>>

Get a transaction’s effects by its digest.

pub async fn transaction_data_effects( &self, digest: Digest, ) -> Result<Option<TransactionDataEffects>>

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

pub async fn transactions( &self, filter: impl Into<Option<TransactionsFilter>>, pagination_filter: PaginationFilter, ) -> Result<Page<SignedTransaction>>

Get a page of transactions based on the provided filters.

pub async fn transactions_effects( &self, filter: impl Into<Option<TransactionsFilter>>, pagination_filter: PaginationFilter, ) -> Result<Page<TransactionEffects>>

Get a page of transactions’ effects based on the provided filters.

pub async fn transactions_data_effects( &self, filter: impl Into<Option<TransactionsFilter>>, pagination_filter: PaginationFilter, ) -> Result<Page<TransactionDataEffects>>

Get a page of transactions’ data and effects based on the provided filters.

pub async fn execute_tx( &self, signatures: &[UserSignature], tx: &Transaction, wait_for: impl Into<Option<WaitForTx>>, ) -> Result<TransactionEffects>

Execute a transaction.

pub async fn is_tx_indexed_on_node(&self, digest: Digest) -> Result<bool>

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

pub async fn is_tx_finalized(&self, digest: Digest) -> Result<bool>

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

pub async fn wait_for_tx( &self, digest: Digest, wait_for: WaitForTx, timeout: impl Into<Option<Duration>>, ) -> Result<()>

Wait for the indexing or finalization of a transaction by its digest. An optional timeout can be provided, which, if exceeded, will return an error (default 60s).

pub async fn normalized_move_function( &self, package: Address, module: &str, function: &str, version: impl Into<Option<u64>>, ) -> Result<Option<MoveFunction>>

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

pub async fn move_object_contents( &self, object_id: ObjectId, version: impl Into<Option<u64>>, ) -> Result<Option<Value>>

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 return Ok(None). Similarly, if this is not an object but an address, it will return Ok(None).

pub async fn normalized_move_module( &self, package: Address, module: &str, version: impl Into<Option<u64>>, pagination_filter_enums: PaginationFilter, pagination_filter_friends: PaginationFilter, pagination_filter_functions: PaginationFilter, pagination_filter_structs: PaginationFilter, ) -> Result<Option<MoveModule>>

Return the normalized Move module data for the provided module.

pub async fn dynamic_field( &self, address: Address, type_: TypeTag, name: impl Into<NameValue>, ) -> Result<Option<DynamicFieldOutput>>

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::Client::new_devnet();
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 async fn dynamic_object_field( &self, address: Address, type_: TypeTag, name: impl Into<NameValue>, ) -> Result<Option<DynamicFieldOutput>>

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 async fn dynamic_fields( &self, address: Address, pagination_filter: PaginationFilter, ) -> Result<Page<DynamicFieldOutput>>

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

This returns Page of DynamicFieldOutputs.

pub async fn iota_names_lookup(&self, name: &str) -> Result<Option<Address>>

Return the resolved address for the given name.

pub async fn iota_names_registrations( &self, address: Address, pagination_filter: PaginationFilter, ) -> Result<Page<NameRegistration>>

Find all registration NFTs for the given address.

pub async fn iota_names_default_name( &self, address: Address, format: impl Into<Option<NameFormat>>, ) -> Result<Option<Name>>

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

Trait Implementations

impl Clone for Client

fn clone(&self) -> Client

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Client

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

Formats the value using the given formatter.