delegation::delegation_service

Module 0xc0ded0c0::delegation_service
This module provides a delegation service for staking on Aptos.
It:
1.builds on top of delegation_state module,
2.consumes the owner_capability of a StakePool owner and uses it to delegate to the pool,
3.makes the liquid staking protocol just one of many delegators,
4.requires the owner to join with the minimum stake as specified by the aptos_framework, and cannot go below that amount until they self-destruct, and,
5.lets the pool owner can retrieve the owner_capability of their StakePool after a successful self-destruct.
​Resource ManagedStakePool​
​Struct ManageCapability​
​Constants​
​Function assert_is_self_destructing​
​Abort conditions​
​Function begin_self_destruct​
​Restrictions​
​Abort conditions​
​Function finish_self_destruct​
​Restrictions​
​Abort conditions​
​Function pay_commission_to_owner​
​Restrictions​
​Function initialize​
​Restrictions​
​Abort conditions​
​Function set_min_delegation_amount​
​Restrictions​
​Function delegate​
​Abort conditions​
​Function change_commission​
​Restrictions​
​Abort condition​
​Function change_commission_recipient​
​Restrictions​
​Abort conditions​
​Function reserve_shares_for_withdraw​
​Restrictions​
​Abort conditions​
​Function trigger_payout_dispersal​
​Abort conditions​
​Function remove_non_owner_delegator​
​Abort conditions​
​Function set_operator​
​Function set_delegated_voter​
​Function assert_not_self_destructing​
​Abort conditions​
​Function assert_pool_exists​
​Abort conditions​
​Function certify_delegation​
​Abort conditions​
​Function ensure_minimum_delegation_remaining​
​Abort conditions​
use 0x1::aptos_coin;
use 0x1::coin;
use 0x1::error;
use 0x1::signer;
use 0x1::stake;
use 0xc0ded0c0::delegation_state;
use 0xc0ded0c0::stake_pool_helpers;
Resource ManagedStakePool
The struct which holds the OwnerCapability of the StakePool and stores config parameters.
struct ManagedStakePool has key
Fields
stake_pool_owner_cap: stake::OwnerCapabilitystores the OwnerCapability of the StakePool owner.in_self_destruct: boolstores whether self-destruct has been called by the owner. The ManagedStakingPool does not accept new delegations in self-destruct mode.min_delegation_amount: u64max_commission: u64
Struct ManageCapability
Holders of ManageCapability can call permissioned functions. It is returned during initialization.
struct ManageCapability has store
Fields
managed_pool_address: address
Constants
The minimum stake that can be delegated to a managed stake pool.
const DEFAULT_MINIMUM_DELEGATION_AMOUNT: u64 = 10000000000000;
When trying to remove the stake pool owner's delegation during self-destruct.
const ECANNOT_FORCE_OWNER_TO_WITHDRAW: u64 = 12;
When the commission being set is higher than the max_commission.
const ECOMMISSION_EXCEEDS_MAX: u64 = 2;
When the delegation amount is below the threshold.
const EDELEGATION_AMOUNT_TOO_SMALL: u64 = 10;
When the managed stake pool already exists at the address during initialization.
const EMANAGED_POOL_ALREADY_EXISTS: u64 = 5;
When the stake of the owner is below the minimum stake, and the pool is not in self-destruct.
const EMINIMUM_VIOLATION: u64 = 7;
When the the pool is not in self-destruct state.
const ENOT_SELF_DESTRUCTING: u64 = 8;
When the managed stake pool does not exist.
const EPOOL_DOES_NOT_EXIST: u64 = 11;
When the commission being charged for the protocol delegator is higher than the commission being charged to outside delegators.
const EPROTOCOL_COMMISSION_EXCEEDS_DEFAULT: u64 = 3;
When the pool is in the self-destruct state.
const ESELF_DESTRUCTING: u64 = 1;
When the maximum number of delegators are already staked.
const ETOO_MANY_DELEGATIONS: u64 = 9;
The maximum number of delegators that can delegate to a managed pool.
const MAX_NUMBER_OF_DELEGATIONS: u64 = 100;
Function assert_is_self_destructing
Assert the pool is in self-destruct mode
Abort conditions
If the managed stake pool is not in self-destruct state.
public fun assert_is_self_destructing(managed_pool_address: address)
Implementation
public fun assert_is_self_destructing(
    managed_pool_address: address
) acquires ManagedStakePool {
    let managed_stake_pool = borrow_global<ManagedStakePool>(
        managed_pool_address
    );
    assert!(
        managed_stake_pool.in_self_destruct,
        error::invalid_state(ENOT_SELF_DESTRUCTING)
    );
}
Function begin_self_destruct
Move the Managed Stake Pool into self-destruct mode. Cannot be reversed.
Restrictions
Can only be called using ManageCapability of the managed pool.
Abort conditions
If the pool does not exist.
public fun begin_self_destruct(manage_cap: &delegation_service::ManageCapability)
Implementation
public fun begin_self_destruct(
    manage_cap: &ManageCapability,
) acquires ManagedStakePool {
    let managed_pool_address = manage_cap.managed_pool_address;
    assert_pool_exists(managed_pool_address);
    let managed_stake_pool = borrow_global_mut<ManagedStakePool>(
        managed_pool_address
    );
    managed_stake_pool.in_self_destruct = true;
}
Function finish_self_destruct
Destroys the ManageStakePool and returns the StakePool's OwnerCapability.
Restrictions
Can only be called using ManageCapability of the managed pool.
Abort conditions
If the pool is not in self-destruct state.
public fun finish_self_destruct(manage_cap: delegation_service::ManageCapability): stake::OwnerCapability
Implementation
public fun finish_self_destruct(
    manage_cap: ManageCapability,
): OwnerCapability acquires ManagedStakePool {
    let managed_pool_address = manage_cap.managed_pool_address;
    assert_is_self_destructing(managed_pool_address);
​
    let ManagedStakePool {
        stake_pool_owner_cap: owner_cap,
        in_self_destruct: _b,
        min_delegation_amount: _c,
        max_commission: _m,
    } = move_from<ManagedStakePool>(managed_pool_address);
​
    delegation_state::pay_commission_to_owner(managed_pool_address);
    delegation_state::disperse_all_payouts(
        managed_pool_address,
        &owner_cap
    );
    delegation_state::self_destruct_internal(managed_pool_address);
​
    let ManageCapability {
        managed_pool_address: _mpa,
    } = manage_cap;
​
    owner_cap
}
Function pay_commission_to_owner
Compound ManagedStakePool's commission. Returns the amount of commission paid to the owner in APT.
Restrictions
Only available to the holder of ManageCapability.
public fun pay_commission_to_owner(manage_cap: &delegation_service::ManageCapability): u64
Implementation
public fun pay_commission_to_owner(
    manage_cap: &ManageCapability,
): u64 {
    assert_pool_exists(manage_cap.managed_pool_address);
    delegation_state::pay_commission_to_owner(
        manage_cap.managed_pool_address
    )
}
Function initialize
Allows a StakePool owner managed_pool_owner to start a ManagedStakePool that can accept delegations from outside delegators. The maximum commission that can be charged is given by max_commission. The address of the Tortuga protocol delegator is given by protocol_delegator_address and the commission charged to the protocol delegator is given by protocol_commission.
Returns the ManageCapability of the newly created ManagedStakePool.
Note: Commissions are specified in 6 decimal precision, following the value of COMMISSION_NORMALIZER in delegation_state module (i.e. commission of 1000000 = 100%).
Restrictions
To be associated with Tortuga protocol, this function should be called from validator_router module.
Abort conditions
If the ManagedStakePool already exists on the given address.
protocol_commission must be lower than max_commission.
public fun initialize(managed_pool_owner: &signer, max_commission: u64, commission_recipient_address: address, protocol_delegator_address: address, protocol_commission: u64): delegation_service::ManageCapability
Implementation
public fun initialize(
    managed_pool_owner: &signer,
    max_commission: u64,
    commission_recipient_address: address,
    protocol_delegator_address: address,
    protocol_commission: u64,
): ManageCapability acquires ManagedStakePool {
    let managed_pool_address = signer::address_of(managed_pool_owner);
    assert!(
        !exists<ManagedStakePool>(managed_pool_address),
        error::invalid_argument(EMANAGED_POOL_ALREADY_EXISTS)
    );
    // extract `owner_capability` from the pool_owner
    let stake_pool_owner_cap = stake::extract_owner_cap(managed_pool_owner);
    let stake_pool_address = stake::get_owned_pool_address(
        &stake_pool_owner_cap
    );
​
    // store the ManagedStakePool
    let managed_stake_pool = ManagedStakePool {
        stake_pool_owner_cap: stake_pool_owner_cap,
        in_self_destruct: false,
        min_delegation_amount: DEFAULT_MINIMUM_DELEGATION_AMOUNT,
        max_commission: max_commission,
    };
    move_to(managed_pool_owner, managed_stake_pool);
​
    delegation_state::initialize_internal(
        managed_pool_owner,
        protocol_delegator_address,
        commission_recipient_address,
        stake_pool_address
    );
​
    change_commission(
        managed_pool_owner,
        max_commission,
        protocol_commission
    );
​
    ManageCapability {
        managed_pool_address: managed_pool_address,
    }
}
Function set_min_delegation_amount
Set minimum acceptable delegations from outside delegators. Does not affect pool owner and the protocol.
Restrictions
Can only be called by the pool_owner.
public fun set_min_delegation_amount(pool_owner: &signer, value: u64)
Implementation
public entry fun set_min_delegation_amount(
    pool_owner: &signer,
    value: u64
) acquires ManagedStakePool {
    let managed_pool_address = signer::address_of(pool_owner);
    let managed_stake_pool = borrow_global_mut<ManagedStakePool>(
        managed_pool_address
    );
    managed_stake_pool.min_delegation_amount = value;
}
Function delegate
Lets a delegator to delegate amount APT with a ManagedStakePool at address managed_pool_address.
Abort conditions
If the ManagedStakePool is in self-destruct state.
If the pool already has MAX_NUMBER_OF_DELEGATIONS delegations.
If the delegation amount is less than min_delegation_amount.
public fun delegate(delegator: &signer, managed_pool_address: address, amount: u64)
Implementation
public entry fun delegate(
    delegator: &signer,
    managed_pool_address: address,
    amount: u64,
) acquires ManagedStakePool {
    assert_not_self_destructing(managed_pool_address);
​
    let delegator_address = signer::address_of(delegator);
    certify_delegation(managed_pool_address, delegator_address, amount);
​
    let coins_to_delegate = coin::withdraw<AptosCoin>(delegator, amount);
    let managed_stake_pool = borrow_global<ManagedStakePool>(
        managed_pool_address
    );
​
    // make sure that newly minted shares for the delegator are not subject
    // to any commissions by paying outstanding commissions first
    delegation_state::pay_commission_to_owner(managed_pool_address);
    delegation_state::disperse_all_payouts(
        managed_pool_address,
        &managed_stake_pool.stake_pool_owner_cap
    );
​
    delegation_state::delegate_internal(
        delegator,
        coins_to_delegate,
        managed_pool_address,
        &managed_stake_pool.stake_pool_owner_cap
    );
}
Function change_commission
Change the default and protocol commissions.
Restrictions
Only the pool_owner can call this function.
Abort condition
If the ManagedStakePool does not exist.
If the new_default_commission is greater than max_commission.
If the new_protocol_commission is greater than new_default_commission.
public fun change_commission(pool_owner: &signer, new_default_commission: u64, new_protocol_commission: u64)
Implementation
public entry fun change_commission(
    pool_owner: &signer,
    new_default_commission: u64,
    new_protocol_commission: u64,
) acquires ManagedStakePool {
    let managed_pool_address = signer::address_of(pool_owner);
    assert_pool_exists(managed_pool_address);
​
    let managed_stake_pool = borrow_global_mut<ManagedStakePool>(
        managed_pool_address
    );
    assert!(
        new_default_commission <= managed_stake_pool.max_commission,
        error::invalid_argument(ECOMMISSION_EXCEEDS_MAX)
    );
    assert!(
        new_protocol_commission <= new_default_commission,
        error::invalid_argument(EPROTOCOL_COMMISSION_EXCEEDS_DEFAULT)
    );
​
    // pay outstanding commission on original commission rate
    delegation_state::pay_commission_to_owner(managed_pool_address);
​
    delegation_state::change_commission_internal(
        pool_owner,
        new_default_commission,
        new_protocol_commission,
    );
}
Function change_commission_recipient
Change the commission recipient of the ManagedStakePool to new_commission_recipient_address.
Restrictions
Only the pool_owner can call this function.
Abort conditions
If the ManagedStakePool does not exist.
public fun change_commission_recipient(pool_owner: &signer, new_commission_recipient_address: address)
Implementation
public entry fun change_commission_recipient(
    pool_owner: &signer,
    new_commission_recipient_address: address,
) {
    let managed_pool_address = signer::address_of(pool_owner);
    assert_pool_exists(managed_pool_address);
​
    // pay outstanding commission to the old recipient
    delegation_state::pay_commission_to_owner(managed_pool_address);
​
    delegation_state::change_commission_recipient_internal(
        managed_pool_address,
        new_commission_recipient_address,
    );
}
Function reserve_shares_for_withdraw
delegator can call this function to withdraw num_shares from the ManagedStakePool at address managed_pool_address. This will move delegator shares from unreserved_pool to reserved_pool and move corresponding StakePool funds from 'active' to 'pending_inactive' state.. May have to call trigger_payout_dispersal when the stake unlocks (i.e., changes state from 'pending_inactive' to 'inactive').
Restrictions
Only the delegator can call this function for themselves.
Abort conditions
If the withdrawal amount will leave less than min_delegation_amount in the delegator's account. However, it allows all the funds to be atomically withdrawn.
public fun reserve_shares_for_withdraw(delegator: &signer, managed_pool_address: address, num_shares: u64)
Implementation
public entry fun reserve_shares_for_withdraw(
    delegator: &signer,
    managed_pool_address: address,
    num_shares: u64,
) acquires ManagedStakePool {
    assert_pool_exists(managed_pool_address);
    let delegator_address = signer::address_of(delegator);
​
    // Check for min violation
    ensure_minimum_delegation_remaining(
        managed_pool_address,
        delegator_address,
        num_shares
    );
​
    let managed_stake_pool = borrow_global<ManagedStakePool>(
        managed_pool_address
    );
​
    // make sure there is no outstanding commission in either pool before
    // transferring
    delegation_state::pay_commission_to_owner(managed_pool_address);
    delegation_state::disperse_all_payouts(
        managed_pool_address,
        &managed_stake_pool.stake_pool_owner_cap
    );
​
    delegation_state::reserve_shares_for_withdraw_internal(
        delegator_address,
        num_shares,
        managed_pool_address,
        &managed_stake_pool.stake_pool_owner_cap
    );
}
Function trigger_payout_dispersal
Disperses all APT if there is inactive stake in the StakePool. Can be called permissionlessly.
Abort conditions
If the ManagedStakePool does not exist.
public fun trigger_payout_dispersal(managed_pool_address: address)
Implementation
public entry fun trigger_payout_dispersal(
    managed_pool_address: address
) acquires ManagedStakePool {
    assert_pool_exists(managed_pool_address);
    let stake_pool_address = delegation_state::get_stake_pool_address(
        managed_pool_address
    );
​
    // nothing to disperse
    if (
        stake_pool_helpers::get_stake_pool_total_withdrawable_amount(
            stake_pool_address
        ) == 0
    ) {
        return
    };
​
    // first pay commission to the owner
    delegation_state::pay_commission_to_owner(managed_pool_address);
​
    let managed_stake_pool = borrow_global<ManagedStakePool>(
        managed_pool_address
    );
    delegation_state::disperse_all_payouts(
        managed_pool_address,
        &managed_stake_pool.stake_pool_owner_cap
    );
}
Function remove_non_owner_delegator
Reserve all shares for withdrawal for delegator_address. Can be called by anyone but only when pool is in self-destruct state. This ensures the owner can remove all delegators and retrieve their owner_capability.
Abort conditions
If the ManagedStakePool does not exist.
If the ManagedStakePool is not in self_destruct state.
If the delegator_address is managed_pool_address itself.
public fun remove_non_owner_delegator(managed_pool_address: address, delegator_address: address)
Implementation
public entry fun remove_non_owner_delegator(
    managed_pool_address: address,
    delegator_address: address,
) acquires ManagedStakePool {
    assert_pool_exists(managed_pool_address);
    assert_is_self_destructing(managed_pool_address);
    assert!(
        delegator_address != managed_pool_address,
        error::invalid_argument(ECANNOT_FORCE_OWNER_TO_WITHDRAW),
    );
​
    let managed_stake_pool = borrow_global<ManagedStakePool>(managed_pool_address);
    delegation_state::pay_commission_to_owner(managed_pool_address);
    delegation_state::disperse_all_payouts(
        managed_pool_address,
        &managed_stake_pool.stake_pool_owner_cap
    );
​
    let delegator_unreserved_shares =
        delegation_state::get_unreserved_shares_with_delegator(
            managed_pool_address,
            delegator_address
        );
​
    delegation_state::reserve_shares_for_withdraw_internal(
        delegator_address,
        delegator_unreserved_shares,
        managed_pool_address,
        &managed_stake_pool.stake_pool_owner_cap,
    );
}
Function set_operator
Allow the stake_pool owner to set new_operator as the operator of the pool. See 0x1::stake::set_operator_with_cap for details.
public fun set_operator(pool_owner: &signer, new_operator: address)
Implementation
public entry fun set_operator(
    pool_owner: &signer,
    new_operator: address
) acquires ManagedStakePool {
    let managed_pool_address = signer::address_of(pool_owner);
    assert_pool_exists(managed_pool_address);
    let managed_stake_pool = borrow_global<ManagedStakePool>(
        managed_pool_address
    );
    stake::set_operator_with_cap(
        &managed_stake_pool.stake_pool_owner_cap,
        new_operator
    );
}
Function set_delegated_voter
Allow the stake_pool owner to set new_voter as the delegated voter of the pool. See 0x1::stake::set_delegated_voter_with_cap for details.
public fun set_delegated_voter(pool_owner: &signer, new_voter: address)
Implementation
public entry fun set_delegated_voter(
    pool_owner: &signer,
    new_voter: address
) acquires ManagedStakePool {
    let managed_pool_address = signer::address_of(pool_owner);
    assert_pool_exists(managed_pool_address);
    let managed_stake_pool = borrow_global<ManagedStakePool>(
        managed_pool_address
    );
    stake::set_delegated_voter_with_cap(
        &managed_stake_pool.stake_pool_owner_cap,
        new_voter
    );
}
Function assert_not_self_destructing
Assert the pool is not in self-destruct mode
Abort conditions
If the pool is in self-destruct mode.
fun assert_not_self_destructing(managed_pool_address: address)
Implementation
fun assert_not_self_destructing(
    managed_pool_address: address
) acquires ManagedStakePool {
    let managed_stake_pool = borrow_global<ManagedStakePool>(
        managed_pool_address
    );
    assert!(
        !managed_stake_pool.in_self_destruct,
        error::invalid_state(ESELF_DESTRUCTING)
    );
}
Function assert_pool_exists
Assert the ManagedStakePool has been initialized at the provided address.
Abort conditions
If the ManagedStakePool does not exist.
fun assert_pool_exists(managed_pool_address: address)
Implementation
fun assert_pool_exists(managed_pool_address: address) {
    assert!(
        exists<ManagedStakePool>(managed_pool_address),
        error::invalid_argument(EPOOL_DOES_NOT_EXIST)
    );
}
Function certify_delegation
Certifies that a delegation with amount from delegator_address can be made. Aborts if criteria are not met. The protocol_delegator and the pool_owner, and existing delegators are not subject to these conditions.
Abort conditions
If the pool already has MAX_NUMBER_OF_DELEGATIONS delegations.
If the delegation amount is less than min_delegation_amount.
fun certify_delegation(managed_pool_address: address, delegator_address: address, amount: u64)
Implementation
fun certify_delegation(
    managed_pool_address: address,
    delegator_address: address,
    amount: u64
) acquires ManagedStakePool {
    if (delegator_address == managed_pool_address) {
        return
    };
    if (
        delegator_address ==
            delegation_state::get_protocol_delegator_address(
                managed_pool_address
            )
    ) {
        return
    };
​
    let managed_stake_pool = borrow_global<ManagedStakePool>(
        managed_pool_address
    );
    let is_current_delegator = delegation_state::is_an_active_delegator(
        managed_pool_address,
        delegator_address
    );
    if (is_current_delegator) {
        return
    };
​
    assert!(
        amount >= managed_stake_pool.min_delegation_amount,
        error::invalid_argument(EDELEGATION_AMOUNT_TOO_SMALL)
    );
​
    let current_length = delegation_state::get_total_length_of_share_maps(
        managed_pool_address
    );
    assert!(
        // this actually allows (MAX_NUMBER_OF_DELEGATIONS + 1) delegators,
        // including the owner
        current_length <= MAX_NUMBER_OF_DELEGATIONS,
        error::out_of_range(ETOO_MANY_DELEGATIONS)
    );
}
Function ensure_minimum_delegation_remaining
Ensures withdrawal does not change the delegator's stake below the minimum, unless a non-stake-pool-owner delegator is withdrawing all of their stake.
Abort conditions
If the non-owner delegator's stake would be non-zero but below the minimum after the withdrawal.
If the owner delegator's stake would be below the min_stake required by the aptos_framework after the withdrawal.
fun ensure_minimum_delegation_remaining(managed_pool_address: address, delegator_address: address, num_shares_to_withdraw: u64)
Implementation
fun ensure_minimum_delegation_remaining(
    managed_pool_address: address,
    delegator_address: address,
    num_shares_to_withdraw: u64
) acquires ManagedStakePool {
    // protocol is not subject to minimums
    if (
        delegator_address ==
            delegation_state::get_protocol_delegator_address(
                managed_pool_address
            )
    ) {
        return
    };
    // only called from `reserve_shares_to_withdraw`, pool existence is
    // ensured
    let managed_stake_pool = borrow_global<ManagedStakePool>(
        managed_pool_address
    );
    let current_unreserved_shares =
        delegation_state::get_unreserved_shares_with_delegator(
            managed_pool_address,
            delegator_address
        );
​
    if (
        delegator_address != managed_pool_address &&
            current_unreserved_shares == num_shares_to_withdraw
    ) {
        // Non-owner delegator can always withdraw all of their stake
        return
    };
​
    let remaining_balance_after_withdrawal =
        delegation_state::get_shares_to_value_unreserved(
            managed_pool_address,
            current_unreserved_shares - num_shares_to_withdraw
        );
​
    let minimum = if (delegator_address == managed_pool_address) {
        stake_pool_helpers::get_framework_min_stake()
    } else {
        managed_stake_pool.min_delegation_amount
    };
​
    assert!(
        remaining_balance_after_withdrawal >= minimum ||
            managed_stake_pool.in_self_destruct,
        error::invalid_argument(EMINIMUM_VIOLATION)
    );
}
delegation::delegation_state
tortuga::validator_router
Last modified 7mo ago