Struct sui_sdk::apis::ReadApi

pub struct ReadApi { /* private fields */ }

The main read API structure with functions for retrieving data about different objects and transactions

Implementations

impl ReadApi

pub async fn get_owned_objects( &self, address: SuiAddress, query: Option<SuiObjectResponseQuery>, cursor: Option<ObjectID>, limit: Option<usize>, ) -> SuiRpcResult<ObjectsPage>

Return a paginated response with the objects owned by the given address, or an error upon failure.

Note that if the address owns more than QUERY_MAX_RESULT_LIMIT objects (default is 50), the pagination is not accurate, because previous page may have been updated when the next page is fetched.

Examples

use sui_sdk::SuiClientBuilder;
use sui_types::base_types::SuiAddress;
use std::str::FromStr;

#[tokio::main]
async fn main() -> Result<(), anyhow::Error> {
    let sui = SuiClientBuilder::default().build_localnet().await?;
    let address = SuiAddress::from_str("0x0000....0000")?;
    let owned_objects = sui
        .read_api()
        .get_owned_objects(address, None, None, None)
        .await?;
    Ok(())
}

pub async fn get_dynamic_fields( &self, object_id: ObjectID, cursor: Option<ObjectID>, limit: Option<usize>, ) -> SuiRpcResult<DynamicFieldPage>

Return a paginated response with the dynamic fields owned by the given [ObjectID], or an error upon failure.

The return type is a list of DynamicFieldInfo objects, where the field name is always present, represented as a Move Value.

If the field is a dynamic field, returns the ID of the Field object (which contains both the name and the value). If the field is a dynamic object field, it returns the ID of the Object (the value of the field).

Examples

use sui_sdk::SuiClientBuilder;
use sui_types::base_types::{ObjectID, SuiAddress};
use std::str::FromStr;

#[tokio::main]
async fn main() -> Result<(), anyhow::Error> {
    let sui = SuiClientBuilder::default().build_localnet().await?;
    let address = SuiAddress::from_str("0x0000....0000")?;
    let owned_objects = sui
        .read_api()
        .get_owned_objects(address, None, None, None)
        .await?;
    // this code example assumes that there are previous owned objects
    let object = owned_objects.data.get(0).expect(&format!(
        "No owned objects for this address {}",
        address
    ));
    let object_data = object.data.as_ref().expect(&format!(
        "No object data for this SuiObjectResponse {:?}",
        object
    ));
    let object_id = object_data.object_id;
    let dynamic_fields = sui
        .read_api()
        .get_dynamic_fields(object_id, None, None)
        .await?;
    Ok(())
}

pub async fn get_dynamic_field_object( &self, parent_object_id: ObjectID, name: DynamicFieldName, ) -> SuiRpcResult<SuiObjectResponse>

Return the dynamic field object information for a specified object.

pub async fn try_get_parsed_past_object( &self, object_id: ObjectID, version: SequenceNumber, options: SuiObjectDataOptions, ) -> SuiRpcResult<SuiPastObjectResponse>

Return a parsed past object for the provided [ObjectID] and version, or an error upon failure.

An object’s version increases (though it is not guaranteed that it increases always by 1) when the object is mutated. A past object can be used to understand how the object changed over time, i.e. what was the total balance at a specific version.

Examples

use sui_sdk::SuiClientBuilder;
use sui_types::base_types::{ObjectID, SuiAddress};
use sui_json_rpc_types::SuiObjectDataOptions;
use std::str::FromStr;

#[tokio::main]
async fn main() -> Result<(), anyhow::Error> {
    let sui = SuiClientBuilder::default().build_localnet().await?;
    let address = SuiAddress::from_str("0x0000....0000")?;
    let owned_objects = sui
        .read_api()
        .get_owned_objects(address, None, None, None)
        .await?;
    // this code example assumes that there are previous owned objects
    let object = owned_objects.data.get(0).expect(&format!(
        "No owned objects for this address {}",
        address
    ));
    let object_data = object.data.as_ref().expect(&format!(
        "No object data for this SuiObjectResponse {:?}",
        object
    ));
    let object_id = object_data.object_id;
    let version = object_data.version;
    let past_object = sui
        .read_api()
        .try_get_parsed_past_object(
            object_id,
            version,
            SuiObjectDataOptions {
                show_type: true,
                show_owner: true,
                show_previous_transaction: true,
                show_display: true,
                show_content: true,
                show_bcs: true,
                show_storage_rebate: true,
            },
        )
        .await?;
    Ok(())
}

