Skip to content

Auto Compound Staking Rewards API

Jump to bottom
Nikhil Vengal edited this page Sep 5, 2022 · 15 revisions

Disclaimer: This API is not yet live and subject to change

Dotsama blockchains that use the parachain-staking pallet deposit rewards into the delegator's wallet at the beginning of every round. Currently in the Dotsama ecosystem, parachain stakers that want to maximize their gains have to manually increase the size of their delegation each time they receive a staking reward. The Turing blockchain allows delegators to auto-compound their stake on a fixed schedule without risking their private key or having to run their own infrastructure.

Scheduling an Auto-Compounding Task

This extrinsic schedules a task that increases a delegator's stake based on configurable parameters. In this example, Charlie is scheduling a task to auto-compound his delegation to the collator Alice every week as long as his account has a minimum of 100 TUR.

Module: AutomationTime

Method: scheduleAutoCompoundDelegatedStakeTask

Args:

  • executionTime: A unix timestamp (to the nearest hour); when the task should run for the first time.
  • frequency: An integer number of seconds (to the nearest hour); how often the wallet balance should be auto compounded.
  • collatorId: The account id of the target collator.
  • accountMinimum: The minimum amount that should be kept in the user's wallet.

Detecting Success

When the task is successfully scheduled the websocket will return a success response and the chain will emit the automationTime.TaskScheduled event. The taskId can be used to track and interact with a scheduled task.

When the task executes successfully the chain will emit the automationTime.SuccesfullyAutoCompoundedDelegatorStake event. This event will include the amount by which the delegation was increased.

Error Handling

Errors can occur both at the time of initial scheduling and when the task is executed. Scheduling errors will be returned as a websocket response while execution errors will be signaled by on-chain events.

List of scheduling errors

Viewing Active Auto-Compounding Tasks

The Turing blockchain exposes a rpc endpoint that allows developers to query a user's scheduled auto compounding tasks.

Module: AutomationTime

Method: getScheduledAutoCompoundDelegatedStakeTasks

Args:

  • accountId: The user's ss58 encoded account id

Example Response:

{
    "jsonrpc": "2.0",
    "result": {
        "0xa22d90bd566e7abfcb3d7a06032a046677c2f33e5a9404ec62724cc07dc6fbad" (taskId): {
            "executionTimes": [
                1657947600 (unix timestamp of next execution)
            ],
            "action": {
                "AutoCompoundDelegatedStake": {
                    "delegator": "69RP3c4mjtHruDpKQWA1TeSacmA2FqS214oiDBZXBPszxzvD" (accountId),
                    "collator": "6AwtFW6sYcQ8RcuAJeXdDKuFtUVXj4xW57ghjYQ5xyciT1yd" (accountId),
                    "accountMinimum": 1000000000000 (TUR),
                    "frequency": 604800 (seconds)
                }
            }
        },
        ...
    },
    "id": 1
}

Cancelling an Auto-Compounding Task

Active auto-compounding tasks can be cancelled by submitting an extrinsic to the Turing blockchain. In this example, Charlie is cancelling the task that he scheduled earlier. Users can only cancel tasks that they have scheduled.

Module: AutomationTime

Method: cancelTask

Args:

  • taskId: Id of the task to cancel

Detecting Success

When a task is successfully cancelled the websocket will return a success response and the chain will emit an automationTime.TaskCancelled event that includes the taskId of the cancelled task.

Error Handling

On error the websocket will return a response that includes a dispatch error of either: TaskDoesNotExist or NotTaskOwner.

Querying for an Optimal Auto-Compounding Time

An RPC call is provided to perform a calculation to return the period of time in days that maximizes APY given a user's principal and target collator. Access to this RPC via API is not currently available in the UI but can be called manually.

Module: AutomationTime

Method: calculateOptimalAutostaking

Args:

  • principal: An integer balance (in Planck); the initial balance a user wishes to stake.
  • collator: The account id of the target collator

Results:

  • period: An integer number of days; how often restaking is optimal for the given parameters
  • apy: A decimal APY.

Example Response:

{
    "jsonrpc": "2.0",
    "result": {
        "apy":0.029450359762913332,
        "period":46
    },
    "id": 1
}

Events

  • AutomationTime.TaskScheduled { who: AccountId, task_id: Hash }
  • AutomationTime.TaskCancelled { who: AccountId, task_id: Hash }
  • AutomationTime.TaskMissed { who: AccountId, task_id: Hash, execution_time: UnixTime }
    • The task could not be performed at the scheduled time
  • AutomationTime.SuccessfullyAutoCompoundedDelegatorStake { task_id: Hash, amount: Balance }
  • AutomationTime.AutoCompoundDelegatorStakeFailed { task_id: Hash, error_message: String, error: DispatchError }
  • ParachainStaking.DelegationIncreased { delegator: AccountId, candidate: AccountId, amount: Balance }
Clone this wiki locally