diff --git a/SUMMARY.md b/SUMMARY.md index cbae0d1..dbb3e7a 100644 --- a/SUMMARY.md +++ b/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) diff --git a/nexus-next/TAP/default-tap.md b/nexus-next/TAP/default-tap.md index c56f154..1ee8939 100644 --- a/nexus-next/TAP/default-tap.md +++ b/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). -{% 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. - + +For a broader security analysis of Nexus, refer to the [whitepaper section 4.4](https://talus.network/nexus/whitepaper.pdf). ## Full Module Code diff --git a/nexus-next/tokenomics/default-gas-extension.md b/nexus-next/tokenomics/default-gas-extension.md new file mode 100644 index 0000000..a43e07d --- /dev/null +++ b/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: +
+ +Toggle code + +```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 = 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, + 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>(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, + 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, + 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>(ExpiryGasOwnerCapKey {}) + .destroy(); + }; + + let cost_per_minute_key = ExpiryCostPerMinuteKey {}; + + if (settings.contains(cost_per_minute_key)) { + settings.remove<_, u64>(cost_per_minute_key); + }; +} +``` + +
+ diff --git a/nexus-next/gas-service.md b/nexus-next/tokenomics/gas-service.md similarity index 69% rename from nexus-next/gas-service.md rename to nexus-next/tokenomics/gas-service.md index 8013b2b..93fdac5 100644 --- a/nexus-next/gas-service.md +++ b/nexus-next/tokenomics/gas-service.md @@ -1,10 +1,6 @@ # Gas Service -{% hint style="warning" %} -The documentation provided here documents code that is currently implemented in the Nexus onchain packages but not yet in the offchain leader node. - -Consequently, these concepts are not enforced as of yet and serve only as informational purpose for future reference. -{% endhint %} +The concepts related to tokenomics as explained in [the tokenomics section](tokenomics.md) are implemented in the `GasService` shared object in Nexus. ## Overview @@ -16,26 +12,26 @@ The gas payment and settlement system in Nexus provides a flexible way to handle The `GasService` is a shared object that manages all gas-related operations. It maintains: -* Gas tickets for tools. -* Gas budgets for different scopes. -* Execution gas settlement state. -* Tool-specific gas settings. +- Gas tickets for tools. +- Gas budgets for different scopes. +- Execution gas settlement state. +- Tool-specific gas settings. ### Gas Tickets Gas tickets represent prepaid access to tool invocations. They can be configured with different modes of operation: 1. **Expiry Mode**: Allows unlimited invocations within a specific time period. -2. **Limited Invocations Mode**: Allows a fixed number of invocations. -3. **Upon Discretion of Tool Mode**: Tool owner has complete control over ticket validity. +1. **Limited Invocations Mode**: Allows a fixed number of invocations. +1. **Upon Discretion of Tool Mode**: Tool owner has complete control over ticket validity. ### Scopes Gas tickets and budgets can be associated with different scopes: 1. **Execution Scope**: Specific to a single DAG execution. -2. **Worksheet Type Scope**: Applies to all executions of a specific worksheet type, i.e. the TAP. -3. **Invoker Address Scope**: Applies to all executions initiated by a specific address. +1. **Worksheet Type Scope**: Applies to all executions of a specific worksheet type, i.e. the TAP. +1. **Invoker Address Scope**: Applies to all executions initiated by a specific address. {% hint style="warning" %} Gas is secured before the tool is invoked to ensure that the tool always gets paid for its usage according to the selected mode. @@ -57,10 +53,10 @@ Manages gas budgets for different scopes in the system. The inner Bag stores bal Manages all gas-related state for a specific tool. This includes: -* Collected gas payments in the vault -* Default cost per invocation -* Tool-specific gas settings -* Available gas tickets for different scopes +- Collected gas payments in the vault +- Default cost per invocation +- Tool-specific gas settings +- Available gas tickets for different scopes ## Gas Payment Modes @@ -69,25 +65,25 @@ Manages all gas-related state for a specific tool. This includes: Tools can set a default cost per invocation. When no gas tickets are available, the system will attempt to charge from the gas budget in the following order: 1. Execution-specific budget -2. Worksheet type budget -3. Invoker address budget +1. Worksheet type budget +1. Invoker address budget ### 2. Gas Extensions -Gas extensions provide alternative payment strategies. The default extension implements an expiry-based system where users can: +Gas extensions provide alternative payment strategies. The [default extension](default-gas-extension.md) implements an expiry-based system where users can: -* Buy access for a specific duration (e.g., 10 minutes). -* Pay a fixed rate per minute. -* Get unlimited invocations during the purchased period. +- Buy access for a specific duration (e.g., 10 minutes). +- Pay a fixed rate per minute. +- Get unlimited invocations during the purchased period. ## Gas Settlement Process 1. When a vertex (tool) is invoked, the system checks if gas has been settled. -2. If not settled, it attempts to find a valid gas ticket for the different scopes in order. -3. Gas tickets are validated against the execution's creation timestamp, not the current time. -4. If no valid ticket is found, it attempts to charge from the gas budget. -5. Once settled, the vertex can be invoked. -6. Gas settlement is idempotent - subsequent checks won't charge again. +1. If not settled, it attempts to find a valid gas ticket for the different scopes in order. +1. Gas tickets are validated against the execution's creation timestamp, not the current time. +1. If no valid ticket is found, it attempts to charge from the gas budget. +1. Once settled, the vertex can be invoked. +1. Gas settlement is idempotent - subsequent checks won't charge again. ### Events @@ -108,7 +104,7 @@ public struct GasSettlementUpdateEvent has copy, drop { } ``` -2. `LeaderClaimedGasEvent` for tracking gas claims by leaders: +1. `LeaderClaimedGasEvent` for tracking gas claims by leaders: ```rust public struct LeaderClaimedGasEvent has copy, drop { @@ -124,28 +120,43 @@ public struct LeaderClaimedGasEvent has copy, drop { There are several ways to check if gas has been paid for a tool invocation: 1. **Using GasService State** - * Anyone can check if gas has been settled for a specific vertex in an execution using [`is_execution_vertex_settled`](#view-operations). - * This is useful both for onchain and offchain actors. - * This is the most direct way to verify gas payment status. - * Returns a boolean indicating whether the vertex can be invoked. -2. **Listening to Events** - * The system emits `GasSettlementUpdateEvent` for each gas settlement attempt. - * Anyone can listen to these events to track gas settlement status. -3. **Checking Gas Tickets** - * Tool owners can check their tool's gas tickets and settings. - * Users can check their own gas budgets and tickets. - * This is useful _before_ the invocation is requested to know whether it's possible to execute with given gas tickets. -4. **Viewing Gas Budgets** - * Users can check their remaining gas budgets for different scopes. - * This is useful _before_ the invocation is requested to know whether it's possible to execute with given gas budgets. + - Anyone can check if gas has been settled for a specific vertex in an execution using [`is_execution_vertex_settled`](#view-operations). + - This is useful both for onchain and offchain actors. + - This is the most direct way to verify gas payment status. + - Returns a boolean indicating whether the vertex can be invoked. +1. **Listening to Events** + - The system emits `GasSettlementUpdateEvent` for each gas settlement attempt. + - Anyone can listen to these events to track gas settlement status. +1. **Checking Gas Tickets** + - Tool owners can check their tool's gas tickets and settings. + - Users can check their own gas budgets and tickets. + - This is useful _before_ the invocation is requested to know whether it's possible to execute with given gas tickets. +1. **Viewing Gas Budgets** + - Users can check their remaining gas budgets for different scopes. + - This is useful _before_ the invocation is requested to know whether it's possible to execute with given gas budgets. + +## Owner Capabilities + +Tool owners have two levels of capabilities for managing their tool's gas operations: + +1. `OverTool` - The main owner cap that provides full control over the tool, including gas operations +1. `OverGas` - A de-escalated version of `OverTool` that provides limited permissions focused only on gas-related operations + +The `OverGas` cap is designed to make tool owners more comfortable using gas extensions by providing a more restricted set of permissions. It allows them to: + +- Add and remove gas tickets. +- Change gas settings. +- Manage gas-related operations. + +without giving them access to other important tool state. This separation of concerns helps maintain security while enabling tool owners to manage their gas operations effectively. ## Security Considerations 1. Gas tickets with expiry or limited invocations cannot be revoked. -2. Only tickets in "Upon Discretion of Tool" mode can be revoked. -3. Tool owners can claim gas at any time. -4. Gas budgets can be refunded if the execution is finished. -5. Workflows that want to pay gas on behalf of the user must assert that they execute in a network with a trusted leader. See [current limitation below](#current-limitation) +1. Only tickets in "Upon Discretion of Tool" mode can be revoked. +1. Tool owners can claim gas at any time. +1. Gas budgets can be refunded if the execution is finished. +1. Workflows that want to pay gas on behalf of the user must assert that they execute in a network with a trusted leader. See [current limitation below](#current-limitation) ### Current limitation @@ -160,9 +171,9 @@ However, this implies that as of right now, the leader is has to be trusted. Tool Owner Operations -#### Gas Cost Management +### Gas Cost Management -1. **Setting Default Cost**\ +1. **Setting Default Cost**\ Sets the default cost in MIST for a single tool invocation. Calling this function enables gas collection by the tool so it's imperative the tool owners calls it to collect fees for tool execution. ```rust @@ -177,7 +188,7 @@ However, this implies that as of right now, the leader is has to be trusted. ``` > Set `single_invocation_cost_mist` to 2^64-1 to enable gas collection but require a gas extension to do it. -2. **Claiming Gas**\ +1. **Claiming Gas**\ Allows the tool owner to withdraw all collected gas payments for their tool. ```rust @@ -190,9 +201,9 @@ However, this implies that as of right now, the leader is has to be trusted. ): Balance ``` -#### Gas Ticket Management +### Gas Ticket Management -1. **Adding Gas Tickets**\ +1. **Adding Gas Tickets**\ Creates a new gas ticket with specified scope and mode of operation. ```rust @@ -210,7 +221,7 @@ However, this implies that as of right now, the leader is has to be trusted. The tool owner can use "upon discretion of the tool" mode to be able to `revoke_gas_ticket` _at will_. -2. **Revoking Gas Tickets**\ +1. **Revoking Gas Tickets**\ Revokes a gas ticket that was created with the "Upon Discretion of Tool" mode. ```rust @@ -223,7 +234,8 @@ The tool owner can use "upon discretion of the tool" mode to be able to `revoke_ ctx: &mut TxContext, ) ``` -3. **Managing Gas Settings**\ + +1. **Managing Gas Settings**\ The tool owner can set the gas settings for the tool. ```rust @@ -235,7 +247,8 @@ The tool owner can use "upon discretion of the tool" mode to be able to `revoke_ ctx: &mut TxContext, ): &mut Bag ``` -4. **De-escalating Permissions**\ + +1. **De-escalating Permissions**\ Converts a tool owner cap into a gas owner cap with reduced permissions. ```rust @@ -267,7 +280,7 @@ public fun donate_to_tool( } ``` -1. **Adding Gas Budget**\ +1. **Adding Gas Budget**\ Adds a gas budget for a specific scope (execution, worksheet type, or invoker address). ```rust @@ -277,7 +290,8 @@ public fun donate_to_tool( budget: Balance, ) ``` -2. **Refunding Execution Gas Budget**\ + +1. **Refunding Execution Gas Budget**\ Refunds any remaining gas budget for a completed execution to the invoker. This operation also cleans up storage by removing the execution gas state, helping to reduce storage costs. ```rust @@ -287,7 +301,8 @@ public fun donate_to_tool( ctx: &mut TxContext, ) ``` -3. **Refunding Invoker Gas Budget**\ + +1. **Refunding Invoker Gas Budget**\ Refunds any remaining gas budget associated with the invoker's address. ```rust @@ -296,7 +311,8 @@ public fun donate_to_tool( ctx: &mut TxContext, ): Balance ``` -4. **Refunding Worksheet Gas Budget**\ + +1. **Refunding Worksheet Gas Budget**\ Refunds any remaining gas budget associated with a specific worksheet type. ```rust @@ -314,7 +330,7 @@ public fun donate_to_tool( #### View Operations -1. **Checking Vertex Settlement**\ +1. **Checking Vertex Settlement**\ Verifies if gas has been settled for a specific vertex in an execution. ```rust @@ -324,7 +340,8 @@ public fun donate_to_tool( vertex: dag::Vertex, ): bool ``` -2. **Reading Tool Gas Settings**\ + +1. **Reading Tool Gas Settings**\ Gets read-only access to a tool's gas settings. ```rust diff --git a/nexus-next/tokenomics/tokenomics.md b/nexus-next/tokenomics/tokenomics.md new file mode 100644 index 0000000..64bec89 --- /dev/null +++ b/nexus-next/tokenomics/tokenomics.md @@ -0,0 +1,61 @@ +# Nexus Tokenomics + +In blockchain systems, typically users pay a gas fee to submit transactions to account for the computational work provided by the validators running the chain. + +In Nexus an agentic workflow is usually triggered by a user action, but the additional work on behalf of the user (or Talus Agent, TAP) during workflow execution is delegated to other parties. This includes: + +- the gas fees the [Leader](../crates/leader.md) incurs when submitting the results of the tool invocations back onchain +- the fees for the service the tool provides + +To manage payment for those fees, Nexus introduces a tokenomics model to manage payments for the agentic (AI) workflow services it provides. + +{% hint style="success" %} +One of the value propositions for Nexus, is its positioning as _Market for Agents_ or _MFA_. It provides the ability for service providers (be it AI or not, offchain or onchain) to offer their service to Talus agent developers using blockchain infrastructure as a unified payment layer. + +This creates a market for agents where users can benefit from blockchain's unique properties, like providing a global, transparent and censorship resistant payment layer and the ability to allow for micro-payments for otherwise inaccessible services. +{% endhint %} + +## Relevant Actors + +From a tokenomics perspective, consider the following actors: + +- the user (human or TAP) +- the tool owner +- the Nexus Leader +- other actors with read access into tokenomics (e.g. explorers) + +## Gas Service Concepts + +The implementation of the `GasService`, a shared object that manages all gas-related operations, can be found in the [dedicated section](gas-service.md). + +### Where to draw gas from? + +Broadly speaking, there's two ways a user gets charged for workflow execution. + +1. They can purchase **prepaid access** to tool invocations, through `GasTickets`. +1. They can add funds directed for gas payments as `GasBudget` + +Tool owners can provide different flavors of gas tickets by using existing or creating custom _gas extensions_ that allow for different modes of operation for the tool to consume gas tickets. The tool owners can also set a cost per single invocation. If no gas tickets are present, tools will charge from a non-zero gas budget instead. + +Both gas tickets and budgets have different _scopes_ to protect users against unintended use of their tickets or budget. + +{% hint style="info" %} +The provision of gas tickets and budgets, gas extensions and different scopes allows for flexibility in handling gas fees for workflow execution. +{% endhint %} + +#### Leader + +The leader requires gas to submit tool invocation outputs onchain and will use gas budget of appropriate scope to do so. + +### Library of gas extensions + +The Talus Labs team will provide some gas exentsion Move packages that can will be able to make up the bulk of use cases, including gas tickets with expiry and limited number of invocations. + +However, the tool developers are free to write custom gas extensions Move packages that correspond to custom mode of operation for their gas tickets. + +For more information and details on the gas service, refer to the [dedicated section](gas-service.md). + +## Nexus CLI + +You'll be able to manage interaction with the gas service through the [Nexus CLI](../../nexus-sdk/cli.md). Please refer to the commands and inspect the gas-related arguments. +