pub async fn try_multi_get_parsed_past_object( &self, past_objects: Vec<SuiGetPastObjectRequest>, options: SuiObjectDataOptions, ) -> SuiRpcResult<Vec<SuiPastObjectResponse>>

Return a list of [SuiPastObjectResponse] objects, or an error upon failure.

See this function for more details about past objects.

Examples

use sui_sdk::SuiClientBuilder;
use sui_types::base_types::{ObjectID, SuiAddress};
use sui_json_rpc_types::{SuiObjectDataOptions, SuiGetPastObjectRequest};
use std::str::FromStr;

#[tokio::main]
async fn main() -> Result<(), anyhow::Error> {
    let sui = SuiClientBuilder::default().build_localnet().await?;
    let address = SuiAddress::from_str("0x0000....0000")?;
    let owned_objects = sui
        .read_api()
        .get_owned_objects(address, None, None, None)
        .await?;
    // this code example assumes that there are previous owned objects
    let object = owned_objects.data.get(0).expect(&format!(
        "No owned objects for this address {}",
        address
    ));
    let object_data = object.data.as_ref().expect(&format!(
        "No object data for this SuiObjectResponse {:?}",
        object
    ));
    let object_id = object_data.object_id;
    let version = object_data.version;
    let past_object = sui
        .read_api()
        .try_get_parsed_past_object(
            object_id,
            version,
            SuiObjectDataOptions {
                show_type: true,
                show_owner: true,
                show_previous_transaction: true,
                show_display: true,
                show_content: true,
                show_bcs: true,
                show_storage_rebate: true,
            },
        )
        .await?;
    let past_object = past_object.into_object()?;
    let multi_past_object = sui
        .read_api()
        .try_multi_get_parsed_past_object(
            vec![SuiGetPastObjectRequest {
                object_id: past_object.object_id,
                version: past_object.version,
            }],
            SuiObjectDataOptions {
                show_type: true,
                show_owner: true,
                show_previous_transaction: true,
                show_display: true,
                show_content: true,
                show_bcs: true,
                show_storage_rebate: true,
            },
        )
        .await?;
    Ok(())
}

pub async fn get_object_with_options( &self, object_id: ObjectID, options: SuiObjectDataOptions, ) -> SuiRpcResult<SuiObjectResponse>

Return a [SuiObjectResponse] based on the provided [ObjectID] and [SuiObjectDataOptions], or an error upon failure.

The [SuiObjectResponse] contains two fields:

1. data for the object’s data (see SuiObjectData),
2. error for the error (if any) (see SuiObjectResponseError).

Examples

use sui_sdk::SuiClientBuilder;
use sui_types::base_types::SuiAddress;
use sui_json_rpc_types::SuiObjectDataOptions;
use std::str::FromStr;

#[tokio::main]
async fn main() -> Result<(), anyhow::Error> {
    let sui = SuiClientBuilder::default().build_localnet().await?;
    let address = SuiAddress::from_str("0x0000....0000")?;
    let owned_objects = sui
        .read_api()
        .get_owned_objects(address, None, None, None)
        .await?;
    // this code example assumes that there are previous owned objects
    let object = owned_objects.data.get(0).expect(&format!(
        "No owned objects for this address {}",
        address
    ));
    let object_data = object.data.as_ref().expect(&format!(
        "No object data for this SuiObjectResponse {:?}",
        object
    ));
    let object_id = object_data.object_id;
    let object = sui.read_api().get_object_with_options(object_id,
            SuiObjectDataOptions {
                show_type: true,
                show_owner: true,
                show_previous_transaction: true,
                show_display: true,
                show_content: true,
                show_bcs: true,
                show_storage_rebate: true,
            },
        ).await?;
    Ok(())
}

