Delegation Pool Operations

Beta: This documentation is in experimental, beta mode. Supply feedback by opening a GitHub issue. See also the related Staking Pool Operations instructions.

Validator operators should follow these instructions to carry out delegation pool operations for delegated staking. You may delegate as little as 10 APT plus a small add stake fee that will be mostly refunded as rewards at the end of the current epoch. You might notice that some UIs might use 11 APT as the minimum for a round number. Note that your validator will become part of the Active Validator Set only when the delegation pool satisfies the minimum cumulative staking requirement of 1 million APT.

The delegation pool owner should set an operator for the pool via the set_operator function described in the Perform pool owner operations section. The operator should then start their own Aptos node, as it is a best practice to have a different account for owner and operator. Once the delegation pool attains 1 million APT, the operator can join the validator set.

The operator address will receive the pool commission that was set at the initialization of the delegation pool, which is automatically distributed as stake in the delegation pool at the end of each epoch. The operator will act as a normal Delegation Pool account that is able to do all the operations described in Perform delegation pool operations.

1. Install and configure the Aptos CLI. If you are looking to develop on the Aptos blockchain, debug apps, or perform node operations, the Aptos tool offers a command line interface for these purposes.
2. Initialize local configuration and create an account on the Aptos blockchain.

Before initializing a delegation pool, you need to know the delegation pool address. You can use the following CLI commands to obtain the delegation pool address depending on where you are in the process:

• Before you create the delegation pool:

  aptos account derive-resource-account-address --address <owner_address> --seed "aptos_framework::delegation_pool<SEED>" --seed-encoding utf8

  • The <SEED> is a number chosen by you to create the resource account address to host the delegation pool resource. Once you choose a seed, you should use the same value for all following usages.
• After you create the delegation pool:

  aptos account derive-resource-account-address

1. Run the command below, substitute in the profile you previously configured during initialization:

   aptos move run --profile <your-profile> \
      --function-id 0x1::delegation_pool::initialize_delegation_pool \
      --args u64:1000 string:00

   Where --args:

   • u64:1000 represents operator_commission_percentage - 1000 is equivalent to 10% and 10000 is 100%.
   • string:00 represents delegation_pool_creation_seed - a number chosen by you to create a resource account associated with your owner address; this account is used to host the delegation pool resource. You should use the same number here as the --seed you used in the previous step to create the delegation pool.

2. Once this command is executed without error an account for resources is established using the owner signer and a provided delegation_pool_creation_seed to hold the delegation pool resource and possess the underlying stake pool.

3. The owner is granted authority over assigning the operator and voter roles, which are initially held by the owner.

4. The delegation pool can now accept a minimum amount of 10 APT from any user who wishes to delegate to it.

5. The delegation pool can now connect to the Aptos Network.

This section describes the available operations that can be performed on this recently created pool. Once the delegation pool has been established, use the Aptos CLI to operate the pool. The available actions that can be performed on it include:

• Add amount of coins to the delegation pool pool_address using the public entry method add_stake(delegator: &signer, pool_address: address, amount u64) and substituting your values into the command below before running it:

  aptos move run --profile delegator \
    --function-id 0x1::delegation_pool::add_stake \
    --args address:<pool_address> u64:<amount>

• Undelegate (unlock) the amount of funds from the delegator’s active and pending active stake up to the limit of the active stake in the stake pool using public entry method unlock(delegator: &signer, pool_address: address, amount: u64) and substituting your values into the command below before running it:

  aptos move run --profile delegator \
    --function-id 0x1::delegation_pool::unlock \
    --args address:<pool_address> u64:<amount>

• Cancel undelegate (reactivate stake) amount of coins from pending_inactive state to active state using public entry method reactivate_stake(delegator: &signer, pool_address: address, amount: u64) with the command and your values:

  aptos move run --profile delegator \
    --function-id 0x1::delegation_pool::reactivate_stake \
    --args address:<pool_address> u64:<amount>

• Withdraw amount of owned inactive stake from the delegation pool at pool_address using the public entry method withdraw(delegator: &signer, pool_address: address, amount: u64) and the command:

  aptos move run --profile delegator \
    --function-id 0x1::delegation_pool::withdraw \
    --args address:<pool_address> u64:<amount>

Delegation pool owners have access to specific methods designed for modifying the operator and voter roles of the delegation pool. Use the following Aptos CLI commands and include the relevant addresses:

• Set the operator address for the delegation pool:

  aptos move run --profile delegation_pool_owner \
    --function-id 0x1::delegation_pool::set_operator \
    --args address:<new_operator_address>

Delegation pool owners can update the commission percentage for the delegation pool. The commission rate change can be requested at least 7.5 days before the current lockup cycle ends. The new commission percentage takes effect upon any synchronize_delegation_pool call after the end of the current lockup cycle. Owners are required to call synchronize_delegation_pool as soon as the lockup cycle ends to ensure that the new commission percentage takes effect. Otherwise, the old commission rate will continue to be used until the next synchronize_delegation_pool call.

• Update the commission percentage for the delegation pool; <new_commission_percentage> has two decimal points precision (e.g., 13.25% is represented as 1325):

  aptos move run --profile delegation_pool_owner \
    --function-id 0x1::delegation_pool::update_commission_percentage \
    --args u64:<new_commission_percentage>

Delegation pool operators can set beneficiary addresses to receive the operator commission earned by the delegation pool.

• The beneficiary addresses can be set by the operator using the following command:

  aptos move run --profile delegation_pool_operator \
    --function-id 0x1::delegation_pool::set_beneficiary_for_operator \
    --args address:<new_beneficiary_address>

• To view the beneficiary address set for the operator, use the following command:

  aptos move view --url <REST API for the network> \
    --function-id 0x1::delegation_pool::beneficiary_for_operator \
    --args address:<operator_address>

Any existing unpaid commission rewards will be paid to the new beneficiary. To ensures payment to the current beneficiary, one should first call synchronize_delegation_pool before switching the beneficiary. In case an operator operates multiple delegation pools, the operator can only set one beneficiary for all the delegation pools, not a separate one for each pool.

Once the beneficiary address is set, the operator commission earned by the delegation pool will be distributed to the beneficiary address. The beneficiary account can perform the operations such as unlock and withdraw for the commission earned.

Until the delegation pool has received 1 million APT and the validator has been added to the set of active validators, there will be no rewards to track during each cycle. In order to obtain information about a delegation pool, use the Aptos View function

• get_owned_pool_address(owner: address): address - Returns the address of the delegation pool belonging to the owner, or produces an error if there is no delegation pool associated with the owner.

• delegation_pool_exists(addr: address): bool - Returns true if a delegation pool exists at the provided address addr.

• operator_commission_percentage(pool_address: address): u64 - Returns the operator commission percentage set on the delegation pool at initialization.

• get_stake(pool_address: address, delegator_address: address): (u64, u64, u64) - Returns total stake owned by delegator_address within delegation pool pool_address in each of its individual states: (active,inactive,pending_inactive).

• get_delegation_pool_stake(pool_address: address): (u64, u64, u64, u64) - Returns the stake amounts on pool_address in the different states: (active,inactive,pending_active,pending_inactive).

• shareholders_count_active_pool(pool_address: address): u64 - Returns the number of delegators owning an active stake within pool_address.

• get_pending_withdrawal(pool_address: address, delegator_address: address): (bool, u64) - Returns if the specified delegator possesses any withdrawable stake. However, if the delegator has recently initiated a request to release some of their stake and the stake pool’s lockup cycle has not ended yet, then their funds may not yet be available for withdrawal.

• can_withdraw_pending_inactive(pool_address: address): bool - Returns whether pending_inactive stake can be directly withdrawn from the delegation pool, implicitly its stake pool, in the special case the validator had gone inactive before its lockup expired.

In the Aptos TypeScript SDK, a View function request would resemble:

import { Aptos, AptosConfig } from "@aptos-labs/ts-sdk";

const NODE_URL = "https://aptos-testnet.public.blastapi.io";

(async () => {
  const aptosConfig = new AptosConfig({ fullnode: NODE_URL });
  const aptos = new Aptos(aptosConfig);
  const payload: InputViewRequestData = {
    function: "0x1::delagation_pool::get_stake",
    functionArguments: ["pool_address", "delegator_address"],
  };
  console.log(await aptos.view({ payload }));
})();

Alternatively, you can use Aptos CLI to call View functions.

aptos move view [OPTIONS] --function-id <FUNCTION_ID>

To discover the available options and the process for making an aptos move view call, access the help information with aptos move view --help. This will display the required arguments for invoking the view functions.

Use this formula to calculate rewards earned for active and pending_inactive staking. This formula assumes that different stake operations such as unlock and reactivate take out the principals first and then rewards. Therefore, rewards earned may vary based upon how the formula you use is constructed:

1. Get the amount of active and pending_inactive staking from the get_stake view function.

2. Calculate principal:

   • “active principal” = AddStakeEvent - UnlockStakeEvent + ReactivateStakeEvent. If at any point during the iteration, “active principal” < 0, reset to 0. Negative principal could happen when the amount users unlock include rewards earned from staking.
   • “pending inactive principal” = UnlockStakeEvent - ReactivateStakeEvent. If at any point during the iteration, “pending inactive principal” < 0, reset to 0. Negative principal could happen when the amount users reactivate include rewards earned from staking.

3. Compute rewards earned:

   • active rewards = active - active principal.
   • pending_inactive_rewards = pending_inactive - “pending inactive principal”.

Delegation pool owners can set an allowlist for their delegation pool. They can add or remove addresses from the allowlist and evict delegators who are not on the allowlist. Here is the flow:

1. By default, a delegation pool is permissionless and does not have an allowlist. The pool owner can set an allowlist, transitioning the pool to a permissioned state.
2. When an allowlist is first established in a delegation pool, it starts empty. This initial empty allowlist does not impact existing stakes in the pool. However, the pool will not accept any new stakes or reactivation of pending-inactive stakes from any stakers because no one is on the allowlist initially.
3. The pool owner may add stakers’ wallet addresses to the allowlist. Once an address is added, the staker can add new stakes or reactivate existing stakes in the pool. Note that this feature does not facilitate a mechanism for stakers to request to be added to the allowlist; such requests must be managed off-chain (e.g., through private communication between the operator and staker, or UI-based solutions).
4. If a delegator is removed from the allowlist, they are no longer able to add or reactivate stakes. However, they retain the ability to unlock and withdraw their existing stakes.
5. The pool owner can evict a delegator who is not included on the allowlist. This action will unlock the delegator’s entire stake, transitioning all of their active stakes to a pending inactive state. As the evicted delegator is not on the allowlist, they cannot reactive their stake. Note that these tokens will remain locked up until the end of the lockup period, and the existing stake will also continue to earn rewards until then. When the lockup period ends, the funds will be unstaked (inactive), but will remain in the pool until the delegator initiates a withdrawal.
6. If a delegator’s stake enters the pending inactive state due to eviction, the pool owner can subsequently add the delegator back to the allowlist. However, this action will not automatically reactivate the stake. Automatic reactivation is not provided to prevent potential misuse by a malicious pool owner who might repeatedly evict and re-allowlist a delegator to prevent them from leaving the pool. Once a delegator is back on the allowlist, the delegator must manually call the reactivate_stake function to reactivate their stake.
7. Delegation pools that have enabled allowlisting can disable it. When disabled, the delegation pool becomes permissionless, allowing any staker to stake to the pool.

• The delegation pool owner can enable allow listing and create an empty allowlist using the following command:

  aptos move run --profile delegation_pool_owner \
    --function-id 0x1::delegation_pool::enable_delegators_allowlisting

• The delegation pool owner can disable allow listing and delete the existing allowlist using the following command:

  aptos move run --profile delegation_pool_owner \
    --function-id 0x1::delegation_pool::disable_delegators_allowlisting

• The delegation pool owner can add an address to the allowlist using the following command:

  aptos move run --profile delegation_pool_owner \
    --function-id 0x1::delegation_pool::allowlist_delegator \
    --args address:<delegator_address>

• The delegation pool owner can remove an address from the allowlist using the following command:

  aptos move run --profile delegation_pool_owner \
    --function-id 0x1::delegation_pool::remove_delegator_from_allowlist \
    --args address:<delegator_address>

• The delegation pool owner can evict a delegator from the pool by unlocking their entire stake using the following command:

  aptos move run --profile delegation_pool_owner \
    --function-id 0x1::delegation_pool::evict_delegator \
    --args address:<delegator_address>

There are also view functions available to check the allowlist status and the addresses on the allowlist:

• The following view function returns whether pool has allow listing enabled:

  aptos move view --url <REST API for the network> \
    --function-id 0x1::delegation_pool::allowlisting_enabled \
    --args address:<pool>

• The following view function returns whether delegator is on the allowlist of pool:

  aptos move view --url <REST API for the network> \
    --function-id 0x1::delegation_pool::delegator_allowlisted \
    --args address:<pool> address:<delegator>

• The following view function returns the allowlist defined on pool:

  aptos move view --url <REST API for the network> \
    --function-id 0x1::delegation_pool::get_delegators_allowlist \
    --args address:<pool>