Struct Client 

pub struct Client { /* private fields */ }

A gRPC client for the Sui fullnode RPC interface.

RPCs made through a client and its clones are multiplexed over a single HTTP/2 connection by default; see with_num_connections to spread them over several.

Ledger streams

Client provides two styles of stream operations for checkpoints, transactions, and events:

• list_* (list_checkpoints, list_transactions, list_events): Finite pagination streams yielding raw response pages until reaching an end bound or the ledger tip.
• stream_* (stream_checkpoints, stream_transactions, stream_events): Resumable, infinite streams starting from any position (Tip, Checkpoint, or Resume cursor) that automatically handle backfill replay, live subscription or polling, and transient error retries.

Stream read masks must include sequence_number for checkpoints; checkpoint and transaction_index for transactions; and checkpoint, transaction_index, and event_index for events ("*" satisfies all three).

Process a payload before persisting its restart position. To resume after a checkpoint, pass cursor + 1 to CheckpointStreamStart::Checkpoint. To resume transactions or events, pass frame.cursor to TransactionStreamStart::Resume or EventStreamStart::Resume.

Example

let client = Client::new(Client::MAINNET_FULLNODE)?;
let read_mask = FieldMask::from_paths(["checkpoint", "transaction_index", "digest"]);
let request = TransactionStreamRequest::new().with_read_mask(read_mask.clone());

let mut stream = Box::pin(client.stream_transactions(request));
let persisted = loop {
    let Some(frame) = stream.next().await else {
        return Ok(());
    };
    let frame = frame?;

    if let Some(transaction) = &frame.transaction {
        process_transaction(transaction).await;
    }
    let persisted = frame.cursor.clone();
    persist_position(&persisted).await;
    break persisted;
};
drop(stream);

let restart_request = TransactionStreamRequest::new()
    .with_read_mask(read_mask)
    .with_start(TransactionStreamStart::Resume(persisted));
let mut resumed = Box::pin(client.stream_transactions(restart_request));
let _ = resumed.next().await;

Timeouts and deadlines

No default bounds the total duration of a call. Two opt-in bounds are available:

• A per-call deadline set with [tonic::Request::set_timeout]. This attaches the standard grpc-timeout header, so a server that supports it enforces the deadline too, and the client enforces it locally end to end: tonic bounds the wait for response headers, and the client’s watchdog (see with_body_idle_timeout) bounds the response body against the same deadline. The ledger-stream list_* and stream_* methods do not accept tonic::Request. One logical operation may issue several RPCs, so per-RPC authentication, common headers, tracing, and timeouts belong on the client: static headers on Client::with_headers, dynamic per-RPC auth or tracing on Client::request_layer. Configuring a Cloned client affects only that clone and shares the underlying connection, so a single stream gets dedicated headers by receiving a configured clone.
• A client-wide response-headers timeout set with with_response_headers_timeout. This is enforced locally only and its timer stops once response headers arrive, so it bounds every unary call (whose headers are not sent until the handler completes) without cutting off long-lived streams.

Independent of any deadline, the watchdog resets RPCs whose response body makes no progress for 30 seconds (configurable), so a call on a stalled connection fails with DeadlineExceeded instead of hanging forever.

Implementations

impl Client

pub async fn get_delegated_stake( &mut self, staked_sui_id: &Address, ) -> Result<DelegatedStake, Status>

pub async fn list_delegated_stake( &mut self, address: &Address, ) -> Result<Vec<DelegatedStake>, Status>

pub async fn calculate_rewards( &mut self, staked_sui_ids: &[Address], ) -> Result<Vec<(Address, u64)>, Status>

pub async fn get_validator_address_by_pool_id( &mut self, pool_ids: &[Address], ) -> Result<Vec<(Address, Address)>, Status>

impl Client

pub async fn select_coins( &self, owner_address: &Address, coin_type: &TypeTag, amount: u64, exclude: &[Address], ) -> Result<Vec<Object>, Status>

Selects coins of a specific type owned by an address until the total value meets the required amount.

Arguments

• owner_address - The address that owns the coins
• coin_type - The TypeTag of coins to select
• amount - The minimum total amount needed
• exclude - Array of addresses to exclude from selection