pub async fn multi_get_object_with_options( &self, object_ids: Vec<ObjectID>, options: SuiObjectDataOptions, ) -> SuiRpcResult<Vec<SuiObjectResponse>>

Return a list of [SuiObjectResponse] from the given vector of [ObjectID]s and [SuiObjectDataOptions], or an error upon failure.

If only one object is needed, use the get_object_with_options function instead.

Examples

use sui_sdk::SuiClientBuilder;
use sui_types::base_types::SuiAddress;
use sui_json_rpc_types::SuiObjectDataOptions;
use std::str::FromStr;
#[tokio::main]
async fn main() -> Result<(), anyhow::Error> {
    let sui = SuiClientBuilder::default().build_localnet().await?;
    let address = SuiAddress::from_str("0x0000....0000")?;
    let owned_objects = sui
        .read_api()
        .get_owned_objects(address, None, None, None)
        .await?;
    // this code example assumes that there are previous owned objects
    let object = owned_objects.data.get(0).expect(&format!(
        "No owned objects for this address {}",
        address
    ));
    let object_data = object.data.as_ref().expect(&format!(
        "No object data for this SuiObjectResponse {:?}",
        object
    ));
    let object_id = object_data.object_id;
    let object_ids = vec![object_id]; // and other object ids
    let object = sui.read_api().multi_get_object_with_options(object_ids,
            SuiObjectDataOptions {
                show_type: true,
                show_owner: true,
                show_previous_transaction: true,
                show_display: true,
                show_content: true,
                show_bcs: true,
                show_storage_rebate: true,
            },
        ).await?;
    Ok(())
}

pub async fn get_move_object_bcs( &self, object_id: ObjectID, ) -> SuiRpcResult<Vec<u8>>

Return An object’s bcs content Vec<u8> based on the provided [ObjectID], or an error upon failure.

pub async fn get_total_transaction_blocks(&self) -> SuiRpcResult<u64>

Return the total number of transaction blocks known to server, or an error upon failure.

Examples

use sui_sdk::SuiClientBuilder;

#[tokio::main]
async fn main() -> Result<(), anyhow::Error> {
    let sui = SuiClientBuilder::default().build_localnet().await?;
    let total_transaction_blocks = sui
        .read_api()
        .get_total_transaction_blocks()
        .await?;
    Ok(())
}

pub async fn get_transaction_with_options( &self, digest: TransactionDigest, options: SuiTransactionBlockResponseOptions, ) -> SuiRpcResult<SuiTransactionBlockResponse>

Return a transaction and its effects in a [SuiTransactionBlockResponse] based on its [TransactionDigest], or an error upon failure.

pub async fn multi_get_transactions_with_options( &self, digests: Vec<TransactionDigest>, options: SuiTransactionBlockResponseOptions, ) -> SuiRpcResult<Vec<SuiTransactionBlockResponse>>

Return a list of [SuiTransactionBlockResponse] based on the given vector of [TransactionDigest], or an error upon failure.

If only one transaction data is needed, use the get_transaction_with_options function instead.

pub async fn get_committee_info( &self, epoch: Option<BigInt<u64>>, ) -> SuiRpcResult<SuiCommittee>

Return the [SuiCommittee] information for the provided epoch, or an error upon failure.

The [SuiCommittee] contains the validators list and their information (name and stakes).

The argument epoch is either a known epoch id or None for the current epoch.

Examples

use sui_sdk::SuiClientBuilder;

#[tokio::main]
async fn main() -> Result<(), anyhow::Error> {
    let sui = SuiClientBuilder::default().build_localnet().await?;
    let committee_info = sui
        .read_api()
        .get_committee_info(None)
        .await?;
    Ok(())
}

pub async fn query_transaction_blocks( &self, query: SuiTransactionBlockResponseQuery, cursor: Option<TransactionDigest>, limit: Option<usize>, descending_order: bool, ) -> SuiRpcResult<TransactionBlocksPage>

Return a paginated response with all transaction blocks information, or an error upon failure.

pub async fn get_chain_identifier(&self) -> SuiRpcResult<String>

Return the first four bytes of the chain’s genesis checkpoint digest, or an error upon failure.

