🧩Build a Nexus SDK Query Monitor
This guide uses the direct Rust SDK/Sui RPC boundary. It is query-only and runnable without a private key, signer, or gas source. There is no public browser-wallet/PTB adapter in this SDK revision. Submitted actions are a separate backend-signer-and-gas architecture, not part of this tutorial.
What you are building
The architecture keeps RPC credentials, object decoding, event checkpoints, and any future signer inside the server; the browser receives only a deliberately narrow view.
The browser owns presentation. The server owns its configured client, event consumer, and authorization policy. Nexus owns protocol validation and durable state. Events make the UI timely, but the relevant object read after a write or retry is the correctness check.
Optional writes remain a separate backend-held signer and gas service; the browser never receives either one.
1. Establish the deployment boundary
Choose one network and configure the client with its RPC endpoint and authenticated NexusObjects. Use the NexusClient construction reference for exact APIs. Render the selected network and a clear unsupported-network state before showing an empty object view.
The runnable fixture reads NEXUS_OBJECTS_JSON as a serialized, authenticated NexusObjects value and NEXUS_EVENT_SOURCE as the exact object address used to scope event ingestion. Obtain both from authenticated deployment evidence; do not invent IDs, versions, or digests. Verify them against the provider's deployment record, Vision Deployment, and a direct Sui object read. A mismatch means stop and fix configuration; do not send a transaction against guessed object IDs. NEXUS_NETWORK and NEXUS_DEPLOYMENT are operator-supplied display labels returned by /api/status; they identify the selected configuration for the UI but are not on-chain proof of network or package compatibility.
Query-only server boundary
Create the client only in the server process. Use the published SDK dependency in the example. If source inspection is needed, use the public SDK repository directly at the selected revision; the runnable example remains independent of that source directory:
The consumer dependency is resolved from crates.io, so the example does not depend on a sibling source tree:
The published example is the exact Cargo manifest, lockfile, server, and browser asset shown by this guide. Its SDK dependency is pinned to the published 2.1.0 crate; no host-specific path is required.
The client construction in src/main.rs is:
This builder has no private key or gas source. Add those only in a separate backend action service before calling a write API such as submit_transaction, and never serialize signing material into the browser response.
2. Build one authoritative typed read
Start with a public object such as an Agent, DAG, Tool, Task, or execution. Keep the identifier in the route, issue the SDK Crawler read on the server, and render loading, found, absent, and unreadable as distinct states. Do not collapse an RPC or BCS decoding error into “not found.”
The fixture calls the SDK's optional typed read for DAGExecution and projects only object metadata into its narrow response:
get_optional_object returns Ok(None) for an absent object and an error for transport or BCS decoding failures, so the application can distinguish absent from unreadable. The fixture's /api/object/<id> route returns loaded, absent, unreadable, or invalid-id and never exposes a raw BCS decoder or arbitrary RPC proxy to the browser.
Verify: open the same object in Vision Search, run sui client object <OBJECT_ID> --json, and compare the identity, version, and digest with the monitor response on the selected network.
3. Add supervised activity without trusting stale data
Create the typed Nexus event ingestor from the same client. Persist the last successfully observed checkpoint and resume from it inclusively. Events are transient notifications; the typed object read remains authoritative.
The fixture’s event setup is:
Consume the fixture's mapped MonitorEventReceiver in a supervised task; the SDK source receiver is mapped at the boundary so the browser never depends on a generated event enum. For each page, process all candidates, persist the checkpoint monotonically, and reset the retry attempt only after that page has completed successfully; merely opening a receiver does not reset backoff. The fixture converts SDK EventIngestionError values into its own MonitorError { kind, message } record so the browser receives a stable local classification without inventing SDK variants. Configuration, decode, stream-protocol, and checkpoint-persistence failures are terminal. RPC transport is retryable only for the SDK's selected tonic codes Cancelled, Unknown, DeadlineExceeded, ResourceExhausted, Aborted, Internal, and Unavailable; InvalidArgument, NotFound, PermissionDenied, Unauthenticated, FailedPrecondition, OutOfRange, Unimplemented, and other non-selected codes are terminal. A ReplayGap is emitted visibly and, with the SDK recovery option enabled, the ingestor resumes from the live cursor; the fixture keeps consuming the next page rather than treating the gap as proof that the object state changed. A closed stream or retryable in-stream RPC exits the receiver loop and re-enters the supervisor's bounded backoff path.
The supervisor copies the page source into the serialized monitor status before processing candidates. The browser can therefore label the latest evidence as replay during historical recovery or live after the subscription resumes; neither label replaces authoritative object and transaction readback.
When a retryable error closes the receiver, arrives in-stream, or interrupts start, the supervisor waits with bounded exponential backoff: 250 ms, 500 ms, 1 s, and so on up to 8 s, with only a bounded jitter addition. Only a successfully processed page resets the attempt counter. This prevents a persistent selected-retryable RPC failure or repeated receiver closure from becoming a 10 ms hot loop while keeping protocol, permanent RPC, configuration, and decode failures terminal until an operator fixes the selected deployment or SDK boundary.
If streaming disconnects or the channel closes, show that live updates are paused, retain the last authoritative read and checkpoint, and reconnect using the saved cursor. Cancellation is explicit: the fixture passes a CancellationToken to both the ingestor and consumer and records the cancellation state before stopping. Never invent a state transition from a missing event.
The event reference defines the exact receiver, page, error, replay, cancellation, and unsupported-candidate signatures. The SDK integration reference explains the direct client, transaction, custody, and application boundary.
4. Expose only a narrow HTTP view
The fixture serves three routes: / for the browser asset, /api/status for stream health/checkpoint state, and /api/object/<id> for a refresh signal associated with one object ID. The server never accepts a private key, gas coin, arbitrary transaction, or arbitrary BCS type from the browser.
The browser fetches /api/status, renders connected/degraded states, polls as a fallback, and listens for a nexus-monitor-invalidate event before fetching again. A notification triggers a fresh server read; it does not replace the read result. Keep browser code in static/index.html and keep signing code out of that directory.
5. Optional writes are a separate service
Choose one domain action from the generated workflow, scheduler, tool, or TAP reference only after adding a backend-held Ed25519 key, an explicit authorization check, and a documented gas source. A browser wallet approval flow is absent until the SDK supplies a public adapter.
Verify: show the transaction result separately from the final object state. Acceptance by Sui does not mean every later lifecycle step is complete: for example, a run first creates a Task, then an eligible occurrence is dispatched before an execution exists.
At the HTTP boundary, require an application authorization check before calling the action facade, return a transaction digest/effects summary, and enqueue an authoritative readback. Do not expose a generic “submit arbitrary Nexus transaction” endpoint to the browser.
6. Run and verify the fixture
Run the published fixture from its example directory. When source-level comparison is required, clone the public SDK repository and record the selected revision instead of relying on an unpinned source directory. Keep its local MonitorError/retry abstraction at the application boundary so it does not invent an SDK error variant. The locked fixture contains crates.io registry dependencies and pinned Git move-binding dependencies, so --locked prevents version/lock drift but does not make dependency acquisition network-free. Use caller-selected writable cache and target directories when the defaults are unavailable:
The compile and unit-test gates make no Nexus deployment calls, but Cargo may contact crates.io or the pinned Git dependency while acquiring missing bytes. Prefetch the locked dependency set when network access is available, then use offline mode only from that warmed cache:
If cargo fetch --locked or either offline command reports a missing registry/Git dependency, the cache is incomplete; rerun the fetch with network access or report the earliest dependency-acquisition blocker rather than claiming the test is network-free. To run the server against a selected deployment, provide the operator-supplied values:
Open http://127.0.0.1:8787/, confirm /api/status reports the configured stream plus the selected network/deployment labels, then compare the object read with Vision Search and sui client object <OBJECT_ID> --json on the same network. The fixture marks the stream connected when its receiver starts; it becomes authoritative only after an object read. If the endpoint is unavailable, the object bindings are stale, or a replay gap is reported, preserve the last read, show the degraded state, and fix configuration or reconnect. A successful page clears a retryable degraded state and preserves the monotonic checkpoint.
Completion checklist
The UI shows the operator-supplied selected network and deployment labels, clearly as configuration metadata rather than chain proof.
The server uses injected, authenticated
NexusObjectsand a query-onlyNexusClient; it does not infer or refresh configuration from a Protocol object.A typed object read distinguishes absent, unreadable, and loaded state.
The supervised event consumer persists a monotonic checkpoint, handles cancellation/channel closure/errors, applies the SDK retry-status matrix, and treats protocol/permanent RPC failures as terminal while unsupported candidates remain classifications.
Events refresh or invalidate data but cannot overwrite a newer authoritative read.
The HTTP surface exposes only
/,/api/status, and/api/object/<id>; no browser signer, gas source, BCS decoder, or arbitrary transaction endpoint exists.A write, if added later, requires explicit server-side authorization, signer policy, gas configuration, transaction effects, and a fresh readback.
The final state is verified by a fresh SDK read, Vision Explorer, and an independent direct Sui object read.
Next: follow Execute and Settle an Agent for the Agent → DAG → skill → Task → execution flow, or consult the SDK integration reference for the direct client surface.
Last updated

