Comment on page
helpers::pool

Module 0xc0ded0c0::pool
module helpers::pool
A data structure to keep track of ownership in a shared pool of assets.
It handles:
1.buy_in and buy_out of shares for a specific address.
2.maintaining the cost basis (or commission_exempt_amount) of the shares for commission calculations.
3.minting extra shares to represent commission.
​module helpers::pool​
​Struct Pool​
​Constants​
​Function create_pool​
​Function destroy_empty​
​Abort conditions​
​Function is_shareholder​
​Function get_commission_exempt_amount​
​Function get_num_shares​
​Function share_supply​
​Function num_share_holders​
​Function buy_in​
​Function buy_out​
​Function remove_next_share_holder​
​Abort conditions​
​Usage notes​
​Function reset_pool​
​Abort conditions​
​Function pay_commission​
​Function calculate_owner_commission_shares_helper​
​Function calculate_commission_rebate_for_protocol​
​Function add_shares​
​Function remove_shares​
use 0x1::error;
use 0x1::option;
use 0xc0ded0c0::iterable_table_custom;
use 0xc0ded0c0::math;
Struct Pool
struct Pool has store
Fields
shares: iterable_table_custom::IterableTableCustom<address, u64>Mapping of address to number of shares they ownshare_supply: u64Total sharescommission_exempt_amount: u64Principal amount on which commission is calculated. Resets to total value of the pool after commission has been paid.
Constants
When the pool is not empty and a destroy/reset is attempted.
const EPOOL_IS_NOT_EMPTY: u64 = 1;
When a shareholder more shares than they own.
const ENOT_ENOUGH_SHARES: u64 = 0;
Function create_pool
Create a new pool.
public fun create_pool(): pool::Pool
Implementation
public fun create_pool(): Pool {
    Pool {
        shares: iterable_table_custom::new<address, u64>(),
        share_supply: 0,
        commission_exempt_amount: 0,
    }
}
Function destroy_empty
Destroy an empty pool, or destroy a pool with a single shareholder, the owner, remaining.
Abort conditions
If the pool is not empty.
public fun destroy_empty(pool: pool::Pool, owner_address: address, remove_owner_first: bool)
Implementation
public fun destroy_empty(
    pool: Pool,
    owner_address: address,
    remove_owner_first: bool
) {
    let share_supply = pool.share_supply;
    if (remove_owner_first) {
        // if the pool is not empty, the owner should be the only one left
        remove_shares(
            &mut pool,
            owner_address,
            share_supply,
        )
    };
​
    assert!(pool.share_supply == 0, error::invalid_state(EPOOL_IS_NOT_EMPTY));
    let Pool {
        shares: shares,
        share_supply: _,
        commission_exempt_amount: _,
    } = pool;
​
    iterable_table_custom::destroy_empty<address, u64>(shares);
}
Function is_shareholder
Returns whether the shareholder_in_question is in the pool. Because zero values are removed from the map, this means they must have non zero shares.
public fun is_shareholder(pool: &pool::Pool, shareholder_in_question: address): bool
Implementation
public fun is_shareholder(pool: &Pool, shareholder_in_question: address): bool {
    iterable_table_custom::contains(&pool.shares, shareholder_in_question)
}
Function get_commission_exempt_amount
Returns get_commission_exempt_amount of the pool.
public fun get_commission_exempt_amount(pool: &pool::Pool): u64
Implementation
public fun get_commission_exempt_amount(pool: &Pool): u64 {
    pool.commission_exempt_amount
}
Function get_num_shares
Returns number of shares for shareholder in the pool. Returns 0 if the shareholder does not exist.
public fun get_num_shares(pool: &pool::Pool, shareholder: address): u64
Implementation
public fun get_num_shares(pool: &Pool, shareholder: address): u64 {
    math::safe_get_from_iterable_table_custom(
        &pool.shares,
        shareholder,
    )
}
Function share_supply
Returns the total number of shares in the pool.
public fun share_supply(pool: &pool::Pool): u64
Implementation
public fun share_supply(pool: &Pool): u64 {
    pool.share_supply
}
Function num_share_holders
Returns the total number of shareholders in the pool.
public fun num_share_holders(pool: &pool::Pool): u64
Implementation
public fun num_share_holders(pool: &Pool): u64 {
    iterable_table_custom::length<address, u64>(&pool.shares)
}
Function buy_in
Add num_shares to shareholder in the pool. Increase commission_exempt_amount by amount, which the new shares are worth.
public fun buy_in(pool: &mut pool::Pool, shareholder: address, num_shares: u64, amount: u64)
Implementation
public fun buy_in(
    pool: &mut Pool,
    shareholder: address,
    num_shares: u64,
    amount: u64
) {
    add_shares(pool, shareholder, num_shares);
    let commission_exempt_amount = &mut pool.commission_exempt_amount;
    *commission_exempt_amount = *commission_exempt_amount + amount;
}
Function buy_out
Remove num_shares from shareholder in the pool. Decrease commission_exempt_amount by amount which removed shares are worth.
public fun buy_out(pool: &mut pool::Pool, shareholder: address, num_shares: u64, amount: u64)
Implementation
public fun buy_out(pool: &mut Pool, shareholder: address, num_shares: u64, amount: u64) {
    remove_shares(pool, shareholder, num_shares);
    let commission_exempt_amount = &mut pool.commission_exempt_amount;
    *commission_exempt_amount = *commission_exempt_amount - amount;
}
Function remove_next_share_holder
Removes the shareholder at the head of the iterable table in the pool. Returns the address of the removed shareholder and the number of shares removed.
Abort conditions
If the pool is empty, i.e., there are no shareholders.
Usage notes
This function is not safe. Only call it after checking there are shares to remove. This should only be used in a loop which removes all shareholders, together with reset_pool to set defaults at the end.
public fun remove_next_share_holder(pool: &mut pool::Pool): (address, u64)
Implementation
public fun remove_next_share_holder(pool: &mut Pool):(address, u64) {
    let key = iterable_table_custom::head_key<address, u64>(&pool.shares);
    let key_address = *option::borrow(&key);
    let (num_shares, _, _) = iterable_table_custom::remove_iter<address, u64>(
        &mut pool.shares,
        key_address,
    );
    (key_address, num_shares)
}
Function reset_pool
Reset share_supply and commission_exempt_amount to 0.
Abort conditions
If the pool has no shareholders.
public fun reset_pool(pool: &mut pool::Pool)
Implementation
public fun reset_pool(pool: &mut Pool) {
    assert!(
        iterable_table_custom::length<address, u64>(&pool.shares) == 0,
        EPOOL_IS_NOT_EMPTY
    );
    pool.commission_exempt_amount = 0;
    pool.share_supply = 0;
}
Function pay_commission
This dilutes the shares of all shareholders of the pool according to commission amount due, by minting new shares for the commission_recipient. It allows a special (lower) commission rate protocol_commission for the protocol_delegator_address, which gets some of the newly minted shares as a rebate. Returns the total new number of shares minted.
public fun pay_commission(pool: &mut pool::Pool, commission_recipient: address, new_total_balance: u64, commission: u64, protocol_commission: u64, commission_normalizer: u64, protocol_delegator_address: address): u64
Implementation
public fun pay_commission(
    pool: &mut Pool,
    commission_recipient: address,
    new_total_balance: u64,
    commission: u64,
    protocol_commission: u64,
    commission_normalizer: u64,
    protocol_delegator_address: address,
): u64 {
    // short circuit if no commission is due
    if (
        new_total_balance == pool.commission_exempt_amount ||
            commission == 0
    ) {
        return 0
    };
​
    // compute the new shares for commission recipient and potential rebate
    // for protocol delegator
    let (
        new_shares_for_owner,
        protocol_delegator_shares,
        total_owner_commission
    ) = calculate_owner_commission_shares_helper(
        pool.share_supply,
        new_total_balance,
        pool.commission_exempt_amount,
        commission,
        protocol_commission,
        commission_normalizer,
        get_num_shares(pool, protocol_delegator_address),
    );
​
    add_shares(pool, protocol_delegator_address, protocol_delegator_shares);
    add_shares(pool, commission_recipient, new_shares_for_owner);
​
    // reset exempt amount as we've already paid commissions
    let commission_exempt_amount = &mut pool.commission_exempt_amount;
    *commission_exempt_amount = new_total_balance;
​
    total_owner_commission
}
Function calculate_owner_commission_shares_helper
Returns the news shares for commission_recipient, for protocol_delegator, and the total value of the new shares minted.
fun calculate_owner_commission_shares_helper(share_supply: u64, total_balance: u64, commission_exempt: u64, current_commission: u64, protocol_commission: u64, commission_normalizer: u64, protocol_delegator_existing_shares: u64): (u64, u64, u64)
Implementation
fun calculate_owner_commission_shares_helper(
    share_supply: u64,
    total_balance: u64,
    commission_exempt: u64,
    current_commission: u64,
    protocol_commission: u64,
    commission_normalizer: u64,
    protocol_delegator_existing_shares: u64,
): (u64, u64, u64) {
    if (share_supply == 0) {
        return (0, 0, 0)
    };
​
    let total_generated = total_balance - commission_exempt;
    // Amount owed as commission
    let total_owner_commission = math::mul_div(
        total_generated,
        current_commission,
        commission_normalizer,
    );
    let total_worth_after_commission =
        total_balance - total_owner_commission;
​
    if (total_owner_commission == 0) {
        return (0, 0, 0)
    };
​
    assert!(
        commission_exempt > 0 &&
            total_worth_after_commission >= commission_exempt,
        error::invalid_state(0)
    );
​
    // Existing shares are now worth:
    //  (total_worth_after_commission / share_supply)
    // Shares are minted at that price for the amount of
    // `total_owner_commission`
    let new_shares_for_owner = math::mul_div(
        total_owner_commission,
        share_supply,
        total_worth_after_commission,
    );
​
    // rebate for the protocol delegator
    let rebate_shares = calculate_commission_rebate_for_protocol(
        protocol_delegator_existing_shares,
        new_shares_for_owner,
        share_supply,
        current_commission,
        protocol_commission,
    );
​
    (
        new_shares_for_owner - rebate_shares,
        rebate_shares,
        total_owner_commission,
    )
}
Function calculate_commission_rebate_for_protocol
Returns the rebate shares for the protocol delegator. This is calculated separately because the protocol might have a lower commission rate than the default commission rate charged to other delegators.
fun calculate_commission_rebate_for_protocol(protocol_delegator_existing_shares: u64, new_shares_for_owner: u64, share_supply: u64, current_commission: u64, protocol_commission: u64): u64
Implementation
fun calculate_commission_rebate_for_protocol(
    protocol_delegator_existing_shares: u64,
    new_shares_for_owner: u64,
    share_supply: u64,
    current_commission: u64,
    protocol_commission: u64,
): u64 {
​
    if (
        protocol_delegator_existing_shares > 0 &&
            current_commission > 0 &&
            protocol_commission < current_commission
    ) {
        // how many of the shares belong to protocol if the protocol
        // commission was zero
        let new_shares_for_protocol = math::mul_div(
            new_shares_for_owner,
            protocol_delegator_existing_shares,
            share_supply,
        );
        // percentage rebate for protocol
        return math::mul_div(
            new_shares_for_protocol,
            (current_commission - protocol_commission),
            current_commission,
        )
    };
​
    0
}
Function add_shares
Add num_shares for shareholder in the pool and increase the share supply
fun add_shares(pool: &mut pool::Pool, shareholder: address, num_shares: u64)
Implementation
fun add_shares(pool: &mut Pool, shareholder: address, num_shares: u64) {
    math::safe_add_to_iterable_table_custom(
        &mut pool.shares,
        shareholder,
        num_shares,
    );
    let share_supply = &mut pool.share_supply;
    *share_supply = *share_supply + num_shares;
}
Function remove_shares
Remove num_shares from the pool and decrease the share supply. If a shareholders ends up with 0 shares, remove their entry from the table.
fun remove_shares(pool: &mut pool::Pool, shareholder: address, num_shares: u64)
Implementation
fun remove_shares(pool: &mut Pool, shareholder: address, num_shares: u64) {
    assert!(
        get_num_shares(pool, shareholder) >= num_shares,
        ENOT_ENOUGH_SHARES
    );
​
    math::subtract_from_iterable_table_custom(
        &mut pool.shares,
        shareholder,
        num_shares,
    );
    let share_supply = &mut pool.share_supply;
    *share_supply = *share_supply - num_shares;
}
helpers::math
helpers::stake_pool_helpers
Last modified 1yr ago
helpers::pool

Module `0xc0ded0c0::pool`

module `helpers::pool`

Struct `Pool`

Constants

Function `create_pool`

Function `destroy_empty`

Abort conditions

Function `is_shareholder`

Function `get_commission_exempt_amount`

Function `get_num_shares`

Function `share_supply`

Function `num_share_holders`

Function `buy_in`

Function `buy_out`

Function `remove_next_share_holder`

Abort conditions

Usage notes

Function `reset_pool`

Abort conditions

Function `pay_commission`

Function `calculate_owner_commission_shares_helper`

Function `calculate_commission_rebate_for_protocol`

Function `add_shares`

Function `remove_shares`
