pool_address: address

equal to address of the resource account owning the stake pool

index: u64

active_shares: pool_u64_unbound::Pool

observed_lockup_cycle: delegation_pool::ObservedLockupCycle

inactive_shares: table::Table<delegation_pool::ObservedLockupCycle, pool_u64_unbound::Pool>

pending_withdrawals: table::Table<address, delegation_pool::ObservedLockupCycle>

stake_pool_signer_cap: account::SignerCapability

total_coins_inactive: u64

operator_commission_percentage: u64

add_stake_events: event::EventHandle<delegation_pool::AddStakeEvent>

reactivate_stake_events: event::EventHandle<delegation_pool::ReactivateStakeEvent>

unlock_stake_events: event::EventHandle<delegation_pool::UnlockStakeEvent>

withdraw_stake_events: event::EventHandle<delegation_pool::WithdrawStakeEvent>

distribute_commission_events: event::EventHandle<delegation_pool::DistributeCommissionEvent>

voter: address

proposal_id: u64

voter: address

pending_voter: address

last_locked_until_secs: u64

active_shares: u128

pending_inactive_shares: u128

active_shares_next_lockup: u128

last_locked_until_secs: u64

votes: smart_table::SmartTable<delegation_pool::VotingRecordKey, u64>

votes_per_proposal: smart_table::SmartTable<u64, u64>

vote_delegation: smart_table::SmartTable<address, delegation_pool::VoteDelegation>

delegated_votes: smart_table::SmartTable<address, delegation_pool::DelegatedVotes>

vote_events: event::EventHandle<delegation_pool::VoteEvent>

create_proposal_events: event::EventHandle<delegation_pool::CreateProposalEvent>

delegate_voting_power_events: event::EventHandle<delegation_pool::DelegateVotingPowerEvent>

beneficiary_for_operator: address

commission_percentage_next_lockup_cycle: u64

effective_after_secs: u64

allowlist: smart_table::SmartTable<address, bool>

pool_address: address

delegator_address: address

amount_added: u64

add_stake_fee: u64

pool_address: address

delegator_address: address

amount_added: u64

add_stake_fee: u64

pool_address: address

delegator_address: address

amount_reactivated: u64

pool_address: address

delegator_address: address

amount_reactivated: u64

pool_address: address

delegator_address: address

amount_unlocked: u64

pool_address: address

delegator_address: address

amount_unlocked: u64

pool_address: address

delegator_address: address

amount_withdrawn: u64

pool_address: address

delegator_address: address

amount_withdrawn: u64

pool_address: address

operator: address

commission_active: u64

commission_pending_inactive: u64

pool_address: address

operator: address

beneficiary: address

commission_active: u64

commission_pending_inactive: u64

voter: address

proposal_id: u64

delegation_pool: address

num_votes: u64

should_pass: bool

voter: address

proposal_id: u64

delegation_pool: address

num_votes: u64

should_pass: bool

proposal_id: u64

voter: address

delegation_pool: address

proposal_id: u64

voter: address

delegation_pool: address

pool_address: address

delegator: address

voter: address

pool_address: address

delegator: address

voter: address

operator: address

old_beneficiary: address

new_beneficiary: address

pool_address: address

owner: address

commission_percentage_next_lockup_cycle: u64

pool_address: address

pool_address: address

pool_address: address

delegator_address: address

pool_address: address

delegator_address: address

pool_address: address

delegator_address: address

public fun owner_cap_exists(addr: address): bool {
    exists<DelegationPoolOwnership>(addr)
}

public fun get_owned_pool_address(owner: address): address acquires DelegationPoolOwnership {
    assert_owner_cap_exists(owner);
    borrow_global<DelegationPoolOwnership>(owner).pool_address
}

public fun delegation_pool_exists(addr: address): bool {
    exists<DelegationPool>(addr)
}

public fun partial_governance_voting_enabled(pool_address: address): bool {
    exists<GovernanceRecords>(pool_address) && stake::get_delegated_voter(pool_address) == pool_address
}

public fun observed_lockup_cycle(pool_address: address): u64 acquires DelegationPool {
    assert_delegation_pool_exists(pool_address);
    borrow_global<DelegationPool>(pool_address).observed_lockup_cycle.index
}

public fun is_next_commission_percentage_effective(pool_address: address): bool acquires NextCommissionPercentage {
    exists<NextCommissionPercentage>(pool_address) &&
        timestamp::now_seconds() >= borrow_global<NextCommissionPercentage>(pool_address).effective_after_secs
}

public fun operator_commission_percentage(
    pool_address: address
): u64 acquires DelegationPool, NextCommissionPercentage {
    assert_delegation_pool_exists(pool_address);
    if (is_next_commission_percentage_effective(pool_address)) {
        operator_commission_percentage_next_lockup_cycle(pool_address)
    } else {
        borrow_global<DelegationPool>(pool_address).operator_commission_percentage
    }
}

public fun operator_commission_percentage_next_lockup_cycle(
    pool_address: address
): u64 acquires DelegationPool, NextCommissionPercentage {
    assert_delegation_pool_exists(pool_address);
    if (exists<NextCommissionPercentage>(pool_address)) {
        borrow_global<NextCommissionPercentage>(pool_address).commission_percentage_next_lockup_cycle
    } else {
        borrow_global<DelegationPool>(pool_address).operator_commission_percentage
    }
}

public fun shareholders_count_active_pool(pool_address: address): u64 acquires DelegationPool {
    assert_delegation_pool_exists(pool_address);
    borrow_global<DelegationPool>(pool_address).active_shares.shareholders_count()
}

public fun get_delegation_pool_stake(pool_address: address): (u64, u64, u64, u64) {
    assert_delegation_pool_exists(pool_address);
    stake::get_stake(pool_address)
}

public fun get_pending_withdrawal(
    pool_address: address,
    delegator_address: address
): (bool, u64) acquires DelegationPool {
    assert_delegation_pool_exists(pool_address);
    let pool = borrow_global<DelegationPool>(pool_address);
    let (
        lockup_cycle_ended,
        _,
        pending_inactive,
        _,
        commission_pending_inactive
    ) = calculate_stake_pool_drift(pool);

    let (withdrawal_exists, withdrawal_olc) = pending_withdrawal_exists(pool, delegator_address);
    if (!withdrawal_exists) {
        // if no pending withdrawal, there is neither inactive nor pending_inactive stake
        (false, 0)
    } else {
        // delegator has either inactive or pending_inactive stake due to automatic withdrawals
        let inactive_shares = pool.inactive_shares.borrow(withdrawal_olc);
        if (withdrawal_olc.index < pool.observed_lockup_cycle.index) {
            // if withdrawal's lockup cycle ended on delegation pool then it is inactive
            (true, inactive_shares.balance(delegator_address))
        } else {
            pending_inactive = inactive_shares.shares_to_amount_with_total_coins(inactive_shares.shares(delegator_address), pending_inactive - commission_pending_inactive);
            // if withdrawal's lockup cycle ended ONLY on stake pool then it is also inactive
            (lockup_cycle_ended, pending_inactive)
        }
    }
}

public fun get_stake(
    pool_address: address,
    delegator_address: address
): (u64, u64, u64) acquires DelegationPool, BeneficiaryForOperator {
    assert_delegation_pool_exists(pool_address);
    let pool = borrow_global<DelegationPool>(pool_address);
    let (
        lockup_cycle_ended,
        active,
        _,
        commission_active,
        commission_pending_inactive
    ) = calculate_stake_pool_drift(pool);

    let total_active_shares = pool.active_shares.total_shares();
    let delegator_active_shares = pool.active_shares.shares(delegator_address);

    let (_, _, pending_active, _) = stake::get_stake(pool_address);
    if (pending_active == 0) {
        // zero `pending_active` stake indicates that either there are no `add_stake` fees or
        // previous epoch has ended and should identify shares owning these fees as released
        total_active_shares -= pool.active_shares.shares(NULL_SHAREHOLDER);
        if (delegator_address == NULL_SHAREHOLDER) {
            delegator_active_shares = 0
        }
    };
    active = pool.active_shares.shares_to_amount_with_total_stats(delegator_active_shares, active - commission_active, total_active_shares);

    // get state and stake (0 if there is none) of the pending withdrawal
    let (withdrawal_inactive, withdrawal_stake) = get_pending_withdrawal(pool_address, delegator_address);
    // report non-active stakes accordingly to the state of the pending withdrawal
    let (inactive, pending_inactive) = if (withdrawal_inactive) (withdrawal_stake, 0) else (0, withdrawal_stake);

    // should also include commission rewards in case of the operator account
    // operator rewards are actually used to buy shares which is introducing
    // some imprecision (received stake would be slightly less)
    // but adding rewards onto the existing stake is still a good approximation
    if (delegator_address == beneficiary_for_operator(get_operator(pool_address))) {
        active += commission_active;
        // in-flight pending_inactive commission can coexist with already inactive withdrawal
        if (lockup_cycle_ended) {
            inactive += commission_pending_inactive
        } else {
            pending_inactive += commission_pending_inactive
        }
    };

    (active, inactive, pending_inactive)
}

