🛠️nexus_tool::tool_registry
Struct ToolRegistry
Shared registry of tools, tracking timeouts, verifier methods, and collateral policy.
Struct ToolRegistryInnerV1
Version one stored layout for [ToolRegistry].
Struct Tool
Generic derived object that holds information about a tool. On-chain and off-chain tools are differentiated based on [ToolRef]
Struct ToolInnerV1
Version one stored layout for [Tool].
Struct ToolRegistryAdminCap
Authority over policy, verification, and collateral in one [ToolRegistry].
Struct ToolRegistryCreatedEvent
Emitted when a new [ToolRegistry] is created.
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.
Struct ToolUnregisteredEvent
Emitted when a tool is unregistered.
Struct ToolSlashedEvent
Emitted when a tool's collateral is slashed.
Struct ToolVerificationStatusChangedEvent
Emitted when a tool's verification status changes.
Struct ToolUpdatedEvent
Emitted when a tool's metadata, URL, timeout, or verifier methods are updated.
Struct ExternalVerifierRegisteredEvent
Emitted when a Tool external verifier is registered.
Enum ToolRef
Location and invocation identity of an off-chain or on-chain Tool.
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