pub async fn get_checkpoint(&self, id: CheckpointId) -> SuiRpcResult<Checkpoint>

Return a checkpoint, or an error upon failure.

A Sui checkpoint is a sequence of transaction sets that a quorum of validators agree upon as having been executed within the Sui system.

pub async fn get_checkpoints( &self, cursor: Option<BigInt<u64>>, limit: Option<usize>, descending_order: bool, ) -> SuiRpcResult<CheckpointPage>

Return a paginated list of checkpoints, or an error upon failure.

pub async fn get_latest_checkpoint_sequence_number( &self, ) -> SuiRpcResult<CheckpointSequenceNumber>

Return the sequence number of the latest checkpoint that has been executed, or an error upon failure.

pub fn get_transactions_stream( &self, query: SuiTransactionBlockResponseQuery, cursor: Option<TransactionDigest>, descending_order: bool, ) -> impl Stream<Item = SuiTransactionBlockResponse> + '_

Return a stream of [SuiTransactionBlockResponse], or an error upon failure.

pub async fn subscribe_transaction( &self, filter: TransactionFilter, ) -> SuiRpcResult<impl Stream<Item = SuiRpcResult<SuiTransactionBlockEffects>>>

Subscribe to a stream of transactions.

This is only available through WebSockets.

pub async fn get_normalized_move_modules_by_package( &self, package: ObjectID, ) -> SuiRpcResult<BTreeMap<String, SuiMoveNormalizedModule>>

Return a map consisting of the move package name and the normalized module, or an error upon failure.

pub async fn get_reference_gas_price(&self) -> SuiRpcResult<u64>

Return the reference gas price, or an error upon failure.

pub async fn dry_run_transaction_block( &self, tx: TransactionData, ) -> SuiRpcResult<DryRunTransactionBlockResponse>

Dry run a transaction block given the provided transaction data. Returns an error upon failure.

Simulate running the transaction, including all standard checks, without actually running it. This is useful for estimating the gas fees of a transaction before executing it. You can also use it to identify any side-effects of a transaction before you execute it on the network.

pub async fn dev_inspect_transaction_block( &self, sender_address: SuiAddress, tx: TransactionKind, gas_price: Option<BigInt<u64>>, epoch: Option<BigInt<u64>>, additional_args: Option<DevInspectArgs>, ) -> SuiRpcResult<DevInspectResults>

Return the inspection of the transaction block, or an error upon failure.

Use this function to inspect the current state of the network by running a programmable transaction block without committing its effects on chain. Unlike dry_run_transaction_block, dev inspect will not validate whether the transaction block would succeed or fail under normal circumstances, e.g.:

• Transaction inputs are not checked for ownership (i.e. you can construct calls involving objects you do not own).
• Calls are not checked for visibility (you can call private functions on modules)
• Inputs of any type can be constructed and passed in, (including Coins and other objects that would usually need to be constructed with a move call).
• Function returns do not need to be used, even if they do not have drop.

Dev inspect’s output includes a breakdown of results returned by every transaction in the block, as well as the transaction’s effects.

To run an accurate simulation of a transaction and understand whether it will successfully validate and run, use the dry_run_transaction_block function instead.

pub async fn get_protocol_config( &self, version: Option<BigInt<u64>>, ) -> SuiRpcResult<ProtocolConfigResponse>

Return the protocol config, or an error upon failure.

pub async fn try_get_object_before_version( &self, object_id: ObjectID, version: SequenceNumber, ) -> SuiRpcResult<SuiPastObjectResponse>

Trait Implementations

impl DataReader for ReadApi

fn get_reference_gas_price<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<u64, Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Returns the reference gas price as a u64 or an error otherwise

fn get_owned_objects<'life0, 'async_trait>( &'life0 self, address: SuiAddress, object_type: StructTag, ) -> Pin<Box<dyn Future<Output = Result<Vec<ObjectInfo>, Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

fn get_object_with_options<'life0, 'async_trait>( &'life0 self, object_id: ObjectID, options: SuiObjectDataOptions, ) -> Pin<Box<dyn Future<Output = Result<SuiObjectResponse, Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

impl Debug for ReadApi

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

Formats the value using the given formatter.