public fun get_add_stake_fee(
    pool_address: address,
    amount: u64
): u64 acquires DelegationPool, NextCommissionPercentage {
    if (stake::is_current_epoch_validator(pool_address)) {
        let (rewards_rate, rewards_rate_denominator) = staking_config::get_reward_rate(&staking_config::get());
        if (rewards_rate_denominator > 0) {
            assert_delegation_pool_exists(pool_address);

            rewards_rate *= (MAX_FEE - operator_commission_percentage(pool_address));
            rewards_rate_denominator *= MAX_FEE;
            ((((amount as u128) * (rewards_rate as u128)) / ((rewards_rate as u128) + (rewards_rate_denominator as u128))) as u64)
        } else { 0 }
    } else { 0 }
}

public fun can_withdraw_pending_inactive(pool_address: address): bool {
    stake::get_validator_state(pool_address) == VALIDATOR_STATUS_INACTIVE &&
        timestamp::now_seconds() >= stake::get_lockup_secs(pool_address)
}

public fun calculate_and_update_voter_total_voting_power(
    pool_address: address,
    voter: address
): u64 acquires DelegationPool, GovernanceRecords, BeneficiaryForOperator, NextCommissionPercentage {
    assert_partial_governance_voting_enabled(pool_address);
    // Delegation pool need to be synced to explain rewards(which could change the coin amount) and
    // commission(which could cause share transfer).
    synchronize_delegation_pool(pool_address);
    let pool = borrow_global<DelegationPool>(pool_address);
    let governance_records = borrow_global_mut<GovernanceRecords>(pool_address);
    let latest_delegated_votes = update_and_borrow_mut_delegated_votes(pool, governance_records, voter);
    calculate_total_voting_power(pool, latest_delegated_votes)
}

public fun calculate_and_update_remaining_voting_power(
    pool_address: address,
    voter_address: address,
    proposal_id: u64
): u64 acquires DelegationPool, GovernanceRecords, BeneficiaryForOperator, NextCommissionPercentage {
    assert_partial_governance_voting_enabled(pool_address);
    // If the whole stake pool has no voting power(e.g. it has already voted before partial
    // governance voting flag is enabled), the delegator also has no voting power.
    if (aptos_governance::get_remaining_voting_power(pool_address, proposal_id) == 0) {
        return 0
    };

    let total_voting_power = calculate_and_update_voter_total_voting_power(pool_address, voter_address);
    let governance_records = borrow_global<GovernanceRecords>(pool_address);
    total_voting_power - get_used_voting_power(governance_records, voter_address, proposal_id)
}

public fun calculate_and_update_delegator_voter(
    pool_address: address,
    delegator_address: address
): address acquires DelegationPool, GovernanceRecords {
    assert_partial_governance_voting_enabled(pool_address);
    calculate_and_update_delegator_voter_internal(
        borrow_global<DelegationPool>(pool_address),
        borrow_global_mut<GovernanceRecords>(pool_address),
        delegator_address
    )
}

public fun calculate_and_update_voting_delegation(
    pool_address: address,
    delegator_address: address
): (address, address, u64) acquires DelegationPool, GovernanceRecords {
    assert_partial_governance_voting_enabled(pool_address);
    let vote_delegation = update_and_borrow_mut_delegator_vote_delegation(
        borrow_global<DelegationPool>(pool_address),
        borrow_global_mut<GovernanceRecords>(pool_address),
        delegator_address
    );

    (vote_delegation.voter, vote_delegation.pending_voter, vote_delegation.last_locked_until_secs)
}

public fun get_expected_stake_pool_address(owner: address, delegation_pool_creation_seed: vector<u8>
): address {
    let seed = create_resource_account_seed(delegation_pool_creation_seed);
    account::create_resource_address(&owner, seed)
}

public fun min_remaining_secs_for_commission_change(): u64 {
    let config = staking_config::get();
    staking_config::get_recurring_lockup_duration(&config) / 4
}

public fun allowlisting_enabled(pool_address: address): bool {
    assert_delegation_pool_exists(pool_address);
    exists<DelegationPoolAllowlisting>(pool_address)
}

public fun delegator_allowlisted(
    pool_address: address,
    delegator_address: address,
): bool acquires DelegationPoolAllowlisting {
    if (!allowlisting_enabled(pool_address)) { return true };
    freeze(borrow_mut_delegators_allowlist(pool_address)).contains(delegator_address)
}

public fun get_delegators_allowlist(
    pool_address: address,
): vector<address> acquires DelegationPoolAllowlisting {
    assert_allowlisting_enabled(pool_address);

    let allowlist = vector[];
    freeze(borrow_mut_delegators_allowlist(pool_address)).for_each_ref(|delegator, _v| {
        vector::push_back(&mut allowlist, *delegator);
    });
    allowlist
}

inline fun check_delegation_pool_management_permission(s: &signer) {
    assert!(
        permissioned_signer::check_permission_exists(s, DelegationPermission::DelegationPoolManagementPermission {}),
        error::permission_denied(ENO_DELEGATION_PERMISSION),
    );
}

public fun grant_delegation_pool_management_permission(master: &signer, permissioned_signer: &signer) {
    permissioned_signer::authorize_unlimited(master, permissioned_signer, DelegationPermission::DelegationPoolManagementPermission {})
}

inline fun check_stake_management_permission(s: &signer) {
    assert!(
        permissioned_signer::check_permission_exists(s, DelegationPermission::StakeManagementPermission {}),
        error::permission_denied(ENO_DELEGATION_PERMISSION),
    );
}

public fun grant_stake_management_permission(master: &signer, permissioned_signer: &signer) {
    permissioned_signer::authorize_unlimited(master, permissioned_signer, DelegationPermission::StakeManagementPermission {})
}

public entry fun initialize_delegation_pool(
    owner: &signer,
    operator_commission_percentage: u64,
    delegation_pool_creation_seed: vector<u8>,
) acquires DelegationPool, GovernanceRecords, BeneficiaryForOperator, NextCommissionPercentage {
    check_delegation_pool_management_permission(owner);
    let owner_address = signer::address_of(owner);
    assert!(!owner_cap_exists(owner_address), error::already_exists(EOWNER_CAP_ALREADY_EXISTS));
    assert!(operator_commission_percentage <= MAX_FEE, error::invalid_argument(EINVALID_COMMISSION_PERCENTAGE));

    // generate a seed to be used to create the resource account hosting the delegation pool
    let seed = create_resource_account_seed(delegation_pool_creation_seed);

    let (stake_pool_signer, stake_pool_signer_cap) = account::create_resource_account(owner, seed);
    coin::register<AptosCoin>(&stake_pool_signer);

    // stake_pool_signer will be owner of the stake pool and have its `stake::OwnerCapability`
    let pool_address = signer::address_of(&stake_pool_signer);
    stake::initialize_stake_owner(&stake_pool_signer, 0, owner_address, owner_address);

    let inactive_shares = table::new<ObservedLockupCycle, pool_u64::Pool>();
    inactive_shares.add(olc_with_index(0), pool_u64::create_with_scaling_factor(SHARES_SCALING_FACTOR));

    move_to(&stake_pool_signer, DelegationPool {
        active_shares: pool_u64::create_with_scaling_factor(SHARES_SCALING_FACTOR),
        observed_lockup_cycle: olc_with_index(0),
        inactive_shares,
        pending_withdrawals: table::new<address, ObservedLockupCycle>(),
        stake_pool_signer_cap,
        total_coins_inactive: 0,
        operator_commission_percentage,
        add_stake_events: account::new_event_handle<AddStakeEvent>(&stake_pool_signer),
        reactivate_stake_events: account::new_event_handle<ReactivateStakeEvent>(&stake_pool_signer),
        unlock_stake_events: account::new_event_handle<UnlockStakeEvent>(&stake_pool_signer),
        withdraw_stake_events: account::new_event_handle<WithdrawStakeEvent>(&stake_pool_signer),
        distribute_commission_events: account::new_event_handle<DistributeCommissionEvent>(&stake_pool_signer),
    });

    // save delegation pool ownership and resource account address (inner stake pool address) on `owner`
    move_to(owner, DelegationPoolOwnership { pool_address });

    // All delegation pool enable partial governance voting by default once the feature flag is enabled.
    enable_partial_governance_voting(pool_address);
}

