Skip to content

Docs update from nexus-sdk #201

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
devops-talus wants to merge 2 commits into
base: staging
Choose a base branch
from
Open

Docs update from nexus-sdk #201

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
078605d
Update docs from nexus-sdk (commit: b83530a6ad93144c3453373ae23fccc2b…
kouks Mar 12, 2026
625399b
Update SUMMARY.md with new files under 'Looking for a home'
devops-talus Mar 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions SUMMARY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -103,3 +103,7 @@
- [Echanges: Coinbase](tools/exchanges-coinbase/README.md)
- [HTTP](tools/http/README.md)
- [Templating: Jinja](tools/templating-jinja/README.md)

## Looking for a home

* [nexus-sdk/guides/tool-communication.md](nexus-sdk/guides/tool-communication.md)
119 changes: 69 additions & 50 deletions nexus-sdk/cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Nexus CLI

> concerns [`nexus-cli` repo](https://github.com/Talus-Network/nexus-sdk/tree/main/cli)
> concerns [`nexus-cli` repo][nexus-cli-repo]

The Nexus CLI is a set of tools that is used by almost all Actors in the Nexus ecosystem.

Expand Down Expand Up @@ -38,7 +38,7 @@ Validate an off-chain Nexus Tool on the provided URL. This command checks whethe
As an improvement, the command could take a `[data]` parameter that invokes the Tool and checks the response against the output schema.
{% endhint %}

This command should also check that the URL is accessible by the Leader node. It should, however, be usable with `localhost` Tools for development purposes, printing a warning.
This command should also check that the URL is accessible by Leader nodes. For local testing, it should still be usable with `localhost` Tools, printing a warning.

---

Expand Down Expand Up @@ -116,6 +116,70 @@ This command requires that a wallet is connected to the CLI...

---

**`nexus tool auth`**

Commands for operating signed HTTP (message signatures) for off-chain Tools.

Signed HTTP is Nexus’ application-layer authentication for `POST /invoke`:

- Leader node → Tool requests are signed so the Tool can verify which Leader node is calling and prevent replay.
- Tool → Leader node responses are signed so the Leader node can verify provenance and bind a response to a specific request.

These commands help Tool operators:

- generate an Ed25519 Tool message-signing keypair,
- register/rotate the Tool’s message-signing public key on-chain (Network Auth), and
- export a local `allowed_leaders.json` file consumed by the Tool runtime for request verification (no RPC at runtime).

See also:

- [Tool Communication (HTTPS + Signed HTTP)](guides/tool-communication.md)

---

**`nexus tool auth keygen [--out <path>]`**

Generates a new Ed25519 Tool message-signing keypair.

- If `--out` is provided, writes a JSON file containing `private_key_hex` and `public_key_hex`.
- You will use the private key in the Tool runtime config (`tool_signing_key`).
- You will register the public key on-chain via `register-key`.

---

**`nexus tool auth register-key --tool-fqn <fqn> --signing-key <key-or-path> [--owner-cap <object_id>] [--description <text>] ...gas`**

Registers (or rotates) the Tool’s message-signing key in the on-chain Network Auth registry.

- Requires an `OwnerCap<OverTool>` (the tool ownership cap) to prove Tool identity.
- Requires a proof-of-possession signature so the chain can verify the registrant controls the private key.
- Returns the registered `tool_kid` (key id) which must match the Tool runtime config.

If `--owner-cap` is omitted, the CLI will try to use the OwnerCap saved in the CLI config for that Tool.

---

**`nexus tool auth export-allowed-leaders (--all | --leader <address>...) --out <path>`**

Exports a local allowlist file (JSON) of permitted Leader nodes and their active signing keys.

Use `--all` to export entries for all leaders registered in `network_auth` (recommended), or pass one or more `--leader` capability IDs.

This file is consumed by the Rust toolkit runtime (`allowed_leaders_path`) so the Tool can verify signed requests without performing Sui RPC calls at runtime.

---

**`nexus tool auth sync-allowed-leaders --out <path> [--interval <duration>] [--once]`**

Continuously syncs an `allowed_leaders.json` file from on-chain `network_auth` (polling).

- `--interval` accepts human durations like `500ms`, `5s`, `2m`, `1h` (default: `30s`).
- Use `--once` to sync a single time and exit.

This is useful for running as a sidecar next to a Tool so leader allowlists stay up-to-date without restarting the Tool.

---

**`nexus tool list`**

List all Nexus Tools available in the Tool Registry. This reads the dynamic object directly from Sui.
Expand Down Expand Up @@ -172,8 +236,6 @@ The input `<data>` is a JSON string with the following structure:
- Each top-level value is an object and its keys refer to the _input port names_ of each vertex (this object can be empty if the vertex has no input ports)
- Values of the second-level object are the data that should be passed to each input port

Data for encrypted ports are automatically encrypted before being sent on-chain.

The `--inspect` argument automatically triggers `nexus dag inspect-execution` upon submitting the execution transaction.

The `--remote` argument accepts a list of `{vertex}.{port}` strings that refer to entry ports and their vertices. The data associated with these ports is stored remotely based on the configured preferred remote storage provider. Note that it is required that the user configure these remote storage providers via the `$ nexus conf set --help` command.
Expand Down Expand Up @@ -226,8 +288,6 @@ Creates a new scheduler task tied to the specified DAG. Key options:

Initial schedule arguments (`--schedule-*`) are only valid for queue-based tasks. Selecting `--generator periodic` prepares the task for periodic execution, but you must configure the recurring schedule separately via `nexus scheduler periodic set`.

Data for encrypted entry ports is automatically encrypted when a session is available.

{% hint style="info" %}
This command requires that a wallet is connected to the CLI and holds sufficient SUI for gas.
{% endhint %}
Expand Down Expand Up @@ -288,50 +348,6 @@ Removes the periodic schedule while leaving any existing sporadic occurrences un
This command requires that a wallet is connected to the CLI and holds sufficient SUI for gas.
{% endhint %}

### `nexus crypto`

Set of commands for managing the CLI’s encrypted secrets (master key, passphrase, identity key) and establishing secure sessions that power DAG data encryption.

---

**`nexus crypto auth [--sui-gas-coin <object_id>] [--sui-gas-budget <mist>]`**

Runs the two-step handshake with the Nexus network to claim a pre-key, perform X3DH with your local identity key, and store a fresh Double Ratchet session on disk. The claimed pre-key bundle is what enables the CLI to complete a Signal-style secure session with the network: X3DH bootstraps shared secrets, and the Double Ratchet derived from that bundle encrypts every DAG payload going forward. The command returns both claim/associate transaction digests and prints the initial message in JSON format, enabling you to audit the handshake.

Before sending the associate transaction, the CLI automatically generates an identity key if one is missing and persists the session in `~/.nexus/crypto.toml`. All subsequent `nexus dag` commands load that session to encrypt entry-port payloads or decrypt remote results, so run `auth` whenever you rotate keys or see “No active sessions found.”

{% hint style="info" %}
This command requires that a wallet is connected to the CLI and spends gas for **two** programmable transactions. Use `--sui-gas-coin` / `--sui-gas-budget` if you need explicit control.
{% endhint %}

---

**`nexus crypto generate-identity-key`**

Creates a brand-new long-term identity key and stores it (encrypted) inside `~/.nexus/crypto.toml`. Because peers can no longer trust sessions tied to the previous identity, the CLI makes it clear that all stored sessions become invalid. Run `nexus crypto auth` immediately after to populate a replacement session.

---

**`nexus crypto init-key [--force]`**

Generates a random 32‑byte master key with [`OsRng`](https://docs.rs/rand/latest/rand/rngs/struct.OsRng.html) and writes it to the OS keyring under the `nexus-cli-store/master-key` entry. The master key controls access to every encrypted field (`Secret<T>`) in the CLI configuration. Rotating it without also wiping the encrypted data would leave the ciphertext inaccessible, so this command automatically truncates the cryptographic configuration after a successful write.

Use `--force` to overwrite an existing raw key or stored passphrase; doing so deletes all saved sessions and identity material because it can no longer be decrypted.

---

**`nexus crypto set-passphrase [--stdin] [--force]`**

Stores a user-provided passphrase in the OS keyring (`nexus-cli-store/passphrase`) and derives the same 32‑byte master key via Argon2id whenever secrets need to be decrypted. By default the command prompts interactively; `--stdin` allows piping from scripts or CI.

Like `init-key`, it refuses to overwrite an existing persistent key unless `--force`. Empty or whitespace-only passphrases are rejected to avoid unusable configs.

---

**`nexus crypto key-status`**

Reports where the current master key will be loaded from, following the same priority order as the runtime resolver: `NEXUS_CLI_STORE_PASSPHRASE` environment variable, keyring passphrase entry, or raw key entry. If a raw key is in use the CLI prints the first 8 hex characters so you can distinguish multiple installations; otherwise it notes the source or that no persistent key exists yet.

---

### `nexus gas`
Expand Down Expand Up @@ -452,3 +468,6 @@ This command requires that a wallet is connected to the CLI...

Provides completion for some well-known shells.

<!-- List of References -->

[nexus-cli-repo]: https://github.com/Talus-Network/nexus-sdk/tree/main/cli
64 changes: 25 additions & 39 deletions nexus-sdk/client.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,22 +1,22 @@
# 🪐 [`NexusClient`] (Rust)

The [`NexusClient`] provides a high-level interface for interacting with Nexus. It wraps key functionality including transaction signing and execution, gas management, cryptographic handshakes, and DAG workflow execution.
The [`NexusClient`] provides a high-level interface for interacting with Nexus. It wraps key functionality including transaction signing and execution, gas management, and DAG workflow execution.

---

## ✨ Overview

The [`NexusClient`] provides access to:

- [`GasActions`]: manage gas coins and budgets
- [`CryptoActions`]: perform cryptographic handshakes with Nexus
- [`GasActions`]: manage gas coins, budgets and tickets
- [`WorkflowActions`]: publish and execute workflows (DAGs)
- [`SchedulerActions`]: create and manage scheduler tasks, occurrences, and periodic schedules
- [`NetworkAuthActions`]: manage message-signing key bindings for Tools/Leader nodes

You can initialize a `NexusClient` via [`NexusClient::builder()`] with:

- a Sui **ed25519 private key**
- an RPC URL (and optional GraphQL URL for event fetching)
- an RPC URL
- one or more gas coins + a gas budget
- the on-chain [`NexusObjects`]

Expand Down Expand Up @@ -46,6 +46,18 @@ async fn main() -> anyhow::Result<()> {

---

## 🔏 Network Auth (signed HTTP)

`NexusClient` exposes `network_auth()` for Tool/Leader node message-signing key operations:

- register/rotate a Tool message-signing key on-chain, and
- export a local allowlist file of permitted Leader nodes for Tool-side verification (no RPC at runtime).
- continuously sync an allowlist file from on-chain `network_auth` (polling).

This is the same functionality exposed via the CLI under `nexus tool auth ...`.

---

## 🔑 Signer

### Signing Mechanism
Expand Down Expand Up @@ -85,37 +97,9 @@ println!("Gas budget added in tx: {:?}", result.tx_digest);

**Returns:**

---

## 🔐 Cryptographic Actions

These actions manage secure handshakes and session setup.

### Perform a Handshake

```rust
use nexus_sdk::crypto::x3dh::IdentityKey;

let ik = IdentityKey::generate();

let handshake = nexus_client.crypto().handshake(&ik).await?;

println!("Session established!");
println!("Claim TX: {:?}", handshake.claim_tx_digest);
println!("Associate TX: {:?}", handshake.associate_tx_digest);

assert!(handshake.session);
```

**What it does:**

1. Claims a pre-key object from Nexus.
1. Fetches the corresponding [`PreKeyBundle`].
1. Initiates an [`X3DH`] handshake to create a secure [`Session`].
1. Associates the pre-key with the sender on-chain.

**Returns:**
[`AddBudgetResult`]: includes the transaction digest.

---

## ⚡ Workflow Actions

Expand All @@ -140,13 +124,14 @@ println!("Published DAG ID: {:?}", publish_result.dag_object_id);

**Returns:**

[`PublishResult`]: includes the transaction digest and DAG object ID.

---

### 2. Execute a Workflow

```rust
use nexus_sdk::types::{PortsData, StorageConf};
use nexus_sdk::crypto::session::Session;
use std::{collections::HashMap, sync::Arc};
use tokio::sync::Mutex;

Expand All @@ -155,7 +140,6 @@ let mut entry_data: HashMap<String, PortsData> = /* your input data */

// Prepare storage and session
let storage_conf = StorageConf::default();
let session = Arc::new(Mutex::new(Session::default()));

let execute_result = nexus_client
.workflow()
Expand All @@ -164,7 +148,6 @@ let execute_result = nexus_client
entry_data,
None, // use default entry group
&storage_conf,
session,
)
.await?;

Expand All @@ -179,9 +162,12 @@ println!("Execution object ID: {:?}", execute_result.execution_object_id);

**Returns:**

[`ExecuteResult`]: includes the transaction digest and execution object ID.

---

### 3. Inspect Workflow Execution

```rust
use tokio::time::Duration;

Expand Down Expand Up @@ -214,10 +200,12 @@ println!("✅ Execution finished successfully!");

**Returns:**

[`InspectExecutionResult`]: includes an event stream and a poller handle.

---

## ⏱️ Scheduler Actions

The [`SchedulerActions`] API allows you to create and manage **on-chain scheduler tasks**.

A scheduler task is split into:
Expand Down Expand Up @@ -376,7 +364,6 @@ nexus_client
| Module | Purpose |
| ------------------ | ------------------------------------------------------- |
| `nexus::client` | Core client, builder, signer, gas management |
| `nexus::crypto` | Cryptographic operations (X3DH, sessions, handshakes) |
| `nexus::gas` | Gas management for Nexus workflows |
| `nexus::workflow` | DAG workflow publishing, execution, and event streaming |
| `nexus::scheduler` | Scheduler tasks, occurrences, and periodic schedules |
Expand All @@ -393,4 +380,3 @@ The `NexusError` enum categorizes issues from configuration errors to RPC and tr
## 🪶 Summary

The [`NexusClient`] aims to make building, publishing, and executing Nexus workflows _simple, safe, and async-ready_. It abstracts away Sui transaction signing and gas management while providing a clean modular interface.

Loading