Docs update from nexus-sdk

nexus-next/TAP/agent-development.md

@@ -33,4 +33,5 @@ The choice of how to build the agent will be determined by weighing:
 Continue learning about agent development with the following sections:
 
 * the [Nexus interface for TAPs](../packages/nexus-interface.md) section, outlining what interface the TAP must comply with
-* the reference [default TAP](default-tap.md) implementation, that serves as an example for a bare-bones TAP
+* the reference [default TAP](default-tap.md) implementation, that serves as an example for a bare-bones TAP
+

nexus-next/TAP/default-tap.md

@@ -349,3 +349,4 @@ fun get_witness(self: &DefaultSAP): &DefaultSAPV1Witness {
 ```
 
 </details>
+

nexus-next/conventions/sui-move.md

@@ -6,3 +6,4 @@ In Nexus and related packages we (to the best of our ability) follow these conve
 
 Each enumeration variant contains a property `_variant_name: AsciiString`, which will always be a static string representing the variant name.
 This helps clients to identify the variant because at the moment RPCs do not include the variant name in the response.
+

nexus-next/crates/leader.md

@@ -165,4 +165,5 @@ stateDiagram-v2
         if_stale --> [*]: NotStale
         MoveBackToQueuedSet --> [*]
     }
-```
+```
+

nexus-next/crates/sui-tx.md

@@ -7,3 +7,4 @@ The Leader will be assigned a wallet via the `SUI_SECRET_MNEMONIC` environment v
 Initially, there will only be one transaction type from Leader back to Workflow. This transaction notifies the Workflow of the Tool invocation result. More details are available in the [Leader](leader.md) documentation.
 
 Once onchain Tools are defined, the Leader will also have to send transactions to invoke these Tools. These are currently still in the design phase however.
+

nexus-next/gas-service.md

@@ -335,3 +335,4 @@ public fun donate_to_tool(
     ```
 
 </details>
+

nexus-next/glossary.md

@@ -26,3 +26,4 @@
 - **`Output Variant`** - A mutually exclusive variant of the tool's output.
 - **`Output Port`** - A single output (field) of a Tool within an Output Variant.
 - **`Entry Group`** - A named set of vertices that define an entry configuration for DAG execution.
+

nexus-next/index.md

@@ -73,3 +73,4 @@ Nexus offers [tool and agent developers](index.md#actors) an easy-to-use SDK con
 Docs:
 
 * [Nexus SDK documentation](../nexus-sdk/index.md)
+

nexus-next/packages/nexus-interface.md

@@ -51,3 +51,4 @@ Unfortunately, Sui does not give us a way to get current package ID.
 When upgrading a package you must create a new type that serves as a witness.
 This new type needs to be used when emitting `AnnounceInterfacePackageEvent` as its generic.
 This event _also_ needs to be emitted with every package upgrade.
+

nexus-next/packages/primitives.md

@@ -18,11 +18,11 @@ Therefore, upgrading components is less likely to require changes to other compo
 
 `UID` (Unique Identifier) proves that an object exist on-chain and its unique. By requiring passing a UID reference as the input and keeping a record of the ID of the UID that was passed as argument we can prove that only the module that defined that object did that operation. As only that module can access the UID.
 
-This is achieved with the [hot potato pattern][move-hot-potato].
+This is achieved with the [hot potato pattern](https://move-book.com/programmability/hot-potato-pattern.html).
 
 {% hint style="info" %}
 This is a step away from explicitness and towards conventions.
-Prior similar work includes [Originbyte's `request` module][ob-request-module] and [Mysten's `transfer_policy` module][sui-transfer-policy].
+Prior similar work includes [Originbyte's `request` module](https://github.com/Origin-Byte/nft-protocol/tree/main/contracts/request/sources/request) and [Mysten's `transfer_policy` module](https://github.com/MystenLabs/sui/blob/main/crates/sui-framework/packages/sui-framework/sources/kiosk/transfer_policy.move).
 {% endhint %}
 
 A hot potato struct that enables authenticated communication between different packages without explicit dependencies. The `ProofOfUID` is created by one package and subsequently utilized across (potentially) multiple calls inside a PTB, allowing different participating packages to add their unique stamps.
@@ -185,8 +185,3 @@ These primitives are designed to work synergistically, enabling the construction
    - Optional recipient restriction adds targeted security
    - Clear verification of data provenance
 
-<!-- List of References -->
-
-[move-hot-potato]: https://move-book.com/programmability/hot-potato-pattern.html
-[ob-request-module]: https://github.com/Origin-Byte/nft-protocol/tree/main/contracts/request/sources/request
-[sui-transfer-policy]: https://github.com/MystenLabs/sui/blob/main/crates/sui-framework/packages/sui-framework/sources/kiosk/transfer_policy.move

nexus-next/packages/reference/nexus_interface/v1.md

@@ -85,3 +85,4 @@ package upgrade.
 
 
 </details>
+

nexus-next/packages/reference/nexus_interface/version.md

@@ -128,3 +128,4 @@
 
 
 </details>
+

nexus-next/packages/reference/nexus_primitives/data.md

@@ -167,3 +167,4 @@ Serialization conventions are agreed on by the off-chain realm.
 
 
 </details>
+

nexus-next/packages/reference/nexus_primitives/event.md

@@ -63,3 +63,4 @@
 
 
 </details>
+

nexus-next/packages/reference/nexus_primitives/owner_cap.md

@@ -476,3 +476,4 @@ Inner [OwnerCap] will be dropped.
 
 
 </details>
+

nexus-next/packages/reference/nexus_primitives/proof_of_uid.md

@@ -345,3 +345,4 @@ Add a stamp to the proof.
 
 
 </details>
+

nexus-next/packages/reference/nexus_primitives/proven_value.md

@@ -257,3 +257,4 @@ Who is the recipient of the value, if any.
 
 
 </details>
+

nexus-next/packages/reference/nexus_workflow/dag.md

@@ -2079,6 +2079,3 @@ Will emit an event if the execution is done.
 <pre><code><b>fun</b> <a href="../nexus_workflow/dag.md#(nexus_workflow=0x0)_dag_if_finished_emit_final_event">if_finished_emit_final_event</a>(self: &(nexus_workflow=0x0)::<a href="../nexus_workflow/dag.md#(nexus_workflow=0x0)_dag_DAGExecution">dag::DAGExecution</a>)
 </code></pre>
 
-
-
-

nexus-next/packages/reference/nexus_workflow/default_gas_extension.md

@@ -153,6 +153,3 @@ Disables this extension.
 <pre><code><b>public</b> <b>fun</b> <a href="../nexus_workflow/default_gas_extension.md#(nexus_workflow=0x0)_default_gas_extension_disable_expiry">disable_expiry</a>(gas_service: &<b>mut</b> (nexus_workflow=0x0)::<a href="../nexus_workflow/gas.md#(nexus_workflow=0x0)_gas_GasService">gas::GasService</a>, <a href="../nexus_workflow/tool_registry.md#(nexus_workflow=0x0)_tool_registry">tool_registry</a>: &(nexus_workflow=0x0)::<a href="../nexus_workflow/tool_registry.md#(nexus_workflow=0x0)_tool_registry_ToolRegistry">tool_registry::ToolRegistry</a>, owner_cap: &(nexus_primitives=0x0)::owner_cap::CloneableOwnerCap&lt;(nexus_workflow=0x0)::<a href="../nexus_workflow/gas.md#(nexus_workflow=0x0)_gas_OverGas">gas::OverGas</a>&gt;, fqn: <a href="../dependencies/std/ascii.md#std_ascii_String">std::ascii::String</a>, ctx: &<b>mut</b> <a href="../dependencies/sui/tx_context.md#sui_tx_context_TxContext">sui::tx_context::TxContext</a>)
 </code></pre>
 
-
-
-

nexus-next/packages/reference/nexus_workflow/default_sap.md

@@ -282,3 +282,4 @@ One calls this after workflow contract is done with advancing the DAG.
 
 
 </details>
+

nexus-next/packages/reference/nexus_workflow/gas.md

@@ -1092,6 +1092,3 @@ amount requested.
 <pre><code><b>fun</b> <a href="../nexus_workflow/gas.md#(nexus_workflow=0x0)_gas_get_or_insert_tool_gas_mut">get_or_insert_tool_gas_mut</a>(self: &<b>mut</b> (nexus_workflow=0x0)::<a href="../nexus_workflow/gas.md#(nexus_workflow=0x0)_gas_GasService">gas::GasService</a>, fqn: <a href="../dependencies/std/ascii.md#std_ascii_String">std::ascii::String</a>, ctx: &<b>mut</b> <a href="../dependencies/sui/tx_context.md#sui_tx_context_TxContext">sui::tx_context::TxContext</a>): &<b>mut</b> (nexus_workflow=0x0)::<a href="../nexus_workflow/gas.md#(nexus_workflow=0x0)_gas_ToolGas">gas::ToolGas</a>
 </code></pre>
 
-
-
-

nexus-next/packages/reference/nexus_workflow/leader_cap.md

@@ -105,6 +105,3 @@ Creates a founding [CloneableOwnerCap] with a random network ID.
 <pre><code><b>public</b> <b>entry</b> <b>fun</b> <a href="../nexus_workflow/leader_cap.md#(nexus_workflow=0x0)_leader_cap_create_for_self_and_addresses">create_for_self_and_addresses</a>(n_per_address: u64, addresses: vector&lt;<b>address</b>&gt;, ctx: &<b>mut</b> <a href="../dependencies/sui/tx_context.md#sui_tx_context_TxContext">sui::tx_context::TxContext</a>)
 </code></pre>
 
-
-
-

nexus-next/packages/reference/nexus_workflow/main.md

@@ -99,6 +99,3 @@ Amount of leader caps to clone per [DEV_ADDRESSES] address.
 <pre><code><b>fun</b> <a href="../nexus_workflow/main.md#(nexus_workflow=0x0)_main_init">init</a>(ctx: &<b>mut</b> <a href="../dependencies/sui/tx_context.md#sui_tx_context_TxContext">sui::tx_context::TxContext</a>)
 </code></pre>
 
-
-
-

nexus-next/packages/reference/nexus_workflow/tool_registry.md

@@ -740,6 +740,3 @@ Has the tool been unregistered for longer than the lock duration?
 <pre><code><b>fun</b> <a href="../nexus_workflow/tool_registry.md#(nexus_workflow=0x0)_tool_registry_did_unregister_period_pass_">did_unregister_period_pass_</a>(self: &(nexus_workflow=0x0)::<a href="../nexus_workflow/tool_registry.md#(nexus_workflow=0x0)_tool_registry_OffChainTool">tool_registry::OffChainTool</a>, clock: &<a href="../dependencies/sui/clock.md#sui_clock_Clock">sui::clock::Clock</a>): bool
 </code></pre>
 
-
-
-

nexus-next/packages/workflow.md

@@ -228,3 +228,4 @@ The amount of `SUI` locked and the interval after which they can be reclaimed is
   This trade-off was deemed worthy.
 - When using the `ProofOfUid` primitive, it must be created with a type that matches the `UID`.
   The type should be considered an authorization ticket and should be treated just as any other capability type.
+

nexus-next/tool.md

@@ -75,3 +75,4 @@ Coming soon.
 ## Tool authorization
 
 Once there are community Tools, we will need a way to authorize communication between the Leader and a Tool. This has been discussed superficially and it needs to be researched in depth in the future.
+

nexus-sdk/cli.md

@@ -1,6 +1,6 @@
 # Nexus CLI
 
-> concerns [`nexus-cli` repo][nexus-cli-repo]
+> concerns [`nexus-cli` repo](https://github.com/Talus-Network/nexus-sdk/tree/main/cli)
 
 The Nexus CLI is a set of tools that is used by almost all Actors in the Nexus ecosystem.
 
@@ -158,7 +158,7 @@ This command requires that a wallet is connected to the CLI...
 
 ---
 
-**`nexus dag execute --dag-id <id> --input-json <data> --entry-group [group] [--inspect]`**
+**`nexus dag execute --dag-id <id> --input-json <data> --entry-group [group] --encrypt [vertex1.port1 vertex2.port2] [--inspect]`**
 
 Execute a DAG with the provided `<id>`. This command also accepts an entry `<group>` of vertices to be invoked. Find out more about entry groups in [[Package: Workflow]]. Entry `<group>` defaults to a starndardized `_default_group` string.
 
@@ -168,6 +168,8 @@ 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
 
+The `--encrypt` argument accepts a space-separated list of `vertex.port` pairs. The data on these ports will be encrypted before being sent to the chain.
+
 The `--inspect` argument automatically triggers `nexus dag inspect-execution` upon submitting the execution transaction.
 
 {% hint style="info" %}
@@ -258,6 +260,3 @@ 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

nexus-sdk/guides/dag-construction.md

@@ -2,7 +2,7 @@
 
 This guide explains how to construct DAG (Directed Acyclic Graph) JSON files for the Nexus platform. DAGs define the workflow that an Agent will execute.
 
-For an explanation of the terms and rules used below, refer to [the Nexus workflow documentation][nexus-next-workflow].
+For an explanation of the terms and rules used below, refer to [the Nexus workflow documentation](../../nexus-next/packages/workflow.md).
 
 {% hint style="info"%}
 Note that for all DAG related terms in the configuration JSON file, snake casing is applied.
@@ -38,11 +38,14 @@ A DAG JSON file consists of sections defining the graph's components:
 ```
 
 - The `name` must be unique within the DAG.
+
 {% hint style="success" %}
 The input ports of a tool are specified by the tool's output schema saved in the Nexus tool registry. Each input port must have exactly one of:
-  1. An edge leading to it
-  2. A default value
-  3. Be part of `entry_ports`
+
+1. An edge leading to it
+2. A default value
+3. Be part of `entry_ports`
+
 {% endhint %}
 
 - Add the input port as part of `entry_ports` only if it does not have an edge leading into it nor has a default value.
@@ -60,7 +63,8 @@ Edges define the flow of data between vertices, connecting an output port of a s
   "from": {
     "vertex": "source_vertex_name", // Name from the "vertices" list
     "output_variant": "ok", // e.g., ok, err, gt, lt, eq
-    "output_port": "output_port_name"
+    "output_port": "output_port_name",
+    "encrypted": true // Optional, default is false
   },
   "to": {
     "vertex": "target_vertex_name", // Name from the "vertices" list
@@ -71,26 +75,27 @@ Edges define the flow of data between vertices, connecting an output port of a s
 
 - The `source_vertex_name` and `target_vertex_name` refer to the `name` field of vertices defined in the `vertices` list.
 - The `target_input_port_name` must be a valid input port for the tool used by the `target_vertex_name`.
+- If the `encrypted` field is set to `true`, the data will be encrypted before being sent on-chain. This is useful for sensitive data that should not be exposed in plaintext.
 
 ## 4. Default Values
 
 Default values provide static inputs to vertices:
 
 ```json
 {
-  "vertex": "vertex_name",  // References a name from the "vertices" list
+  "vertex": "vertex_name", // References a name from the "vertices" list
   "input_port": "port_name",
   "value": {
     "storage": "inline",
-    "data": value           // This is a JSON value
+    "data": value, // This is a JSON value
   }
 }
 ```
 
 **Important Constraints:**
 
-- An _input port_ can receive data either from an _incoming edge_ or a _default value_, but **never both**. ([workflow rules][nexus-next-workflow] Rule 4)
-- Entry ports **cannot** have default values (by definition). Default values are only permitted for input ports that are _not_ entry ports. ([workflow rules][nexus-next-workflow] Rule 11)
+- An _input port_ can receive data either from an _incoming edge_ or a _default value_, but **never both**. ([workflow rules](../../nexus-next/packages/workflow.md) Rule 4)
+- Entry ports **cannot** have default values (by definition). Default values are only permitted for input ports that are _not_ entry ports. ([workflow rules](../../nexus-next/packages/workflow.md) Rule 11)
 
 ## 5. Entry Groups (Optional)
 
@@ -114,9 +119,28 @@ Being part of an entry group does not imply that all vertices in the group get e
 {% endhint %}
 
 Practically speaking, this means that you'll need to add all vertices to the entry group that either (non-exclusive):
+
 - will immediately start execution
 - need to be provided client input for entry ports
 
+## 6. Outputs (Optional)
+
+Outputs can be defined on vertices that have no outgoing edges. These can be thought of as the return values of a DAG execution. Only ports that are specified here will be part of the `EndStateReachedEvent` emitted by the DAG execution.
+
+```json
+{
+  "vertex": "vertex_name", // Name must exist in the `vertices` list
+  "output_variant": "ok", // e.g., ok, err, gt, lt, eq
+  "output_port": "output_port_name", // e.g., result
+  "encrypted": true // Optional, default is false
+}
+```
+
+**Important Constraints:**
+
+- DAG construction will fail if you attempt to add an output on a vertex that has outgoing edges.
+- Only data from ports that are specified here or in the `edges` field will flow onchain.
+
 ### Summary
 
 - An _entry group_ allows selecting a specific starting configuration of the workflow with selected entry points via `nexus dag execute --entry-group group_name ...`.
@@ -126,11 +150,11 @@ Practically speaking, this means that you'll need to add all vertices to the ent
 - A default entry group can be named `_default_group`. This group is used when no `--entry-group` flag is provided during execution.
 - If no _entry group_ is specified, all vertices that have _entry ports_ are considered part of the `_default_group`.
 
-## 6. Validation Rules
+## 7. Validation Rules
 
-The [Nexus CLI][nexus-cli] (`nexus dag validate`) performs static analysis to enforce the critical rules defined in [workflow rules][nexus-next-workflow].
+The [Nexus CLI](../cli.md) (`nexus dag validate`) performs static analysis to enforce the critical rules defined in [workflow rules](../../nexus-next/packages/workflow.md).
 
-## 7. Best Practices
+## 8. Best Practices
 
 1. **Naming Conventions**:
 
@@ -152,7 +176,7 @@ The [Nexus CLI][nexus-cli] (`nexus dag validate`) performs static analysis to en
    - Document the purpose of each vertex.
    - Refer to the tool documentation for the expected input/output formats for each vertex.
 
-## 8. Example Workflow
+## 9. Example Workflow
 
 Here's a step-by-step process to create a DAG:
 
@@ -189,7 +213,7 @@ Here's a step-by-step process to create a DAG:
    - Verify all connections
    - Test with sample inputs
 
-## 9. Examples
+## 10. Examples
 
 For working examples, see the following files in the `cli/src/dag/_dags` directory:
 
@@ -200,10 +224,5 @@ For working examples, see the following files in the `cli/src/dag/_dags` directo
 - `ig_story_planner_valid.json`: Example of a complex workflow
 - `entry_groups_valid.json`: Example of using entry groups.
 
-For examples of invalid DAGs and common mistakes to avoid (especially regarding Rule 5 - Race Conditions), see the diagrams in [workflow documentation][nexus-next-workflow] and the `*_invalid.json` files in the [testing DAG directory][example-dags].
-
-<!-- List of references -->
+For examples of invalid DAGs and common mistakes to avoid (especially regarding Rule 5 - Race Conditions), see the diagrams in [workflow documentation](../../nexus-next/packages/workflow.md) and the `*_invalid.json` files in the [testing DAG directory](https://github.com/Talus-Network/nexus-sdk/tree/v0.1.0/cli/src/dag/_dags).
 
-[nexus-next-workflow]: ../../nexus-next/packages/workflow.md
-[example-dags]: https://github.com/Talus-Network/nexus-sdk/tree/v0.1.0/cli/src/dag/_dags
-[nexus-cli]: ../cli.md

nexus-sdk/guides/llm-openai-chat-prep-tool.md

@@ -3,9 +3,10 @@
 This guide walks through the development of a tool that converts numbers into a message format compatible with the OpenAI chat completion tool. This is particularly useful when you want to use the results of mathematical operations from the [math tool](../../tools/math/README.md) as input for the [chat completion tool](../../tools/llm-openai-chat-completion/README.md).
 
 {% hint style="info" %} Prerequisites
-* Follow the [setup guide](setup.md) to make sure you've got the [Nexus CLI](../cli.md) installed.
-* Read the [Toolkit Rust](../toolkit-rust.md) and [Tool development](../tool-development.md) docs that provide more context.
-{% endhint %}
+
+- Follow the [setup guide](setup.md) to make sure you've got the [Nexus CLI](../cli.md) installed.
+- Read the [Toolkit Rust](../toolkit-rust.md) and [Tool development](../tool-development.md) docs that provide more context.
+  {% endhint %}
 
 ## Project Setup
 
@@ -318,6 +319,14 @@ This tool is typically used in a DAG to convert the output of a mathematical ope
         }
       }
     }
+  ],
+  "outputs": [
+    {
+      "vertex": "chat",
+      "output_variant": "ok",
+      "output_port": "message",
+      "encrypted": false
+    }
   ]
 }
 ```
@@ -363,3 +372,4 @@ Consider for what use cases you could use this tool to prepare it to add as an L
 ## Next Steps
 
 This tool provides a simple but essential bridge between mathematical operations and chat completion, enabling the creation of more sophisticated DAGs that combine numerical computation with natural language processing. Follow along with the developer guides to expand the [Math Branching Example DAG with LLM chat completion](math-branching-with-chat.md).
+