Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

🧰NexusClient Construction and Configuration

Audience: Nexus SDK integrators (Rust).

Area: NexusClient Construction and Configuration.

Generated from: Nexus SDK public API at release v2.1.1 commit 08bfe76e726922ce512d623fbc1d2e1bd786bcd4; the existing generated inventory is preserved and 2.1.1 additions are source-verified.

sdk/src/nexus/client.rs

Consistent state and event reads

NexusClientBuilder::with_state_catalog_rpc_url configures the indexed state-catalog endpoint used for recent-activity discovery while the configured Sui RPC remains authoritative for object and transaction reads. NexusClient::filtered_event_ingestor and filtered_runtime_event_ingestor keep the supported event-filter boundary explicit; filtered_event_ingestor_for_context carries the selected package graph into a context-bound read.

Indexed activity identifies work to inspect, but it does not prove that a transaction finalized. Re-read transaction effects and affected object versions before treating an event notification as a state transition.

GasSource and Gas

#[derive(Clone, Debug)]
pub enum GasSource { Coin(CoinGasPool), AddressBalance(AddressBalanceGas) }
pub type Gas = GasSource;

GasSource::Coin uses owned SUI coin objects; GasSource::AddressBalance uses an address balance with a reusable nonce authority. Gas is the public alias used when inspecting a configured client.

GasSource::coin and GasSource::get_budget

pub fn coin(coins: Vec<sui::types::ObjectReference>, budget: u64) -> GasSource
pub fn get_budget(&self) -> u64

Create a coin-backed source and inspect either source's budget. Coin acquisition and release are SDK-internal pool operations, not public client APIs.

sdk/src/nexus/registered_key.rs

RegisteredKey constants and commitment domains

Lengths and domain separators shared with the direct-v3 on-chain verifier.

output_sha256

Return SHA-256(RAW_OUTPUT_DOMAIN || canonical_response_bcs).

tool_signature_message

Build TOOL_RESPONSE_DOMAIN || leader_signature || nonce || output_sha256(canonical_response_bcs).

fetch_external_verifier_record

Read and validate the configured Tool-bound External verifier record.

fetch_external_verifier_runtime_call

Resolve the Tool-bound method, witness ID, and ordered immutable shared-object references required at runtime.

Shared wallet and runtime observations

NexusClient::wallet() exposes the signing WalletClient for reuse, and NexusClientBuilder::with_wallet accepts it. This shares one signer and RPC connection with the native Walrus adapter. NexusClientBuilder no longer implements UnwindSafe or RefUnwindSafe; review code that relies on those auto-traits.

Install a sui::observation::Observer once before SDK work with observation::install. Callbacks report logical reads, attempts, retry delays, recovery admission, and RPC completion through final gRPC trailers; dropped futures report cancellation. Callbacks must be fast and must not block, perform I/O, or panic. The application owns metric names and export. Operation labels contain no execution identities or raw endpoint URLs. RPC hooks cover clients constructed through sui::grpc::client; directly constructing the re-exported raw client bypasses them.

Source-derived public API inventory

SubmissionContext

NonceAllocator

NonceAllocator::new

NonceAllocator::allocate

fetch_submission_context

finish_transaction

DEFAULT_GAS_BUDGET

GasSource

Gas

GasSource::coin

GasSource::get_budget

CoinGasPool

AddressBalanceGas

AddressBalanceGas::new

AddressBalanceGas::with_nonce_allocator

NexusClientBuilder

NexusClientBuilder::new

NexusClientBuilder::with_private_key

NexusClientBuilder::with_wallet

NexusClientBuilder::with_rpc_url

NexusClientBuilder::with_state_catalog_rpc_url

NexusClientBuilder::with_gas

NexusClientBuilder::with_address_balance_gas

NexusClientBuilder::with_address_balance_gas_config

NexusClientBuilder::with_nexus_objects

NexusClientBuilder::with_transaction_timeout

NexusClientBuilder::build

NexusClient

NexusClient::builder

NexusClient::network

NexusClient::workflow

NexusClient::scheduler