public fun beneficiary_for_operator(operator: address): address acquires BeneficiaryForOperator {
    if (exists<BeneficiaryForOperator>(operator)) {
        return borrow_global<BeneficiaryForOperator>(operator).beneficiary_for_operator
    } else {
        operator
    }
}

public entry fun enable_partial_governance_voting(
    pool_address: address,
) acquires DelegationPool, GovernanceRecords, BeneficiaryForOperator, NextCommissionPercentage {
    assert_delegation_pool_exists(pool_address);
    // synchronize delegation and stake pools before any user operation.
    synchronize_delegation_pool(pool_address);

    let delegation_pool = borrow_global<DelegationPool>(pool_address);
    let stake_pool_signer = retrieve_stake_pool_owner(delegation_pool);
    // delegated_voter is managed by the stake pool itself, which signer capability is managed by DelegationPool.
    // So voting power of this stake pool can only be used through this module.
    stake::set_delegated_voter(&stake_pool_signer, signer::address_of(&stake_pool_signer));

    move_to(&stake_pool_signer, GovernanceRecords {
        votes: smart_table::new(),
        votes_per_proposal: smart_table::new(),
        vote_delegation: smart_table::new(),
        delegated_votes: smart_table::new(),
        vote_events: account::new_event_handle<VoteEvent>(&stake_pool_signer),
        create_proposal_events: account::new_event_handle<CreateProposalEvent>(&stake_pool_signer),
        delegate_voting_power_events: account::new_event_handle<DelegateVotingPowerEvent>(&stake_pool_signer),
    });
}

public entry fun vote(
    voter: &signer,
    pool_address: address,
    proposal_id: u64,
    voting_power: u64,
    should_pass: bool
) acquires DelegationPool, GovernanceRecords, BeneficiaryForOperator, NextCommissionPercentage {
    check_stake_management_permission(voter);
    assert_partial_governance_voting_enabled(pool_address);
    // synchronize delegation and stake pools before any user operation.
    synchronize_delegation_pool(pool_address);

    let voter_address = signer::address_of(voter);
    let remaining_voting_power = calculate_and_update_remaining_voting_power(
        pool_address,
        voter_address,
        proposal_id
    );
    if (voting_power > remaining_voting_power) {
        voting_power = remaining_voting_power;
    };
    aptos_governance::assert_proposal_expiration(pool_address, proposal_id);
    assert!(voting_power > 0, error::invalid_argument(ENO_VOTING_POWER));

    let governance_records = borrow_global_mut<GovernanceRecords>(pool_address);
    // Check a edge case during the transient period of enabling partial governance voting.
    assert_and_update_proposal_used_voting_power(governance_records, pool_address, proposal_id, voting_power);
    let used_voting_power = borrow_mut_used_voting_power(governance_records, voter_address, proposal_id);
    *used_voting_power += voting_power;

    let pool_signer = retrieve_stake_pool_owner(borrow_global<DelegationPool>(pool_address));
    aptos_governance::partial_vote(&pool_signer, pool_address, proposal_id, voting_power, should_pass);

    event::emit(
        Vote {
            voter: voter_address,
            proposal_id,
            delegation_pool: pool_address,
            num_votes: voting_power,
            should_pass,
        }
    );
}

public entry fun create_proposal(
    voter: &signer,
    pool_address: address,
    execution_hash: vector<u8>,
    metadata_location: vector<u8>,
    metadata_hash: vector<u8>,
    is_multi_step_proposal: bool,
) acquires DelegationPool, GovernanceRecords, BeneficiaryForOperator, NextCommissionPercentage {
    check_stake_management_permission(voter);
    assert_partial_governance_voting_enabled(pool_address);

    // synchronize delegation and stake pools before any user operation
    synchronize_delegation_pool(pool_address);

    let voter_addr = signer::address_of(voter);
    let pool = borrow_global<DelegationPool>(pool_address);
    let governance_records = borrow_global_mut<GovernanceRecords>(pool_address);
    let total_voting_power = calculate_and_update_delegated_votes(pool, governance_records, voter_addr);
    assert!(
        total_voting_power >= aptos_governance::get_required_proposer_stake(),
        error::invalid_argument(EINSUFFICIENT_PROPOSER_STAKE));
    let pool_signer = retrieve_stake_pool_owner(borrow_global<DelegationPool>(pool_address));
    let proposal_id = aptos_governance::create_proposal_v2_impl(
        &pool_signer,
        pool_address,
        execution_hash,
        metadata_location,
        metadata_hash,
        is_multi_step_proposal,
    );

    event::emit(
        CreateProposal {
            proposal_id,
            voter: voter_addr,
            delegation_pool: pool_address,
        }
    );
}

fun assert_owner_cap_exists(owner: address) {
    assert!(owner_cap_exists(owner), error::not_found(EOWNER_CAP_NOT_FOUND));
}

fun assert_delegation_pool_exists(pool_address: address) {
    assert!(delegation_pool_exists(pool_address), error::invalid_argument(EDELEGATION_POOL_DOES_NOT_EXIST));
}

fun assert_min_active_balance(pool: &DelegationPool, delegator_address: address) {
    let balance = pool.active_shares.balance(delegator_address);
    assert!(balance >= MIN_COINS_ON_SHARES_POOL, error::invalid_argument(EDELEGATOR_ACTIVE_BALANCE_TOO_LOW));
}

fun assert_min_pending_inactive_balance(pool: &DelegationPool, delegator_address: address) {
    let balance = pending_inactive_shares_pool(pool).balance(delegator_address);
    assert!(
        balance >= MIN_COINS_ON_SHARES_POOL,
        error::invalid_argument(EDELEGATOR_PENDING_INACTIVE_BALANCE_TOO_LOW)
    );
}

fun assert_partial_governance_voting_enabled(pool_address: address) {
    assert_delegation_pool_exists(pool_address);
    assert!(
        partial_governance_voting_enabled(pool_address),
        error::invalid_state(EPARTIAL_GOVERNANCE_VOTING_NOT_ENABLED)
    );
}

fun assert_allowlisting_enabled(pool_address: address) {
    assert!(allowlisting_enabled(pool_address), error::invalid_state(EDELEGATORS_ALLOWLISTING_NOT_ENABLED));
}

fun assert_delegator_allowlisted(
    pool_address: address,
    delegator_address: address,
) acquires DelegationPoolAllowlisting {
    assert!(
        delegator_allowlisted(pool_address, delegator_address),
        error::permission_denied(EDELEGATOR_NOT_ALLOWLISTED)
    );
}

fun coins_to_redeem_to_ensure_min_stake(
    src_shares_pool: &pool_u64::Pool,
    shareholder: address,
    amount: u64,
): u64 {
    // find how many coins would be redeemed if supplying `amount`
    let redeemed_coins = src_shares_pool.shares_to_amount(amount_to_shares_to_redeem(src_shares_pool, shareholder, amount));
    // if balance drops under threshold then redeem it entirely
    let src_balance = src_shares_pool.balance(shareholder);
    if (src_balance - redeemed_coins < MIN_COINS_ON_SHARES_POOL) {
        amount = src_balance;
    };
    amount
}

