From 654714faf3f689bb3b6697548e876aea0d8a0fd8 Mon Sep 17 00:00:00 2001 From: chariot6 Date: Sat, 10 May 2025 18:31:31 +0200 Subject: [PATCH] grammar tweaks for automation api-reference --- automation/api-reference.md | 77 ++++++++++++++++++------------------- 1 file changed, 38 insertions(+), 39 deletions(-) diff --git a/automation/api-reference.md b/automation/api-reference.md index 902e054..000bb15 100644 --- a/automation/api-reference.md +++ b/automation/api-reference.md @@ -8,32 +8,31 @@ 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 \ --task-automation-fee-cap 10000 \ ---function-id "0x1::your_module::"function name" \ +--function-id "0x1::your_module::function name" \ --args address: u64: ``` -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) ``` @@ -41,14 +40,14 @@ This method cancels the task by index. The task remains scheduled for the curren #### Read Functions -| Function name | Functionality | -| ----------------------------------------------------------------------- | ----------------------------------------------------------------------- | -| `public fun get_active_task_ids(): vector` | 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` | 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. @@ -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
### 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.\ @@ -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 @@ -130,12 +129,12 @@ Additional fiels used in registry: | Method name | Function | | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------- | -| `public fun get_task_ids(): vector` | List all registered task IDs | -| `public fun get_active_task_ids(): vector` | 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` | List all registered task IDs. | +| `public fun get_active_task_ids(): vector` | 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. | @@ -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