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

🔌Nexus Rust SDK Integration

Audience: Application and service developers integrating with Nexus through the supported SDK, CLI, and Sui transaction boundary.

Goal: Choose the correct API surface, preserve authority and custody boundaries, and verify each on-chain result.

The Nexus SDK is a direct Rust/Sui RPC API. A NexusClient resolves the selected deployment configuration, provides object reads and action facades, and can create an all-Nexus event ingestor. The CLI exposes corresponding operator-oriented commands. Reads and event ingestion query the network; action facades submit Sui programmable transactions, and neither replaces the signer approval boundary. This page is not the HTTP REST/SSE/API-key Nexus API; use that reference for indexed endpoint and stream contracts.

Integration map

Need
Use
Canonical signatures

Configure RPC, signer, gas, or deployment object bindings

NexusClient with NexusObjects/NexusContext

Read a DAG, Task, occurrence, execution, payment, Agent registry, or Tool state

SDK crawler/action read documented by its domain

Build a state change

SDK action facade or transaction builder, then submit through a signer/gas source

Transactions and the domain action page

Receive Nexus activity

NexusClient::event_ingestor and NexusEventKind

Operate from a terminal

nexus command family

Decode an on-chain rule or error

Generated Move interface plus SDK type/error pages

Safe application flow

SDK action, event, and authoritative readback

The direct SDK architecture keeps transaction authority and object decoding in the application server. Events make a consumer timely, but the readback after a write or retry remains authoritative. For stateful objects, use StateResolver::resolve_context_snapshot to validate the anchor, witness, and inner field together, then use load_inner_from_snapshot for local decoding. resolve_transaction_view_context_snapshot, finalized_inner_outputs, and causal_inner_values operate on caller-supplied acknowledged transaction effects; a missing output may produce None, while inconsistent identity or field data produces an SDK error. These methods preserve causal evidence already obtained from Sui and cannot manufacture an acknowledgment when the public RPC response is unavailable.

The ordered flow is deliberately read-after-event and read-after-write: a notification or successful Sui transaction does not by itself prove that the final Nexus lifecycle state is complete.

Events are excellent for updating a UI or background index, but an event is not a substitute for an authoritative object read before an irreversible action. Re-read the relevant on-chain object after a failed or retried action, and use the transaction effects plus object state as the success boundary.

Client and deployment lifecycle

Build a client with an RPC URL and selected NexusObjects; choose coin or address-balance gas only when the process will submit. build validates missing or conflicting configuration. Keep the selected network and object bindings together in one server-side boundary. Exact builder and gas signatures are in Client construction. The removed Protocol-resolution surface is documented only as historical compatibility.

For effectful writes, configuration resolution is only the first step: resolve the configured RuntimeAuthority and runtime package/type witness, inspect the target object's typed witness, then submit with the required signer/capability and verify transaction effects plus authoritative object readback. If the selected build does not expose those authority fields, report the capability as unavailable and do not treat a cached Protocol reference as permission to mutate.

For reads, identify which durable object is authoritative: Agent and skill registration, DAG, Tool registration, Task and occurrence, execution, or payment. Use the public Crawler reads surface and treat absence, RPC failure, decode failure, and an unsupported selected network as separate UI states. An object version or transaction digest is evidence for a particular read, not a permanent cache lease.

Event ingestion lifecycle

NexusClient::event_ingestor returns the SDK's NexusEventIngestor, an EventIngestor<NexusEventQuery> scoped to the resolved Nexus object configuration. Its query filters the Nexus wrapper event types and classifies decoded payloads as NexusEventCandidate::Supported or NexusEventCandidate::Unsupported. An unsupported wrapper payload is a delivered compatibility classification carrying its source package and type; it is not itself an ingestion failure. Malformed identity or contents remain EventIngestionError::Decode values. Preserve the last processed checkpoint in your own durable consumer state, start with with_channel_capacity, with_cancellation_token, and (when the application accepts a live-cursor fallback) with_replay_gap_recovery, then call start(from_checkpoint) and cancel the consumer on shutdown.

The Nexus SDK does not define a browser stream adapter or universal “resume exactly once” helper. Its event ingestor accepts an inclusive checkpoint and can report a ReplayGap before resuming at the live cursor when recovery is enabled. On reconnect, resume from your stored cursor, tolerate duplicate wakeups, and refresh affected objects authoritatively. A channel close, transport failure, replay gap, or decode error means the consumer must surface degraded live updates and reconnect or fail according to its own service policy; it must not infer that a missing event implies a missing on-chain update.

Actions, effects, and recovery

Action facades and NexusTransaction compose protocol calls; submit_transaction signs and submits with the client's configured signer and gas source. Use the generated domain reference to identify required capabilities, object IDs, return/custody rules, and error types. After submission, record transaction effects, then fetch the relevant authoritative object. For delayed execution, a successful Task creation is not evidence that an execution has already happened.

Authority and custody

  • A browser wallet or service signer authorizes a transaction; do not put private keys or a signing flow in a query-only feature.

  • Gas and protocol assets have distinct custody rules. Choose the documented GasSource and use the domain action's returned objects exactly as the generated reference specifies.

  • A browser draft is transient. A published DAG, Agent, skill, Task, occurrence, execution, and payment are on-chain state with their own lifecycle and authority checks.

  • Deployment bindings can change. Reacquire NexusObjects/NexusContext from trusted configuration and read back the relevant object instead of assuming a cached identifier stays valid; pair effectful work with the configured RuntimeAuthority, package/object witness, transaction effects, and readback checks described in Protocol Upgrades and Compatibility.

Failure and verification

Treat RPC, decoding, transaction, and protocol-rule errors as different classes. The SDK error reference is the canonical type list; transaction effects establish whether Sui accepted the write, while a fresh object read establishes the post-transaction state. A retry should begin from a fresh authoritative read, not a stale UI cache or an older event.

Next: follow the Build a query monitor for an ordered junior-developer workflow, or inspect the same public objects in Talus Vision Explorer. For HTTP REST/SSE/API-key integration, use the Nexus API reference.

Last updated