Skip to content

grammar tweaks for automation api-reference #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
chariot6 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

grammar tweaks for automation api-reference #3

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
77 changes: 38 additions & 39 deletions automation/api-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,47 +8,46 @@ The on-chain module `automation_registry` provides the following APIs:

#### Registration

Users cannot call the `register()` function directly.Instead, tasks are registered by submitting a signed transaction that wraps the target function and its arguments into an internal payload. This is handled automatically via the Supra CLI, REST API, or SDK. The registry validates and activates the task based on submitted parameters and network rules.
Users cannot call the `register()` function directly. Instead, tasks are registered by submitting a signed transaction that wraps the target function and its arguments into an internal payload. This is handled automatically via the Supra CLI, REST API, or SDK. The registry validates and activates the task based on submitted parameters and network rules.

**Example: Registering a Task Using Supra CLI**

```
bash
```bash
supra move automation register \
--task-max-gas-amount 50000 \
--task-gas-price-cap 200 \
--task-expiry-time-secs <TIMESTAMP> \
--task-automation-fee-cap 10000 \
--function-id "0x1::your_module::"function name" \
--function-id "0x1::your_module::function name" \
--args address:<recipient> u64:<amount>
```

This command prepares a task that invokes the specified fuction with the given arguments. It does not call `register()` directy, it creates a `signed` transaction that interacts with the on-chain registry.
This command prepares a task that invokes the specified function with the given arguments. It does not call `register()` directy. It creates a `signed` transaction that interacts with the on-chain registry.

To simulate task creation without submission, use the following command:

```
```bash
supra move automation register --simulate ...
```

#### Cancellation