Returns

A vector of Object instances representing the selected coins

Errors

Returns an error if there are insufficient funds to meet the required amount or if there is an RPC error

pub async fn select_up_to_n_largest_coins( &self, owner_address: &Address, coin_type: &TypeTag, n: usize, exclude: &[Address], ) -> Result<Vec<Object>, Status>

Selects up to N coins of a specific type owned by an address.

Arguments

• owner_address - The address that owns the coins
• coin_type - The TypeTag of coins to select
• n - The maximum number of coins to select
• exclude - Array of addresses to exclude from selection

Returns

A vector of Object instances representing the selected coins (may be fewer than n if not enough coins are available)

Errors

Returns an error if there is an RPC error during coin retrieval

impl Client

pub fn list_checkpoints( &self, request: ListCheckpointsRequest, ) -> impl Stream<Item = Result<ListCheckpointsResponse, Status>> + Send + 'static

Paginates ListCheckpoints requests into a stream of raw response pages.

Automatically follows ItemLimit and ScanLimit pagination until reaching the request’s end bound or the ledger tip.

pub fn list_checkpoints_with_config( &self, request: ListCheckpointsRequest, config: ListConfig, ) -> impl Stream<Item = Result<ListCheckpointsResponse, Status>> + Send + 'static

Performs Client::list_checkpoints using config.

pub fn stream_checkpoints( &self, request: CheckpointStreamRequest, ) -> impl Stream<Item = Result<CheckpointStreamFrame, Status>> + Send + 'static

Streams checkpoints indefinitely, automatically retrying transient errors.

The request’s read mask must include sequence_number (or *). To resume after a previous checkpoint, pass cursor + 1 to CheckpointStreamStart::Checkpoint.

For a finite read that stops at a bound, use Client::list_checkpoints.

pub fn stream_checkpoints_with_config( &self, request: CheckpointStreamRequest, config: LedgerStreamConfig, ) -> impl Stream<Item = Result<CheckpointStreamFrame, Status>> + Send + 'static

Performs Client::stream_checkpoints using config.

pub fn list_transactions( &self, request: ListTransactionsRequest, ) -> impl Stream<Item = Result<ListTransactionsResponse, Status>> + Send + 'static

Paginates ListTransactions requests into a stream of raw response pages.

Automatically follows ItemLimit and ScanLimit pagination until reaching the request’s end bound or the ledger tip.

pub fn list_transactions_with_config( &self, request: ListTransactionsRequest, config: ListConfig, ) -> impl Stream<Item = Result<ListTransactionsResponse, Status>> + Send + 'static

Performs Client::list_transactions using config.

pub fn stream_transactions( &self, request: TransactionStreamRequest, ) -> impl Stream<Item = Result<TransactionStreamFrame, Status>> + Send + 'static

Streams transactions indefinitely, automatically retrying transient errors.

The request’s read mask must include checkpoint and transaction_index (or *). To resume from a previous frame, pass frame.cursor to TransactionStreamStart::Resume.

For a finite read that stops at a bound, use Client::list_transactions.

pub fn stream_transactions_with_config( &self, request: TransactionStreamRequest, config: LedgerStreamConfig, ) -> impl Stream<Item = Result<TransactionStreamFrame, Status>> + Send + 'static

Performs Client::stream_transactions using config.

pub fn list_events( &self, request: ListEventsRequest, ) -> impl Stream<Item = Result<ListEventsResponse, Status>> + Send + 'static

Paginates ListEvents requests into a stream of raw response pages.

Automatically follows ItemLimit and ScanLimit pagination until reaching the request’s end bound or the ledger tip.

pub fn list_events_with_config( &self, request: ListEventsRequest, config: ListConfig, ) -> impl Stream<Item = Result<ListEventsResponse, Status>> + Send + 'static

Performs Client::list_events using config.

pub fn stream_events( &self, request: EventStreamRequest, ) -> impl Stream<Item = Result<EventStreamFrame, Status>> + Send + 'static

Streams events indefinitely, automatically retrying transient errors.

The request’s read mask must include checkpoint, transaction_index, and event_index (or *). To resume from a previous frame, pass frame.cursor to EventStreamStart::Resume.