fun coins_to_transfer_to_ensure_min_stake(
    src_shares_pool: &pool_u64::Pool,
    dst_shares_pool: &pool_u64::Pool,
    shareholder: address,
    amount: u64,
): u64 {
    // find how many coins would be redeemed from source if supplying `amount`
    let redeemed_coins = src_shares_pool.shares_to_amount(amount_to_shares_to_redeem(src_shares_pool, shareholder, amount));
    // if balance on destination would be less than threshold then redeem difference to threshold
    let dst_balance = dst_shares_pool.balance(shareholder);
    if (dst_balance + redeemed_coins < MIN_COINS_ON_SHARES_POOL) {
        // `redeemed_coins` >= `amount` - 1 as redeem can lose at most 1 coin
        amount = MIN_COINS_ON_SHARES_POOL - dst_balance + 1;
    };
    // check if new `amount` drops balance on source under threshold and adjust
    coins_to_redeem_to_ensure_min_stake(src_shares_pool, shareholder, amount)
}

fun retrieve_stake_pool_owner(pool: &DelegationPool): signer {
    account::create_signer_with_capability(&pool.stake_pool_signer_cap)
}

fun get_pool_address(pool: &DelegationPool): address {
    account::get_signer_capability_address(&pool.stake_pool_signer_cap)
}

fun get_delegator_active_shares(pool: &DelegationPool, delegator: address): u128 {
    pool.active_shares.shares(delegator)
}

fun get_delegator_pending_inactive_shares(pool: &DelegationPool, delegator: address): u128 {
    pending_inactive_shares_pool(pool).shares(delegator)
}

fun get_used_voting_power(governance_records: &GovernanceRecords, voter: address, proposal_id: u64): u64 {
    let votes = &governance_records.votes;
    let key = VotingRecordKey {
        voter,
        proposal_id,
    };
    *votes.borrow_with_default(key, &0)
}

fun create_resource_account_seed(
    delegation_pool_creation_seed: vector<u8>,
): vector<u8> {
    let seed = vector::empty<u8>();
    // include module salt (before any subseeds) to avoid conflicts with other modules creating resource accounts
    seed.append(MODULE_SALT);
    // include an additional salt in case the same resource account has already been created
    seed.append(delegation_pool_creation_seed);
    seed
}

inline fun borrow_mut_used_voting_power(
    governance_records: &mut GovernanceRecords,
    voter: address,
    proposal_id: u64
): &mut u64 {
    let votes = &mut governance_records.votes;
    let key = VotingRecordKey {
        proposal_id,
        voter,
    };
    votes.borrow_mut_with_default(key, 0)
}

fun update_and_borrow_mut_delegator_vote_delegation(
    pool: &DelegationPool,
    governance_records: &mut GovernanceRecords,
    delegator: address
): &mut VoteDelegation {
    let pool_address = get_pool_address(pool);
    let locked_until_secs = stake::get_lockup_secs(pool_address);

    let vote_delegation_table = &mut governance_records.vote_delegation;
    // By default, a delegator's delegated voter is itself.
    // TODO: recycle storage when VoteDelegation equals to default value.
    if (!vote_delegation_table.contains(delegator)) {
        return vote_delegation_table.borrow_mut_with_default(delegator, VoteDelegation {
            voter: delegator,
            last_locked_until_secs: locked_until_secs,
            pending_voter: delegator,
        })
    };

    let vote_delegation = vote_delegation_table.borrow_mut(delegator);
    // A lockup period has passed since last time `vote_delegation` was updated. Pending voter takes effect.
    if (vote_delegation.last_locked_until_secs < locked_until_secs) {
        vote_delegation.voter = vote_delegation.pending_voter;
        vote_delegation.last_locked_until_secs = locked_until_secs;
    };
    vote_delegation
}

fun update_and_borrow_mut_delegated_votes(
    pool: &DelegationPool,
    governance_records: &mut GovernanceRecords,
    voter: address
): &mut DelegatedVotes {
    let pool_address = get_pool_address(pool);
    let locked_until_secs = stake::get_lockup_secs(pool_address);

    let delegated_votes_per_voter = &mut governance_records.delegated_votes;
    // By default, a delegator's voter is itself.
    // TODO: recycle storage when DelegatedVotes equals to default value.
    if (!delegated_votes_per_voter.contains(voter)) {
        let active_shares = get_delegator_active_shares(pool, voter);
        let inactive_shares = get_delegator_pending_inactive_shares(pool, voter);
        return delegated_votes_per_voter.borrow_mut_with_default(voter, DelegatedVotes {
            active_shares,
            pending_inactive_shares: inactive_shares,
            active_shares_next_lockup: active_shares,
            last_locked_until_secs: locked_until_secs,
        })
    };

    let delegated_votes = delegated_votes_per_voter.borrow_mut(voter);
    // A lockup period has passed since last time `delegated_votes` was updated. Pending voter takes effect.
    if (delegated_votes.last_locked_until_secs < locked_until_secs) {
        delegated_votes.active_shares = delegated_votes.active_shares_next_lockup;
        delegated_votes.pending_inactive_shares = 0;
        delegated_votes.last_locked_until_secs = locked_until_secs;
    };
    delegated_votes
}

fun olc_with_index(index: u64): ObservedLockupCycle {
    ObservedLockupCycle { index }
}

fun calculate_total_voting_power(delegation_pool: &DelegationPool, latest_delegated_votes: &DelegatedVotes): u64 {
    let active_amount = delegation_pool.active_shares.shares_to_amount(latest_delegated_votes.active_shares);
    let pending_inactive_amount = pending_inactive_shares_pool(delegation_pool).shares_to_amount(latest_delegated_votes.pending_inactive_shares);
    active_amount + pending_inactive_amount
}

fun calculate_and_update_delegator_voter_internal(
    pool: &DelegationPool,
    governance_records: &mut GovernanceRecords,
    delegator: address
): address {
    let vote_delegation = update_and_borrow_mut_delegator_vote_delegation(pool, governance_records, delegator);
    vote_delegation.voter
}

fun calculate_and_update_delegated_votes(
    pool: &DelegationPool,
    governance_records: &mut GovernanceRecords,
    voter: address
): u64 {
    let delegated_votes = update_and_borrow_mut_delegated_votes(pool, governance_records, voter);
    calculate_total_voting_power(pool, delegated_votes)
}

inline fun borrow_mut_delegators_allowlist(pool_address: address): &mut SmartTable<address, bool> {
    &mut borrow_global_mut<DelegationPoolAllowlisting>(pool_address).allowlist
}

public entry fun set_operator(
    owner: &signer,
    new_operator: address
) acquires DelegationPoolOwnership, DelegationPool, GovernanceRecords, BeneficiaryForOperator, NextCommissionPercentage {
    check_delegation_pool_management_permission(owner);
    let pool_address = get_owned_pool_address(signer::address_of(owner));
    // synchronize delegation and stake pools before any user operation
    // ensure the old operator is paid its uncommitted commission rewards
    synchronize_delegation_pool(pool_address);
    stake::set_operator(&retrieve_stake_pool_owner(borrow_global<DelegationPool>(pool_address)), new_operator);
}

public entry fun set_beneficiary_for_operator(
    operator: &signer,
    new_beneficiary: address
) acquires BeneficiaryForOperator {
    check_stake_management_permission(operator);
    // The beneficiay address of an operator is stored under the operator's address.
    // So, the operator does not need to be validated with respect to a staking pool.
    let operator_addr = signer::address_of(operator);
    let old_beneficiary = beneficiary_for_operator(operator_addr);
    if (exists<BeneficiaryForOperator>(operator_addr)) {
        borrow_global_mut<BeneficiaryForOperator>(operator_addr).beneficiary_for_operator = new_beneficiary;
    } else {
        move_to(operator, BeneficiaryForOperator { beneficiary_for_operator: new_beneficiary });
    };

    emit(SetBeneficiaryForOperator {
        operator: operator_addr,
        old_beneficiary,
        new_beneficiary,
    });
}