```
```move
public entry fun cancel_task(owner: &signer, id: u64)
```

This method cancels the task by index. The task remains scheduled for the current epoch and is removed in the next.

#### Read Functions

| Function name | Functionality |
| ----------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `public fun get_active_task_ids(): vector<u64>` | Returns all active tasks IDs for the current epoch. |
| `public fun get_task_details(id: u64): TaskMetadata` | Returns the full task metadata for a specific task ID. |
| `public fun get_task_count(): u64` | Returns the total number of registered tasks. |
| `public fun get_automation_registry_config(): RegistryConfig` | Returns the current automation registry configuration. |
| `public fun get_epoch_locked_balance(account: address): u64` | Returns the locked balance for the given account (after current epoch). |
| `public fun has_sender_active_task_with_id(sendr:address, id:u64):bool` | Verifies whether the sender has an active task with given ID. |
| Function name | Functionality |
| ------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `public fun get_active_task_ids(): vector<u64>` | Returns all active tasks IDs for the current epoch. |
| `public fun get_task_details(id: u64): TaskMetadata` | Returns the full task metadata for a specific task ID. |
| `public fun get_task_count(): u64` | Returns the total number of registered tasks. |
| `public fun get_automation_registry_config(): RegistryConfig` | Returns the current automation registry configuration. |
| `public fun get_epoch_locked_balance(account: address): u64` | Returns the locked balance for the given account (after current epoch). |
| `public fun has_sender_active_task_with_id(sendr: address, id:u64): bool` | Verifies whether the sender has an active task with given ID. |

These functions allow visibility into registry state and configuration.

Expand Down Expand Up @@ -81,20 +80,20 @@ These are surfaced via on-chain transaction logs and are useful for debugging or

These events are emitted by the registry module and are indexed for external observability:

| Events | Description |
| ------------------------ | --------------------------------------------------------------- |
| `AutomationTaskMetadata` | Emitted when a task is accepted into the registry. |
| `TaskCancelled` | Triggered when a rask is manually cancelled or pruned. |
| `AutomationFeeWithdrawn` | Indicates automation fees collected by the system. |
| `AutomationRefundIssued` | Sent bwhen an unused task is refunded due to expiry or failure. |
| Events | Description |
| ------------------------ | ------------------------------------------------------------------ |
| `AutomationTaskMetadata` | Emitted when a task is accepted into the registry. |
| `TaskCancelled` | Emitted when a task is manually cancelled or pruned. |
| `AutomationFeeWithdrawn` | Indicates automation fees collected by the system. |
| `AutomationRefundIssued` | Emitted when an unused task is refunded due to expiry or failure. |

The diagram below showx the API architecture map
The diagram below shows the API architecture map

<figure><img src=".gitbook/assets/5-v2.png" alt=""><figcaption></figcaption></figure>

### Registry API Overview

The Automation Registry is a native on-chain module that stores all registered tasks. This registry controls task lifecycle, condition validation, execution ordering, and expiry/cancellation management.\
The Automation Registry is a native on-chain module that stores all registered tasks. This registry controls the task lifecycle, condition validation, execution ordering, and expiry/cancellation management.\
Automation tasks are treated as internal transactions. These are executed directly by the blockchain’s validator layer.\


Expand All @@ -108,16 +107,16 @@ This diagram will give you an overview of interaction of Registry System

Registers a new automation task with all required metadata.

| Metadata | Function |
| ------------------------------ | ------------------------------------------------------------------ |
| `owner` | Signer address registering the task |
| `payload_tx` | Binary-encoded entry function call (contains condition and action) |
| `expiry_time` | Epoch timestamp when the task becomes invalid |
| `max_gas_amount` | Maximum gas allowed per execution |
| `gas_price_cap` | Maximum acceptable gas price |
| `automation_fee_cap_for_epoch` | Maximum automation fee for a single epoch |
| Metadata | Function |
| ------------------------------ | ------------------------------------------------------------------- |
| `owner` | Signer address registering the task. |
| `payload_tx` | Binary-encoded entry function call (contains condition and action). |
| `expiry_time` | Epoch timestamp when the task becomes invalid. |
| `max_gas_amount` | Maximum gas allowed per execution. |
| `gas_price_cap` | Maximum acceptable gas price. |
| `automation_fee_cap_for_epoch` | Maximum automation fee for a single epoch. |

Additional fiels used in registry:
Additional fields used in registry:

* `tx_hash`: Hash of the registration transaction
* `aux_data`: Reserved for future use
Expand All @@ -130,12 +129,12 @@ Additional fiels used in registry:

| Method name | Function |
| ----------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `public fun get_task_ids(): vector<u64>` | List all registered task IDs |
| `public fun get_active_task_ids(): vector<u64>` | List active task IDs for the current epoch |
| `public fun get_task_details(id:u64): TaskMetadata` | Returns metadata for a given task index |
| `public fun get_task_count(): u64` | Total number of registered tasks |
| `public fun get_next_task_index(): u64` | Predicts index for next registered task |
| `public fun has_sender_active_task_with_id(address: addresss, id: u64)` | Verifies sender ownership |
| `public fun get_task_ids(): vector<u64>` | List all registered task IDs. |
| `public fun get_active_task_ids(): vector<u64>` | List active task IDs for the current epoch. |
| `public fun get_task_details(id:u64): TaskMetadata` | Returns metadata for a given task index. |
| `public fun get_task_count(): u64` | Total number of registered tasks. |
| `public fun get_next_task_index(): u64` | Predicts index for next registered task. |
| `public fun has_sender_active_task_with_id(address: address, id: u64)` | Verifies sender ownership. |
| `public fun get_gas_committed_for_current_epoch(): u64` | Returns the amount of gas fee set for current epoch. |
| `public fun get_epoch_locked_balance(): u64` | Returns the locked balance after the epoch. |
| `public fun get_registry_fee_address(): address` | Returns address of the fee. |
Expand Down Expand Up @@ -168,7 +167,7 @@ Charged at each epoch based on:

#### Congestion Fee

It is applied when task occupancy exceeds a predefined threshold. It grows polynomially with congestion in the registry.
The congestion fee is applied when task occupancy exceeds a predefined threshold. It increases polynomially with the congestion in the registry.

#### Refunds

Expand Down