🧰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) -> u64Create 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

