Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

🛠️nexus_tool::tool_registry

Struct ToolRegistry

Shared registry of tools, tracking timeouts, verifier methods, and collateral policy.

Fields

id: sui::object::UID

Struct ToolRegistryInnerV1

Version one stored layout for [ToolRegistry].

Fields

tool_ids: sui::linked_table::LinkedTable<std::ascii::String, sui::object::ID>Current FQN-to-stable-Tool-ID membership.registered_tools: sui::table::Table<sui::object::ID, bool>Current stable Tool-ID membership for submission-time liveness checks.meta_schemas: sui::table::Table<sui::object::ID, nexus_interface::meta_schema::MetaSchema>Immutable protocol schema for each currently registered Tool ID.timeouts: sui::linked_table::LinkedTable<std::ascii::String, u64>Timeout by Tool FQN for execution-time lookup without loading each derived Tool object.verifier_support: sui::table::Table<sui::object::ID, nexus_interface::verifier::ToolVerifierSupport>The one verified mode supported by each configured off-chain Tool.external_verifiers: sui::table::Table<sui::object::ID, nexus_tool::external_verifier::ExternalVerifier>External verifier configuration by stable Tool ID.invocation_costs_mist: sui::table::Table<std::ascii::String, u64>Invocation price in MIST by Tool FQN.on_chain_tool_witnesses: sui::linked_table::LinkedTable<std::ascii::String, sui::object::ID>Registered on-chain tool witness IDs by FQN.workflow_authorization_cap_first: sui::linked_table::LinkedTable<std::ascii::String, bool>On-chain tools whose execute function requires workflow vertex authorization cap as the first argument.us_collateral_to_lock: u64How much [US] (in base units) to lock to register a tool.lock_duration_ms: u64How long is the collateral locked for in milliseconds after unregistering. Copied to tool upon registration.

Struct Tool

Generic derived object that holds information about a tool. On-chain and off-chain tools are differentiated based on [ToolRef]

Fields

id: sui::object::UID

Struct ToolInnerV1

Version one stored layout for [Tool].

Fields

registry: sui::object::IDfqn: std::ascii::StringFully qualified name of the tool.ref: nexus_tool::tool_registry::ToolRefOn-chain package reference or off-chain HTTP endpoint.description: vector<u8>Description of the tool.meta_schema: nexus_interface::meta_schema::MetaSchemaImmutable protocol schema used for registration, DAG construction, and execution.verified: boolVerification status set by the slashing authority. Tools are registered as unverified by default.vault: sui::balance::Balance<talus::us::US>To register a tool one must lock [ToolRegistry::us_collateral_to_lock] [US].workflow_authorization_cap_first: boolTrue when an on-chain tool's execute function expects nexus_primitives::authorization::ProvenValue as its first argument.lock_duration_ms: u64Collateral lock duration in milliseconds after unregistration.registered_at_ms: u64Timestamp when the Tool was registered.unregistered_at_ms: std::option::Option<u64>Unregistration timestamp, used to enforce the lock before the creator can reclaim collateral.

Struct ToolRegistryAdminCap

Authority over policy, verification, and collateral in one [ToolRegistry].

Fields

id: sui::object::UIDregistry: sui::object::ID

Struct ToolRegistryCreatedEvent

Emitted when a new [ToolRegistry] is created.

Fields

registry: sui::object::ID

Struct ToolRegisteredEvent

Emitted when a Tool is registered or re-registered. Re-registration starts a new trust epoch: it retains the stable Tool identity and immutable schema, restores collateral to the current lock policy when needed, applies a fresh timeout, clears verifier support, and sets verified to false. Metadata updates require a non-empty description and likewise clear verified; they do not alter the registration-time schema.

Fields

tool: sui::object::IDfqn: std::ascii::String

Struct ToolUnregisteredEvent

Emitted when a tool is unregistered.

Fields

tool: sui::object::IDfqn: std::ascii::String

Struct ToolSlashedEvent

Emitted when a tool's collateral is slashed.

Fields

tool: sui::object::IDfqn: std::ascii::Stringamount: u64Amount of US collateral in base units slashed.

Struct ToolVerificationStatusChangedEvent

Emitted when a tool's verification status changes.

Fields

tool: sui::object::IDfqn: std::ascii::Stringverified: bool

Struct ToolUpdatedEvent

Emitted when a tool's metadata, URL, timeout, or verifier methods are updated.

Fields

tool: sui::object::IDfqn: std::ascii::String

Struct ExternalVerifierRegisteredEvent

Emitted when a Tool external verifier is registered.

Fields

registry: sui::object::IDtool: sui::object::IDmethod: nexus_interface::verifier::VerifierMethodIdwitness: sui::object::ID

Enum ToolRef

Location and invocation identity of an off-chain or on-chain Tool.

Variants

Variant Httpurl: vector<u8>Variant Suipackage_address: addressmodule_name: std::ascii::Stringtool_witness_id: sui::object::ID

Constants

How much [US] (in base units) to lock to register a tool.

TODO: This is only a testing value.

How long is the collateral locked for in milliseconds after unregistering.

TODO: This is only a testing value.

What is the lower bound for tool timeouts in milliseconds.

What is the upper bound for tool timeouts in milliseconds.

Buffer added to tool timeout for leader evaluation.

Function register_off_chain_tool

Registers a new off-chain HTTP Tool with an immutable schema and invocation price. The registry enforces FQN uniqueness, schema validity, and timeout bounds; URL and FQN conventions remain caller/SDK responsibilities.

Collateral

