Skip to Content
Join our Discord server! ↗
AutomationYour First Automation TaskCalculate task-expiry-time & task-automation-fee

Calculate task-expiry-time & task-automation-fee

View the command

supra move automation register --help

Understand parameters

supra move automation register \
  --task-max-gas-amount <MAX_GAS> \
  --task-gas-price-cap <GAS_PRICE_CAP> \
  --task-expiry-time-secs <EXPIRY> \
  --task-automation-fee-cap <FEE_CAP> \
  --function-id "<ADDRESS>::<MODULE>::<FUNCTION>" \
  --rpc-url <RPC_URL>

Check Network Details for the RPC URL of Mainnet, Testnet and Devnet. The sections below explain how to derive each placeholder from the chain. The registry parameters can change through governance, so read them again before each registration.

All amounts are in quants (1 SUPRA = 100,000,000 quants).

How to Calculate --task-expiry-time-secs

A task registered during a cycle becomes active when the next cycle starts, so its expiry time must fall after the end of the current cycle. It must also fall within the task duration cap counted from the registration time.

Get the current cycle

supra move tool view \
  --function-id 0x1::automation_registry::get_cycle_info \
  --rpc-url <RPC_URL>

The same view through the REST API:

curl -X POST <RPC_URL>/rpc/v3/view \
  -H 'content-type: application/json' \
  -d '{"function": "0x1::automation_registry::get_cycle_info", "type_arguments": [], "arguments": []}'

Read start_time and duration_secs from the response. Both are in seconds.

Get the task duration cap

supra move tool view \
  --function-id 0x1::automation_registry::get_automation_registry_config \
  --rpc-url <RPC_URL>

The same view through the REST API:

curl -X POST <RPC_URL>/rpc/v3/view \
  -H 'content-type: application/json' \
  -d '{"function": "0x1::automation_registry::get_automation_registry_config", "type_arguments": [], "arguments": []}'

Read task_duration_cap_in_secs from the response. This is the longest time, counted from registration, that a task can be registered for.

Final formula to calculate the task expiry time

buffer is the number of seconds you want the task to stay active after the next cycle starts. A buffer larger than duration_secs also covers the case where a new cycle starts between reading the cycle and registering the task.

task-expiry-time-secs = start_time + duration_secs + buffer

The registration aborts if the result does not satisfy both conditions:

  • task-expiry-time-secs > start_time + duration_secs, otherwise with EEXPIRY_BEFORE_NEXT_CYCLE
  • task-expiry-time-secs - registration time <= task_duration_cap_in_secs, otherwise with EEXPIRY_TIME_UPPER

registration time is the chain time when the transaction executes, in seconds since the Unix epoch. An expiry time that is not after the registration time aborts with EINVALID_EXPIRY_TIME.

Use: --task-expiry-time-secs <EXPIRY>, where <EXPIRY> is the result of the formula.

How to Estimate --task-max-gas-amount and --task-automation-fee-cap

Choose your max gas: <MAX_GAS> is the maximum gas you expect one execution of your task to use. The registry also limits the total gas committed by all tasks for the next cycle. Read the limit and the amount already committed:

supra move tool view \
  --function-id 0x1::automation_registry::get_next_epoch_registry_max_gas_cap \
  --rpc-url <RPC_URL>
 
supra move tool view \
  --function-id 0x1::automation_registry::get_gas_committed_for_next_epoch \
  --rpc-url <RPC_URL>

<MAX_GAS> plus the committed gas must not exceed the limit, otherwise the registration aborts with EGAS_AMOUNT_UPPER.

Estimate the fee: the fee cap must be at least the automation fee for one cycle at <MAX_GAS>:

supra move tool view \
  --function-id 0x1::automation_registry::estimate_automation_fee \
  --args u64:<MAX_GAS> \
  --rpc-url <RPC_URL>

The same view through the REST API:

curl -X POST <RPC_URL>/rpc/v3/view \
  -H 'content-type: application/json' \
  -d '{"function": "0x1::automation_registry::estimate_automation_fee", "type_arguments": [], "arguments": ["<MAX_GAS>"]}'

The result is the fee in quants. A cap below the estimate aborts the registration with EINSUFFICIENT_AUTOMATION_FEE_CAP_FOR_EPOCH.

The estimate depends on the gas already committed by other tasks, so it can rise before your transaction executes. Set <FEE_CAP> slightly above the estimate. The fee is charged at the start of each cycle, and a task whose fee for a cycle exceeds its cap is removed. The cap is also locked as a deposit when the task is registered; see Fee Structure for when it is refunded.

Each cycle’s fee is charged from the account’s balance, not from the deposit. If the balance cannot cover the fee at the start of a cycle, the task is removed and its deposit is not refunded. Keep the balance above the fee for every cycle until the task expires.

Example calculation

  1. Choose <MAX_GAS> as described above.
  2. Run estimate_automation_fee with <MAX_GAS> as the argument. Call the result value <ESTIMATE>.
  3. Set <FEE_CAP> to <ESTIMATE> plus the headroom you want, for example 10 percent.
  4. Divide <FEE_CAP> by 100,000,000 to get the cap in SUPRA.

How the fee is calculated

estimate_automation_fee computes the fee for one cycle from:

  • the cycle duration;
  • <MAX_GAS> as a share of the registry’s gas cap for the next cycle (get_next_epoch_registry_max_gas_cap);
  • automation_base_fee_in_quants_per_sec;
  • a congestion fee, which applies when the gas committed for the next cycle, including <MAX_GAS>, exceeds congestion_threshold_percentage of that cap. It rises faster for a higher congestion_exponent.

The fee parameters come from get_automation_registry_config.

Parameter Guide

--task-max-gas-amountMax gas your function can use in one execution
--task-gas-price-capHighest gas unit price you accept. A block whose gas unit price is above the cap skips the task. Read the current prices from <RPC_URL>/rpc/v3/transactions/estimate_gas_price and set a cap at or above max_gas_price
--task-expiry-time-secsDeadline for task (UNIX time)
--task-automation-fee-capMax automation fee per cycle, in quants
--function-idTarget public entry function to trigger
--args (optional, per target function)Arguments to pass to the function
--simulateRun a dry run to check for success

The fields of get_automation_registry_config that affect registration and fees:

FieldMeaning
task_duration_cap_in_secsMaximum allowable duration (in seconds) from the registration time that an automation task can run. If the expiration time exceeds this duration, the task registration will fail.
registry_max_gas_capMaximum gas allocation for automation tasks per cycle. Exceeding this limit during task registration will cause failure, and it is used in fee calculation.
automation_base_fee_in_quants_per_secBase fee per second for the full capacity of the automation registry, measured in quants/sec. The capacity is considered full if the total committed gas of all registered tasks equals registry_max_gas_cap.
flat_registration_fee_in_quantsFlat registration fee charged for each task. It is not refunded.
congestion_threshold_percentageRelative to registry_max_gas_cap. Beyond this threshold, congestion fees apply.
congestion_base_fee_in_quants_per_secBase fee per second for the full capacity of the automation registry when the congestion threshold is exceeded.
congestion_exponentExponent applied to the fraction above the congestion threshold. A higher value makes the congestion fee rise faster as the registry fills.
task_capacityMaximum number of tasks that the registry can hold. A registration aborts with EREGISTRY_IS_FULL when it is reached.

At registration, the account pays flat_registration_fee_in_quants plus the deposit equal to <FEE_CAP>.

Last updated on
Create the Move Smart ContractRegister your Automation Task