public entry fun update_commission_percentage(
    owner: &signer,
    new_commission_percentage: u64
) acquires DelegationPoolOwnership, DelegationPool, GovernanceRecords, BeneficiaryForOperator, NextCommissionPercentage {
    check_delegation_pool_management_permission(owner);
    assert!(new_commission_percentage <= MAX_FEE, error::invalid_argument(EINVALID_COMMISSION_PERCENTAGE));
    let owner_address = signer::address_of(owner);
    let pool_address = get_owned_pool_address(owner_address);
    assert!(
        operator_commission_percentage(pool_address) + MAX_COMMISSION_INCREASE >= new_commission_percentage,
        error::invalid_argument(ETOO_LARGE_COMMISSION_INCREASE)
    );
    assert!(
        stake::get_remaining_lockup_secs(pool_address) >= min_remaining_secs_for_commission_change(),
        error::invalid_state(ETOO_LATE_COMMISSION_CHANGE)
    );

    // synchronize delegation and stake pools before any user operation. this ensures:
    // (1) the operator is paid its uncommitted commission rewards with the old commission percentage, and
    // (2) any pending commission percentage change is applied before the new commission percentage is set.
    synchronize_delegation_pool(pool_address);

    if (exists<NextCommissionPercentage>(pool_address)) {
        let commission_percentage = borrow_global_mut<NextCommissionPercentage>(pool_address);
        commission_percentage.commission_percentage_next_lockup_cycle = new_commission_percentage;
        commission_percentage.effective_after_secs = stake::get_lockup_secs(pool_address);
    } else {
        let delegation_pool = borrow_global<DelegationPool>(pool_address);
        let pool_signer = account::create_signer_with_capability(&delegation_pool.stake_pool_signer_cap);
        move_to(&pool_signer, NextCommissionPercentage {
            commission_percentage_next_lockup_cycle: new_commission_percentage,
            effective_after_secs: stake::get_lockup_secs(pool_address),
        });
    };

    event::emit(CommissionPercentageChange {
        pool_address,
        owner: owner_address,
        commission_percentage_next_lockup_cycle: new_commission_percentage,
    });
}

public entry fun set_delegated_voter(
    _owner: &signer,
    _new_voter: address
) {
    abort ECAN_NO_LONGER_SET_DELEGATED_VOTER
}

public entry fun delegate_voting_power(
    delegator: &signer,
    pool_address: address,
    new_voter: address
) acquires DelegationPool, GovernanceRecords, BeneficiaryForOperator, NextCommissionPercentage {
    check_stake_management_permission(delegator);
    assert_partial_governance_voting_enabled(pool_address);

    // synchronize delegation and stake pools before any user operation
    synchronize_delegation_pool(pool_address);

    let delegator_address = signer::address_of(delegator);
    let delegation_pool = borrow_global<DelegationPool>(pool_address);
    let governance_records = borrow_global_mut<GovernanceRecords>(pool_address);
    let delegator_vote_delegation = update_and_borrow_mut_delegator_vote_delegation(
        delegation_pool,
        governance_records,
        delegator_address
    );
    let pending_voter: address = delegator_vote_delegation.pending_voter;

    // No need to update if the voter doesn't really change.
    if (pending_voter != new_voter) {
        delegator_vote_delegation.pending_voter = new_voter;
        let active_shares = get_delegator_active_shares(delegation_pool, delegator_address);
        // <active shares> of <pending voter of shareholder> -= <active_shares>
        // <active shares> of <new voter of shareholder> += <active_shares>
        let pending_delegated_votes = update_and_borrow_mut_delegated_votes(
            delegation_pool,
            governance_records,
            pending_voter
        );
        pending_delegated_votes.active_shares_next_lockup -= active_shares;

        let new_delegated_votes = update_and_borrow_mut_delegated_votes(
            delegation_pool,
            governance_records,
            new_voter
        );
        new_delegated_votes.active_shares_next_lockup += active_shares;
    };

    event::emit(DelegateVotingPower {
        pool_address,
        delegator: delegator_address,
        voter: new_voter,
    });
}

public entry fun enable_delegators_allowlisting(
    owner: &signer,
) acquires DelegationPoolOwnership, DelegationPool {
    check_delegation_pool_management_permission(owner);
    assert!(
        features::delegation_pool_allowlisting_enabled(),
        error::invalid_state(EDELEGATORS_ALLOWLISTING_NOT_SUPPORTED)
    );

    let pool_address = get_owned_pool_address(signer::address_of(owner));
    if (allowlisting_enabled(pool_address)) { return };

    let pool_signer = retrieve_stake_pool_owner(borrow_global<DelegationPool>(pool_address));
    move_to(&pool_signer, DelegationPoolAllowlisting { allowlist: smart_table::new<address, bool>() });

    event::emit(EnableDelegatorsAllowlisting { pool_address });
}

public entry fun disable_delegators_allowlisting(
    owner: &signer,
) acquires DelegationPoolOwnership, DelegationPoolAllowlisting {
    check_delegation_pool_management_permission(owner);
    let pool_address = get_owned_pool_address(signer::address_of(owner));
    assert_allowlisting_enabled(pool_address);

    let DelegationPoolAllowlisting { allowlist } = move_from<DelegationPoolAllowlisting>(pool_address);
    // if the allowlist becomes too large, the owner can always remove some delegators
    allowlist.destroy();

    event::emit(DisableDelegatorsAllowlisting { pool_address });
}

public entry fun allowlist_delegator(
    owner: &signer,
    delegator_address: address,
) acquires DelegationPoolOwnership, DelegationPoolAllowlisting {
    check_delegation_pool_management_permission(owner);
    let pool_address = get_owned_pool_address(signer::address_of(owner));
    assert_allowlisting_enabled(pool_address);

    if (delegator_allowlisted(pool_address, delegator_address)) { return };

    borrow_mut_delegators_allowlist(pool_address).add(delegator_address, true);

    event::emit(AllowlistDelegator { pool_address, delegator_address });
}

public entry fun remove_delegator_from_allowlist(
    owner: &signer,
    delegator_address: address,
) acquires DelegationPoolOwnership, DelegationPoolAllowlisting {
    check_delegation_pool_management_permission(owner);
    let pool_address = get_owned_pool_address(signer::address_of(owner));
    assert_allowlisting_enabled(pool_address);

    if (!delegator_allowlisted(pool_address, delegator_address)) { return };

    borrow_mut_delegators_allowlist(pool_address).remove(delegator_address);

    event::emit(RemoveDelegatorFromAllowlist { pool_address, delegator_address });
}

public entry fun evict_delegator(
    owner: &signer,
    delegator_address: address,
) acquires DelegationPoolOwnership, DelegationPool, GovernanceRecords, BeneficiaryForOperator, NextCommissionPercentage, DelegationPoolAllowlisting {
    check_delegation_pool_management_permission(owner);
    let pool_address = get_owned_pool_address(signer::address_of(owner));
    assert_allowlisting_enabled(pool_address);
    assert!(
        !delegator_allowlisted(pool_address, delegator_address),
        error::invalid_state(ECANNOT_EVICT_ALLOWLISTED_DELEGATOR)
    );

    // synchronize pool in order to query latest balance of delegator
    synchronize_delegation_pool(pool_address);

    let pool = borrow_global<DelegationPool>(pool_address);
    if (get_delegator_active_shares(pool, delegator_address) == 0) { return };

    unlock_internal(delegator_address, pool_address, pool.active_shares.balance(delegator_address));

    event::emit(EvictDelegator { pool_address, delegator_address });
}

