> For the complete documentation index, see [llms.txt](https://docs.talus.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.talus.network/talus-docs-v2.1.0/reference/sdk/integration.md).
# Nexus Rust SDK Integration
{% hint style="info" %}
**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.
{% endhint %}
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](/talus-docs-v2.1.0/guides/nexus-api.md); use that reference for indexed endpoint and stream contracts.
{% hint style="warning" %}
**SDK boundary.** The selected SDK has no `ProtocolResolver` or Protocol-refresh API. Obtain selected package and object bindings through `NexusObjects` and `NexusContext`; for mutation, require the runtime package/type witness, transaction effects, and authoritative readback. See [Protocol Upgrades and Compatibility](/talus-docs-v2.1.0/concepts/14-protocol-upgrades-and-compatibility.md).
{% endhint %}
### Integration map
| Need | Use | Canonical signatures |
| ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Configure RPC, signer, gas, or deployment object bindings | `NexusClient` with `NexusObjects`/`NexusContext` | [Client construction](/talus-docs-v2.1.0/reference/sdk/client.md) and [Decoded types](/talus-docs-v2.1.0/reference/sdk/types.md) |
| Read a DAG, Task, occurrence, execution, payment, Agent registry, or Tool state | SDK crawler/action read documented by its domain | [Decoded types](/talus-docs-v2.1.0/reference/sdk/types.md), [Workflow actions](/talus-docs-v2.1.0/reference/sdk/actions-workflow.md), and [Scheduler actions](/talus-docs-v2.1.0/reference/sdk/actions-scheduler.md) |
| Build a state change | SDK action facade or transaction builder, then submit through a signer/gas source | [Transactions](/talus-docs-v2.1.0/reference/sdk/transactions.md) and the domain action page |
| Receive Nexus activity | `NexusClient::event_ingestor` and `NexusEventKind` | [Event ingestion](/talus-docs-v2.1.0/reference/sdk/events.md) |
| Operate from a terminal | `nexus` command family | [CLI reference](/talus-docs-v2.1.0/reference/cli.md) |
| Decode an on-chain rule or error | Generated Move interface plus SDK type/error pages | [Move reference](/talus-docs-v2.1.0/reference/move.md) and [SDK errors](/talus-docs-v2.1.0/reference/sdk/errors.md) |
#### Safe application flow
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.
```mermaid
sequenceDiagram
participant Service as Rust service
participant SDK as NexusClient
participant Sui as Sui RPC and chain
participant Events as Event ingestor
Service->>SDK: Construct with deployment metadata and baseline config
SDK->>Sui: Read authoritative object or compose PTB
Sui-->>SDK: Object state or transaction effects
SDK-->>Service: Decode result and record identity
SDK->>Events: Start from saved checkpoint
Events-->>Service: Invalidation or replay-gap/error classification
Service->>SDK: Re-read affected object
SDK->>Sui: Fetch authoritative state
Sui-->>Service: Authoritative readback
```
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](/talus-docs-v2.1.0/reference/sdk/client.md). The removed Protocol-resolution surface is documented only as [historical compatibility](/talus-docs-v2.1.0/reference/sdk/protocol.md).
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](/talus-docs-v2.1.0/reference/sdk/crawler.md) 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` 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](/talus-docs-v2.1.0/concepts/14-protocol-upgrades-and-compatibility.md).
#### Failure and verification
Treat RPC, decoding, transaction, and protocol-rule errors as different classes. The SDK [error reference](/talus-docs-v2.1.0/reference/sdk/errors.md) 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](/talus-docs-v2.1.0/guides/sdk/build-a-query-monitor.md) for an ordered junior-developer workflow, or inspect the same public objects in [Talus Vision Explorer](/talus-docs-v2.1.0/guides/vision-explorer.md). For HTTP REST/SSE/API-key integration, use the [Nexus API reference](/talus-docs-v2.1.0/guides/nexus-api.md).
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.talus.network/talus-docs-v2.1.0/reference/sdk/integration.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