For a finite read that stops at a bound, use Client::list_events.

pub fn stream_events_with_config( &self, request: EventStreamRequest, config: LedgerStreamConfig, ) -> impl Stream<Item = Result<EventStreamFrame, Status>> + Send + 'static

Performs Client::stream_events using config.

impl Client

pub fn list_owned_objects( &self, request: impl IntoRequest<ListOwnedObjectsRequest>, ) -> impl Stream<Item = Result<Object, Status>> + 'static

Creates a stream of objects based on the provided request.

The stream handles pagination automatically by using the page_token from responses to fetch subsequent pages. The original request’s page_token is used as the starting point.

Arguments

• request - The initial ListOwnedObjectsRequest with search criteria

Returns

A stream that yields Result<Object> instances. If any RPC call fails, the tonic::Status from that request is returned.

pub fn list_dynamic_fields( &self, request: impl IntoRequest<ListDynamicFieldsRequest>, ) -> impl Stream<Item = Result<DynamicField, Status>> + 'static

Creates a stream of DynamicFields based on the provided request.

The stream handles pagination automatically by using the page_token from responses to fetch subsequent pages. The original request’s page_token is used as the starting point.

Arguments

• request - The initial ListDynamicFieldsRequest with search criteria

Returns

A stream that yields Result<DynamicField> instances. If any RPC call fails, the tonic::Status from that request is returned.

pub fn list_balances( &self, request: impl IntoRequest<ListBalancesRequest>, ) -> impl Stream<Item = Result<Balance, Status>> + 'static

Creates a stream of Balances based on the provided request.

The stream handles pagination automatically by using the page_token from responses to fetch subsequent pages. The original request’s page_token is used as the starting point.

Arguments

• request - The initial ListBalancesRequest with search criteria

Returns

A stream that yields Result<Balance> instances. If any RPC call fails, the tonic::Status from that request is returned.

pub fn list_package_versions( &self, request: impl IntoRequest<ListPackageVersionsRequest>, ) -> impl Stream<Item = Result<PackageVersion, Status>> + 'static

Creates a stream of PackageVersions based on the provided request.

The stream handles pagination automatically by using the page_token from responses to fetch subsequent pages. The original request’s page_token is used as the starting point.

Arguments

• request - The initial ListPackageVersionsRequest with search criteria

Returns

A stream that yields Result<PackageVersion> instances. If any RPC call fails, the tonic::Status from that request is returned.

impl Client

pub async fn execute_transaction_and_wait_for_checkpoint( &mut self, request: impl IntoRequest<ExecuteTransactionRequest>, timeout: Duration, ) -> Result<Response<ExecuteTransactionResponse>, ExecuteAndWaitError>

Executes a transaction and waits for it to be included in a checkpoint.

This method provides “read your writes” consistency by executing the transaction and waiting for it to appear in a checkpoint, which gauruntees indexes have been updated on this node.

Arguments

• request - The transaction execution request (ExecuteTransactionRequest)
• timeout - Maximum time to wait for indexing confirmation

Returns

A Result containing the response if the transaction was executed and checkpoint confirmed, or an error that may still include the response if execution succeeded but checkpoint confirmation failed.

Duplicate submissions

Submitting a transaction that has already been executed is handled gracefully. While the execution RPC is in flight the ledger is probed for the transaction, and a transaction that is already in a checkpoint is returned without waiting for execution to finish. Likewise, if execution fails but the ledger shows the transaction in a checkpoint (for example when a resubmission races the original submission), the execution error is discarded and the committed transaction is returned. In both cases the response is assembled from GetTransaction using the request’s read mask, so it carries the same fields an execution response would, with digest, checkpoint, and timestamp always populated.

pub async fn get_reference_gas_price(&mut self) -> Result<u64, Status>

Retrieves the current reference gas price from the latest epoch information.

Returns

The reference gas price as a u64

Errors

Returns an error if there is an RPC error when fetching the epoch information

impl Client

pub const MAINNET_FULLNODE: &str = "https://fullnode.mainnet.sui.io"

URL for the public-good, Sui Foundation provided fullnodes for mainnet.