public entry fun add_stake(
    delegator: &signer,
    pool_address: address,
    amount: u64
) acquires DelegationPool, GovernanceRecords, BeneficiaryForOperator, NextCommissionPercentage, DelegationPoolAllowlisting {
    check_stake_management_permission(delegator);
    // short-circuit if amount to add is 0 so no event is emitted
    if (amount == 0) { return };

    let delegator_address = signer::address_of(delegator);
    assert_delegator_allowlisted(pool_address, delegator_address);

    // synchronize delegation and stake pools before any user operation
    synchronize_delegation_pool(pool_address);

    // fee to be charged for adding `amount` stake on this delegation pool at this epoch
    let add_stake_fee = get_add_stake_fee(pool_address, amount);

    let pool = borrow_global_mut<DelegationPool>(pool_address);

    // stake the entire amount to the stake pool
    aptos_account::transfer(delegator, pool_address, amount);
    stake::add_stake(&retrieve_stake_pool_owner(pool), amount);

    // but buy shares for delegator just for the remaining amount after fee
    buy_in_active_shares(pool, delegator_address, amount - add_stake_fee);
    assert_min_active_balance(pool, delegator_address);

    // grant temporary ownership over `add_stake` fees to a separate shareholder in order to:
    // - not mistake them for rewards to pay the operator from
    // - distribute them together with the `active` rewards when this epoch ends
    // in order to appreciate all shares on the active pool atomically
    buy_in_active_shares(pool, NULL_SHAREHOLDER, add_stake_fee);

    event::emit(
        AddStake {
            pool_address,
            delegator_address,
            amount_added: amount,
            add_stake_fee,
        },
    );
}

public entry fun unlock(
    delegator: &signer,
    pool_address: address,
    amount: u64
) acquires DelegationPool, GovernanceRecords, BeneficiaryForOperator, NextCommissionPercentage {
    check_stake_management_permission(delegator);
    // short-circuit if amount to unlock is 0 so no event is emitted
    if (amount == 0) { return };

    // synchronize delegation and stake pools before any user operation
    synchronize_delegation_pool(pool_address);

    let delegator_address = signer::address_of(delegator);
    unlock_internal(delegator_address, pool_address, amount);
}

fun unlock_internal(
    delegator_address: address,
    pool_address: address,
    amount: u64
) acquires DelegationPool, GovernanceRecords {
    assert!(delegator_address != NULL_SHAREHOLDER, error::invalid_argument(ECANNOT_UNLOCK_NULL_SHAREHOLDER));

    // fail unlock of more stake than `active` on the stake pool
    let (active, _, _, _) = stake::get_stake(pool_address);
    assert!(amount <= active, error::invalid_argument(ENOT_ENOUGH_ACTIVE_STAKE_TO_UNLOCK));

    let pool = borrow_global_mut<DelegationPool>(pool_address);
    amount = coins_to_transfer_to_ensure_min_stake(
        &pool.active_shares,
        pending_inactive_shares_pool(pool),
        delegator_address,
        amount,
    );
    amount = redeem_active_shares(pool, delegator_address, amount);

    stake::unlock(&retrieve_stake_pool_owner(pool), amount);

    buy_in_pending_inactive_shares(pool, delegator_address, amount);
    assert_min_pending_inactive_balance(pool, delegator_address);

    event::emit(
        UnlockStake {
            pool_address,
            delegator_address,
            amount_unlocked: amount,
        },
    );
}

public entry fun reactivate_stake(
    delegator: &signer,
    pool_address: address,
    amount: u64
) acquires DelegationPool, GovernanceRecords, BeneficiaryForOperator, NextCommissionPercentage, DelegationPoolAllowlisting {
    check_stake_management_permission(delegator);
    // short-circuit if amount to reactivate is 0 so no event is emitted
    if (amount == 0) { return };

    let delegator_address = signer::address_of(delegator);
    assert_delegator_allowlisted(pool_address, delegator_address);

    // synchronize delegation and stake pools before any user operation
    synchronize_delegation_pool(pool_address);

    let pool = borrow_global_mut<DelegationPool>(pool_address);
    amount = coins_to_transfer_to_ensure_min_stake(
        pending_inactive_shares_pool(pool),
        &pool.active_shares,
        delegator_address,
        amount,
    );
    let observed_lockup_cycle = pool.observed_lockup_cycle;
    amount = redeem_inactive_shares(pool, delegator_address, amount, observed_lockup_cycle);

    stake::reactivate_stake(&retrieve_stake_pool_owner(pool), amount);

    buy_in_active_shares(pool, delegator_address, amount);
    assert_min_active_balance(pool, delegator_address);

    event::emit(
        ReactivateStake {
            pool_address,
            delegator_address,
            amount_reactivated: amount,
        },
    );
}

public entry fun withdraw(
    delegator: &signer,
    pool_address: address,
    amount: u64
) acquires DelegationPool, GovernanceRecords, BeneficiaryForOperator, NextCommissionPercentage {
    check_stake_management_permission(delegator);
    assert!(amount > 0, error::invalid_argument(EWITHDRAW_ZERO_STAKE));
    // synchronize delegation and stake pools before any user operation
    synchronize_delegation_pool(pool_address);
    withdraw_internal(borrow_global_mut<DelegationPool>(pool_address), signer::address_of(delegator), amount);
}

fun withdraw_internal(
    pool: &mut DelegationPool,
    delegator_address: address,
    amount: u64
) acquires GovernanceRecords {
    // TODO: recycle storage when a delegator fully exits the delegation pool.
    // short-circuit if amount to withdraw is 0 so no event is emitted
    if (amount == 0) { return };

    let pool_address = get_pool_address(pool);
    let (withdrawal_exists, withdrawal_olc) = pending_withdrawal_exists(pool, delegator_address);
    // exit if no withdrawal or (it is pending and cannot withdraw pending_inactive stake from stake pool)
    if (!(
        withdrawal_exists &&
            (withdrawal_olc.index < pool.observed_lockup_cycle.index || can_withdraw_pending_inactive(pool_address))
    )) { return };

    if (withdrawal_olc.index == pool.observed_lockup_cycle.index) {
        amount = coins_to_redeem_to_ensure_min_stake(
            pending_inactive_shares_pool(pool),
            delegator_address,
            amount,
        )
    };
    amount = redeem_inactive_shares(pool, delegator_address, amount, withdrawal_olc);

    let stake_pool_owner = &retrieve_stake_pool_owner(pool);
    // stake pool will inactivate entire pending_inactive stake at `stake::withdraw` to make it withdrawable
    // however, bypassing the inactivation of excess stake (inactivated but not withdrawn) ensures
    // the OLC is not advanced indefinitely on `unlock`-`withdraw` paired calls
    if (can_withdraw_pending_inactive(pool_address)) {
        // get excess stake before being entirely inactivated
        let (_, _, _, pending_inactive) = stake::get_stake(pool_address);
        if (withdrawal_olc.index == pool.observed_lockup_cycle.index) {
            // `amount` less excess if withdrawing pending_inactive stake
            pending_inactive -= amount
        };
        // escape excess stake from inactivation
        stake::reactivate_stake(stake_pool_owner, pending_inactive);
        stake::withdraw(stake_pool_owner, amount);
        // restore excess stake to the pending_inactive state
        stake::unlock(stake_pool_owner, pending_inactive);
    } else {
        // no excess stake if `stake::withdraw` does not inactivate at all
        stake::withdraw(stake_pool_owner, amount);
    };
    aptos_account::transfer(stake_pool_owner, delegator_address, amount);

    // commit withdrawal of possibly inactive stake to the `total_coins_inactive`
    // known by the delegation pool in order to not mistake it for slashing at next synchronization
    let (_, inactive, _, _) = stake::get_stake(pool_address);
    pool.total_coins_inactive = inactive;

    event::emit(
        WithdrawStake {
            pool_address,
            delegator_address,
            amount_withdrawn: amount,
        },
    );
}

fun pending_withdrawal_exists(pool: &DelegationPool, delegator_address: address): (bool, ObservedLockupCycle) {
    if (pool.pending_withdrawals.contains(delegator_address)) {
        (true, *pool.pending_withdrawals.borrow(delegator_address))
    } else {
        (false, olc_with_index(0))
    }
}

fun pending_inactive_shares_pool_mut(pool: &mut DelegationPool): &mut pool_u64::Pool {
    let observed_lockup_cycle = pool.observed_lockup_cycle;
    pool.inactive_shares.borrow_mut(observed_lockup_cycle)
}

fun pending_inactive_shares_pool(pool: &DelegationPool): &pool_u64::Pool {
    pool.inactive_shares.borrow(pool.observed_lockup_cycle)
}

