Docs update from nexus-next

SUMMARY.md

@@ -1,72 +1,74 @@
 # Table of contents
 
-* [🏠 Home](README.md)
+- [🏠 Home](README.md)
 
 ## 🔮 Talus Overview
 
-* [🐸 Introduction to Talus](talus-overview/readme.md)
-* [🤖 AI Agent: What's in a Name?](talus-overview/ai-agent-whats-in-a-name.md)
-* [🔬 Nexus Whitepaper](talus-overview/nexus-whitepaper.md)
+- [🐸 Introduction to Talus](talus-overview/readme.md)
+- [🤖 AI Agent: What's in a Name?](talus-overview/ai-agent-whats-in-a-name.md)
+- [🔬 Nexus Whitepaper](talus-overview/nexus-whitepaper.md)
 
 ## 🚀 Getting Started
 
-* [🔌 Setup Guide](nexus-sdk/guides/setup.md)
-* [💨 Dev Quickstart](nexus-sdk/guides/math-branching-quickstart.md)
-* [📓 Dev Guides](getting-started/dev-guides/README.md)
-  * [Build the Quickstart](nexus-sdk/guides/math-branching-dag-builder.md)
-  * [Add Flexibility with Entry Groups](nexus-sdk/guides/math-branching-dag-entry.md)
-  * [Build the Missing Tool](nexus-sdk/guides/llm-openai-chat-prep-tool.md)
-  * [Add an LLM to your DAG](nexus-sdk/guides/math-branching-with-chat.md)
-  * [Protect your Tool](nexus-sdk/guides/tool-firewall.md)
+- [🔌 Setup Guide](nexus-sdk/guides/setup.md)
+- [💨 Dev Quickstart](nexus-sdk/guides/math-branching-quickstart.md)
+- [📓 Dev Guides](getting-started/dev-guides/README.md)
+  - [Build the Quickstart](nexus-sdk/guides/math-branching-dag-builder.md)
+  - [Add Flexibility with Entry Groups](nexus-sdk/guides/math-branching-dag-entry.md)
+  - [Build the Missing Tool](nexus-sdk/guides/llm-openai-chat-prep-tool.md)
+  - [Add an LLM to your DAG](nexus-sdk/guides/math-branching-with-chat.md)
+  - [Protect your Tool](nexus-sdk/guides/tool-firewall.md)
 
 ## 🌟 Product Docs
 
-* [👋 Introducing Nexus](products/introducing-nexus.md)
-* [💧 Why Sui Move?](talus-overview/why-sui-move.md)
-* [💸 Towards an Agentic Economy](products/towards-an-agentic-economy.md)
-* [🎨 Nexus Use Cases](products/nexus-use-cases.md)
+- [👋 Introducing Nexus](products/introducing-nexus.md)
+- [💧 Why Sui Move?](talus-overview/why-sui-move.md)
+- [💸 Towards an Agentic Economy](products/towards-an-agentic-economy.md)
+- [🎨 Nexus Use Cases](products/nexus-use-cases.md)
 
 ## 💻 Developer Docs
 
-* [🫀 Nexus Core](nexus-next/index.md)
-  * [Onchain Nexus](developer-docs/index/onchain-nexus/README.md)
-    * [Workflow](nexus-next/packages/workflow.md)
-    * [Primitives](nexus-next/packages/primitives.md)
-    * [Nexus Interface](nexus-next/packages/nexus-interface.md)
-    * [Sui Move Conventions](nexus-next/conventions/sui-move.md)
-  * [Offchain Nexus](developer-docs/index/offchain-nexus/README.md)
-    * [Leader](nexus-next/crates/leader.md)
-    * [Leader Sui TXs](nexus-next/crates/sui-tx.md)
-  * [Agent Development](nexus-next/TAP/agent-development.md)
-  * [Default TAP](nexus-next/TAP/default-tap.md)
-  * [Tool](nexus-next/tool.md)
-  * [Gas Service](nexus-next/gas-service.md)
-  * [Nexus Core API docs](developer-docs/index/nexus-core-api-docs/README.md)
-    * [nexus\_interface/v1](nexus-next/packages/reference/nexus_interface/v1.md)
-    * [nexus\_interface/version](nexus-next/packages/reference/nexus_interface/version.md)
-    * [nexus\_primitives/data](nexus-next/packages/reference/nexus_primitives/data.md)
-    * [nexus\_primitives/event](nexus-next/packages/reference/nexus_primitives/event.md)
-    * [nexus\_primitives/owner\_cap](nexus-next/packages/reference/nexus_primitives/owner_cap.md)
-    * [nexus\_primitives/proof\_of\_uid](nexus-next/packages/reference/nexus_primitives/proof_of_uid.md)
-    * [nexus\_primitives/proven\_value](nexus-next/packages/reference/nexus_primitives/proven_value.md)
-    * [nexus\_workflow/dag](nexus-next/packages/reference/nexus_workflow/dag.md)
-    * [nexus\_workflow/default\_gas\_extension](nexus-next/packages/reference/nexus_workflow/default_gas_extension.md)
-    * [nexus\_workflow/default\_sap](nexus-next/packages/reference/nexus_workflow/default_sap.md)
-    * [nexus\_workflow/gas](nexus-next/packages/reference/nexus_workflow/gas.md)
-    * [nexus\_workflow/leader\_cap](nexus-next/packages/reference/nexus_workflow/leader_cap.md)
-    * [nexus\_workflow/main](nexus-next/packages/reference/nexus_workflow/main.md)
-    * [nexus\_workflow/tool\_registry](nexus-next/packages/reference/nexus_workflow/tool_registry.md)
-* [🧰 Nexus SDK](nexus-sdk/index.md)
-  * [CLI](nexus-sdk/cli.md)
-  * [Tool Development](nexus-sdk/tool-development.md)
-  * [Toolkit Rust](nexus-sdk/toolkit-rust.md)
-  * [How to Build a DAG](nexus-sdk/guides/dag-construction.md)
-* [Technical Glossary](nexus-next/glossary.md)
+- [🫀 Nexus Core](nexus-next/index.md)
+  - [Onchain Nexus](developer-docs/index/onchain-nexus/README.md)
+    - [Workflow](nexus-next/packages/workflow.md)
+    - [Primitives](nexus-next/packages/primitives.md)
+    - [Nexus Interface](nexus-next/packages/nexus-interface.md)
+    - [Sui Move Conventions](nexus-next/conventions/sui-move.md)
+  - [Offchain Nexus](developer-docs/index/offchain-nexus/README.md)
+    - [Leader](nexus-next/crates/leader.md)
+    - [Leader Sui TXs](nexus-next/crates/sui-tx.md)
+  - [Agent Development](nexus-next/TAP/agent-development.md)
+  - [Default TAP](nexus-next/TAP/default-tap.md)
+  - [Tool](nexus-next/tool.md)
+  - [Tokenomics](nexus-next/tokenomics/tokenomics.md)
+    - [Gas Service](nexus-next/tokenomics/gas-service.md)
+    - [Default Gas Extension](nexus-next/tokenomics/default-gas-extension.md)
+  - [Nexus Core API docs](developer-docs/index/nexus-core-api-docs/README.md)
+    - [nexus\_interface/v1](nexus-next/packages/reference/nexus_interface/v1.md)
+    - [nexus\_interface/version](nexus-next/packages/reference/nexus_interface/version.md)
+    - [nexus\_primitives/data](nexus-next/packages/reference/nexus_primitives/data.md)
+    - [nexus\_primitives/event](nexus-next/packages/reference/nexus_primitives/event.md)
+    - [nexus\_primitives/owner\_cap](nexus-next/packages/reference/nexus_primitives/owner_cap.md)
+    - [nexus\_primitives/proof\_of\_uid](nexus-next/packages/reference/nexus_primitives/proof_of_uid.md)
+    - [nexus\_primitives/proven\_value](nexus-next/packages/reference/nexus_primitives/proven_value.md)
+    - [nexus\_workflow/dag](nexus-next/packages/reference/nexus_workflow/dag.md)
+    - [nexus\_workflow/default\_gas\_extension](nexus-next/packages/reference/nexus_workflow/default_gas_extension.md)
+    - [nexus\_workflow/default\_sap](nexus-next/packages/reference/nexus_workflow/default_sap.md)
+    - [nexus\_workflow/gas](nexus-next/packages/reference/nexus_workflow/gas.md)
+    - [nexus\_workflow/leader\_cap](nexus-next/packages/reference/nexus_workflow/leader_cap.md)
+    - [nexus\_workflow/main](nexus-next/packages/reference/nexus_workflow/main.md)
+    - [nexus\_workflow/tool\_registry](nexus-next/packages/reference/nexus_workflow/tool_registry.md)
+- [🧰 Nexus SDK](nexus-sdk/index.md)
+  - [CLI](nexus-sdk/cli.md)
+  - [Tool Development](nexus-sdk/tool-development.md)
+  - [Toolkit Rust](nexus-sdk/toolkit-rust.md)
+  - [How to Build a DAG](nexus-sdk/guides/dag-construction.md)
+- [Technical Glossary](nexus-next/glossary.md)
 
 ## 🛠️ Tools
 
-* [⚓ Nexus Standard Tools](tools/nexus-standard-tools.md)
-  * [Math](tools/math/README.md)
-  * [LLM: OpenAI Chat Completion](tools/llm-openai-chat-completion/README.md)
-  * [Social : X](tools/social-twitter/README.md)
-  * [Storage: Walrus](tools/storage-walrus/README.md)
+- [⚓ Nexus Standard Tools](tools/nexus-standard-tools.md)
+  - [Math](tools/math/README.md)
+  - [LLM: OpenAI Chat Completion](tools/llm-openai-chat-completion/README.md)
+  - [Social : X](tools/social-twitter/README.md)
+  - [Storage: Walrus](tools/storage-walrus/README.md)

nexus-next/TAP/default-tap.md

@@ -6,28 +6,31 @@ The Default TAP is a useful helper component for Nexus agent developers. It serv
 
 ## Interface Compliance
 
-The Default TAP implements the [Nexus Interface V1](../packages/nexus-interface.md#v1)  specification, which defines the required functionality for any Talus Agent Package to integrate with the Nexus workflow engine. Key interface requirements include:
+The Default TAP implements the [Nexus Interface V1](../packages/nexus-interface.md#v1) specification, which defines the required functionality for any Talus Agent Package to integrate with the Nexus workflow engine. Key interface requirements include:
 
 1. **Version Management**
    - Must declare and maintain interface version compatibility.
    - Must support version checking for backward compatibility.
 
-2. **Workflow Management**
+1. **Workflow Management**
    - Must handle worksheet management and state tracking.
    - Must support tool evaluation confirmation.
 
-3. **Authorization**
+1. **Authorization**
    - Must implement witness-based authorization.
    - Must support package upgrade mechanisms.
 
 For detailed interface requirements, see the [Nexus Interface Documentation](../packages/nexus-interface.md).
 
 <!-- Gitbook syntax -->
-{% hint style="info" %} In the code snippets below, we reference some Sui Move patterns (e.g. hot potato), please refer to the [primitives package doc](../packages/primitives.md) for more information on the approach taken here. {% endhint %}
+{% hint style="info" %}
+In the code snippets below, we reference some Sui Move patterns (e.g. hot potato), please refer to the [primitives package doc](../packages/primitives.md) for more information on the approach taken here. 
+{% endhint %}
 
 ### DefaultTAP Structure
 
 The agent will be represented by the `DefaultTAP` struct, which is a shared object that contains:
+
 - `id`: A unique identifier for the TAP instance.
 - `witness`: A Bag containing authorization tokens for package identification and upgrade management.
 - `iv`: The interface version (currently v1) that clients can use to determine compatibility.
@@ -56,10 +59,11 @@ public struct DefaultTAP has key {
 ### Constructor and Leader Registration
 
 The DefaultTAP is created using the `new()` constructor function, which:
+
 1. Creates a new DefaultTAP instance with a unique ID.
-2. Initializes a witness token for package identification.
-3. Sets the Nexus interface version to v1.
-4. Registers the TAP with the Nexus leader.
+1. Initializes a witness token for package identification.
+1. Sets the Nexus interface version to v1.
+1. Registers the TAP with the Nexus leader.
 
 ```rust
 use nexus_interface::version::{Self, InterfaceVersion};
@@ -97,8 +101,8 @@ public struct DefaultSAPV1Witness has key, store {
 The worksheet function is a core requirement of the Nexus Interface V1 specification. It creates a proof of UID (Unique Identifier) that serves as a "stamp collector" for tracking workflow execution state. This proof:
 
 1. Acts as a hot-potato object that collects execution confirmations from Nexus components like the DAG.
-2. Must be constructed with a type defined in the same package and module that implements the interface.
-3. Is used to verify that required operations have been performed in the correct sequence.
+1. Must be constructed with a type defined in the same package and module that implements the interface.
+1. Is used to verify that required operations have been performed in the correct sequence.
 
 ```rust
 use nexus_interface::version::InterfaceVersion;
@@ -115,8 +119,8 @@ public fun worksheet(self: &DefaultSAP): ProofOfUID {
 The `confirm_tool_eval_for_walk` function is another core requirement of the Nexus Interface V1 specification. It is invoked by the Nexus Leader after a workflow contract has advanced the DAG to:
 
 1. Consume the worksheet hot-potato.
-2. Verify that all required confirmations have been collected.
-3. Complete the tool evaluation cycle for a specific walk in the workflow.
+1. Verify that all required confirmations have been collected.
+1. Complete the tool evaluation cycle for a specific walk in the workflow.
 
 ```rust
 use nexus_interface::version::InterfaceVersion
@@ -144,10 +148,10 @@ The Default TAP works in conjunction with the Nexus workflow engine, which provi
    - Support for vertices, edges, and input/output ports.
    - Entry group management for workflow initiation.
 
-2. **Tool Registry**
+1. **Tool Registry**
    - Registration and management of available tools.
 
-3. **Tool Invocation**
+1. **Tool Invocation**
    - Support for tool execution invocation, onchain or offchain.
    - Leader capability management.
 
@@ -160,10 +164,10 @@ The DAG execution is initiated through the `begin_dag_execution` function.
 This function:
 
 1. Takes a DAG and entry vertices with their input data.
-2. Creates a worksheet to track execution state.
-3. Begins execution of the entry group through the DAG.
-4. Requests the network to execute walks through the DAG.
-5. Shares the execution object for tracking progress.
+1. Creates a worksheet to track execution state.
+1. Begins execution of the entry group through the DAG.
+1. Requests the network to execute walks through the DAG.
+1. Shares the execution object for tracking progress.
 
 ```rust
 use nexus_primitives::data::NexusData;
@@ -215,7 +219,8 @@ public fun begin_dag_execution(
 - Interface version checking ensures compatibility.
 - Worksheet proofs ensure state integrity.
 - Tool execution is properly isolated.
-<!-- TODO: refer to Security analysis after integrating Stephen's whitepaper section on it -->
+
+For a broader security analysis of Nexus, refer to the [whitepaper section 4.4](https://talus.network/nexus/whitepaper.pdf).
 
 ## Full Module Code
 

nexus-next/tokenomics/default-gas-extension.md

@@ -0,0 +1,134 @@
+# Gas extensions example
+
+Gas extensions provide the ability for tool owners to provide gas tickets to users for custom payment strategies.
+
+Nexus considers two default modes of operation for gas tickets: expiry and limited invocations. The implementation in move code is provided below as an inspiration for custom gas extensions that leverage the `UponDiscretionOfTool` modus operandi.
+
+## Implementation of default gas extension (expiry based)
+
+Toggle to see the full module code for the default gas extension move module:
+<details>
+
+<summary>Toggle code</summary>
+
+```rust
+use nexus_workflow::gas;
+use nexus_workflow::tool_registry::ToolRegistry;
+use std::ascii::String as AsciiString;
+use sui::clock::Clock;
+use sui::coin::Coin;
+use sui::sui::SUI;
+
+// === Errors ===
+
+#[error]
+const EThisMethodIsNotEnabled: vector<u8> = b"This method is not enabled";
+
+// === Expiry Extension ===
+
+/// How many [SUI] tokens should be paid for each minute.
+public struct ExpiryCostPerMinuteKey has copy, drop, store {}
+/// Will hold the gas owner cap to do requests on behalf of the tool owner.
+public struct ExpiryGasOwnerCapKey has copy, drop, store {}
+
+public entry fun buy_expiry_gas_ticket(
+    gas_service: &mut gas::GasService,
+    tool_registry: &ToolRegistry,
+    fqn: AsciiString,
+    minutes: u64,
+    pay_with: &mut Coin<SUI>,
+    clock: &Clock,
+    ctx: &mut TxContext,
+) {
+    let settings = gas_service.get_tool_gas_setting(fqn);
+
+    assert!(settings.contains(ExpiryGasOwnerCapKey {}), EThisMethodIsNotEnabled);
+    let owner_cap = settings
+        .borrow<_, CloneableOwnerCap<gas::OverGas>>(ExpiryGasOwnerCapKey {})
+        .clone(ctx);
+
+    let cost_per_minute = *settings.borrow<_, u64>(ExpiryCostPerMinuteKey {});
+
+    gas_service.add_gas_ticket(
+        tool_registry,
+        &owner_cap,
+        fqn,
+        gas::scope_invoker_address(ctx.sender()),
+        gas::modus_operandi_expiry(minutes * 60 * 1000),
+        clock,
+        ctx,
+    );
+    owner_cap.destroy();
+
+    gas_service.donate_to_tool(fqn, pay_with.balance_mut().split(cost_per_minute * minutes));
+}
+
+/// Enables buying gas tickets that expire after a certain time in token
+/// [SUI] for [cost_per_minute] of those tokens.
+///
+/// To update the cost just call this function again with the new value.
+public fun enable_expiry(
+    gas_service: &mut gas::GasService,
+    tool_registry: &ToolRegistry,
+    owner_cap: &CloneableOwnerCap<gas::OverGas>,
+    cost_per_minute: u64,
+    fqn: AsciiString,
+    ctx: &mut TxContext,
+) {
+    let owner_cap = owner_cap.clone(ctx);
+
+    let settings = gas_service.get_tool_gas_setting_mut(
+        tool_registry,
+        &owner_cap,
+        fqn,
+        ctx,
+    );
+
+    if (!settings.contains(ExpiryGasOwnerCapKey {})) {
+        settings.add(ExpiryGasOwnerCapKey {}, owner_cap);
+    } else {
+        owner_cap.destroy();
+    };
+
+    let cost_per_minute_key = ExpiryCostPerMinuteKey {};
+
+    if (settings.contains(cost_per_minute_key)) {
+        // already configured, let's reset it
+
+        settings.remove<_, u64>(cost_per_minute_key);
+    };
+
+    settings.add(cost_per_minute_key, cost_per_minute);
+}
+
+/// Disables this extension.
+public fun disable_expiry(
+    gas_service: &mut gas::GasService,
+    tool_registry: &ToolRegistry,
+    owner_cap: &CloneableOwnerCap<gas::OverGas>,
+    fqn: AsciiString,
+    ctx: &mut TxContext,
+) {
+    let settings = gas_service.get_tool_gas_setting_mut(
+        tool_registry,
+        owner_cap,
+        fqn,
+        ctx,
+    );
+
+    if (settings.contains(ExpiryGasOwnerCapKey {})) {
+        settings
+            .remove<_, CloneableOwnerCap<gas::OverGas>>(ExpiryGasOwnerCapKey {})
+            .destroy();
+    };
+
+    let cost_per_minute_key = ExpiryCostPerMinuteKey {};
+
+    if (settings.contains(cost_per_minute_key)) {
+        settings.remove<_, u64>(cost_per_minute_key);
+    };
+}
+```
+
+</details>
+