pub const TESTNET_FULLNODE: &str = "https://fullnode.testnet.sui.io"

URL for the public-good, Sui Foundation provided fullnodes for testnet.

pub const DEVNET_FULLNODE: &str = "https://fullnode.devnet.sui.io"

URL for the public-good, Sui Foundation provided fullnodes for devnet.

pub const MAINNET_ARCHIVE: &str = "https://archive.mainnet.sui.io"

URL for the public-good, Sui Foundation provided archive for mainnet.

pub const TESTNET_ARCHIVE: &str = "https://archive.testnet.sui.io"

URL for the public-good, Sui Foundation provided archive for testnet.

pub fn from_endpoint(endpoint: &Endpoint) -> Self

Build a client from a fully custom [tonic::transport::Endpoint].

This bypasses every transport default that Client::new applies, including the HTTP/2 flow-control windows that protect a connection from starvation by stalled streaming responses. Prefer Client::new plus the with_* configuration methods unless an endpoint setting is needed that the client does not expose. The idle-body watchdog (see Client::with_body_idle_timeout) is part of the client rather than the endpoint and stays enabled.

In particular, do not rely on http2_adaptive_window as a substitute for large static windows: with adaptive windowing, hyper starts the connection window at the 64 KiB HTTP/2 spec default until bandwidth-delay probing ramps up, so a single stalled stream can starve the whole connection.

pub fn new<T>(uri: T) -> Result<Self, Status>

where T: TryInto<Uri>, T::Error: Into<Box<dyn Error + Send + Sync + 'static>>,

pub fn with_body_idle_timeout(self, timeout: Duration) -> Self

Set the idle timeout for the client’s response-body watchdog. Defaults to 30 seconds.

The watchdog bounds the time between response-body progress events: if a whole idle period passes without a frame of the response being delivered to the caller – because the connection is starved or dead, or because the caller has parked a streaming response without polling it – the watchdog resets the stream, releasing the HTTP/2 flow-control window it had pinned, and the call observes a DeadlineExceeded status on its next poll. This is what turns “an RPC on a starved connection hangs forever” into a bounded failure, and what keeps an abandoned stream from starving the shared connection in the first place.

Streams that are legitimately quiet for longer than the timeout (the fullnode’s checkpoint subscription is not: it emits watermarks every few seconds) should raise or disable the watchdog for that call with a BodyIdleTimeout request extension.

pub fn without_body_idle_timeout(self) -> Self

Disable the client’s response-body watchdog (see with_body_idle_timeout).

Without it, an RPC whose response can no longer make progress hangs indefinitely; only disable the watchdog when every call is bounded by the caller. It can be re-enabled for individual requests with a BodyIdleTimeout request extension.

pub fn with_response_headers_timeout(self, timeout: Duration) -> Self

Set a timeout for the response-headers phase of every RPC made through this client. Disabled by default.

The timer covers a request from dispatch on the connection until response headers arrive and is dropped once they do, so a client-wide value does not cut off long-lived streaming responses. Because a server does not send response headers for a unary call until the handler completes, this effectively bounds the total duration of unary calls; the body that follows is bounded by the idle-body watchdog (see with_body_idle_timeout) and, when set, the per-call deadline. Connection establishment is bounded separately by the connect timeout.

This timeout is enforced locally only; it is not communicated to the server. When a per-call deadline ([tonic::Request::set_timeout]) is also set, the shorter of the two bounds the headers phase locally, so a per-call deadline can tighten this bound but never extend it – size the timeout for the slowest expected RPC. Expiry surfaces as DeadlineExceeded.

This rebuilds the underlying channel, so it must be called before the client is used or cloned; earlier clones keep the previous configuration.

pub fn with_num_connections(self, num_connections: usize) -> Self

Set how many HTTP/2 connections the client opens to the endpoint. Defaults to 1; a count of 0 is treated as 1.

Requests are distributed across the connections rather than sharing one connection’s flow-control window and driver task. A single connection’s throughput is bounded by that window and by the one task driving its multiplexed streams, so workloads that keep many streams in flight at once (bulk or streaming reads) can be limited by it well before the server is. Every connection carries the same endpoint configuration, so the window sizes described in with_initial_connection_window_size apply to each one, and the client’s total window budget scales with the count.