fun execute_pending_withdrawal(pool: &mut DelegationPool, delegator_address: address) acquires GovernanceRecords {
    let (withdrawal_exists, withdrawal_olc) = pending_withdrawal_exists(pool, delegator_address);
    if (withdrawal_exists && withdrawal_olc.index < pool.observed_lockup_cycle.index) {
        withdraw_internal(pool, delegator_address, MAX_U64);
    }
}

fun buy_in_active_shares(
    pool: &mut DelegationPool,
    shareholder: address,
    coins_amount: u64,
): u128 acquires GovernanceRecords {
    let new_shares = pool.active_shares.amount_to_shares(coins_amount);
    // No need to buy 0 shares.
    if (new_shares == 0) { return 0 };

    // Always update governance records before any change to the shares pool.
    let pool_address = get_pool_address(pool);
    if (partial_governance_voting_enabled(pool_address)) {
        update_governance_records_for_buy_in_active_shares(pool, pool_address, new_shares, shareholder);
    };

    pool.active_shares.buy_in(shareholder, coins_amount);
    new_shares
}

fun buy_in_pending_inactive_shares(
    pool: &mut DelegationPool,
    shareholder: address,
    coins_amount: u64,
): u128 acquires GovernanceRecords {
    let new_shares = pending_inactive_shares_pool(pool).amount_to_shares(coins_amount);
    // never create a new pending withdrawal unless delegator owns some pending_inactive shares
    if (new_shares == 0) { return 0 };

    // Always update governance records before any change to the shares pool.
    let pool_address = get_pool_address(pool);
    if (partial_governance_voting_enabled(pool_address)) {
        update_governance_records_for_buy_in_pending_inactive_shares(pool, pool_address, new_shares, shareholder);
    };

    // cannot buy inactive shares, only pending_inactive at current lockup cycle
    pending_inactive_shares_pool_mut(pool).buy_in(shareholder, coins_amount);

    // execute the pending withdrawal if exists and is inactive before creating a new one
    execute_pending_withdrawal(pool, shareholder);

    // save observed lockup cycle for the new pending withdrawal
    let observed_lockup_cycle = pool.observed_lockup_cycle;
    assert!(*pool.pending_withdrawals.borrow_mut_with_default(shareholder, observed_lockup_cycle) == observed_lockup_cycle,
        error::invalid_state(EPENDING_WITHDRAWAL_EXISTS)
    );

    new_shares
}

fun amount_to_shares_to_redeem(
    shares_pool: &pool_u64::Pool,
    shareholder: address,
    coins_amount: u64,
): u128 {
    if (coins_amount >= shares_pool.balance(shareholder)) {
        // cap result at total shares of shareholder to pass `EINSUFFICIENT_SHARES` on subsequent redeem
        shares_pool.shares(shareholder)
    } else {
        shares_pool.amount_to_shares(coins_amount)
    }
}

fun redeem_active_shares(
    pool: &mut DelegationPool,
    shareholder: address,
    coins_amount: u64,
): u64 acquires GovernanceRecords {
    let shares_to_redeem = amount_to_shares_to_redeem(&pool.active_shares, shareholder, coins_amount);
    // silently exit if not a shareholder otherwise redeem would fail with `ESHAREHOLDER_NOT_FOUND`
    if (shares_to_redeem == 0) return 0;

    // Always update governance records before any change to the shares pool.
    let pool_address = get_pool_address(pool);
    if (partial_governance_voting_enabled(pool_address)) {
        update_governanace_records_for_redeem_active_shares(pool, pool_address, shares_to_redeem, shareholder);
    };

    pool.active_shares.redeem_shares(shareholder, shares_to_redeem)
}

fun redeem_inactive_shares(
    pool: &mut DelegationPool,
    shareholder: address,
    coins_amount: u64,
    lockup_cycle: ObservedLockupCycle,
): u64 acquires GovernanceRecords {
    let shares_to_redeem = amount_to_shares_to_redeem(
        pool.inactive_shares.borrow(lockup_cycle),
        shareholder,
        coins_amount);
    // silently exit if not a shareholder otherwise redeem would fail with `ESHAREHOLDER_NOT_FOUND`
    if (shares_to_redeem == 0) return 0;

    // Always update governance records before any change to the shares pool.
    let pool_address = get_pool_address(pool);
    // Only redeem shares from the pending_inactive pool at `lockup_cycle` == current OLC.
    if (partial_governance_voting_enabled(pool_address) && lockup_cycle.index == pool.observed_lockup_cycle.index) {
        update_governanace_records_for_redeem_pending_inactive_shares(
            pool,
            pool_address,
            shares_to_redeem,
            shareholder
        );
    };

    let inactive_shares = pool.inactive_shares.borrow_mut(lockup_cycle);
    // 1. reaching here means delegator owns inactive/pending_inactive shares at OLC `lockup_cycle`
    let redeemed_coins = inactive_shares.redeem_shares(shareholder, shares_to_redeem);

    // if entirely reactivated pending_inactive stake or withdrawn inactive one,
    // re-enable unlocking for delegator by deleting this pending withdrawal
    if (inactive_shares.shares(shareholder) == 0) {
        // 2. a delegator owns inactive/pending_inactive shares only at the OLC of its pending withdrawal
        // 1 & 2: the pending withdrawal itself has been emptied of shares and can be safely deleted
        pool.pending_withdrawals.remove(shareholder);
    };
    // destroy inactive shares pool of past OLC if all its stake has been withdrawn
    if (lockup_cycle.index < pool.observed_lockup_cycle.index && inactive_shares.total_coins() == 0) {
        pool.inactive_shares.remove(lockup_cycle).destroy_empty();
    };

    redeemed_coins
}

fun calculate_stake_pool_drift(pool: &DelegationPool): (bool, u64, u64, u64, u64) {
    let (active, inactive, pending_active, pending_inactive) = stake::get_stake(get_pool_address(pool));
    assert!(
        inactive >= pool.total_coins_inactive,
        error::invalid_state(ESLASHED_INACTIVE_STAKE_ON_PAST_OLC)
    );
    // determine whether a new lockup cycle has been ended on the stake pool and
    // inactivated SOME `pending_inactive` stake which should stop earning rewards now,
    // thus requiring separation of the `pending_inactive` stake on current observed lockup
    // and the future one on the newly started lockup
    let lockup_cycle_ended = inactive > pool.total_coins_inactive;

    // actual coins on stake pool belonging to the active shares pool
    active += pending_active;
    // actual coins on stake pool belonging to the shares pool hosting `pending_inactive` stake
    // at current observed lockup cycle, either pending: `pending_inactive` or already inactivated:
    if (lockup_cycle_ended) {
        // `inactive` on stake pool = any previous `inactive` stake +
        // any previous `pending_inactive` stake and its rewards (both inactivated)
        pending_inactive = inactive - pool.total_coins_inactive
    };

    // on stake-management operations, total coins on the internal shares pools and individual
    // stakes on the stake pool are updated simultaneously, thus the only stakes becoming
    // unsynced are rewards and slashes routed exclusively to/out the stake pool

    // operator `active` rewards not persisted yet to the active shares pool
    let pool_active = pool.active_shares.total_coins();
    let commission_active = if (active > pool_active) {
        math64::mul_div(active - pool_active, pool.operator_commission_percentage, MAX_FEE)
    } else {
        // handle any slashing applied to `active` stake
        0
    };
    // operator `pending_inactive` rewards not persisted yet to the pending_inactive shares pool
    let pool_pending_inactive = pending_inactive_shares_pool(pool).total_coins();
    let commission_pending_inactive = if (pending_inactive > pool_pending_inactive) {
        math64::mul_div(
            pending_inactive - pool_pending_inactive,
            pool.operator_commission_percentage,
            MAX_FEE
        )
    } else {
        // handle any slashing applied to `pending_inactive` stake
        0
    };

    (lockup_cycle_ended, active, pending_inactive, commission_active, commission_pending_inactive)
}