NexusClient::transaction_for_object

NexusClient::transaction_for_creator

NexusClient::network_auth

NexusClient::tool

NexusClient::tap

NexusClient::crawler

NexusClient::state_resolver

NexusClient::context_for_object

NexusClient::context_for_root

NexusClient::context_for_object_with_roots

NexusClient::context_for_creator

NexusClient::routing_context

NexusClient::runtime_context

NexusClient::owner

NexusClient::grpc_client

NexusClient::clone_grpc_client

NexusClient::fetch_coins_by_type

NexusClient::fetch_coin

NexusClient::fetch_coin_with_balance

NexusClient::fetch_coin_by_type

NexusClient::rpc_url

NexusClient::wallet

NexusClient::signer

NexusClient::event_ingestor

NexusClient::filtered_event_ingestor

NexusClient::filtered_runtime_event_ingestor

NexusClient::filtered_event_ingestor_for_context

NexusClient::set_gas_source

NexusClient::gas_config

NexusClient::get_reference_gas_price

NexusClient::get_nexus_objects

NexusClient::submit_transaction

SHA256_LEN

ED25519_SIGNATURE_LEN

INVOCATION_NONCE_DOMAIN

re-export pub, use, crate, commitments, output_sha256, tool_signature_message, RAW_OUTPUT_DOMAIN, TOOL_RESPONSE_DOMAIN

canonical_tool_inputs_sha256

canonical_resolved_tool_inputs_sha256

invocation_nonce

registered_key_auxiliary

validate_registered_key_auxiliary

WorkAdmissionCommittee

WorkAdmissionCommittee::rank

WorkAdmissionCommittee::contains

fetch_work_admission_committee

rank_work_admission_leaders

extract_network_id_from_leader_registry

find_owned_capability_by_what_for

preflight_external_verifier_registration

ExecutedTransaction

Signer

Signer::new

Signer::wallet

Signer::get_active_address

Signer::sign_tx

Signer::execute_tx

Signer::execute_tx_without_gas_coin

ObservedStateField

ObservedState

ObservedStateSnapshot

ObservedStateSnapshot::observed

ObservedStateSnapshot::inner_object_reference

ObservedState::witness_type

ObservedState::inner_type

StateResolver

StateResolver::new

StateResolver::with_catalog

StateResolver::observe

StateResolver::observe_snapshot

StateResolver::observe_finalized_snapshot

StateResolver::resolve_context

StateResolver::resolve_context_snapshot

StateResolver::resolve_transaction_view_context_snapshot

StateResolver::resolve_context_with_roots

StateResolver::resolve_inner_with_roots

StateResolver::resolve_package_graph

StateResolver::resolve_explicit_package_graph

StateResolver::resolve_emitter_context

StateResolver::resolve_creator_context

StateResolver::resolve_routing_context

StateResolver::resolve_runtime_context

StateResolver::resolve_package

StateResolver::load_inner

StateResolver::load_inner_from_snapshot

StateResolver::finalized_inner_outputs

StateResolver::causal_inner_values

StateResolver::load_inner_from_observation

StateResolver::validate_state_pair

StateResolver::resolve_and_load_inner

Snapshot and causal context reads

StateResolver::observe_snapshot captures a validated anchor, witness, and inner-field observation for one object; resolve_context_snapshot resolves the package graph from that snapshot. load_inner_from_snapshot validates and decodes retained bytes without another Sui request. resolve_transaction_view_context_snapshot and observe_finalized_snapshot consume a caller-supplied, acknowledged ExecutedTransaction and digest to advance a known snapshot; they return None when the transaction did not write the inner field and return an error for inconsistent identity, ownership, or type data. finalized_inner_outputs and causal_inner_values decode transaction-tied values and report InvalidTransactionOutput when the supplied effects do not establish the expected output.

These helpers preserve causal evidence already acknowledged by the caller. They cannot turn an unacknowledged or unavailable public RPC response into proof of a transaction or state transition; retain the transaction digest, effects, object versions, and checkpoint used for the read.

Last updated