To prevent spamming, we lock [ToolRegistry.us_collateral_to_lock] [US] as collateral. If the tool is unregistered, the collateral is available after [ToolRegistry.lock_duration_ms] milliseconds.

Slashing

The registry administrator may call [slash] when the Tool fails to uphold its registered contract.

Owner Cap

The returned Tool owner capability must be transferred or otherwise consumed.

Payment Tickets

The returned payment capability controls invocation price and tickets.

Function register_on_chain_tool

Registers a new on-chain Tool with an immutable schema and invocation price.

Onchain Tools are published as separate Move modules. They must expose a public execute function that consumes [UIDRequirements] followed by an owned OnchainToolResult. Workflow Tools may precede those arguments with an owned ProvenValue<AgentVertexAuthorization>. Public visibility lets the current Scheduler compose an older Tool package in one transaction. The Tool must satisfy its UID requirement and finalize the result in that same transaction.

Owner Cap

The returned Tool owner capability must be transferred or otherwise consumed.

Function register_on_chain_tool_with_workflow_authorization_cap

Registers an on-chain Tool whose execute function requires a vertex authorization value first.

The caller/SDK must set this only after normalized signature analysis proves execute takes nexus_primitives::authorization::ProvenValue<nexus_interface::authorization::AgentVertexAuthorization> first.

Function unregister

Atomically retires a Tool from every live registry lookup and verifier record.

Function reregister_tool

Re-register a previously unregistered tool.

Rebuilds base registry state with a fresh timeout and no verifier support, and snapshots the registry's current collateral-lock duration for the re-registered Tool.

Function claim_collateral

Return collateral to a tool owner.

Function deescalate

Returns a new [CloneableOwnerCap] for the given tool but with the given generic type that doesn't have any permissions within this module. Works for both off-chain and on-chain Tools.

See also [assert_tool_owner_generic].

Function delegate_cashier_admin

Creates delegated cashier administration from full [Tool] ownership.

Function assert_tool_owner_generic

Assert that the owner cap is for the given tool but allows any generic type to be used.

See also [deescalate].

Function did_unregister_period_pass

Returns whether the collateral lock duration has elapsed since the tool was unregistered.

Returns false if the tool is still registered.

Function is_registered

Returns whether the tool is currently registered (not unregistered).

Function is_verified

Returns whether the tool has been marked verified by the slashing authority.

Function assert_tool_registered

Assert that a tool is registered and not unregistered.

Function fqn

Returns the fully qualified name of the tool.

Function assert_registered_vertex

Asserts a DAG vertex is bound to this registry's exact Tool ID and immutable schema.

Function assert_registered_dag

Asserts every DAG vertex still matches this registry's live Tool state.

Function tool_timeout_ms

Returns the configured timeout (in milliseconds) for the tool with the given FQN.

Function walk_timeout_ms_for_runtime_vertex

Build the timeout window for a runtime DAG vertex.

Function contains_tool

Return whether a tool FQN is registered in this registry.

Function contains_tool_id

Function tool_id

Function invocation_cost_mist

Returns the current invocation price in MIST for a registered Tool.

Function snapshot_invocation_cost

Records the current Tool price on an execution payment.

An unregistered Tool is snapshotted with a zero price so callers can preserve a complete execution snapshot before liveness is checked.

Function set_invocation_cost_mist

Sets the invocation price in MIST using delegated [OverToolCashier] authority.

Function verifier_support

Function supports_verifier_mode

Function add_vertex_to_dag

Adds a DAG vertex bound to this registry's current stable Tool ID and immutable schema.

Function set_registered_vertex_verifier_mode

Selects a per-vertex mode after checking the Tool's one global support value.

Function register_external_verifier

Owner-authorized initial registration of one External verifier.

Function has_external_verifier

Returns whether a Tool has external verifier configuration.

Function external_verifier_method

Returns the external verifier method configured for a Tool.

Function external_verifier_witness

Returns the witness configured for a Tool external verifier.

Function external_verifier_objects

Returns the immutable shared objects configured for a Tool external verifier.

Function on_chain_tool_takes_workflow_authorization_cap_first

Return whether the registered on-chain tool requires workflow authorization cap as its first execute argument.

Function vertex_requires_authorization_grant

Return whether a DAG runtime vertex requires a workflow authorization grant for execution.

Function assert_on_chain_tool_witness

Assert that witness_id is the witness registered for an on-chain tool.

Function on_chain_tool_witness_id

Function set_us_collateral_to_lock

Sets the collateral in US base units required to register a Tool.

Function set_lock_duration_ms

Sets the collateral lock duration in milliseconds after Tool removal.

Function slash

Takes given amount of collateral from a Tool. If the remaining collateral is below the registry's current us_collateral_to_lock requirement, an active Tool is retired; collateral exactly equal to that requirement keeps it active. Slashing an already retired Tool preserves its original retirement timestamp rather than restarting the collateral-lock period.

Function set_verified

Set a tool's verification status.

Function update_off_chain_tool_url

Update the URL of an off-chain (HTTP) tool.

The tool must be registered and the caller must hold the owner cap.

Function migrate_on_chain_tool_package

Updates the package address of an active on-chain Tool using its bound owner capability.

Function update_tool_metadata

Updates the mutable description of a registered Tool.

The registration-time [MetaSchema] remains immutable because DAG bindings and the registry snapshot rely on that exact schema. Description changes require renewed verification.

Function update_tool_timeout

Update a tool timeout.

The tool must be registered and the caller must hold the owner cap.

Function configure_registered_key_support

Declares registered key verifier support for a Tool.

Verification still requires live Tool and Leader key bindings.

Last updated