> For the complete documentation index, see [llms.txt](https://docs.talus.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.talus.network/reference/move/nexus_tool/invocation.md).

# nexus\_tool::invocation

* [Struct `ReserveKey`](#struct-reservekey)
* [Struct `Invocation`](#struct-invocation)
* [Constants](#constants)
* [Function `new_invocation`](#function-new_invocation)
* [Function `new_invocation_with_reserve`](#function-new_invocation_with_reserve)
* [Function `id`](#function-id)
* [Function `execution_id`](#function-execution_id)
* [Function `vertex_key`](#function-vertex_key)
* [Function `tool`](#function-tool)
* [Function `cashier`](#function-cashier)
* [Function `beneficiary`](#function-beneficiary)
* [Function `refund_address`](#function-refund_address)
* [Function `policy`](#function-policy)
* [Function `sources`](#function-sources)
* [Function `amount`](#function-amount)
* [Function `place`](#function-place)
* [Function `receive`](#function-receive)
* [Function `receive_refund`](#function-receive_refund)
* [Function `resolve`](#function-resolve)
* [Function `collect`](#function-collect)
* [Function `collect_with_reserve`](#function-collect_with_reserve)
* [Function `claim_refund`](#function-claim_refund)

### Struct `ReserveKey`

Typed reserve key for policy witness \[P].

```move
public struct ReserveKey<phantom P: drop> has copy, drop, store
```

<details>

<summary>Fields</summary>

</details>

#### Struct `Invocation`

Exact policy authorization for one Tool invocation.

The missing \[store] ability ensures that only this module can transfer or receive an \[Invocation].

```move
public struct Invocation has key
```

<details>

<summary>Fields</summary>

[`id`](#nexus_tool_invocation_id)`: sui::object::UID`[`execution_id`](#nexus_tool_invocation_execution_id)`: address`[`vertex_key`](#nexus_tool_invocation_vertex_key)`: vector<u8>tool_id: sui::object::IDcashier_id: sui::object::ID`[`beneficiary`](#nexus_tool_invocation_beneficiary)`:` [`nexus_interface::payment::PaymentSourceKind`](/reference/move/nexus_interface/payment.md#nexus_interface_payment_PaymentSourceKind)[`policy`](#nexus_tool_invocation_policy)`: std::type_name::TypeName`[`sources`](#nexus_tool_invocation_sources)`: vector<sui::object::ID>`[`amount`](#nexus_tool_invocation_amount)`: u64refund_to: std::option::Option<address>funds: sui::balance::Balance<sui::sui::SUI>`

</details>

#### Constants

```move
#[error]
const EInvocationMismatch: vector<u8> = b"Invocation does not match its exact accounting receipt";
```

```move
#[error]
const EInvocationRequestMismatch: vector<u8> = b"Invocation request does not match this Tool cashier";
```

```move
#[error]
const EInvocationAmountExceedsSnapshot: vector<u8> = b"Invocation amount exceeds the execution price snapshot";
```

```move
#[error]
const EPolicyNotAccepted: vector<u8> = b"Invocation policy is not accepted";
```

#### Function `new_invocation`

Consumes a canonical request and creates one Invocation under policy \[P].

```move
public fun new_invocation<P: drop>(cashier: &nexus_tool::tool_cashier::ToolCashier, request: nexus_interface::payment::InvocationRequest, _: P, sources: vector<sui::object::ID>, amount: u64, ctx: &mut sui::tx_context::TxContext): nexus_tool::invocation::Invocation
```

#### Function `new_invocation_with_reserve`

Creates one Invocation carrying the exact policy reserve restored on refund.

```move
public fun new_invocation_with_reserve<P: drop, R: store>(cashier: &nexus_tool::tool_cashier::ToolCashier, request: nexus_interface::payment::InvocationRequest, policy: P, reserve: R, refund_to: address, sources: vector<sui::object::ID>, amount: u64, ctx: &mut sui::tx_context::TxContext): nexus_tool::invocation::Invocation
```

#### Function `id`

Returns the object ID of \[Invocation].

```move
public fun id(self: &nexus_tool::invocation::Invocation): sui::object::ID
```

#### Function `execution_id`

Returns the execution authorized by \[Invocation].

```move
public fun execution_id(self: &nexus_tool::invocation::Invocation): address
```

#### Function `vertex_key`

Returns the runtime vertex key authorized by \[Invocation].

```move
public fun vertex_key(self: &nexus_tool::invocation::Invocation): vector<u8>
```

#### Function `tool`

Returns the Tool authorized by \[Invocation].

```move
public fun tool(self: &nexus_tool::invocation::Invocation): sui::object::ID
```

#### Function `cashier`

Returns the cashier selected by \[Invocation].

```move
public fun cashier(self: &nexus_tool::invocation::Invocation): sui::object::ID
```

#### Function `beneficiary`

Returns the payment source eligible for \[Invocation].

```move
public fun beneficiary(self: &nexus_tool::invocation::Invocation): nexus_interface::payment::PaymentSourceKind
```

#### Function `refund_address`

Returns the address that receives a policy reserve after refund. This accessor aborts with `EInvocationMismatch` when the Invocation has no configured reserve/refund recipient; callers must not use it as an optional-query API.

```move
public fun refund_address(self: &nexus_tool::invocation::Invocation): address
```

#### Function `policy`

Returns the policy witness type that created \[Invocation].

```move
public fun policy(self: &nexus_tool::invocation::Invocation): std::type_name::TypeName
```

#### Function `sources`

Returns the exact economic sources used by \[Invocation].

```move
public fun sources(self: &nexus_tool::invocation::Invocation): vector<sui::object::ID>
```

#### Function `amount`

Returns the SUI obligation selected by \[Invocation].

```move
public fun amount(self: &nexus_tool::invocation::Invocation): u64
```

#### Function `place`

Places \[Invocation] under its execution after consuming its exact lock receipt.

```move
public fun place(invocation: nexus_tool::invocation::Invocation, receipt: nexus_interface::payment::InvocationLockReceipt)
```

#### Function `receive`

Receives an \[Invocation] owned by its execution.

```move
public fun receive(execution: &mut sui::object::UID, receiving: sui::transfer::Receiving<nexus_tool::invocation::Invocation>): nexus_tool::invocation::Invocation
```

#### Function `receive_refund`

Receives a refunded \[Invocation] at its recorded policy account.

```move
public fun receive_refund(account: &mut sui::object::UID, receiving: sui::transfer::Receiving<nexus_tool::invocation::Invocation>): nexus_tool::invocation::Invocation
```

#### Function `resolve`

Resolves \[Invocation] using the exact terminal receipt from its payment.

Finalization joins the recorded SUI and sends the completed Invocation to its cashier. Refund sends a reserved Invocation to its beneficiary or destroys an Invocation with no reserved resource.

```move
public fun resolve(invocation: nexus_tool::invocation::Invocation, paid: sui::balance::Balance<sui::sui::SUI>, receipt: nexus_interface::payment::InvocationSettlementReceipt)
```

#### Function `collect`

Receives completed Invocations created by configless policy witness \[P].

```move
public fun collect<P: drop>(cashier: &mut nexus_tool::tool_cashier::ToolCashier, owner_cap: &nexus_primitives::owner_cap::CloneableOwnerCap<nexus_tool::tool_cashier::OverToolCashier>, _: P, invocations: vector<sui::transfer::Receiving<nexus_tool::invocation::Invocation>>): sui::balance::Balance<sui::sui::SUI>
```

#### Function `collect_with_reserve`

Receives completed Invocations and returns their exact policy reserves.

```move
public fun collect_with_reserve<P: drop, R: store>(cashier: &mut nexus_tool::tool_cashier::ToolCashier, owner_cap: &nexus_primitives::owner_cap::CloneableOwnerCap<nexus_tool::tool_cashier::OverToolCashier>, _: P, invocations: vector<sui::transfer::Receiving<nexus_tool::invocation::Invocation>>): (sui::balance::Balance<sui::sui::SUI>, vector<R>)
```

#### Function `claim_refund`

Recovers the exact policy reserve from a refunded \[Invocation].

An Invocation has no \[store] ability, so only the address that received the refund can supply it and only this function can unpack it.

```move
public fun claim_refund<P: drop, R: store>(invocation: nexus_tool::invocation::Invocation, _: P): R
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.talus.network/reference/move/nexus_tool/invocation.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.