Placement is effectively random per request, not a strict rotation, so connections carry equal load only on average. Requests held open concurrently, such as long-lived streams, can land unevenly.

Connections are established lazily and reconnect independently, and one that cannot be established fails only the requests routed to it.

This rebuilds the underlying channel, so it must be called before the client is used or cloned; earlier clones keep the previous configuration.

pub fn with_initial_stream_window_size(self, size: u32) -> Self

Set the HTTP/2 per-stream receive window, in bytes.

This bounds how much unread response data a single RPC can buffer before the server must stop sending on that stream. It also bounds how much of the shared connection window (see with_initial_connection_window_size) one stalled stream can pin. Defaults to 2 MiB.

This rebuilds the underlying channel, so it must be called before the client is used or cloned; earlier clones keep the previous configuration.

pub fn with_initial_connection_window_size(self, size: u32) -> Self

Set the HTTP/2 connection-level receive window, in bytes.

This window is shared by every RPC multiplexed over one of the client’s HTTP/2 connections, including those issued by clones of the client. Response data that the application has not yet read counts against it, so it determines how many concurrently stalled streaming responses it takes to starve a connection and hang every other RPC on it. Defaults to 64 MiB (~32 stalled streams at the default 2 MiB stream window). The window applies per connection, so a client configured with with_num_connections has this much on each.

This rebuilds the underlying channel, so it must be called before the client is used or cloned; earlier clones keep the previous configuration.

pub fn with_headers(self, headers: HeadersInterceptor) -> Self

pub fn request_layer<L, ResBody, E>(self, layer: L) -> Self

where L: Layer<BoxService<Request<Body>, Response<Body>, Box<dyn Error + Send + Sync + 'static>>> + Send + Sync + 'static, L::Service: Service<Request<Body>, Response = Response<ResBody>, Error = E> + Send + 'static, <L::Service as Service<Request<Body>>>::Future: Send + 'static, ResBody: Body<Data = Bytes> + Send + 'static, ResBody::Error: Into<Box<dyn Error + Send + Sync + 'static>>, E: Into<Box<dyn Error + Send + Sync + 'static>> + Send + 'static,

Provide an optional [Layer] that will be used to wrap all RPC requests.

This could be helpful in providing global metrics and logging for all outbound requests.

The layer’s service may return any response body that implements [http_body::Body<Data = bytes::Bytes>] and any error type that implements Into<Box<dyn Error + Send + Sync>>. Both are mapped to the internal types automatically.

Example

Add a layer that logs each request URI:

use sui_rpc::Client;
use tower::ServiceBuilder;

let client = Client::new(Client::MAINNET_FULLNODE)
    .unwrap()
    .request_layer(ServiceBuilder::new().map_request(|req: http::Request<_>| {
        println!("request to {}", req.uri());
        req
    }));

pub fn with_max_decoding_message_size(self, limit: usize) -> Self

pub fn uri(&self) -> &Uri

pub fn ledger_client( &mut self, ) -> LedgerServiceClient<BoxService<Request<Body>, Response<Body>, Status>>

pub fn state_client( &mut self, ) -> StateServiceClient<BoxService<Request<Body>, Response<Body>, Status>>

pub fn execution_client( &mut self, ) -> TransactionExecutionServiceClient<BoxService<Request<Body>, Response<Body>, Status>>

pub fn package_client( &mut self, ) -> MovePackageServiceClient<BoxService<Request<Body>, Response<Body>, Status>>

pub fn signature_verification_client( &mut self, ) -> SignatureVerificationServiceClient<BoxService<Request<Body>, Response<Body>, Status>>

pub fn subscription_client( &mut self, ) -> SubscriptionServiceClient<BoxService<Request<Body>, Response<Body>, Status>>

pub fn proof_client( &mut self, ) -> ProofServiceClient<BoxService<Request<Body>, Response<Body>, Status>>

Available on crate feature unstable only.

Returns a client for the unstable alpha ProofService, which serves Object Checkpoint State (OCS) inclusion proofs.

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.