diff --git a/nexus-next/TAP/default-tap.md b/nexus-next/TAP/default-tap.md index 1ee8939..8fa4e68 100644 --- a/nexus-next/TAP/default-tap.md +++ b/nexus-next/TAP/default-tap.md @@ -9,10 +9,12 @@ The Default TAP is a useful helper component for Nexus agent developers. It serv 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. 1. **Workflow Management** + - Must handle worksheet management and state tracking. - Must support tool evaluation confirmation. @@ -23,8 +25,9 @@ The Default TAP implements the [Nexus Interface V1](../packages/nexus-interface. 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. +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 @@ -50,7 +53,7 @@ public struct DefaultTAP has key { /// so we need to always create a new type and query it from the type via /// its type name. witness: Bag, - /// Clients can search the smart agent shared object for this type to + /// Clients can search the talus agent shared object for this type to /// determine what interface to expect. iv: InterfaceVersion, } @@ -72,26 +75,26 @@ use sui::object::UID; use sui::transfer::share_object; public(package) fun new(ctx: &mut TxContext) { - let default_sap = DefaultSAP { + let default_tap = DefaultTAP { id: object::new(ctx), witness: { let mut b = bag::new(ctx); - b.add(b"witness", DefaultSAPV1Witness { id: object::new(ctx) }); + b.add(b"witness", DefaultTAPV1Witness { id: object::new(ctx) }); b }, iv: version::v(1), }; announce_interface_package( - default_sap.get_witness(), - vector[object::id(&default_sap)], + default_tap.get_witness(), + vector[object::id(&default_tap)], ); - share_object(default_sap); + share_object(default_tap); } /// with... -public struct DefaultSAPV1Witness has key, store { +public struct DefaultTAPV1Witness has key, store { id: UID, } ``` @@ -108,7 +111,7 @@ The worksheet function is a core requirement of the Nexus Interface V1 specifica use nexus_interface::version::InterfaceVersion; use nexus_primitives::proof_of_uid::{Self, ProofOfUID}; -public fun worksheet(self: &DefaultSAP): ProofOfUID { +public fun worksheet(self: &DefaultTAP): ProofOfUID { self.iv.expect_v(1); proof_of_uid::new_with_type(&self.get_witness().id, self.get_witness()) } @@ -126,7 +129,7 @@ The `confirm_tool_eval_for_walk` function is another core requirement of the Nex use nexus_interface::version::InterfaceVersion public fun confirm_tool_eval_for_walk( - self: &mut DefaultSAP, + self: &mut DefaultTAP, worksheet: ProofOfUID, ) { self.iv.expect_v(1); @@ -134,7 +137,7 @@ public fun confirm_tool_eval_for_walk( } /// with... -fun get_witness(self: &DefaultSAP): &DefaultSAPV1Witness { +fun get_witness(self: &DefaultTAP): &DefaultTAPV1Witness { self.witness.borrow(b"witness") } ``` @@ -144,11 +147,13 @@ fun get_witness(self: &DefaultSAP): &DefaultSAPV1Witness { The Default TAP works in conjunction with the Nexus workflow engine, which provides: 1. **DAG Implementation** + - Directed Acyclic Graph data structure for modeling complex workflows. - Support for vertices, edges, and input/output ports. - Entry group management for workflow initiation. 1. **Tool Registry** + - Registration and management of available tools. 1. **Tool Invocation** @@ -177,7 +182,7 @@ use nexus_workflow::dag::{DAG, Vertex, InputPort, EntryGroup}; /// Invokes the provided entry vertex on a DAG with the provided input data for /// each input port. public fun begin_dag_execution( - self: &mut DefaultSAP, + self: &mut DefaultTAP, dag: &DAG, network: ID, entry_group: EntryGroup, @@ -225,14 +230,15 @@ For a broader security analysis of Nexus, refer to the [whitepaper section 4.4]( ## Full Module Code Toggle to see the full module code for the default TAP: +
Toggle code ```rust -module nexus_workflow::default_sap; +module nexus_workflow::default_tap; -//! Module defining a default smart agent package with no added logic but +//! Module defining a default talus agent package with no added logic but //! executing the provided DAG. This can be used for examples, tests or to run //! JSON-defined DAGs from the CLI or via other means. @@ -246,7 +252,7 @@ use sui::transfer::{share_object, public_share_object}; use sui::vec_map::{VecMap}; /// Shared object. -public struct DefaultSAP has key { +public struct DefaultTAP has key { id: UID, /// On package upgrade, we'll want to replace the previous witness with a /// new one that identifies the new package. @@ -255,7 +261,7 @@ public struct DefaultSAP has key { /// so we need to always create a new type and query it from the type via /// its type name. witness: Bag, - /// Clients can search the smart agent shared object for this type to + /// Clients can search the talus agent shared object for this type to /// determine what interface to expect. iv: InterfaceVersion, } @@ -264,27 +270,27 @@ public struct DefaultSAP has key { /// /// Will also serve as authorization token to change list of shared objects for /// nexus interface v1. -public struct DefaultSAPV1Witness has key, store { +public struct DefaultTAPV1Witness has key, store { id: UID, } public(package) fun new(ctx: &mut TxContext) { - let default_sap = DefaultSAP { + let default_tap = DefaultTAP { id: object::new(ctx), witness: { let mut b = bag::new(ctx); - b.add(b"witness", DefaultSAPV1Witness { id: object::new(ctx) }); + b.add(b"witness", DefaultTAPV1Witness { id: object::new(ctx) }); b }, iv: nexus_interface::version::v(1), }; nexus_interface::v1::announce_interface_package( - default_sap.get_witness(), - vector[object::id(&default_sap)], + default_tap.get_witness(), + vector[object::id(&default_tap)], ); - share_object(default_sap); + share_object(default_tap); } // === Client entry === @@ -293,7 +299,7 @@ public(package) fun new(ctx: &mut TxContext) { /// each input port. #[allow(lint(share_owned))] public fun begin_dag_execution( - self: &mut DefaultSAP, + self: &mut DefaultTAP, dag: &DAG, network: ID, entry_group: EntryGroup, @@ -331,7 +337,7 @@ public fun begin_dag_execution( // === Nexus interface v1 === /// Nexus resources can prove that they did a thing. -public fun worksheet(self: &DefaultSAP): ProofOfUID { +public fun worksheet(self: &DefaultTAP): ProofOfUID { self.iv.expect_v(1); proof_of_uid::new_with_type(&self.get_witness().id, self.get_witness()) @@ -339,7 +345,7 @@ public fun worksheet(self: &DefaultSAP): ProofOfUID { /// One calls this after workflow contract is done with advancing the DAG. public fun confirm_tool_eval_for_walk( - self: &mut DefaultSAP, + self: &mut DefaultTAP, worksheet: ProofOfUID, ) { self.iv.expect_v(1); @@ -347,7 +353,7 @@ public fun confirm_tool_eval_for_walk( worksheet.consume(&self.get_witness().id); } -fun get_witness(self: &DefaultSAP): &DefaultSAPV1Witness { +fun get_witness(self: &DefaultTAP): &DefaultTAPV1Witness { self.witness.borrow(b"witness") } diff --git a/nexus-next/packages/reference/nexus_workflow/dag.md b/nexus-next/packages/reference/nexus_workflow/dag.md index fdd0f1b..cf01cdd 100644 --- a/nexus-next/packages/reference/nexus_workflow/dag.md +++ b/nexus-next/packages/reference/nexus_workflow/dag.md @@ -518,7 +518,7 @@ vertices and following the edges. worksheet_from_type: std::type_name::TypeName
- The off-chain realm can determine the Smart Agent Package to invoke + The off-chain realm can determine the Talus Agent Package to invoke thanks to the package address and module name from this field.
@@ -910,7 +910,7 @@ for more information. worksheet_from_type: std::type_name::TypeName
- The off-chain realm can determine the Smart Agent Package to invoke + The off-chain realm can determine the Talus Agent Package to invoke thanks to the package address and module name from this field.
diff --git a/nexus-next/packages/reference/nexus_workflow/default_tap.md b/nexus-next/packages/reference/nexus_workflow/default_tap.md new file mode 100644 index 0000000..b6e2415 --- /dev/null +++ b/nexus-next/packages/reference/nexus_workflow/default_tap.md @@ -0,0 +1,237 @@ + + +# Module `(nexus_workflow=0x0)::default_tap` + +- [Struct `DefaultTAP`](<#(nexus_workflow=0x0)_default_tap_DefaultTAP>) +- [Struct `DefaultTAPV1Witness`](<#(nexus_workflow=0x0)_default_tap_DefaultTAPV1Witness>) +- [Function `new`](<#(nexus_workflow=0x0)_default_tap_new>) +- [Function `begin_dag_execution`](<#(nexus_workflow=0x0)_default_tap_begin_dag_execution>) +- [Function `worksheet`](<#(nexus_workflow=0x0)_default_tap_worksheet>) +- [Function `confirm_tool_eval_for_walk`](<#(nexus_workflow=0x0)_default_tap_confirm_tool_eval_for_walk>) +- [Function `get_witness`](<#(nexus_workflow=0x0)_default_tap_get_witness>) + +
use (nexus_interface=0x0)::v1;
+use (nexus_interface=0x0)::version;
+use (nexus_primitives=0x0)::data;
+use (nexus_primitives=0x0)::event;
+use (nexus_primitives=0x0)::owner_cap;
+use (nexus_primitives=0x0)::proof_of_uid;
+use (nexus_workflow=0x0)::dag;
+use (nexus_workflow=0x0)::leader_cap;
+use std::address;
+use std::ascii;
+use std::bcs;
+use std::option;
+use std::string;
+use std::type_name;
+use std::vector;
+use sui::address;
+use sui::bag;
+use sui::clock;
+use sui::dynamic_field;
+use sui::dynamic_object_field;
+use sui::event;
+use sui::hex;
+use sui::object;
+use sui::object_table;
+use sui::table;
+use sui::transfer;
+use sui::tx_context;
+use sui::vec_map;
+use sui::vec_set;
+
+ + + +## Struct `DefaultTAP` + +Shared object. + +
public struct DefaultTAP has key
+
+ +
+Fields + +
+
+id: sui::object::UID +
+
+
+
+witness: sui::bag::Bag +
+
+ On package upgrade, we'll want to replace the previous witness with a + new one that identifies the new package. + This is because as of now Sui doesn't give us access to the package ID + so we need to always create a new type and query it from the type via + its type name. +
+
+iv: (nexus_interface=0x0)::version::InterfaceVersion +
+
+ Clients can search the talus agent shared object for this type to + determine what interface to expect. +
+
+ +
+ + + +## Struct `DefaultTAPV1Witness` + +Used to identify the package::module deployment. + +Will also serve as authorization token to change list of shared objects for +nexus interface v1. + +
public struct DefaultTAPV1Witness has key, store
+
+ +
+Fields + +
+
+id: sui::object::UID +
+
+
+
+ +
+ + + +## Function `new` + +
public(package) fun new(ctx: &mut sui::tx_context::TxContext)
+
+ +
+Implementation + +
public(package) fun new(ctx: &mut TxContext) {
+    let default_tap = DefaultTAP {
+        id: object::new(ctx),
+        witness: {
+            let mut b = bag::new(ctx);
+            b.add(b"witness", DefaultTAPV1Witness { id: object::new(ctx) });
+            b
+        },
+        iv: nexus_interface::version::v(1),
+    };
+    nexus_interface::v1::announce_interface_package(
+        default_tap.get_witness(),
+        vector[object::id(&default_tap)],
+    );
+    share_object(default_tap);
+}
+
+ +
+ + + +## Function `begin_dag_execution` + +Invokes the provided entry vertex on a DAG with the provided input data for +each input port. + +
public fun begin_dag_execution(self: &mut (nexus_workflow=0x0)::default_tap::DefaultTAP, dag: &(nexus_workflow=0x0)::dag::DAG, network: sui::object::ID, entry_group: (nexus_workflow=0x0)::dag::EntryGroup, with_vertex_inputs: sui::vec_map::VecMap<(nexus_workflow=0x0)::dag::Vertex, sui::vec_map::VecMap<(nexus_workflow=0x0)::dag::InputPort, (nexus_primitives=0x0)::data::NexusData>>, clock: &sui::clock::Clock, ctx: &mut sui::tx_context::TxContext)
+
+ +
+Implementation + +
public fun begin_dag_execution(
+    self: &mut DefaultTAP,
+    dag: &DAG,
+    network: ID,
+    entry_group: EntryGroup,
+    with_vertex_inputs: VecMap<Vertex, VecMap<InputPort, NexusData>>,
+    clock: &Clock,
+    ctx: &mut TxContext,
+) {
+    self.iv.expect_v(1);
+    let mut worksheet = self.worksheet();
+    let (mut execution, ticket) = dag.begin_execution_of_entry_group(
+        &mut worksheet,
+        network,
+        entry_group,
+        with_vertex_inputs,
+        clock,
+        ctx
+    );
+    worksheet.consume(&self.get_witness().id);
+    dag.request_network_to_execute_walks(&mut execution, ticket, ctx);
+    public_share_object(execution);
+}
+
+ +
+ + + +## Function `worksheet` + +Nexus resources can prove that they did a thing. + +
public fun worksheet(self: &(nexus_workflow=0x0)::default_tap::DefaultTAP): (nexus_primitives=0x0)::proof_of_uid::ProofOfUID
+
+ +
+Implementation + +
public fun worksheet(self: &DefaultTAP): ProofOfUID {
+    self.iv.expect_v(1);
+    proof_of_uid::new_with_type(&self.get_witness().id, self.get_witness())
+}
+
+ +
+ + + +## Function `confirm_tool_eval_for_walk` + +One calls this after workflow contract is done with advancing the DAG. + +
public fun confirm_tool_eval_for_walk(self: &mut (nexus_workflow=0x0)::default_tap::DefaultTAP, worksheet: (nexus_primitives=0x0)::proof_of_uid::ProofOfUID)
+
+ +
+Implementation + +
public fun confirm_tool_eval_for_walk(
+    self: &mut DefaultTAP,
+    worksheet: ProofOfUID,
+) {
+    self.iv.expect_v(1);
+    worksheet.consume(&self.get_witness().id);
+}
+
+ +
+ + + +## Function `get_witness` + +
fun get_witness(self: &(nexus_workflow=0x0)::default_tap::DefaultTAP): &(nexus_workflow=0x0)::default_tap::DefaultTAPV1Witness
+
+ +
+Implementation + +
fun get_witness(self: &DefaultTAP): &DefaultTAPV1Witness {
+    self.witness.borrow(b"witness")
+}
+
+ +
+ diff --git a/nexus-next/packages/reference/nexus_workflow/gas.md b/nexus-next/packages/reference/nexus_workflow/gas.md index 885f62f..9928bd7 100644 --- a/nexus-next/packages/reference/nexus_workflow/gas.md +++ b/nexus-next/packages/reference/nexus_workflow/gas.md @@ -1,55 +1,51 @@ - # Module `(nexus_workflow=0x0)::gas` - - -- [Struct `GasService`](#(nexus_workflow=0x0)_gas_GasService) -- [Struct `ExecutionGas`](#(nexus_workflow=0x0)_gas_ExecutionGas) -- [Struct `GasBudgets`](#(nexus_workflow=0x0)_gas_GasBudgets) -- [Struct `ToolGas`](#(nexus_workflow=0x0)_gas_ToolGas) -- [Struct `GasTicket`](#(nexus_workflow=0x0)_gas_GasTicket) -- [Struct `OverGas`](#(nexus_workflow=0x0)_gas_OverGas) -- [Struct `GasSettlementUpdateEvent`](#(nexus_workflow=0x0)_gas_GasSettlementUpdateEvent) -- [Struct `LeaderClaimedGasEvent`](#(nexus_workflow=0x0)_gas_LeaderClaimedGasEvent) -- [Enum `ModusOperandi`](#(nexus_workflow=0x0)_gas_ModusOperandi) -- [Enum `Scope`](#(nexus_workflow=0x0)_gas_Scope) - - [For Clients](#@For_Clients_0) -- [Constants](#@Constants_1) -- [Function `modus_operandi_limited_invocations`](#(nexus_workflow=0x0)_gas_modus_operandi_limited_invocations) -- [Function `modus_operandi_expiry`](#(nexus_workflow=0x0)_gas_modus_operandi_expiry) -- [Function `modus_operandi_upon_discretion_of_the_tool`](#(nexus_workflow=0x0)_gas_modus_operandi_upon_discretion_of_the_tool) -- [Function `scope_invoker_address`](#(nexus_workflow=0x0)_gas_scope_invoker_address) -- [Function `scope_worksheet_type`](#(nexus_workflow=0x0)_gas_scope_worksheet_type) -- [Function `scope_execution`](#(nexus_workflow=0x0)_gas_scope_execution) -- [Function `new_service`](#(nexus_workflow=0x0)_gas_new_service) -- [Function `share_service`](#(nexus_workflow=0x0)_gas_share_service) -- [Function `set_single_invocation_cost_mist`](#(nexus_workflow=0x0)_gas_set_single_invocation_cost_mist) -- [Function `claim_gas`](#(nexus_workflow=0x0)_gas_claim_gas) -- [Function `add_gas_ticket`](#(nexus_workflow=0x0)_gas_add_gas_ticket) -- [Function `revoke_gas_ticket`](#(nexus_workflow=0x0)_gas_revoke_gas_ticket) -- [Function `get_tool_gas_setting_mut`](#(nexus_workflow=0x0)_gas_get_tool_gas_setting_mut) -- [Function `deescalate`](#(nexus_workflow=0x0)_gas_deescalate) -- [Function `claim_leader_gas`](#(nexus_workflow=0x0)_gas_claim_leader_gas) - - [How does the leader estimate the amount?](#@How_does_the_leader_estimate_the_amount?_2) - - [Trust the leader?](#@Trust_the_leader?_3) -- [Function `sync_gas_state`](#(nexus_workflow=0x0)_gas_sync_gas_state) -- [Function `sync_gas_state_for_vertex`](#(nexus_workflow=0x0)_gas_sync_gas_state_for_vertex) -- [Function `donate_to_tool`](#(nexus_workflow=0x0)_gas_donate_to_tool) -- [Function `add_gas_budget`](#(nexus_workflow=0x0)_gas_add_gas_budget) -- [Function `refund_execution_gas_budget`](#(nexus_workflow=0x0)_gas_refund_execution_gas_budget) -- [Function `refund_invoker_gas_budget`](#(nexus_workflow=0x0)_gas_refund_invoker_gas_budget) -- [Function `refund_worksheet_gas_budget`](#(nexus_workflow=0x0)_gas_refund_worksheet_gas_budget) -- [Function `is_execution_vertex_settled`](#(nexus_workflow=0x0)_gas_is_execution_vertex_settled) -- [Function `get_tool_gas_setting`](#(nexus_workflow=0x0)_gas_get_tool_gas_setting) -- [Function `try_settle_execution_for_vertex`](#(nexus_workflow=0x0)_gas_try_settle_execution_for_vertex) -- [Function `try_stamp`](#(nexus_workflow=0x0)_gas_try_stamp) -- [Function `try_stamp_scope`](#(nexus_workflow=0x0)_gas_try_stamp_scope) - - [Important](#@Important_4) -- [Function `try_one_time_charge`](#(nexus_workflow=0x0)_gas_try_one_time_charge) -- [Function `get_or_insert_tool_gas_mut`](#(nexus_workflow=0x0)_gas_get_or_insert_tool_gas_mut) - +- [Struct `GasService`](<#(nexus_workflow=0x0)_gas_GasService>) +- [Struct `ExecutionGas`](<#(nexus_workflow=0x0)_gas_ExecutionGas>) +- [Struct `GasBudgets`](<#(nexus_workflow=0x0)_gas_GasBudgets>) +- [Struct `ToolGas`](<#(nexus_workflow=0x0)_gas_ToolGas>) +- [Struct `GasTicket`](<#(nexus_workflow=0x0)_gas_GasTicket>) +- [Struct `OverGas`](<#(nexus_workflow=0x0)_gas_OverGas>) +- [Struct `GasSettlementUpdateEvent`](<#(nexus_workflow=0x0)_gas_GasSettlementUpdateEvent>) +- [Struct `LeaderClaimedGasEvent`](<#(nexus_workflow=0x0)_gas_LeaderClaimedGasEvent>) +- [Enum `ModusOperandi`](<#(nexus_workflow=0x0)_gas_ModusOperandi>) +- [Enum `Scope`](<#(nexus_workflow=0x0)_gas_Scope>) + - [For Clients](#@For_Clients_0) +- [Constants](#@Constants_1) +- [Function `modus_operandi_limited_invocations`](<#(nexus_workflow=0x0)_gas_modus_operandi_limited_invocations>) +- [Function `modus_operandi_expiry`](<#(nexus_workflow=0x0)_gas_modus_operandi_expiry>) +- [Function `modus_operandi_upon_discretion_of_the_tool`](<#(nexus_workflow=0x0)_gas_modus_operandi_upon_discretion_of_the_tool>) +- [Function `scope_invoker_address`](<#(nexus_workflow=0x0)_gas_scope_invoker_address>) +- [Function `scope_worksheet_type`](<#(nexus_workflow=0x0)_gas_scope_worksheet_type>) +- [Function `scope_execution`](<#(nexus_workflow=0x0)_gas_scope_execution>) +- [Function `new_service`](<#(nexus_workflow=0x0)_gas_new_service>) +- [Function `share_service`](<#(nexus_workflow=0x0)_gas_share_service>) +- [Function `set_single_invocation_cost_mist`](<#(nexus_workflow=0x0)_gas_set_single_invocation_cost_mist>) +- [Function `claim_gas`](<#(nexus_workflow=0x0)_gas_claim_gas>) +- [Function `add_gas_ticket`](<#(nexus_workflow=0x0)_gas_add_gas_ticket>) +- [Function `revoke_gas_ticket`](<#(nexus_workflow=0x0)_gas_revoke_gas_ticket>) +- [Function `get_tool_gas_setting_mut`](<#(nexus_workflow=0x0)_gas_get_tool_gas_setting_mut>) +- [Function `deescalate`](<#(nexus_workflow=0x0)_gas_deescalate>) +- [Function `claim_leader_gas`](<#(nexus_workflow=0x0)_gas_claim_leader_gas>) + - [How does the leader estimate the amount?](#@How_does_the_leader_estimate_the_amount?_2) + - [Trust the leader?](#@Trust_the_leader?_3) +- [Function `sync_gas_state`](<#(nexus_workflow=0x0)_gas_sync_gas_state>) +- [Function `sync_gas_state_for_vertex`](<#(nexus_workflow=0x0)_gas_sync_gas_state_for_vertex>) +- [Function `donate_to_tool`](<#(nexus_workflow=0x0)_gas_donate_to_tool>) +- [Function `add_gas_budget`](<#(nexus_workflow=0x0)_gas_add_gas_budget>) +- [Function `refund_execution_gas_budget`](<#(nexus_workflow=0x0)_gas_refund_execution_gas_budget>) +- [Function `refund_invoker_gas_budget`](<#(nexus_workflow=0x0)_gas_refund_invoker_gas_budget>) +- [Function `refund_worksheet_gas_budget`](<#(nexus_workflow=0x0)_gas_refund_worksheet_gas_budget>) +- [Function `is_execution_vertex_settled`](<#(nexus_workflow=0x0)_gas_is_execution_vertex_settled>) +- [Function `get_tool_gas_setting`](<#(nexus_workflow=0x0)_gas_get_tool_gas_setting>) +- [Function `try_settle_execution_for_vertex`](<#(nexus_workflow=0x0)_gas_try_settle_execution_for_vertex>) +- [Function `try_stamp`](<#(nexus_workflow=0x0)_gas_try_stamp>) +- [Function `try_stamp_scope`](<#(nexus_workflow=0x0)_gas_try_stamp_scope>) + - [Important](#@Important_4) +- [Function `try_one_time_charge`](<#(nexus_workflow=0x0)_gas_try_one_time_charge>) +- [Function `get_or_insert_tool_gas_mut`](<#(nexus_workflow=0x0)_gas_get_or_insert_tool_gas_mut>) 
use (nexus_primitives=0x0)::data;
 use (nexus_primitives=0x0)::event;
@@ -89,24 +85,18 @@
 use sui::vec_set;
- - ## Struct `GasService` Shared object. - 
public struct GasService has key
- -
Fields -
id: sui::object::UID @@ -137,7 +127,6 @@ Shared object.
-
@@ -146,16 +135,12 @@ Shared object. Dynamic object field. - 
public struct ExecutionGas has key, store
- -
Fields -
id: sui::object::UID @@ -170,7 +155,6 @@ Dynamic object field.
-
@@ -186,16 +170,12 @@ This budget will also be used to pay for leader gas. The key is a [Scope]. - 
public struct GasBudgets has store
- -
Fields -
inner: sui::bag::Bag @@ -204,7 +184,6 @@ The key is a [Scope].
-
@@ -223,16 +202,12 @@ When resolving a gas ticket for a [DAGExecution] the gas service: 3. If none ok then it looks for a ticket for the address. 4. If none ok then the the gas payment is invalid. - 
public struct ToolGas has store
- -
Fields -
vault: sui::balance::Balance<sui::sui::SUI> @@ -283,7 +258,6 @@ When resolving a gas ticket for a [DAGExecution] the gas service:
-
@@ -294,16 +268,12 @@ Someone has prepaid for tool with expectations defined in this state. See [try_stamp] for info on mutations to this state. - 
public struct GasTicket has drop, store
- -
Fields -
created_at_ms: u64 @@ -319,7 +289,6 @@ See [try_stamp] for info on mutations to this state.
-
@@ -333,37 +302,27 @@ This is a de-escalated version of the [OverTool] owner cap. It should make tool owners more comfortable using gas extensions as they don't give them access to important state. - 
public struct OverGas has drop
- -
Fields -
-
## Struct `GasSettlementUpdateEvent` - - 
public struct GasSettlementUpdateEvent has copy, drop
- -
Fields -
execution: sui::object::ID @@ -390,7 +349,6 @@ don't give them access to important state.
-
@@ -402,16 +360,12 @@ gas they can use this event to track the gas claimed. The event's ID comprises also the tx hash and so the verifier can use it to cross check the gas claimed with the tx gas budget spent. - 
public struct LeaderClaimedGasEvent has copy, drop
- -
Fields -
network: sui::object::ID @@ -427,7 +381,6 @@ cross check the gas claimed with the tx gas budget spent.
-
@@ -436,16 +389,12 @@ cross check the gas claimed with the tx gas budget spent. How should the gas ticket behave. - 
public enum ModusOperandi has copy, drop, store
- -
Variants -
Variant Expiry @@ -462,7 +411,6 @@ Variant Expiry
-
valid_for_ms: u64 @@ -487,7 +435,6 @@ Variant LimitedInvocations
-
total: u64 @@ -498,7 +445,6 @@ Variant LimitedInvocations
-
used: u64 @@ -526,7 +472,6 @@ Variant UponDiscretionOfTheTool
-
@@ -535,27 +480,21 @@ Variant UponDiscretionOfTheTool See the docs to understand how scopes work. - ### For Clients - We ignore enum variant convention out of convenience as in this specific example the variant is unambiguous. - 
public enum Scope has copy, drop, store
- -
Variants -
Variant Execution @@ -601,138 +540,80 @@ Variant InvokerAddress
-
## Constants - - - 
#[error]
 const ECannotRevokeGasTicket: vector<u8> = b"Tickets with expiry or limited number of invocations cannot be revoked";
- - - - 
#[error]
 const ECannotClaimLeaderGas: vector<u8> = b"There is not enough gas in the budget to pay for leader gas";
- - ## Function `modus_operandi_limited_invocations` - - 
public fun modus_operandi_limited_invocations(total: u64, used: u64): (nexus_workflow=0x0)::gas::ModusOperandi
- - - - ## Function `modus_operandi_expiry` - - 
public fun modus_operandi_expiry(valid_for_ms: u64): (nexus_workflow=0x0)::gas::ModusOperandi
- - - - ## Function `modus_operandi_upon_discretion_of_the_tool` - - 
public fun modus_operandi_upon_discretion_of_the_tool(): (nexus_workflow=0x0)::gas::ModusOperandi
- - - - ## Function `scope_invoker_address` - - 
public fun scope_invoker_address(invoker_address: address): (nexus_workflow=0x0)::gas::Scope
- - - - ## Function `scope_worksheet_type` - - 
public fun scope_worksheet_type(worksheet_type_name: std::type_name::TypeName): (nexus_workflow=0x0)::gas::Scope
- - - - ## Function `scope_execution` - - 
public fun scope_execution(execution_id: sui::object::ID): (nexus_workflow=0x0)::gas::Scope
- - - - ## Function `new_service` - - 
public(package) fun new_service(ctx: &mut sui::tx_context::TxContext): (nexus_workflow=0x0)::gas::GasService
- - - - ## Function `share_service` - - 
public(package) fun share_service(self: (nexus_workflow=0x0)::gas::GasService)
- - - - ## Function `set_single_invocation_cost_mist` @@ -742,28 +623,18 @@ Changes how much tool charges per single invocation. Note that this enables gas collection by the tool so the tool owner should be interested in calling this. - 
public fun set_single_invocation_cost_mist(self: &mut (nexus_workflow=0x0)::gas::GasService, tool_registry: &(nexus_workflow=0x0)::tool_registry::ToolRegistry, owner_cap: &(nexus_primitives=0x0)::owner_cap::CloneableOwnerCap<(nexus_workflow=0x0)::gas::OverGas>, fqn: std::ascii::String, single_invocation_cost_mist: u64, ctx: &mut sui::tx_context::TxContext)
- - - - ## Function `claim_gas` Claims all gas settlement for the given tool. - 
public fun claim_gas(self: &mut (nexus_workflow=0x0)::gas::GasService, tool_registry: &(nexus_workflow=0x0)::tool_registry::ToolRegistry, owner_cap: &(nexus_primitives=0x0)::owner_cap::CloneableOwnerCap<(nexus_workflow=0x0)::tool_registry::OverTool>, fqn: std::ascii::String, ctx: &mut sui::tx_context::TxContext): sui::balance::Balance<sui::sui::SUI>
- - - - ## Function `add_gas_ticket` @@ -777,14 +648,9 @@ defined by the Talus/Nexus terms - see the docs. The tool owner can use "upon discretion of the tool" mode to be able to [revoke_gas_ticket] at will. - 
public fun add_gas_ticket(self: &mut (nexus_workflow=0x0)::gas::GasService, tool_registry: &(nexus_workflow=0x0)::tool_registry::ToolRegistry, owner_cap: &(nexus_primitives=0x0)::owner_cap::CloneableOwnerCap<(nexus_workflow=0x0)::gas::OverGas>, fqn: std::ascii::String, scope: (nexus_workflow=0x0)::gas::Scope, modus_operandi: (nexus_workflow=0x0)::gas::ModusOperandi, clock: &sui::clock::Clock, ctx: &mut sui::tx_context::TxContext)
- - - - ## Function `revoke_gas_ticket` @@ -793,54 +659,37 @@ The tool owner can revoke a gas ticket with mode "upon discretion of the tool". This means that the tool owner can invalidate a gas ticket at any time. - 
public fun revoke_gas_ticket(self: &mut (nexus_workflow=0x0)::gas::GasService, tool_registry: &(nexus_workflow=0x0)::tool_registry::ToolRegistry, owner_cap: &(nexus_primitives=0x0)::owner_cap::CloneableOwnerCap<(nexus_workflow=0x0)::gas::OverGas>, fqn: std::ascii::String, scope: (nexus_workflow=0x0)::gas::Scope, ctx: &mut sui::tx_context::TxContext)
- - - - ## Function `get_tool_gas_setting_mut` The tool owner can set the gas settings for the tool. - 
public fun get_tool_gas_setting_mut(self: &mut (nexus_workflow=0x0)::gas::GasService, tool_registry: &(nexus_workflow=0x0)::tool_registry::ToolRegistry, owner_cap: &(nexus_primitives=0x0)::owner_cap::CloneableOwnerCap<(nexus_workflow=0x0)::gas::OverGas>, fqn: std::ascii::String, ctx: &mut sui::tx_context::TxContext): &mut sui::bag::Bag
- - - - ## Function `deescalate` Lowers privileges of the tool owner cap into a gas owner cap. - 
public fun deescalate(tool_registry: &(nexus_workflow=0x0)::tool_registry::ToolRegistry, owner_cap: &(nexus_primitives=0x0)::owner_cap::CloneableOwnerCap<(nexus_workflow=0x0)::tool_registry::OverTool>, fqn: std::ascii::String, ctx: &mut sui::tx_context::TxContext): (nexus_primitives=0x0)::owner_cap::CloneableOwnerCap<(nexus_workflow=0x0)::gas::OverGas>
- - - - ## Function `claim_leader_gas` The leader claims just about the amount of gas it costs to pay for the tx. - ### How does the leader estimate the amount? - The leader dry runs the tx and reads how much gas it would cost to pay for the tx. Then it sets the gas budget for the tx to the amount obtained in the dry-run @@ -848,40 +697,28 @@ Then it sets the gas budget for the tx to the amount obtained in the dry-run The submitted tx will use claim_leader_gas with the amount obtained in the dry-run. - ### Trust the leader? - At the moment the leader can claim any amount of gas it wants from anybody who uploads gas budgets. To hold the leader accountable we emit LeaderClaimedGasEvent event which can be read by 3rd parties that check that the amount claimed is not over the top. - 
public fun claim_leader_gas(self: &mut (nexus_workflow=0x0)::gas::GasService, execution: &(nexus_workflow=0x0)::dag::DAGExecution, leader_cap: &(nexus_primitives=0x0)::owner_cap::CloneableOwnerCap<(nexus_workflow=0x0)::leader_cap::OverNetwork>, amount: u64): sui::balance::Balance<sui::sui::SUI>
- - - - ## Function `sync_gas_state` Calls [sync_gas_state_for_vertex] for each vertex invoked in this tx. - 
public fun sync_gas_state(self: &mut (nexus_workflow=0x0)::gas::GasService, dag: &(nexus_workflow=0x0)::dag::DAG, execution: &(nexus_workflow=0x0)::dag::DAGExecution, request_walk_execution: &(nexus_workflow=0x0)::dag::RequestWalkExecution, ctx: &mut sui::tx_context::TxContext)
- - - - ## Function `sync_gas_state_for_vertex` @@ -889,39 +726,31 @@ Calls [sync_gas_state_for_vertex] for each vertex invoked in this tx. Syncs gas payment with an execution. This function is a no-op if + 1. The vertex is not in the registry. 2. The vertex is not invoked. 3. The vertex is already settled. This function aborts if + 1. The DAG doesn't contain the provided vertex. This function is permission-less and idempotent. Anyone can sync the gas state for a vertex and this function will only do work provided the above conditions are met. - 
public fun sync_gas_state_for_vertex(self: &mut (nexus_workflow=0x0)::gas::GasService, dag: &(nexus_workflow=0x0)::dag::DAG, execution: &(nexus_workflow=0x0)::dag::DAGExecution, vertex: (nexus_workflow=0x0)::dag::Vertex, ctx: &mut sui::tx_context::TxContext)
- - - - ## Function `donate_to_tool` Donate given balance to the tool's gas total. - 
public fun donate_to_tool(self: &mut (nexus_workflow=0x0)::gas::GasService, fqn: std::ascii::String, amount: sui::balance::Balance<sui::sui::SUI>)
- - - - ## Function `add_gas_budget` @@ -929,14 +758,9 @@ Donate given balance to the tool's gas total. Adds gas budget for the given scope. Gas budget will be used to pay for invocation if no gas ticket is present. - 
public fun add_gas_budget(self: &mut (nexus_workflow=0x0)::gas::GasService, scope: (nexus_workflow=0x0)::gas::Scope, budget: sui::balance::Balance<sui::sui::SUI>)
- - - - ## Function `refund_execution_gas_budget` @@ -945,14 +769,9 @@ Can be called once the execution finishes. The gas will be refunded to the invoker's address if finished. - 
public fun refund_execution_gas_budget(self: &mut (nexus_workflow=0x0)::gas::GasService, execution: &(nexus_workflow=0x0)::dag::DAGExecution, ctx: &mut sui::tx_context::TxContext)
- - - - ## Function `refund_invoker_gas_budget` @@ -960,71 +779,46 @@ The gas will be refunded to the invoker's address if finished. Can be called by the invoker. Will be empty if not present. - 
public fun refund_invoker_gas_budget(self: &mut (nexus_workflow=0x0)::gas::GasService, ctx: &mut sui::tx_context::TxContext): sui::balance::Balance<sui::sui::SUI>
- - - - ## Function `refund_worksheet_gas_budget` -Can be called by the SAP. +Can be called by the TAP. Will be empty if not present. - 
public fun refund_worksheet_gas_budget<T>(self: &mut (nexus_workflow=0x0)::gas::GasService, _witness: &T): sui::balance::Balance<sui::sui::SUI>
- - - - ## Function `is_execution_vertex_settled` Can the vertex be invoked once? - 
public fun is_execution_vertex_settled(self: &(nexus_workflow=0x0)::gas::GasService, execution: &(nexus_workflow=0x0)::dag::DAGExecution, vertex: (nexus_workflow=0x0)::dag::Vertex): bool
- - - - ## Function `get_tool_gas_setting` Anyone can read the tool gas settings. - 
public fun get_tool_gas_setting(self: &(nexus_workflow=0x0)::gas::GasService, fqn: std::ascii::String): &sui::bag::Bag
- - - - ## Function `try_settle_execution_for_vertex` Updates state of gas settlement for the given execution. - 
fun try_settle_execution_for_vertex(self: &mut (nexus_workflow=0x0)::gas::GasService, dag: &(nexus_workflow=0x0)::dag::DAG, execution: &(nexus_workflow=0x0)::dag::DAGExecution, vertex: (nexus_workflow=0x0)::dag::Vertex, ctx: &mut sui::tx_context::TxContext)
- - - - ## Function `try_stamp` @@ -1033,14 +827,9 @@ Tries to stamp a ticket for the given execution. The caller must ensure that it is appropriate to stamp the ticket. - 
fun try_stamp(self: &mut (nexus_workflow=0x0)::gas::ToolGas, execution: &(nexus_workflow=0x0)::dag::DAGExecution): bool
- - - - ## Function `try_stamp_scope` @@ -1048,26 +837,19 @@ The caller must ensure that it is appropriate to stamp the ticket. Returns true if the gas ticket is valid. The key determines the scope we're stamping. - ### Important - This function mutates the ticket state. It's important that the return values are used to update the state of the caller. Once a [GasTicket] cannot be stamped anymore it is removed. - 
fun try_stamp_scope<K: copy, drop, store>(self: &mut (nexus_workflow=0x0)::gas::ToolGas, key: K, execution_created_at: u64): bool
- - - - ## Function `try_one_time_charge` @@ -1075,20 +857,13 @@ Once a [GasTicket] cannot be stamped anymore it is removed. Balance is either empty if no gas could be used or it contains the exact amount requested. - 
fun try_one_time_charge(self: &mut (nexus_workflow=0x0)::gas::GasBudgets, execution: &(nexus_workflow=0x0)::dag::DAGExecution, amount: u64): sui::balance::Balance<sui::sui::SUI>
- - - - ## Function `get_or_insert_tool_gas_mut` - - 
fun get_or_insert_tool_gas_mut(self: &mut (nexus_workflow=0x0)::gas::GasService, fqn: std::ascii::String, ctx: &mut sui::tx_context::TxContext): &mut (nexus_workflow=0x0)::gas::ToolGas
diff --git a/nexus-next/packages/reference/nexus_workflow/main.md b/nexus-next/packages/reference/nexus_workflow/main.md index 7a46a04..6bb19ee 100644 --- a/nexus-next/packages/reference/nexus_workflow/main.md +++ b/nexus-next/packages/reference/nexus_workflow/main.md @@ -1,14 +1,10 @@ - # Module `(nexus_workflow=0x0)::main` - - -- [Constants](#@Constants_0) - - [Important](#@Important_1) -- [Function `init`](#(nexus_workflow=0x0)_main_init) - +- [Constants](#@Constants_0) + - [Important](#@Important_1) +- [Function `init`](<#(nexus_workflow=0x0)_main_init>) 
use (nexus_interface=0x0)::v1;
 use (nexus_interface=0x0)::version;
@@ -17,7 +13,7 @@
 use (nexus_primitives=0x0)::owner_cap;
 use (nexus_primitives=0x0)::proof_of_uid;
 use (nexus_workflow=0x0)::dag;
-use (nexus_workflow=0x0)::default_sap;
+use (nexus_workflow=0x0)::default_tap;
 use (nexus_workflow=0x0)::gas;
 use (nexus_workflow=0x0)::leader_cap;
 use (nexus_workflow=0x0)::tool_registry;
@@ -52,20 +48,16 @@
 use sui::vec_set;
- - ## Constants - Each dev can list their local addresses and when we deploy the contract relevant addresses will obtain leader cap. Useful mainly for testing and going into testnet. - ### Important @@ -74,28 +66,20 @@ This is development only configuration. When we go into later stages of development, we will remove this in favour of a proper deploy script. - 
const DEV_ADDRESSES: vector<address> = vector[0x9f205ddfe4be3c9c07a57d8e1ef233f7b7537a1248dd46b1514ba93261621d52, 0x4fbfd7d8b5683bf9adc9936c026ec79a559e5d6420123ebcdfb85e1c9b2fd84c];
- - Amount of leader caps to clone per [DEV_ADDRESSES] address. - 
const LEADER_CAPS_PER_ADDRESS: u64 = 5;
- - ## Function `init` - - 
fun init(ctx: &mut sui::tx_context::TxContext)