public entry fun synchronize_delegation_pool(
    pool_address: address
) acquires DelegationPool, GovernanceRecords, BeneficiaryForOperator, NextCommissionPercentage {
    assert_delegation_pool_exists(pool_address);
    let pool = borrow_global_mut<DelegationPool>(pool_address);
    let (
        lockup_cycle_ended,
        active,
        pending_inactive,
        commission_active,
        commission_pending_inactive
    ) = calculate_stake_pool_drift(pool);

    // zero `pending_active` stake indicates that either there are no `add_stake` fees or
    // previous epoch has ended and should release the shares owning the existing fees
    let (_, _, pending_active, _) = stake::get_stake(pool_address);
    if (pending_active == 0) {
        // renounce ownership over the `add_stake` fees by redeeming all shares of
        // the special shareholder, implicitly their equivalent coins, out of the active shares pool
        redeem_active_shares(pool, NULL_SHAREHOLDER, MAX_U64);
    };

    // distribute rewards remaining after commission, to delegators (to already existing shares)
    // before buying shares for the operator for its entire commission fee
    // otherwise, operator's new shares would additionally appreciate from rewards it does not own

    // update total coins accumulated by `active` + `pending_active` shares
    // redeemed `add_stake` fees are restored and distributed to the rest of the pool as rewards
    pool.active_shares.update_total_coins(active - commission_active);
    // update total coins accumulated by `pending_inactive` shares at current observed lockup cycle
    pending_inactive_shares_pool_mut(pool).update_total_coins(pending_inactive - commission_pending_inactive);

    // reward operator its commission out of uncommitted active rewards (`add_stake` fees already excluded)
    buy_in_active_shares(pool, beneficiary_for_operator(stake::get_operator(pool_address)), commission_active);
    // reward operator its commission out of uncommitted pending_inactive rewards
    buy_in_pending_inactive_shares(
        pool,
        beneficiary_for_operator(stake::get_operator(pool_address)),
        commission_pending_inactive
    );

    event::emit_event(
        &mut pool.distribute_commission_events,
        DistributeCommissionEvent {
            pool_address,
            operator: stake::get_operator(pool_address),
            commission_active,
            commission_pending_inactive,
        },
    );

    emit(DistributeCommission {
        pool_address,
        operator: stake::get_operator(pool_address),
        beneficiary: beneficiary_for_operator(stake::get_operator(pool_address)),
        commission_active,
        commission_pending_inactive,
    });

    // advance lockup cycle on delegation pool if already ended on stake pool (AND stake explicitly inactivated)
    if (lockup_cycle_ended) {
        // capture inactive coins over all ended lockup cycles (including this ending one)
        let (_, inactive, _, _) = stake::get_stake(pool_address);
        pool.total_coins_inactive = inactive;

        // advance lockup cycle on the delegation pool
        pool.observed_lockup_cycle.index += 1;
        // start new lockup cycle with a fresh shares pool for `pending_inactive` stake
        pool.inactive_shares.add(pool.observed_lockup_cycle, pool_u64::create_with_scaling_factor(SHARES_SCALING_FACTOR));
    };

    if (is_next_commission_percentage_effective(pool_address)) {
        pool.operator_commission_percentage = borrow_global<NextCommissionPercentage>(
            pool_address
        ).commission_percentage_next_lockup_cycle;
    }
}

inline fun assert_and_update_proposal_used_voting_power(
    governance_records: &mut GovernanceRecords, pool_address: address, proposal_id: u64, voting_power: u64
) {
    let stake_pool_remaining_voting_power = aptos_governance::get_remaining_voting_power(pool_address, proposal_id);
    let stake_pool_used_voting_power = aptos_governance::get_voting_power(
        pool_address
    ) - stake_pool_remaining_voting_power;
    let proposal_used_voting_power = governance_records.votes_per_proposal.borrow_mut_with_default(proposal_id, 0);
    // A edge case: Before enabling partial governance voting on a delegation pool, the delegation pool has
    // a voter which can vote with all voting power of this delegation pool. If the voter votes on a proposal after
    // partial governance voting flag is enabled, the delegation pool doesn't have enough voting power on this
    // proposal for all the delegators. To be fair, no one can vote on this proposal through this delegation pool.
    // To detect this case, check if the stake pool had used voting power not through delegation_pool module.
    assert!(
        stake_pool_used_voting_power == *proposal_used_voting_power,
        error::invalid_argument(EALREADY_VOTED_BEFORE_ENABLE_PARTIAL_VOTING)
    );
    *proposal_used_voting_power += voting_power;
}

fun update_governance_records_for_buy_in_active_shares(
    pool: &DelegationPool, pool_address: address, new_shares: u128, shareholder: address
) acquires GovernanceRecords {
    // <active shares> of <shareholder> += <new_shares> ---->
    // <active shares> of <current voter of shareholder> += <new_shares>
    // <active shares> of <next voter of shareholder> += <new_shares>
    let governance_records = borrow_global_mut<GovernanceRecords>(pool_address);
    let vote_delegation = update_and_borrow_mut_delegator_vote_delegation(pool, governance_records, shareholder);
    let current_voter = vote_delegation.voter;
    let pending_voter = vote_delegation.pending_voter;
    let current_delegated_votes =
        update_and_borrow_mut_delegated_votes(pool, governance_records, current_voter);
    current_delegated_votes.active_shares += new_shares;
    if (pending_voter == current_voter) {
        current_delegated_votes.active_shares_next_lockup += new_shares;
    } else {
        let pending_delegated_votes =
            update_and_borrow_mut_delegated_votes(pool, governance_records, pending_voter);
        pending_delegated_votes.active_shares_next_lockup += new_shares;
    };
}

fun update_governance_records_for_buy_in_pending_inactive_shares(
    pool: &DelegationPool, pool_address: address, new_shares: u128, shareholder: address
) acquires GovernanceRecords {
    // <pending inactive shares> of <shareholder> += <new_shares>   ---->
    // <pending inactive shares> of <current voter of shareholder> += <new_shares>
    // no impact on <pending inactive shares> of <next voter of shareholder>
    let governance_records = borrow_global_mut<GovernanceRecords>(pool_address);
    let current_voter = calculate_and_update_delegator_voter_internal(pool, governance_records, shareholder);
    let current_delegated_votes = update_and_borrow_mut_delegated_votes(pool, governance_records, current_voter);
    current_delegated_votes.pending_inactive_shares += new_shares;
}

fun update_governanace_records_for_redeem_active_shares(
    pool: &DelegationPool, pool_address: address, shares_to_redeem: u128, shareholder: address
) acquires GovernanceRecords {
    // <active shares> of <shareholder> -= <shares_to_redeem> ---->
    // <active shares> of <current voter of shareholder> -= <shares_to_redeem>
    // <active shares> of <next voter of shareholder> -= <shares_to_redeem>
    let governance_records = borrow_global_mut<GovernanceRecords>(pool_address);
    let vote_delegation = update_and_borrow_mut_delegator_vote_delegation(
        pool,
        governance_records,
        shareholder
    );
    let current_voter = vote_delegation.voter;
    let pending_voter = vote_delegation.pending_voter;
    let current_delegated_votes = update_and_borrow_mut_delegated_votes(pool, governance_records, current_voter);
    current_delegated_votes.active_shares -= shares_to_redeem;
    if (current_voter == pending_voter) {
        current_delegated_votes.active_shares_next_lockup -= shares_to_redeem;
    } else {
        let pending_delegated_votes =
            update_and_borrow_mut_delegated_votes(pool, governance_records, pending_voter);
        pending_delegated_votes.active_shares_next_lockup -= shares_to_redeem;
    };
}

fun update_governanace_records_for_redeem_pending_inactive_shares(
    pool: &DelegationPool, pool_address: address, shares_to_redeem: u128, shareholder: address
) acquires GovernanceRecords {
    // <pending inactive shares> of <shareholder> -= <shares_to_redeem>  ---->
    // <pending inactive shares> of <current voter of shareholder> -= <shares_to_redeem>
    // no impact on <pending inactive shares> of <next voter of shareholder>
    let governance_records = borrow_global_mut<GovernanceRecords>(pool_address);
    let current_voter = calculate_and_update_delegator_voter_internal(pool, governance_records, shareholder);
    let current_delegated_votes = update_and_borrow_mut_delegated_votes(pool, governance_records, current_voter);
    current_delegated_votes.pending_inactive_shares -= shares_to_redeem;
}

public fun multiply_then_divide(x: u64, y: u64, z: u64): u64 {
    math64::mul_div(x, y, z)
}