Module `0xc0deb00c::incentives`

Incentive-associated parameters and data structures.

Contains hard-coded "genesis parameters" that are are set upon module publication per init_module(), and which can be updated later per set_incentive_parameters().

General overview sections

Incentive model

Functions

View functions
Public getters
Other public functions
Public entry functions
Public friend functions

Dependency charts

Incentive parameters setters
Econia fee account operations
Registrant operations
Integrator operations
Match operations

Complete DocGen index

Incentive model

As a permissionless system, Econia mitigates denial-of-service (DoS) attacks by charging utility coins for assorted operations. Econia also charges taker fees, denominated in the quote coin for a given market, which are distributed between integrators and Econia. The share of taker fees distributed between an integrator and Econia, for a given market, is determined by the "tier" to which the integrator has "activated" their fee store: when the matching engine fills a taker order, the integrator who facilitated the transaction has a portion of taker fees deposited to their fee store, and Econia gets the rest, with the split thereof determined by the integrator's fee store tier for the given market. Econia does not charge maker fees.

Hence Econia involves 5 major incentive parameters, defined at IncentiveParameters:

The utility coin type.
The fee, denominated in the utility coin, to register a market.
The fee, denominated in the utility coin, to register as an underwriter for a generic market.
The fee, denominated in the utility coin, to register as custodian.
The taker fee divisor, denoting the portion of quote coins for a particular trade, paid by the taker, to be split between the integrator who facilitated the trade, and Econia.

IncentiveParameters also includes a vector of IntegratorFeeStoreTierParameters, which define 3 parameters per tier:

The taker fee divisor, denoting the portion of quote coins for a particular trade, paid by the taker, to be collected by an integrator whose fee store is activated to the given tier.
The cumulative fee, denominated in the utility coin, to activate to the given tier.
The fee, denominated in the utility coin, to withdraw quote coins collected as fees, from an integrator's fee store.

Upon module publication, the Econia "genesis parameters" are set according to hard-coded values via init_module(). Later, the parameters can be updated via set_incentive_parameters(), so long as the number of tiers is not reduced and other minor restrictions are met. For an implementation-exact description of restrictions and corresponding abort codes, see:

set_incentive_parameters()
set_incentive_parameters_range_check_inputs()
set_incentive_parameters_parse_tiers_vector()

Functions

View functions

get_cost_to_upgrade_integrator_fee_store_view()
get_custodian_registration_fee()
get_fee_share_divisor()
get_integrator_withdrawal_fee_view()
get_market_registration_fee()
get_n_fee_store_tiers()
get_taker_fee_divisor()
get_tier_activation_fee()
get_tier_withdrawal_fee()
get_underwriter_registration_fee()
is_utility_coin_type()

Public getters

get_cost_to_upgrade_integrator_fee_store()
get_integrator_withdrawal_fee()
verify_utility_coin_type()

Other public functions

upgrade_integrator_fee_store()
withdraw_econia_fees()
withdraw_econia_fees_all()
withdraw_integrator_fees()
withdraw_utility_coins()
withdraw_utility_coins_all()

Public entry functions

update_incentives()
upgrade_integrator_fee_store_via_coinstore()
withdraw_econia_fees_all_to_coin_store()
withdraw_econia_fees_to_coin_store()
withdraw_integrator_fees_via_coinstores()
withdraw_utility_coins_all_to_coin_store()
withdraw_utility_coins_to_coin_store()

Public friend functions

assess_taker_fees()
calculate_max_quote_match()
deposit_custodian_registration_utility_coins()
deposit_market_registration_utility_coins()
deposit_underwriter_registration_utility_coins()
register_econia_fee_store_entry()
register_integrator_fee_store()

Dependency charts

The below dependency charts use mermaid.js syntax, which can be automatically rendered into a diagram (depending on the browser) when viewing the documentation file generated from source code. If a browser renders the diagrams with coloring that makes it difficult to read, try a different browser.

Incentive parameter setters

flowchart LR

update_incentives --> set_incentive_parameters
init_module --> set_incentive_parameters
set_incentive_parameters -->
set_incentive_parameters_parse_tiers_vector
set_incentive_parameters --> resource_account::get_signer
set_incentive_parameters -->
set_incentive_parameters_range_check_inputs
set_incentive_parameters --> init_utility_coin_store
set_incentive_parameters --> get_n_fee_store_tiers

Loading

Econia fee account operations

flowchart LR

deposit_utility_coins --> resource_account::get_address
deposit_utility_coins --> range_check_coin_merge
deposit_utility_coins_verified --> verify_utility_coin_type
deposit_utility_coins_verified --> deposit_utility_coins
withdraw_utility_coins --> withdraw_utility_coins_internal
withdraw_utility_coins_all --> withdraw_utility_coins_internal
withdraw_utility_coins_all_to_coin_store -->
withdraw_utility_coins_to_coin_store_internal
withdraw_utility_coins_to_coin_store -->
withdraw_utility_coins_to_coin_store_internal
withdraw_utility_coins_to_coin_store_internal -->
withdraw_utility_coins_internal
withdraw_utility_coins_internal --> resource_account::get_address
withdraw_econia_fees --> withdraw_econia_fees_internal
withdraw_econia_fees_all --> withdraw_econia_fees_internal
withdraw_econia_fees_internal --> resource_account::get_address
withdraw_econia_fees_all_to_coin_store -->
withdraw_econia_fees_to_coin_store_internal
withdraw_econia_fees_to_coin_store -->
withdraw_econia_fees_to_coin_store_internal
withdraw_econia_fees_to_coin_store_internal -->
withdraw_econia_fees_internal
register_econia_fee_store_entry --> resource_account::get_signer

Loading

Registrant operations

flowchart LR

deposit_custodian_registration_utility_coins -->
get_custodian_registration_fee
deposit_custodian_registration_utility_coins -->
deposit_utility_coins_verified
deposit_underwriter_registration_utility_coins -->
get_underwriter_registration_fee
deposit_underwriter_registration_utility_coins --->
deposit_utility_coins_verified
deposit_market_registration_utility_coins -->
deposit_utility_coins_verified
deposit_market_registration_utility_coins -->
get_market_registration_fee

Loading

Integrator operations

flowchart LR

withdraw_integrator_fees_via_coinstores -->
get_integrator_withdrawal_fee
get_integrator_withdrawal_fee --> get_tier_withdrawal_fee
withdraw_integrator_fees_via_coinstores --> withdraw_integrator_fees
withdraw_integrator_fees --> get_tier_withdrawal_fee
withdraw_integrator_fees --> deposit_utility_coins_verified
register_integrator_fee_store ---> deposit_utility_coins_verified
register_integrator_fee_store --> get_tier_activation_fee
upgrade_integrator_fee_store_via_coinstore -->
upgrade_integrator_fee_store
upgrade_integrator_fee_store_via_coinstore -->
get_cost_to_upgrade_integrator_fee_store
upgrade_integrator_fee_store --> deposit_utility_coins_verified
upgrade_integrator_fee_store -->
get_cost_to_upgrade_integrator_fee_store
get_cost_to_upgrade_integrator_fee_store -->
get_cost_to_upgrade_integrator_fee_store_view
get_integrator_withdrawal_fee --> get_integrator_withdrawal_fee_view

Loading

Match operations

flowchart LR

assess_taker_fees --> get_fee_share_divisor
assess_taker_fees --> get_taker_fee_divisor
assess_taker_fees --> resource_account::get_address
assess_taker_fees --> range_check_coin_merge

Loading

Complete DocGen index

The below index is automatically generated from source code:

General overview sections
Incentive model
Functions
- View functions
- Public getters
- Other public functions
- Public entry functions
- Public friend functions
Dependency charts
- Incentive parameter setters
- Econia fee account operations
- Registrant operations
- Integrator operations
- Match operations
Complete DocGen index
Resource EconiaFeeStore
Resource IncentiveParameters
Struct IntegratorFeeStore
Resource IntegratorFeeStores
Struct IntegratorFeeStoreTierParameters
Resource UtilityCoinStore
Constants
Function get_cost_to_upgrade_integrator_fee_store_view
- Type parameters
- Parameters
- Returns
- Aborts
- Restrictions
- Testing
Function get_custodian_registration_fee
- Testing
Function get_fee_share_divisor
- Testing
Function get_integrator_withdrawal_fee_view
- Restrictions
Function get_market_registration_fee
- Testing
Function get_n_fee_store_tiers
- Testing
Function get_taker_fee_divisor
- Testing
Function get_tier_activation_fee
- Testing
Function get_tier_withdrawal_fee
- Testing
Function get_underwriter_registration_fee
- Testing
Function is_utility_coin_type
- Testing
Function get_cost_to_upgrade_integrator_fee_store
- Testing
Function get_integrator_withdrawal_fee
Function upgrade_integrator_fee_store
- Type parameters
- Parameters
Function verify_utility_coin_type
- Aborts
- Testing
Function withdraw_econia_fees
Function withdraw_econia_fees_all
Function withdraw_integrator_fees
- Type parameters
- Parameters
- Returns
Function withdraw_utility_coins
- Testing
Function withdraw_utility_coins_all
- Testing
Function update_incentives
- Testing
Function upgrade_integrator_fee_store_via_coinstore
- Testing
Function withdraw_econia_fees_all_to_coin_store
- Testing
Function withdraw_econia_fees_to_coin_store
- Testing
Function withdraw_integrator_fees_via_coinstores
- Type parameters
- Parameters
Function withdraw_utility_coins_all_to_coin_store
- Testing
Function withdraw_utility_coins_to_coin_store
- Testing
Function assess_taker_fees
- Type parameters
- Parameters
- Returns
- Aborts
- Assumptions
Function calculate_max_quote_match
- Example buy
- Example sell
- Variables
- Equations
  - Buy
  - Sell
- Overflow correction
- Parameters
- Returns
- Assumptions
- Testing
Function deposit_custodian_registration_utility_coins
- Testing
Function deposit_market_registration_utility_coins
- Testing
Function deposit_underwriter_registration_utility_coins
- Testing
Function register_econia_fee_store_entry
Function register_integrator_fee_store
- Type parameters
- Parameters
Function deposit_utility_coins
- Aborts
- Testing
Function deposit_utility_coins_verified
- Aborts
- Testing
Function init_module
- Testing
Function init_utility_coin_store
- Type Parameters
- Parameters
- Aborts
- Testing
Function range_check_coin_merge
- Aborts
- Testing
Function set_incentive_parameters
- Type Parameters
- Parameters
- Assumptions
- Aborts
Function set_incentive_parameters_parse_tiers_vector
- Aborts
- Assumptions
- Testing
Function set_incentive_parameters_range_check_inputs
- Parameters
- Aborts
- Testing
Function withdraw_econia_fees_internal
- Aborts
Function withdraw_econia_fees_to_coin_store_internal
- Testing
Function withdraw_utility_coins_internal
- Aborts
Function withdraw_utility_coins_to_coin_store_internal
- Testing

use 0x1::aptos_coin;
use 0x1::coin;
use 0x1::signer;
use 0x1::type_info;
use 0x1::vector;
use 0xc0deb00c::resource_account;
use 0xc0deb00c::tablist;

Show all the modules that "incentives" depends on directly or indirectly

Show all the modules that depend on "incentives" directly or indirectly

Resource `EconiaFeeStore`

Portion of taker fees not claimed by an integrator, which are reserved for Econia.

struct EconiaFeeStore<QuoteCoinType> has key

Fields

map: tablist::Tablist<u64, coin::Coin<QuoteCoinType>>: Map from market ID to fees collected for given market, enabling duplicate checks and iterable indexing.

Resource `IncentiveParameters`

Incentive parameters for assorted operations.

struct IncentiveParameters has drop, key

Fields

utility_coin_type_info: type_info::TypeInfo: Utility coin type info. Corresponds to the phantom CoinType (address:module::MyCoin rather than aptos_framework::coin::Coin<address:module::MyCoin>) of the coin required for utility purposes. Set to APT at mainnet launch, later the Econia coin.
market_registration_fee: u64: Coin.value required to register a market.
underwriter_registration_fee: u64: Coin.value required to register as an underwriter.
custodian_registration_fee: u64: Coin.value required to register as a custodian.
taker_fee_divisor: u64: Nominal amount divisor for quote coin fee charged to takers. For example, if a transaction involves a quote coin fill of 1000000 units and the taker fee divisor is 2000, takers pay 1/2000th (0.05%) of the nominal amount (500 quote coin units) in fees. Instituted as a divisor for optimized calculations.
integrator_fee_store_tiers: vector<incentives::IntegratorFeeStoreTierParameters>: 0-indexed list from tier number to corresponding parameters.

Struct `IntegratorFeeStore`

Fee store for a given integrator, on a given market.

struct IntegratorFeeStore<QuoteCoinType> has store

Fields

tier: u8: Activation tier, incremented by paying utility coins.
coins: coin::Coin<QuoteCoinType>: Collected fees, in quote coins for given market.

Resource `IntegratorFeeStores`

All of an integrator's IntegratorFeeStores for given QuoteCoinType.

struct IntegratorFeeStores<QuoteCoinType> has key

Fields

map: tablist::Tablist<u64, incentives::IntegratorFeeStore<QuoteCoinType>>: Map from market ID to IntegratorFeeStore, enabling duplicate checks and iterable indexing.

Struct `IntegratorFeeStoreTierParameters`

Integrator fee store tier parameters for a given tier.

struct IntegratorFeeStoreTierParameters has drop, store

Fields

fee_share_divisor: u64: Nominal amount divisor for taker quote coin fee reserved for integrators having activated their fee store to the given tier. For example, if a transaction involves a quote coin fill of 1000000 units and the fee share divisor at the given tier is 4000, integrators get 1/4000th (0.025%) of the nominal amount (250 quote coin units) in fees at the given tier. Instituted as a divisor for optimized calculations. May not be larger than the IncentiveParameters.taker_fee_divisor, since the integrator fee share is deducted from the taker fee (with the remaining proceeds going to an EconiaFeeStore for the given market).
tier_activation_fee: u64: Cumulative cost, in utility coin units, to activate to the current tier. For example, if an integrator has already activated to tier 3, which has a tier activation fee of 1000 units, and tier 4 has a tier activation fee of 10000 units, the integrator only has to pay 9000 units to activate to tier 4.
withdrawal_fee: u64: Cost, in utility coin units, to withdraw from an integrator fee store. Shall never be nonzero, since a disincentive is required to prevent excessively-frequent withdrawals and thus transaction collisions with the matching engine.

Resource `UtilityCoinStore`

Container for utility coin fees collected by Econia.

struct UtilityCoinStore<CoinType> has key

Fields

coins: coin::Coin<CoinType>: Coins collected as utility fees.

Constants

Caller is not Econia, but should be.

const E_NOT_ECONIA: u64 = 0;

u64 bitmask with all bits set, generated in Python via hex(int('1' * 64, 2)).

const HI_64: u64 = 18446744073709551615;

Buy direction flag, as defined in market.move.

const BUY: bool = false;

Genesis parameter.

const CUSTODIAN_REGISTRATION_FEE: u64 = 81967;

The indicated tier activation fee is too small.

const E_ACTIVATION_FEE_TOO_SMALL: u64 = 9;

Custodian registration fee is less than the minimum.

const E_CUSTODIAN_REGISTRATION_FEE_LESS_THAN_MIN: u64 = 6;

Depositing to an Econia fee store would result in an overflow.

const E_ECONIA_FEE_STORE_OVERFLOW: u64 = 20;

Passed fee store tiers vector is empty.

const E_EMPTY_FEE_STORE_TIERS: u64 = 2;

Indicated fee share divisor for given tier is too big.

const E_FEE_SHARE_DIVISOR_TOO_BIG: u64 = 3;

The indicated fee share divisor for a given tier is less than the indicated taker fee divisor.

const E_FEE_SHARE_DIVISOR_TOO_SMALL: u64 = 4;

An update to the incentive parameters set indicates a reduction in fee store tiers.

const E_FEWER_TIERS: u64 = 16;

The cost to activate to tier 0 is nonzero.

const E_FIRST_TIER_ACTIVATION_FEE_NONZERO: u64 = 17;

Depositing to an integrator fee store would result in an overflow.

const E_INTEGRATOR_FEE_STORE_OVERFLOW: u64 = 19;

There is no tier with given number.

const E_INVALID_TIER: u64 = 22;

Type is not the utility coin type.

const E_INVALID_UTILITY_COIN_TYPE: u64 = 12;

Market registration fee is less than the minimum.

const E_MARKET_REGISTRATION_FEE_LESS_THAN_MIN: u64 = 5;

Indicated tier is not higher than existing tier.

const E_NOT_AN_UPGRADE: u64 = 15;

Type does not correspond to an initialized coin.

const E_NOT_COIN: u64 = 1;

Not enough utility coins provided.

const E_NOT_ENOUGH_UTILITY_COINS: u64 = 13;

Taker fee divisor is less than the minimum.

const E_TAKER_DIVISOR_LESS_THAN_MIN: u64 = 7;

Cumulative activation fee for new tier is not greater than that of current tier.

const E_TIER_COST_NOT_INCREASE: u64 = 23;

The wrong number of fields are passed for a given tier.

const E_TIER_FIELDS_WRONG_LENGTH: u64 = 8;

Too many integrator fee store tiers indicated.

const E_TOO_MANY_TIERS: u64 = 14;

Custodian registration fee is less than the minimum.

const E_UNDERWRITER_REGISTRATION_FEE_LESS_THAN_MIN: u64 = 18;

Depositing to a utility coin store would result in an overflow.

const E_UTILITY_COIN_STORE_OVERFLOW: u64 = 21;

The indicated withdrawal fee is too big.

const E_WITHDRAWAL_FEE_TOO_BIG: u64 = 10;

The indicated withdrawal fee is too small.

const E_WITHDRAWAL_FEE_TOO_SMALL: u64 = 11;

Genesis parameter.

const FEE_SHARE_DIVISOR_0: u64 = 10000;

Genesis parameter.

const FEE_SHARE_DIVISOR_1: u64 = 8333;

Genesis parameter.

const FEE_SHARE_DIVISOR_2: u64 = 7692;

Genesis parameter.

const FEE_SHARE_DIVISOR_3: u64 = 7143;

Genesis parameter.

const FEE_SHARE_DIVISOR_4: u64 = 6667;

Genesis parameter.

const FEE_SHARE_DIVISOR_5: u64 = 6250;

Genesis parameter.

const FEE_SHARE_DIVISOR_6: u64 = 5882;

Index of fee share in vectorized representation of an IntegratorFeeStoreTierParameters.

const FEE_SHARE_DIVISOR_INDEX: u64 = 0;

Genesis parameter.

const MARKET_REGISTRATION_FEE: u64 = 204918032;

Maximum number of integrator fee store tiers is largest number that can fit in a u8.

const MAX_INTEGRATOR_FEE_STORE_TIERS: u64 = 255;

Minimum possible divisor for avoiding divide-by-zero error, including during denominator calculation for a SELL in calculate_max_quote_match().

const MIN_DIVISOR: u64 = 2;

Minimum possible flat fee, required to disincentivize excessive bogus transactions.

const MIN_FEE: u64 = 1;

Number of fields in an IntegratorFeeStoreTierParameters.

const N_TIER_FIELDS: u64 = 3;

Sell direction flag, as defined in market.move.

const SELL: bool = true;

Genesis parameter.

const TAKER_FEE_DIVISOR: u64 = 2000;

Genesis parameter.

const TIER_ACTIVATION_FEE_0: u64 = 0;

Genesis parameter.

const TIER_ACTIVATION_FEE_1: u64 = 1639344;

Genesis parameter.

const TIER_ACTIVATION_FEE_2: u64 = 24590163;

Genesis parameter.

const TIER_ACTIVATION_FEE_3: u64 = 327868852;

Genesis parameter.

const TIER_ACTIVATION_FEE_4: u64 = 4098360655;

Genesis parameter.

const TIER_ACTIVATION_FEE_5: u64 = 49180327868;

Genesis parameter.

const TIER_ACTIVATION_FEE_6: u64 = 573770491803;

Index of tier activation fee in vectorized representation of an IntegratorFeeStoreTierParameters.

const TIER_ACTIVATION_FEE_INDEX: u64 = 1;

Genesis parameter.

const UNDERWRITER_REGISTRATION_FEE: u64 = 81967;

Genesis parameter.

const WITHDRAWAL_FEE_0: u64 = 1639344;

Genesis parameter.

const WITHDRAWAL_FEE_1: u64 = 1557377;

Genesis parameter.

const WITHDRAWAL_FEE_2: u64 = 1475409;

Genesis parameter.

const WITHDRAWAL_FEE_3: u64 = 1393442;

Genesis parameter.

const WITHDRAWAL_FEE_4: u64 = 1311475;

Genesis parameter.

const WITHDRAWAL_FEE_5: u64 = 1229508;

Genesis parameter.

const WITHDRAWAL_FEE_6: u64 = 1147540;

Index of withdrawal fee in vectorized representation of an IntegratorFeeStoreTierParameters.

const WITHDRAWAL_FEE_INDEX: u64 = 2;

Function `get_cost_to_upgrade_integrator_fee_store_view`

Calculate cost to upgrade IntegratorFeeStore to higher tier.

Type parameters

QuoteCoinType: The quote coin type for market.
UtilityCoinType: The utility coin type.

Parameters

integrator_address: Integrator address.
market_id: Market ID for corresponding market.
new_tier: Tier to upgrade to.

Returns

u64: Cost, in utility coins, to upgrade to given tier, calculated as the difference between the cumulative activation cost for each tier. For example, if it costs 1000 to activate to tier 3 and 100 to activate to tier 1, it costs 900 to upgrade from tier 1 to tier 3.

Aborts

E_NOT_AN_UPGRADE: new_tier is not higher than the one that the IntegratorFeeStore is already activated to.
E_TIER_COST_NOT_INCREASE: Cumulative activation fee for new tier is not greater than that of current tier.

Restrictions

Restricted to private view function to prevent excessive public queries on an IntegratorFeeStore and thus transaction collisions with the matching engine.

Testing

test_get_cost_to_upgrade_integrator_fee_store_not_increase()
test_get_cost_to_upgrade_integrator_fee_store_not_upgrade()

#[view]
fun get_cost_to_upgrade_integrator_fee_store_view<QuoteCoinType, UtilityCoinType>(integrator_address: address, market_id: u64, new_tier: u8): u64

Implementation

fun get_cost_to_upgrade_integrator_fee_store_view<
    QuoteCoinType,
    UtilityCoinType
>(
    integrator_address: address,
    market_id: u64,
    new_tier: u8
): u64
acquires
    IncentiveParameters,
    IntegratorFeeStores
{
    // Immutably borrow integrator fee stores map for given quote
    // coin type.
    let integrator_fee_stores_map_ref =
        &borrow_global<IntegratorFeeStores<QuoteCoinType>>(
            integrator_address).map;
    // Immutably borrow corresponding integrator fee store for
    // given market ID.
    let integrator_fee_store_ref = tablist::borrow(
        integrator_fee_stores_map_ref, market_id);
    // Get current tier number.
    let current_tier = integrator_fee_store_ref.tier;
    // Assert actually attempting to upgrade to new tier.
    assert!(new_tier > current_tier, E_NOT_AN_UPGRADE);
    // Get cumulative activation fee for current tier.
    let current_tier_fee = get_tier_activation_fee(current_tier);
    // Get cumulative activation fee for new tier.
    let new_tier_fee = get_tier_activation_fee(new_tier);
    // Assert new tier fee is greater than current tier fee.
    assert!(new_tier_fee > current_tier_fee, E_TIER_COST_NOT_INCREASE);
    // Return difference in cumulative cost to upgrade.
    new_tier_fee - current_tier_fee
}

Function `get_custodian_registration_fee`

Return custodian registration fee.

Testing

test_init_update_get_incentives()

#[view]
public fun get_custodian_registration_fee(): u64

Implementation

public fun get_custodian_registration_fee():
u64
acquires IncentiveParameters {
    borrow_global<IncentiveParameters>(@econia).custodian_registration_fee
}

Function `get_fee_share_divisor`

Return integrator fee share divisor for tier.

Testing

test_get_fee_share_divisor_invalid_tier()
test_init_update_get_incentives()

#[view]
public fun get_fee_share_divisor(tier: u8): u64

Implementation

public fun get_fee_share_divisor(
    tier: u8
): u64
acquires IncentiveParameters {
    // Borrow immutable reference to integrator fee store tiers
    // vector.
    let integrator_fee_store_tiers_ref =
        &borrow_global<IncentiveParameters>(@econia).
            integrator_fee_store_tiers;
    // Assert provided 0-indexed tier number is within range.
    assert!((tier as u64) < vector::length(integrator_fee_store_tiers_ref),
            E_INVALID_TIER);
    // Borrow immutable reference to indicated tier parameters.
    let integrator_fee_store_tier_ref = vector::borrow(
        integrator_fee_store_tiers_ref, (tier as u64));
    // Return corresponding fee share divisor.
    integrator_fee_store_tier_ref.fee_share_divisor
}

Function `get_integrator_withdrawal_fee_view`

Return withdrawal fee for given integrator_address and market_id.

Restrictions

Restricted to private view function to prevent excessive public queries on an IntegratorFeeStore and thus transaction collisions with the matching engine.

#[view]
fun get_integrator_withdrawal_fee_view<QuoteCoinType>(integrator_address: address, market_id: u64): u64

Implementation

fun get_integrator_withdrawal_fee_view<QuoteCoinType>(
    integrator_address: address,
    market_id: u64,
): u64
acquires
    IncentiveParameters,
    IntegratorFeeStores
{
    // Borrow mutable reference to integrator fee stores map for
    // quote coin type.
    let integrator_fee_stores_map_ref = &borrow_global<
        IntegratorFeeStores<QuoteCoinType>>(integrator_address).map;
    // Borrow mutable reference to integrator fee store for given
    // market ID.
    let integrator_fee_store_ref = tablist::borrow(
        integrator_fee_stores_map_ref, market_id);
    // Return withdrawal fee for given tier.
    get_tier_withdrawal_fee(integrator_fee_store_ref.tier)
}

Function `get_market_registration_fee`

Return market registration fee.

Testing

test_init_update_get_incentives()

#[view]
public fun get_market_registration_fee(): u64

Implementation

public fun get_market_registration_fee():
u64
acquires IncentiveParameters {
    borrow_global<IncentiveParameters>(@econia).market_registration_fee
}

Function `get_n_fee_store_tiers`

Return number of fee store tiers.

Testing

test_init_update_get_incentives()

#[view]
public fun get_n_fee_store_tiers(): u64

Implementation

public fun get_n_fee_store_tiers():
u64
acquires IncentiveParameters {
    // Borrow immutable reference to integrator fee store tiers
    // vector.
    let integrator_fee_store_tiers_ref =
        &borrow_global<IncentiveParameters>(@econia).
            integrator_fee_store_tiers;
    // Return its vector length
    vector::length(integrator_fee_store_tiers_ref)
}

Function `get_taker_fee_divisor`

Return taker fee divisor.

Testing

test_init_update_get_incentives()

#[view]
public fun get_taker_fee_divisor(): u64

Implementation

public fun get_taker_fee_divisor():
u64
acquires IncentiveParameters {
    borrow_global<IncentiveParameters>(@econia).taker_fee_divisor
}

Function `get_tier_activation_fee`

Return fee to activate an IntegratorFeeStore to given tier.

Testing

test_get_tier_activation_fee_invalid_tier()
test_init_update_get_incentives()

#[view]
public fun get_tier_activation_fee(tier: u8): u64

Implementation

public fun get_tier_activation_fee(
    tier: u8
): u64
acquires IncentiveParameters {
    // Borrow immutable reference to integrator fee store tiers
    // vector.
    let integrator_fee_store_tiers_ref =
        &borrow_global<IncentiveParameters>(@econia).
            integrator_fee_store_tiers;
    // Assert provided 0-indexed tier number is within range.
    assert!((tier as u64) < vector::length(integrator_fee_store_tiers_ref),
            E_INVALID_TIER);
    // Borrow immutable reference to given tier.
    let integrator_fee_store_tier_ref = vector::borrow(
        integrator_fee_store_tiers_ref, (tier as u64));
    // Return its activation fee.
    integrator_fee_store_tier_ref.tier_activation_fee
}

Function `get_tier_withdrawal_fee`

Return fee to withdraw from IntegratorFeeStore activated to given tier.

Testing

test_get_tier_withdrawal_fee_invalid_tier()
test_init_update_get_incentives()

#[view]
public fun get_tier_withdrawal_fee(tier: u8): u64

Implementation

public fun get_tier_withdrawal_fee(
    tier: u8
): u64
acquires IncentiveParameters {
    // Borrow immutable reference to integrator fee store tiers
    // vector.
    let integrator_fee_store_tiers_ref =
        &borrow_global<IncentiveParameters>(@econia).
            integrator_fee_store_tiers;
    // Assert provided 0-indexed tier number is within range.
    assert!((tier as u64) < vector::length(integrator_fee_store_tiers_ref),
            E_INVALID_TIER);
    // Borrow immutable reference to given tier.
    let integrator_fee_store_tier_ref = vector::borrow(
        integrator_fee_store_tiers_ref, (tier as u64));
    // Return its withdrawal fee.
    integrator_fee_store_tier_ref.withdrawal_fee
}

Function `get_underwriter_registration_fee`

Return underwriter registration fee.

Testing

test_init_update_get_incentives()

#[view]
public fun get_underwriter_registration_fee(): u64

Implementation

public fun get_underwriter_registration_fee():
u64
acquires IncentiveParameters {
    borrow_global<IncentiveParameters>(@econia).
        underwriter_registration_fee
}

Function `is_utility_coin_type`

Return true if T is the utility coin type.

Testing

test_init_update_get_incentives()

#[view]
public fun is_utility_coin_type<T>(): bool

Implementation

public fun is_utility_coin_type<T>():
bool
acquires IncentiveParameters {
    // Return if provided type info is that of the utility coin.
    type_info::type_of<T>() ==
        borrow_global<IncentiveParameters>(@econia).utility_coin_type_info
}

Function `get_cost_to_upgrade_integrator_fee_store`

Public function wrapper for get_cost_to_upgrade_integrator_fee_store_view(), requiring integrator signature to prevent runtime transaction collisions.

Testing

test_get_cost_to_upgrade_integrator_fee_store_not_increase()
test_get_cost_to_upgrade_integrator_fee_store_not_upgrade()

public fun get_cost_to_upgrade_integrator_fee_store<QuoteCoinType, UtilityCoinType>(integrator: &signer, market_id: u64, new_tier: u8): u64

Implementation

public fun get_cost_to_upgrade_integrator_fee_store<
    QuoteCoinType,
    UtilityCoinType
>(
    integrator: &signer,
    market_id: u64,
    new_tier: u8,
): u64
acquires
    IncentiveParameters,
    IntegratorFeeStores
{
    get_cost_to_upgrade_integrator_fee_store_view<
        QuoteCoinType, UtilityCoinType>(
            address_of(integrator), market_id, new_tier)
}

Function `get_integrator_withdrawal_fee`

Public function wrapper for get_integrator_withdrawal_fee_view(), requiring integrator signature to prevent runtime transaction collisions.

public fun get_integrator_withdrawal_fee<QuoteCoinType>(integrator: &signer, market_id: u64): u64

Implementation

public fun get_integrator_withdrawal_fee<QuoteCoinType>(
    integrator: &signer,
    market_id: u64,
): u64
acquires
    IncentiveParameters,
    IntegratorFeeStores
{
    get_integrator_withdrawal_fee_view<QuoteCoinType>(
            address_of(integrator), market_id)
}

Function `upgrade_integrator_fee_store`

Upgrade IntegratorFeeStore to a higher tier.

Type parameters

QuoteCoinType: The quote coin type for market.
UtilityCoinType: The utility coin type.

Parameters

integrator: Integrator account.
market_id: Market ID for corresponding market.
new_tier: Tier to upgrade to.
utility_coins: Utility coins paid for upgrade.

public fun upgrade_integrator_fee_store<QuoteCoinType, UtilityCoinType>(integrator: &signer, market_id: u64, new_tier: u8, utility_coins: coin::Coin<UtilityCoinType>)

Implementation

public fun upgrade_integrator_fee_store<
    QuoteCoinType,
    UtilityCoinType
>(
    integrator: &signer,
    market_id: u64,
    new_tier: u8,
    utility_coins: coin::Coin<UtilityCoinType>
) acquires
    IncentiveParameters,
    IntegratorFeeStores,
    UtilityCoinStore
{
    // Get cost to upgrade to new tier.
    let cost = get_cost_to_upgrade_integrator_fee_store<QuoteCoinType,
        UtilityCoinType>(integrator, market_id, new_tier);
    // Deposit verified amount and type of utility coins.
    deposit_utility_coins_verified<UtilityCoinType>(utility_coins, cost);
    // Get integrator address.
    let integrator_address = address_of(integrator);
    // Borrow mutable reference to integrator fee stores map for
    // quote coin type.
    let integrator_fee_stores_map_ref_mut =
        &mut borrow_global_mut<IntegratorFeeStores<QuoteCoinType>>(
            integrator_address).map;
    // Borrow mutable reference to integrator fee store for given
    // market ID.
    let integrator_fee_store_ref_mut = tablist::borrow_mut(
        integrator_fee_stores_map_ref_mut, market_id);
    // Set the new tier.
    integrator_fee_store_ref_mut.tier = new_tier;
}

Function `verify_utility_coin_type`

Assert T is utility coin type.

Aborts

E_INVALID_UTILITY_COIN_TYPE: T is not utility coin type.

Testing

test_verify_utility_coin_type()

public fun verify_utility_coin_type<T>()

Implementation

public fun verify_utility_coin_type<T>()
acquires IncentiveParameters {
    assert!(is_utility_coin_type<T>(), E_INVALID_UTILITY_COIN_TYPE);
}

Function `withdraw_econia_fees`

Withdraw amount of fee coins from an EconiaFeeStore of given QuoteCoinType and having market_id, under authority of econia.

See inner function withdraw_econia_fees_internal().

Testing

test_register_assess_withdraw()
test_withdraw_econia_fees_not_econia()

public fun withdraw_econia_fees<QuoteCoinType>(econia: &signer, market_id: u64, amount: u64): coin::Coin<QuoteCoinType>

Implementation

public fun withdraw_econia_fees<QuoteCoinType>(
    econia: &signer,
    market_id: u64,
    amount: u64
): coin::Coin<QuoteCoinType>
acquires
    EconiaFeeStore
{
    withdraw_econia_fees_internal<QuoteCoinType>(
        econia, market_id, false, amount)
}

Function `withdraw_econia_fees_all`

Withdraw all fee coins from an EconiaFeeStore of given QuoteCoinType and having market_id, under authority of econia.

See inner function withdraw_econia_fees_internal().

Testing

test_register_assess_withdraw()
test_withdraw_econia_fees_all_not_econia()

public fun withdraw_econia_fees_all<QuoteCoinType>(econia: &signer, market_id: u64): coin::Coin<QuoteCoinType>

Implementation

public fun withdraw_econia_fees_all<QuoteCoinType>(
    econia: &signer,
    market_id: u64,
): coin::Coin<QuoteCoinType>
acquires
    EconiaFeeStore
{
    withdraw_econia_fees_internal<QuoteCoinType>(
        econia, market_id, true, 0)
}

Function `withdraw_integrator_fees`

Withdraw all fees from an IntegratorFeeStore.

Type parameters

QuoteCoinType: The quote coin type for market.
UtilityCoinType: The utility coin type.

Parameters

integrator: Integrator account.
market_id: Market ID for corresponding market.
utility_coins: Utility coins paid in order to make withdrawal, required to disincentivize excessively frequent withdrawals and thus transaction collisions with the matching engine.

Returns

coin::Coin<QuoteCoinType>: Quote coin fees for given market.

public fun withdraw_integrator_fees<QuoteCoinType, UtilityCoinType>(integrator: &signer, market_id: u64, utility_coins: coin::Coin<UtilityCoinType>): coin::Coin<QuoteCoinType>

Implementation

public fun withdraw_integrator_fees<
    QuoteCoinType,
    UtilityCoinType
>(
    integrator: &signer,
    market_id: u64,
    utility_coins: coin::Coin<UtilityCoinType>
): coin::Coin<QuoteCoinType>
acquires
    IncentiveParameters,
    IntegratorFeeStores,
    UtilityCoinStore
{
    // Borrow mutable reference to integrator fee stores map for
    // quote coin type.
    let integrator_fee_stores_map_ref_mut = &mut borrow_global_mut<
        IntegratorFeeStores<QuoteCoinType>>(address_of(integrator)).map;
    // Borrow mutable reference to integrator fee store for given
    // market ID.
    let integrator_fee_store_ref_mut = tablist::borrow_mut(
        integrator_fee_stores_map_ref_mut, market_id);
    // Get fee to withdraw from fee store at given tier.
    let withdrawal_fee = get_tier_withdrawal_fee(
        integrator_fee_store_ref_mut.tier);
    // Deposit verified amount and type of utility coins.
    deposit_utility_coins_verified(utility_coins, withdrawal_fee);
    // Extract and return all coins in integrator fee store.
    coin::extract_all(&mut integrator_fee_store_ref_mut.coins)
}

Function `withdraw_utility_coins`

Withdraw amount of utility coins from the UtilityCoinStore, under authority of econia.

See inner function withdraw_utility_coins_internal().

Testing

test_deposit_withdraw_utility_coins()
test_register_assess_withdraw()
test_withdraw_utility_coins_not_econia()

public fun withdraw_utility_coins<UtilityCoinType>(econia: &signer, amount: u64): coin::Coin<UtilityCoinType>

Implementation

public fun withdraw_utility_coins<UtilityCoinType>(
    econia: &signer,
    amount: u64
): coin::Coin<UtilityCoinType>
acquires
    UtilityCoinStore
{
    withdraw_utility_coins_internal<UtilityCoinType>(econia, false, amount)
}

Function `withdraw_utility_coins_all`

Withdraw all utility coins from the UtilityCoinStore, under authority of econia.

See inner function withdraw_utility_coins_internal().

Testing

test_deposit_withdraw_utility_coins()
test_register_assess_withdraw()
test_withdraw_utility_coins_all_not_econia()

public fun withdraw_utility_coins_all<UtilityCoinType>(econia: &signer): coin::Coin<UtilityCoinType>

Implementation

public fun withdraw_utility_coins_all<UtilityCoinType>(
    econia: &signer
): coin::Coin<UtilityCoinType>
acquires
    UtilityCoinStore
{
    withdraw_utility_coins_internal<UtilityCoinType>(econia, true, 0)
}

Function `update_incentives`

Wrapped call to set_incentive_parameters(), when calling after initialization.

Accepts same arguments as set_incentive_parameters().

Testing

test_init_update_get_incentives()
test_update_incentives_fewer_tiers()

public entry fun update_incentives<UtilityCoinType>(econia: &signer, market_registration_fee: u64, underwriter_registration_fee: u64, custodian_registration_fee: u64, taker_fee_divisor: u64, integrator_fee_store_tiers: vector<vector<u64>>)

Implementation

public entry fun update_incentives<UtilityCoinType>(
    econia: &signer,
    market_registration_fee: u64,
    underwriter_registration_fee: u64,
    custodian_registration_fee: u64,
    taker_fee_divisor: u64,
    integrator_fee_store_tiers: vector<vector<u64>>
) acquires
    IncentiveParameters
{
    set_incentive_parameters<UtilityCoinType>(econia,
        market_registration_fee, underwriter_registration_fee,
        custodian_registration_fee, taker_fee_divisor,
        &integrator_fee_store_tiers, true);
}

Function `upgrade_integrator_fee_store_via_coinstore`

Wrapped call to upgrade_integrator_fee_store(), for paying utility coins from an aptos_framework::Coin::CoinStore.

See wrapped function upgrade_integrator_fee_store().

Testing

upgrade_integrator_fee_store_via_coinstore()

public entry fun upgrade_integrator_fee_store_via_coinstore<QuoteCoinType, UtilityCoinType>(integrator: &signer, market_id: u64, new_tier: u8)

Implementation

public entry fun upgrade_integrator_fee_store_via_coinstore<
    QuoteCoinType,
    UtilityCoinType
>(
    integrator: &signer,
    market_id: u64,
    new_tier: u8,
) acquires
    IncentiveParameters,
    IntegratorFeeStores,
    UtilityCoinStore
{
    // Get cost to upgrade to new tier.
    let cost = get_cost_to_upgrade_integrator_fee_store<QuoteCoinType,
        UtilityCoinType>(integrator, market_id, new_tier);
    // Upgrade integrator fee store, paying cost from coin store.
    upgrade_integrator_fee_store<QuoteCoinType, UtilityCoinType>(
        integrator, market_id, new_tier, coin::withdraw(
            integrator, cost));
}

Function `withdraw_econia_fees_all_to_coin_store`

Wrapped call to withdraw_econia_fees_to_coin_store_internal(), similar to withdraw_econia_fees_all().

Testing

test_withdraw_to_coin_store_econia()

public entry fun withdraw_econia_fees_all_to_coin_store<QuoteCoinType>(econia: &signer, market_id: u64)

Implementation

public entry fun withdraw_econia_fees_all_to_coin_store<QuoteCoinType>(
    econia: &signer,
    market_id: u64,
) acquires
    EconiaFeeStore
{
    withdraw_econia_fees_to_coin_store_internal<QuoteCoinType>(
        econia, market_id, true, 0);
}

Function `withdraw_econia_fees_to_coin_store`

Wrapped call to withdraw_econia_fees_to_coin_store_internal(), similar to withdraw_econia_fees().

Testing

test_withdraw_to_coin_store_econia()

public entry fun withdraw_econia_fees_to_coin_store<QuoteCoinType>(econia: &signer, market_id: u64, amount: u64)

Implementation

public entry fun withdraw_econia_fees_to_coin_store<QuoteCoinType>(
    econia: &signer,
    market_id: u64,
    amount: u64
) acquires
    EconiaFeeStore
{
    withdraw_econia_fees_to_coin_store_internal<QuoteCoinType>(
        econia, market_id, false, amount);
}

Function `withdraw_integrator_fees_via_coinstores`

Wrapped call to get_withdraw_integrator_fees(), for paying utility coins from an aptos_framework::Coin::CoinStore and depositing quote coins to one too.

See wrapped function withdraw_integrator_fees().

Type parameters

QuoteCoinType: The quote coin type for market.
UtilityCoinType: The utility coin type.

Parameters

integrator: Integrator account.
market_id: Market ID of corresponding market.

Testing

test_register_assess_withdraw()

public entry fun withdraw_integrator_fees_via_coinstores<QuoteCoinType, UtilityCoinType>(integrator: &signer, market_id: u64)

Implementation

public entry fun withdraw_integrator_fees_via_coinstores<
    QuoteCoinType,
    UtilityCoinType
>(
    integrator: &signer,
    market_id: u64
) acquires
    IncentiveParameters,
    IntegratorFeeStores,
    UtilityCoinStore
{
    // Get fee to withdraw from integrator fee coin store.
    let withdrawal_fee = get_integrator_withdrawal_fee<QuoteCoinType>(
        integrator, market_id);
    // Withdraw enough utility coins to pay fee.
    let utility_coins = coin::withdraw<UtilityCoinType>(
        integrator, withdrawal_fee);
    let quote_coins = // Withdraw integrator fees (quote coins).
        withdraw_integrator_fees<QuoteCoinType, UtilityCoinType>(
            integrator, market_id, utility_coins);
    // Get integrator address.
    let integrator_address = address_of(integrator);
    // If integrator does not have quote coin store, register one.
    if (!coin::is_account_registered<QuoteCoinType>(integrator_address))
        coin::register<QuoteCoinType>(integrator);
    // Deposit quote coins to integrator quote coin store.
    coin::deposit(address_of(integrator), quote_coins);
}

Function `withdraw_utility_coins_all_to_coin_store`

Wrapped withdraw_utility_coins_to_coin_store_internal() call, similar to withdraw_utility_coins_all().

Testing

test_withdraw_to_coin_store_econia()

public entry fun withdraw_utility_coins_all_to_coin_store<UtilityCoinType>(econia: &signer)

Implementation

public entry fun withdraw_utility_coins_all_to_coin_store<UtilityCoinType>(
    econia: &signer,
) acquires
    UtilityCoinStore
{
    withdraw_utility_coins_to_coin_store_internal<UtilityCoinType>(
        econia, true, 0);
}

Function `withdraw_utility_coins_to_coin_store`

Wrapped withdraw_utility_coins_to_coin_store_internal() call, similar to withdraw_utility_coins().

Testing

test_withdraw_to_coin_store_econia()

public entry fun withdraw_utility_coins_to_coin_store<UtilityCoinType>(econia: &signer, amount: u64)

Implementation

public entry fun withdraw_utility_coins_to_coin_store<UtilityCoinType>(
    econia: &signer,
    amount: u64
) acquires
    UtilityCoinStore
{
    withdraw_utility_coins_to_coin_store_internal<UtilityCoinType>(
        econia, false, amount);
}

Function `assess_taker_fees`

Assess fees after a taker fill.

First attempts to assess an integrator's share of taker fees, then provides Econia with the remaining share. If the integrator_address does not have an IntegratorFeeStore for the given market_id and QuoteCoinType, all taker fees are passed on to Econia. Otherwise the integrator's fee share is determined based on their tier for the given market.

Type parameters

QuoteCoinType: Quote coin type for market.

Parameters

market_id: Market ID for corresponding market.
integrator_address: Integrator's address. May be intentionally marked an address known not to be an integrator, for example @0x0 or @econia, in the service of diverting all fees to Econia.
taker_fee_divisor: Taker fee divisor.
quote_fill: Amount of quote coins filled during taker match.
quote_coins: Quote coins to withdraw fees from.

Returns

coin::Coin<QuoteCoinType>: Remaining quote coins after fees assessed.
u64: Amount of fees assessed.

Aborts

E_INTEGRATOR_FEE_STORE_OVERFLOW: Depositing to integrator fee store would result in an overflow. Rather than relying on the underlying coin operation to abort, this check is performed to provide additional feedback in the unlikely event that a coin with a supply far in excess of HI_64 is the quote coin for a market.
E_ECONIA_FEE_STORE_OVERFLOW: Depositing to Econia fee store would result in an overflow per above.

Assumptions

taker_fee_divisor is nonzero.

Testing

test_register_assess_withdraw()

public(friend) fun assess_taker_fees<QuoteCoinType>(market_id: u64, integrator_address: address, taker_fee_divisor: u64, quote_fill: u64, quote_coins: coin::Coin<QuoteCoinType>): (coin::Coin<QuoteCoinType>, u64)

Implementation

public(friend) fun assess_taker_fees<QuoteCoinType>(
    market_id: u64,
    integrator_address: address,
    taker_fee_divisor: u64,
    quote_fill: u64,
    quote_coins: coin::Coin<QuoteCoinType>,
): (
    coin::Coin<QuoteCoinType>,
    u64
) acquires
    EconiaFeeStore,
    IncentiveParameters,
    IntegratorFeeStores
{
    // Declare tracker for amount of fees collected by integrator.
    let integrator_fee_share = 0;
    // Calculate total taker fee.
    let total_fee = quote_fill / taker_fee_divisor;
    // If integrator fee stores map for quote coin type exists at
    // indicated integrator address:
    if (exists<IntegratorFeeStores<QuoteCoinType>>(integrator_address)) {
        // Borrow mutable reference to integrator fee stores map.
        let integrator_fee_stores_map_ref_mut =
            &mut borrow_global_mut<IntegratorFeeStores<QuoteCoinType>>(
                integrator_address).map;
        // Determine if the fee stores map contains an entry for the
        // given market ID.
        let contains_market_id_entry = tablist::contains(
            integrator_fee_stores_map_ref_mut, market_id);
        // If fee stores map contains an entry for given market ID:
        if (contains_market_id_entry) {
            // Borrow mutable reference to corresponding fee store.
            let integrator_fee_store_ref_mut = tablist::borrow_mut(
                integrator_fee_stores_map_ref_mut, market_id);
            // Get fee share divisor for given tier.
            let fee_share_divisor = get_fee_share_divisor(
                integrator_fee_store_ref_mut.tier);
            // Calculate resultant integrator fee share.
            integrator_fee_share = quote_fill / fee_share_divisor;
            // Verify merge will not overflow integrator fee store.
            range_check_coin_merge(
                integrator_fee_share, &integrator_fee_store_ref_mut.coins,
                E_INTEGRATOR_FEE_STORE_OVERFLOW);
            // Extract resultant amount from supplied quote coins.
            let integrator_fees =
                coin::extract(&mut quote_coins, integrator_fee_share);
            // Merge the fees into the corresponding fee store.
            coin::merge(&mut integrator_fee_store_ref_mut.coins,
                integrator_fees);
        }
    }; // Integrator fee share has been assessed.
    // Fee share remaining for Econia is the total taker fee amount
    // less the integrator fee share.
    let econia_fee_share = total_fee - integrator_fee_share;
    // Extract resultant amount from supplied quote coins.
    let econia_fees = coin::extract(&mut quote_coins, econia_fee_share);
    // Get fee account address.
    let fee_account_address = resource_account::get_address();
    // Borrow mutable reference to Econia fee store map for given
    // quote coin type.
    let econia_fee_store_map_ref_mut =
        &mut borrow_global_mut<EconiaFeeStore<QuoteCoinType>>(
            fee_account_address).map;
    // Borrow mutable reference to fees for given market ID.
    let econia_fee_store_coins_ref_mut = tablist::borrow_mut(
        econia_fee_store_map_ref_mut, market_id);
    // Verify merge will not overflow Econia fee store.
    range_check_coin_merge(
        econia_fee_share, econia_fee_store_coins_ref_mut,
        E_ECONIA_FEE_STORE_OVERFLOW);
    // Merge the Econia fees into the fee store.
    coin::merge(econia_fee_store_coins_ref_mut, econia_fees);
    (quote_coins, total_fee) // Return coins, fee paid.
}

Function `calculate_max_quote_match`

Get max quote coin match amount, per user input and fee divisor.

Whether a taker buy or sell, users specify a maximum quote coin amount when initiating the transaction. This amount indicates the maximum amount of quote coins they are willing to spend in the case of a taker buy, and the maximum amount of quote coins they are willing to receive in the case of a taker sell. The user-specified amount refers to the net change in taker's quote coin holdings due to matching and fees, which are assessed after matching concludes. Hence it is necessary to calculate a maximum quote match amount prior to matching.

Example buy

Taker is willing to spend 105 quote coins.
Fee is 5% (divisor of 20).
Max match is thus 100 quote coins.
Matching engine halts after 100 quote coins filled.
5% fee then assessed, withdrawn from takers's quote coins.
Taker has spent 105 quote coins.

Example sell

Taker is willing to receive 100 quote coins.
Fee is 4% (divisor of 25).
Max match is thus 104 quote coins.
Matching engine halts after 104 quote coins filled.
4% fee then assessed, withdrawn from quote coins received.
Taker has received 100 quote coins.

Variables

The relationship between user-indicated maximum quote coin trade amount, taker fee divisor, and the amount of quote coins matched can be described with the following variables:

$\Delta_t$: Change in quote coins seen by taker.
$d_t$: Taker fee divisor.
$q_m$: Quote coins matched.
$f = \frac{q_m}{d_t}$: Fees assessed.

Equations

Buy

$$q_m = \Delta_t - f = \Delta_t - \frac{q_m}{d_t}$$

$$\Delta_t = q_m + \frac{q_m}{d_t} = q_m(1 + \frac{1}{d_t})$$

$$ q_m = \frac{\Delta_t}{1 + \frac{1}{d_t}} $$

$$ q_m = \frac{d_t \Delta_t}{d_t + 1}$$

Sell

$$q_m = \Delta_t + f = \Delta_t + \frac{q_m}{d_t}$$

$$\Delta_t = q_m - \frac{q_m}{d_t} = q_m(1 - \frac{1}{d_t})$$

$$ q_m = \frac{\Delta_t}{1 - \frac{1}{d_t}} $$

$$ q_m = \frac{d_t \Delta_t}{d_t - 1}$$

Overflow correction

Per above, if a taker specifies that they are willing to receive HI_64 coins during a sell, the corresponding max quote match amount will overflow a u64, since more than HI_64 quote coins will need to be matched before a fee is assessed. Hence if the maximum quote match amount for a sell is calculated to be in excess of HI_64, the maximum quote match amount is simply corrected to HI_64. Here, the maximum user-specified amount that will not require such correction, $\Delta_{t, m}$ , is defined in terms of the maximum possible quote match amount $q_{m, m} = 2^{63} - 1$ (HI_64), and the taker fee divisor:

$$ \Delta_{t, m} + \frac{q_{m, m}}{d_t} = q_{m, m} $$

$$ \Delta_{t, m} = q_{m, m} - \frac{q_{m, m}}{d_t} $$

Such an overflow correction does not apply in the case of a taker buy because the maximum quote match amount is strictly smaller than the user-specified change in quote coins (the amount of quote coins the taker is willing to spend).

Parameters

direction: BUY or SELL.
taker_fee_divisor: Taker fee divisor.
max_quote_delta_user: Maximum change in quote coins seen by user: spent if a BUY and received if a SELL.

Returns

u64: Maximum amount of quote coins to match.

Assumptions

Taker fee divisor is greater than 1.

Testing

test_calculate_max_quote_match()
test_calculate_max_quote_match_overflow()

public(friend) fun calculate_max_quote_match(direction: bool, taker_fee_divisor: u64, max_quote_delta_user: u64): u64

Implementation

public(friend) fun calculate_max_quote_match(
    direction: bool,
    taker_fee_divisor: u64,
    max_quote_delta_user: u64
): u64 {
    // Calculate numerator for both buy and sell equations.
    let numerator = (taker_fee_divisor as u128) *
        (max_quote_delta_user as u128);
    // Calculate denominator based on direction.
    let denominator = if (direction == BUY)
        (taker_fee_divisor + 1 as u128) else
        (taker_fee_divisor - 1 as u128);
    // Calculate maximum quote coins to match.
    let max_quote_match = numerator / denominator;
    // Return corrected sell overflow match amount if needed,
    if (max_quote_match > (HI_64 as u128)) HI_64 else
        (max_quote_match as u64) // Else max quote match amount.
}

Function `deposit_custodian_registration_utility_coins`

Deposit coins of UtilityCoinType, verifying that the proper amount is supplied for custodian registration.

Testing

test_deposit_registration_fees_mixed()

public(friend) fun deposit_custodian_registration_utility_coins<UtilityCoinType>(coins: coin::Coin<UtilityCoinType>)

Implementation

public(friend) fun deposit_custodian_registration_utility_coins<
    UtilityCoinType
>(
    coins: coin::Coin<UtilityCoinType>
) acquires
    IncentiveParameters,
    UtilityCoinStore
{
    deposit_utility_coins_verified<UtilityCoinType>(coins,
        get_custodian_registration_fee());
}

Function `deposit_market_registration_utility_coins`

Deposit coins of UtilityCoinType, verifying that the proper amount is supplied for market registration.

Testing

test_deposit_registration_fees_mixed()

public(friend) fun deposit_market_registration_utility_coins<UtilityCoinType>(coins: coin::Coin<UtilityCoinType>)

Implementation

public(friend) fun deposit_market_registration_utility_coins<
    UtilityCoinType
>(
    coins: coin::Coin<UtilityCoinType>
) acquires
    IncentiveParameters,
    UtilityCoinStore
{
    deposit_utility_coins_verified<UtilityCoinType>(coins,
        get_market_registration_fee());
}

Function `deposit_underwriter_registration_utility_coins`

Deposit coins of UtilityCoinType, verifying that the proper amount is supplied for underwriter registration.

Testing

test_deposit_registration_fees_mixed()

public(friend) fun deposit_underwriter_registration_utility_coins<UtilityCoinType>(coins: coin::Coin<UtilityCoinType>)

Implementation

public(friend) fun deposit_underwriter_registration_utility_coins<
    UtilityCoinType
>(
    coins: coin::Coin<UtilityCoinType>
) acquires
    IncentiveParameters,
    UtilityCoinStore
{
    deposit_utility_coins_verified<UtilityCoinType>(coins,
        get_underwriter_registration_fee());
}

Function `register_econia_fee_store_entry`

Register an EconiaFeeStore entry for given market_id and QuoteCoinType.

Testing

test_register_assess_withdraw()

public(friend) fun register_econia_fee_store_entry<QuoteCoinType>(market_id: u64)

Implementation

public(friend) fun register_econia_fee_store_entry<QuoteCoinType>(
    market_id: u64
) acquires
    EconiaFeeStore,
{
    // Get fee account signer.
    let fee_account = resource_account::get_signer();
    // Get fee account address.
    let fee_account_address = address_of(&fee_account);
    // If an Econia fee store for the quote coin type has not
    // already been initialized at the fee account:
    if (!exists<EconiaFeeStore<QuoteCoinType>>(fee_account_address))
        // Move to the Econia fee account an empty one.
        move_to<EconiaFeeStore<QuoteCoinType>>(&fee_account,
            EconiaFeeStore{map: tablist::new()});
    // Borrow mutable reference to Econia fee store map for
    // given quote coin type.
    let econia_fee_store_map_ref_mut =
        &mut borrow_global_mut<EconiaFeeStore<QuoteCoinType>>(
            fee_account_address).map;
    // Declare zero coins of quote coin type
    let zero_coins = coin::zero<QuoteCoinType>();
    // Add to fee store map an entry given market ID and no coins.
    tablist::add(econia_fee_store_map_ref_mut, market_id, zero_coins);
}

Function `register_integrator_fee_store`

Register an IntegratorFeeStore entry for given integrator.

Type parameters

QuoteCoinType: The quote coin type for market.
UtilityCoinType: The utility coin type.

Parameters

integrator: Integrator account.
market_id: Market ID for corresponding market.
tier: IntegratorFeeStore tier to activate to.
utility_coins: Utility coins paid to activate to given tier.

Testing

test_register_assess_withdraw()
test_upgrade_integrator_fee_store_via_coinstore()

public(friend) fun register_integrator_fee_store<QuoteCoinType, UtilityCoinType>(integrator: &signer, market_id: u64, tier: u8, utility_coins: coin::Coin<UtilityCoinType>)

Implementation

public(friend) fun register_integrator_fee_store<
    QuoteCoinType,
    UtilityCoinType
>(
    integrator: &signer,
    market_id: u64,
    tier: u8,
    utility_coins: coin::Coin<UtilityCoinType>
) acquires
    IncentiveParameters,
    IntegratorFeeStores,
    UtilityCoinStore
{
    // Get tier activation fee for given tier.
    let tier_activation_fee = get_tier_activation_fee(tier);
    // Deposit utility coins, verifying sufficient amount provided.
    // Deposit verified amount and type of utility coins.
    deposit_utility_coins_verified(utility_coins, tier_activation_fee);
    // Get integrator address.
    let integrator_address = address_of(integrator);
    // If an integrator fee store for the quote coin type has not
    // already been initialized at the integrator account:
    if (!exists<IntegratorFeeStores<QuoteCoinType>>(integrator_address))
        // Move to the integrator account an empty one.
        move_to<IntegratorFeeStores<QuoteCoinType>>(integrator,
            IntegratorFeeStores{map: tablist::new()});
    // Declare integrator fee store for given tier, with no coins.
    let integrator_fee_store =
        IntegratorFeeStore{tier, coins: coin::zero<QuoteCoinType>()};
    // Borrow mutable reference to integrator fee stores map for
    // given quote coin type.
    let integrator_fee_stores_map_ref_mut =
        &mut borrow_global_mut<IntegratorFeeStores<QuoteCoinType>>(
            integrator_address).map;
    // Add to the map an entry having with given market ID and
    // generated integrator fee store.
    tablist::add(integrator_fee_stores_map_ref_mut, market_id,
        integrator_fee_store);
}

Function `deposit_utility_coins`

Deposit coins to the Econia UtilityCoinStore.

Aborts

E_UTILITY_COIN_STORE_OVERFLOW: Depositing to utility coin store would result in an overflow. Rather than relying on the underlying coin operation to abort, this check is performed to provide additional feedback in the unlikely event that a coin with a supply far in excess of HI_64 is used as a utility coin.

Testing

test_deposit_withdraw_utility_coins()

fun deposit_utility_coins<UtilityCoinType>(coins: coin::Coin<UtilityCoinType>)

Implementation

fun deposit_utility_coins<UtilityCoinType>(
    coins: coin::Coin<UtilityCoinType>
) acquires
    UtilityCoinStore
{
    // Get fee account address.
    let fee_account_address = resource_account::get_address();
    // Borrow mutable reference to coins in utility coin store.
    let utility_coins_ref_mut =
        &mut borrow_global_mut<UtilityCoinStore<UtilityCoinType>>(
            fee_account_address).coins;
    // Verify merge will not overflow utility coin store.
    range_check_coin_merge(coin::value(&coins),
        utility_coins_ref_mut, E_UTILITY_COIN_STORE_OVERFLOW);
    // Merge in deposited coins.
    coin::merge(utility_coins_ref_mut, coins);
}

Function `deposit_utility_coins_verified`

Verify that UtilityCoinType is the utility coin type and that coins has at least the min_amount, then deposit all utility coins to UtilityCoinStore.

Aborts

E_NOT_ENOUGH_UTILITY_COINS: Insufficient utility coins provided.

Testing

test_deposit_utility_coins_verified_not_enough()

fun deposit_utility_coins_verified<UtilityCoinType>(coins: coin::Coin<UtilityCoinType>, min_amount: u64)

Implementation

fun deposit_utility_coins_verified<UtilityCoinType>(
    coins: coin::Coin<UtilityCoinType>,
    min_amount: u64
) acquires
    IncentiveParameters,
    UtilityCoinStore
{
    // Verify utility coin type.
    verify_utility_coin_type<UtilityCoinType>();
    // Assert sufficient utility coins provided.
    assert!(coin::value(&coins) >= min_amount, E_NOT_ENOUGH_UTILITY_COINS);
    // Deposit all utility coins to utility coin store.
    deposit_utility_coins(coins);
}

Function `init_module`

Initialize incentives during first-time publication.

Uses hard-coded genesis parameters that can be updated later.

Testing

test_init_update_get_incentives()

fun init_module(econia: &signer)

Implementation

fun init_module(
    econia: &signer
) acquires
    IncentiveParameters
{
    // Vectorize fee store tier parameters.
    let integrator_fee_store_tiers = vector[
        vector[FEE_SHARE_DIVISOR_0,
               TIER_ACTIVATION_FEE_0,
               WITHDRAWAL_FEE_0],
        vector[FEE_SHARE_DIVISOR_1,
               TIER_ACTIVATION_FEE_1,
               WITHDRAWAL_FEE_1],
        vector[FEE_SHARE_DIVISOR_2,
               TIER_ACTIVATION_FEE_2,
               WITHDRAWAL_FEE_2],
        vector[FEE_SHARE_DIVISOR_3,
               TIER_ACTIVATION_FEE_3,
               WITHDRAWAL_FEE_3],
        vector[FEE_SHARE_DIVISOR_4,
               TIER_ACTIVATION_FEE_4,
               WITHDRAWAL_FEE_4],
        vector[FEE_SHARE_DIVISOR_5,
               TIER_ACTIVATION_FEE_5,
               WITHDRAWAL_FEE_5],
        vector[FEE_SHARE_DIVISOR_6,
               TIER_ACTIVATION_FEE_6,
               WITHDRAWAL_FEE_6]];
    // Set incentive parameters for the first time.
    set_incentive_parameters<AptosCoin>(econia,
        MARKET_REGISTRATION_FEE, UNDERWRITER_REGISTRATION_FEE,
        CUSTODIAN_REGISTRATION_FEE, TAKER_FEE_DIVISOR,
        &integrator_fee_store_tiers, false);
}

Function `init_utility_coin_store`

Initialize a UtilityCoinStore under the Econia fee account.

Returns without initializing if a UtilityCoinStore already exists for given CoinType, which may happen in the case of switching back to a utility coin type after having abandoned it.

Type Parameters

CoinType: Utility coin phantom type.

Parameters

fee_account: Econia fee account signer.

Aborts

E_NOT_COIN: CoinType does not correspond to an initialized aptos_framework::coin::Coin.

Testing

test_init_utility_coin_store()
test_init_utility_coin_store_not_coin()

fun init_utility_coin_store<CoinType>(fee_account: &signer)

Implementation

fun init_utility_coin_store<CoinType>(
    fee_account: &signer
) {
    // Assert coin type corresponds to initialized coin.
    assert!(coin::is_coin_initialized<CoinType>(), E_NOT_COIN);
    // If a utility coin store does not already exist at account,
    if(!exists<UtilityCoinStore<CoinType>>(address_of(fee_account)))
        // Move to the fee account an initialized one.
        move_to<UtilityCoinStore<CoinType>>(fee_account,
            UtilityCoinStore{coins: coin::zero<CoinType>()});
}

Function `range_check_coin_merge`

Verify that attempting to merge amount into target_coins does not overflow a u64, aborting with error_code if it does.

Since coins can be minted in excess of a HI_64 supply, this is an unlikely but potentially catastrophic event, especially if the overflowed account blocks other transactions from proceeding. Hence the extra feedback in this module, in the form of a custom error code for the given operation, which allows for diagnosis in extreme cases.

Aborts

error_code: Proposed coin merge overflows a u64.

Testing

test_range_check_coin_merge()

fun range_check_coin_merge<CoinType>(amount: u64, target_coins: &coin::Coin<CoinType>, error_code: u64)

Implementation

fun range_check_coin_merge<CoinType>(
    amount: u64,
    target_coins: &coin::Coin<CoinType>,
    error_code: u64
) {
    // Get value of target coins.
    let target_value = coin::value(target_coins);
    // Assert merge does not overflow a u64.
    assert!((amount as u128) + (target_value as u128) <= (HI_64 as u128),
        error_code);
}

Function `set_incentive_parameters`

Set all fields for IncentiveParameters under Econia account.

Rather than pass-by-value a vector<IntegratorFeeStoreTierParameters>, mutably reassigns the values of IncentiveParameters.integrator_fee_store_tiers via set_incentive_parameters_parse_tiers_vector().

Type Parameters

UtilityCoinType: Utility coin phantom type.

Parameters

econia: Econia account signer.
market_registration_fee: Market registration fee to set.
underwriter_registration_fee: Underwriter registration fee to set.
custodian_registration_fee: Custodian registration fee to set.
taker_fee_divisor: Taker fee divisor to set.
integrator_fee_store_tiers_ref: Immutable reference to 0-indexed vector of 3-element vectors, with each 3-element vector containing fields for a corresponding IntegratorFeeStoreTierParameters.
updating: true if updating incentive parameters that have already been set, false if setting parameters for the first time.

Assumptions

If updating is true, an IncentiveParameters already exists at the Econia account.
If updating is false, an IncentiveParameters does not exist at the Econia account.

Aborts

E_FEWER_TIERS: updating is true and the new parameter set indicates a reduction in the number of fee store activation tiers, which would mean that integrators who had previously upgraded to the highest tier would become subject to undefined behavior.

fun set_incentive_parameters<UtilityCoinType>(econia: &signer, market_registration_fee: u64, underwriter_registration_fee: u64, custodian_registration_fee: u64, taker_fee_divisor: u64, integrator_fee_store_tiers_ref: &vector<vector<u64>>, updating: bool)

Implementation

fun set_incentive_parameters<UtilityCoinType>(
    econia: &signer,
    market_registration_fee: u64,
    underwriter_registration_fee: u64,
    custodian_registration_fee: u64,
    taker_fee_divisor: u64,
    integrator_fee_store_tiers_ref: &vector<vector<u64>>,
    updating: bool
) acquires
    IncentiveParameters
{
    // Range check inputs.
    set_incentive_parameters_range_check_inputs(econia,
        market_registration_fee, underwriter_registration_fee,
        custodian_registration_fee, taker_fee_divisor,
        integrator_fee_store_tiers_ref);
    // Get fee account signer.
    let fee_account = resource_account::get_signer();
    // Initialize a utility coin store under the fee account (aborts
    // if not an initialized coin type).
    init_utility_coin_store<UtilityCoinType>(&fee_account);
    if (updating) { // If updating previously-set values:
        // Get number of tiers before upgrade.
        let n_old_tiers = get_n_fee_store_tiers();
        // Get number of tiers in new parameter set.
        let n_new_tiers = vector::length(integrator_fee_store_tiers_ref);
        // Assert new parameter set indicates at least as many fee
        // store tiers as the set from before the upgrade.
        assert!(n_new_tiers >= n_old_tiers, E_FEWER_TIERS);
        // Borrow a mutable reference to the incentive parameters
        // resource at the Econia account.
        let incentive_parameters_ref_mut =
            borrow_global_mut<IncentiveParameters>(@econia);
        // Set integrator fee stores to empty vector before
        // moving from.
        incentive_parameters_ref_mut.integrator_fee_store_tiers =
            vector::empty();
        // Move from and drop the existing incentive parameters
        // resource at the Econia account.
        move_from<IncentiveParameters>(@econia);
    };
    // Get utility coin type info.
    let utility_coin_type_info = type_info::type_of<UtilityCoinType>();
    // Declare integrator fee store tiers vector as empty.
    let integrator_fee_store_tiers = vector::empty();
    // Initialize an incentive parameters resource with
    // range-checked inputs and empty tiers vector.
    move_to<IncentiveParameters>(econia, IncentiveParameters{
        utility_coin_type_info, market_registration_fee,
        underwriter_registration_fee, custodian_registration_fee,
        taker_fee_divisor, integrator_fee_store_tiers});
    // Borrow a mutable reference to the incentive parameters
    // resource at the Econia account.
    let incentive_parameters_ref_mut =
        borrow_global_mut<IncentiveParameters>(@econia);
    // Parse in integrator fee store tier parameters.
    set_incentive_parameters_parse_tiers_vector(
        taker_fee_divisor, integrator_fee_store_tiers_ref,
        &mut incentive_parameters_ref_mut.integrator_fee_store_tiers);
}

Function `set_incentive_parameters_parse_tiers_vector`

Parse vectorized fee store tier parameters passed to set_incentive_parameters().

taker_fee_divisor: Taker fee divisor just set.
integrator_fee_store_tiers_ref: Immutable reference to 0-indexed vector of 3-element vectors, with each 3-element vector containing fields for a corresponding IntegratorFeeStoreTierParameters.
integrator_fee_store_tiers_target_ref_mut: Mutable reference to the IncentiveParameters.integrator_fee_store_tiers field to parse into.

Aborts

E_TIER_FIELDS_WRONG_LENGTH: An indicated inner vector from integrator_fee_store_tiers_ref is the wrong length.
E_FEE_SHARE_DIVISOR_TOO_BIG: Fee share divisor does not decrease with tier number.
E_FEE_SHARE_DIVISOR_TOO_SMALL: A fee share divisor is less than taker fee divisor.
E_FIRST_TIER_ACTIVATION_FEE_NONZERO: Tier activation fee for first tier is nonzero.
E_ACTIVATION_FEE_TOO_SMALL: Tier activation fee does not increase with tier number.
E_WITHDRAWAL_FEE_TOO_BIG: Withdrawal fee does not decrease with tier number.
E_WITHDRAWAL_FEE_TOO_SMALL: The withdrawal fee for a given tier does not meet minimum threshold.

Assumptions

taker_fee_divisor has been range-checked via set_incentive_parameters_range_check_inputs().
An IncentiveParameters exists at the Econia account.
integrator_fee_store_tiers_ref does not indicate an empty vector.
integrator_fee_store_tiers_target_ref_mut indicates an empty vector.

Testing

test_set_incentive_params_parse_tiers_vec_activate_0()
test_set_incentive_params_parse_tiers_vec_activate_1()
test_set_incentive_params_parse_tiers_vec_divisor_big_0()
test_set_incentive_params_parse_tiers_vec_divisor_big_1()
test_set_incentive_params_parse_tiers_vec_divisor_small()
test_set_incentive_params_parse_tiers_vec_withdraw_big_0()
test_set_incentive_params_parse_tiers_vec_withdraw_big_1()
test_set_incentive_params_parse_tiers_vec_withdraw_small()
test_set_incentive_params_parse_tiers_vec_wrong_length()

fun set_incentive_parameters_parse_tiers_vector(taker_fee_divisor: u64, integrator_fee_store_tiers_ref: &vector<vector<u64>>, integrator_fee_store_tiers_target_ref_mut: &mut vector<incentives::IntegratorFeeStoreTierParameters>)

Implementation

fun set_incentive_parameters_parse_tiers_vector(
    taker_fee_divisor: u64,
    integrator_fee_store_tiers_ref: &vector<vector<u64>>,
    integrator_fee_store_tiers_target_ref_mut:
        &mut vector<IntegratorFeeStoreTierParameters>
) {
    // Initialize tracker variables for the fee store parameters of
    // the last parsed tier.
    let (divisor_last, activation_fee_last, withdrawal_fee_last) = (
                HI_64,                   0,               HI_64);
    // Get number of specified integrator fee store tiers.
    let n_tiers = vector::length(integrator_fee_store_tiers_ref);
    let i = 0; // Declare counter for loop variable.
    while (i < n_tiers) { // Loop over all specified tiers
        // Borrow immutable reference to fields for given tier.
        let tier_fields_ref =
            vector::borrow(integrator_fee_store_tiers_ref, i);
        // Assert containing vector is correct length.
        assert!(vector::length(tier_fields_ref) == N_TIER_FIELDS,
            E_TIER_FIELDS_WRONG_LENGTH);
        // Borrow immutable reference to fee share divisor.
        let fee_share_divisor_ref =
            vector::borrow(tier_fields_ref, FEE_SHARE_DIVISOR_INDEX);
        // Assert indicated fee share divisor is less than divisor
        // from last tier.
        assert!(*fee_share_divisor_ref < divisor_last,
            E_FEE_SHARE_DIVISOR_TOO_BIG);
        // Assert indicated fee share divisor is greater than or
        // equal to taker fee divisor.
        assert!(*fee_share_divisor_ref >= taker_fee_divisor,
            E_FEE_SHARE_DIVISOR_TOO_SMALL);
        // Borrow immutable reference to tier activation fee.
        let tier_activation_fee_ref =
            vector::borrow(tier_fields_ref, TIER_ACTIVATION_FEE_INDEX);
        if (i == 0) { // If parsing parameters for first tier:
            // Assert activation fee is 0.
            assert!(*tier_activation_fee_ref == 0,
                E_FIRST_TIER_ACTIVATION_FEE_NONZERO);
        } else { // If parameters for tier that is not first:
            // Assert activation fee greater than that of last tier.
            assert!(*tier_activation_fee_ref > activation_fee_last,
                E_ACTIVATION_FEE_TOO_SMALL);
        };
        // Borrow immutable reference to withdrawal fee.
        let withdrawal_fee_ref =
            vector::borrow(tier_fields_ref, WITHDRAWAL_FEE_INDEX);
        // Assert withdrawal fee is less than that of last tier.
        assert!(*withdrawal_fee_ref < withdrawal_fee_last,
            E_WITHDRAWAL_FEE_TOO_BIG);
        // Assert withdrawal fee meets minimum threshold.
        assert!(*withdrawal_fee_ref >= MIN_FEE,
                E_WITHDRAWAL_FEE_TOO_SMALL);
        // Mark indicated tier in target tiers vector.
        vector::push_back(integrator_fee_store_tiers_target_ref_mut,
            IntegratorFeeStoreTierParameters{
                fee_share_divisor: *fee_share_divisor_ref,
                tier_activation_fee: *tier_activation_fee_ref,
                withdrawal_fee: *withdrawal_fee_ref});
        // Store divisor for comparison during next iteration.
        divisor_last = *fee_share_divisor_ref;
        // Store activation fee to compare during next iteration.
        activation_fee_last = *tier_activation_fee_ref;
        // Store withdrawal fee to compare during next iteration.
        withdrawal_fee_last = *withdrawal_fee_ref;
        i = i + 1; // Increment loop counter
    };
}

Function `set_incentive_parameters_range_check_inputs`

Range check inputs for set_incentive_parameters().

Parameters

econia: Econia account signer.
market_registration_fee: Market registration fee to set.
underwriter_registration_fee: Underwriter registration fee to set.
custodian_registration_fee: Custodian registration fee to set.
taker_fee_divisor: Taker fee divisor to set.
integrator_fee_store_tiers_ref: Immutable reference to 0-indexed vector of 3-element vectors, with each 3-element vector containing fields for a corresponding IntegratorFeeStoreTierParameters.

Aborts

E_NOT_ECONIA: econia is not Econia account.
E_MARKET_REGISTRATION_FEE_LESS_THAN_MIN: market_registration_fee does not meet minimum threshold.
E_UNDERWRITER_REGISTRATION_FEE_LESS_THAN_MIN: underwriter_registration_fee does not meet minimum threshold.
E_CUSTODIAN_REGISTRATION_FEE_LESS_THAN_MIN: custodian_registration_fee does not meet minimum threshold.
E_TAKER_DIVISOR_LESS_THAN_MIN: taker_fee_divisor does not meet minimum threshold.
E_EMPTY_FEE_STORE_TIERS: integrator_fee_store_tiers_ref indicates an empty vector.
E_TOO_MANY_TIERS: integrator_fee_store_tiers_ref indicates a vector that is too long.

Testing

test_set_incentive_params_range_check_inputs_custodian_fee()
test_set_incentive_params_range_check_inputs_divisor()
test_set_incentive_params_range_check_inputs_market_fee()
test_set_incentive_params_range_check_inputs_not_econia()
test_set_incentive_params_range_check_inputs_underwriter()
test_set_incentive_params_range_check_inputs_vector_empty()
test_set_incentive_params_range_check_inputs_vector_long()

fun set_incentive_parameters_range_check_inputs(econia: &signer, market_registration_fee: u64, underwriter_registration_fee: u64, custodian_registration_fee: u64, taker_fee_divisor: u64, integrator_fee_store_tiers_ref: &vector<vector<u64>>)

Implementation

fun set_incentive_parameters_range_check_inputs(
    econia: &signer,
    market_registration_fee: u64,
    underwriter_registration_fee: u64,
    custodian_registration_fee: u64,
    taker_fee_divisor: u64,
    integrator_fee_store_tiers_ref: &vector<vector<u64>>
) {
    // Assert signer is from Econia account.
    assert!(address_of(econia) == @econia, E_NOT_ECONIA);
    // Assert market registration fee meets minimum threshold.
    assert!(market_registration_fee >= MIN_FEE,
        E_MARKET_REGISTRATION_FEE_LESS_THAN_MIN);
    // Assert underwriter registration fee meets minimum threshold.
    assert!(underwriter_registration_fee >= MIN_FEE,
        E_UNDERWRITER_REGISTRATION_FEE_LESS_THAN_MIN);
    // Assert custodian registration fee meets minimum threshold.
    assert!(custodian_registration_fee >= MIN_FEE,
        E_CUSTODIAN_REGISTRATION_FEE_LESS_THAN_MIN);
    // Assert taker fee divisor is meets minimum threshold.
    assert!(taker_fee_divisor >= MIN_DIVISOR,
        E_TAKER_DIVISOR_LESS_THAN_MIN);
    // Assert integrator fee store parameters vector not empty.
    assert!(!vector::is_empty(integrator_fee_store_tiers_ref),
        E_EMPTY_FEE_STORE_TIERS);
    // Assert integrator fee store parameters vector not too long.
    assert!(vector::length(integrator_fee_store_tiers_ref) <=
        MAX_INTEGRATOR_FEE_STORE_TIERS, E_TOO_MANY_TIERS);
}

Function `withdraw_econia_fees_internal`

Withdraw all fee coins from an EconiaFeeStore for given QuoteCoinType and market_id if all is true, otherwise withdraw amount (which may correspond to all coins), aborting if account is not Econia.

Aborts

E_NOT_ECONIA: account is not Econia account.

fun withdraw_econia_fees_internal<QuoteCoinType>(account: &signer, market_id: u64, all: bool, amount: u64): coin::Coin<QuoteCoinType>

Implementation

fun withdraw_econia_fees_internal<QuoteCoinType>(
    account: &signer,
    market_id: u64,
    all: bool,
    amount: u64
): coin::Coin<QuoteCoinType>
acquires
    EconiaFeeStore
{
    // Assert account is Econia.
    assert!(address_of(account) == @econia, E_NOT_ECONIA);
    // Get fee account address.
    let fee_account_address = resource_account::get_address();
    // Borrow mutable reference to Econia fee store map for given
    // quote coin type.
    let econia_fee_store_map_ref_mut =
        &mut borrow_global_mut<EconiaFeeStore<QuoteCoinType>>(
            fee_account_address).map;
    // Borrow mutable reference to fees for given market ID.
    let fee_coins_ref_mut = tablist::borrow_mut(
        econia_fee_store_map_ref_mut, market_id);
    // If flagged to extract all, extract all and return.
    if (all) coin::extract_all(fee_coins_ref_mut) else
        // Else extract specified amount and return.
        coin::extract(fee_coins_ref_mut, amount)
}

Function `withdraw_econia_fees_to_coin_store_internal`

Wrapped call to withdraw_econia_fees_internal(), for depositing withdrawn coins to an aptos_framework::coin::CoinStore.

Testing

test_withdraw_to_coin_store_econia()

fun withdraw_econia_fees_to_coin_store_internal<QuoteCoinType>(econia: &signer, market_id: u64, all: bool, amount: u64)

Implementation

fun withdraw_econia_fees_to_coin_store_internal<QuoteCoinType>(
    econia: &signer,
    market_id: u64,
    all: bool,
    amount: u64
) acquires EconiaFeeStore {
    // Withdraw coins from fee store, verifying Econia signer.
    let coins = withdraw_econia_fees_internal<QuoteCoinType>(
        econia, market_id, all, amount);
    // If Econia does not have coin store for coin type:
    if (!coin::is_account_registered<QuoteCoinType>(@econia))
        // Register one.
        coin::register<QuoteCoinType>(econia);
    // Deposit quote coins to coin store under Econia account.
    coin::deposit(@econia, coins);
}

Function `withdraw_utility_coins_internal`

Withdraw all utility coins from the UtilityCoinStore if all is true, otherwise withdraw amount (which may correspond to all coins), aborting if account is not Econia.

Aborts

E_NOT_ECONIA: account is not Econia account.

fun withdraw_utility_coins_internal<UtilityCoinType>(account: &signer, all: bool, amount: u64): coin::Coin<UtilityCoinType>

Implementation

fun withdraw_utility_coins_internal<UtilityCoinType>(
    account: &signer,
    all: bool,
    amount: u64
): coin::Coin<UtilityCoinType>
acquires
    UtilityCoinStore
{
    // Assert account is Econia.
    assert!(address_of(account) == @econia, E_NOT_ECONIA);
    // Get fee account address.
    let fee_account_address = resource_account::get_address();
    // Borrow mutable reference to coins in utility coin store.
    let utility_coins_ref_mut =
        &mut borrow_global_mut<UtilityCoinStore<UtilityCoinType>>(
            fee_account_address).coins;
    // If flagged to extract all, extract all and return.
    if (all) coin::extract_all(utility_coins_ref_mut) else
        // Else extract specified amount and return.
        coin::extract(utility_coins_ref_mut, amount)
}

Function `withdraw_utility_coins_to_coin_store_internal`

Wrapped call to withdraw_utility_coins_internal(), for depositing withdrawn coins to an aptos_framework::coin::CoinStore.

Testing

test_withdraw_to_coin_store_econia()

fun withdraw_utility_coins_to_coin_store_internal<UtilityCoinType>(econia: &signer, all: bool, amount: u64)

Implementation

fun withdraw_utility_coins_to_coin_store_internal<UtilityCoinType>(
    econia: &signer,
    all: bool,
    amount: u64
) acquires UtilityCoinStore {
    // Withdraw coins from fee store, verifying Econia signer.
    let coins = withdraw_utility_coins_internal<UtilityCoinType>(
        econia, all, amount);
    // If Econia does not have coin store for coin type:
    if (!coin::is_account_registered<UtilityCoinType>(@econia))
        // Register one.
        coin::register<UtilityCoinType>(econia);
    // Deposit utility coins to coin store under Econia account.
    coin::deposit(@econia, coins);
}

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

incentives.md

incentives.md

Module `0xc0deb00c::incentives`

General overview sections

Incentive model

Functions

View functions

Public getters

Other public functions

Public entry functions

Public friend functions

Dependency charts

Incentive parameter setters

Econia fee account operations

Registrant operations

Integrator operations

Match operations

Complete DocGen index

Show all the modules that "incentives" depends on directly or indirectly

Show all the modules that depend on "incentives" directly or indirectly

Resource `EconiaFeeStore`

Fields

Resource `IncentiveParameters`

Fields

Struct `IntegratorFeeStore`

Fields

Resource `IntegratorFeeStores`

Fields

Struct `IntegratorFeeStoreTierParameters`

Fields

Resource `UtilityCoinStore`

Files

incentives.md

Latest commit

History

incentives.md

File metadata and controls

Module 0xc0deb00c::incentives

General overview sections

Incentive model

Functions

View functions

Public getters

Other public functions

Public entry functions

Public friend functions

Dependency charts

Incentive parameter setters

Econia fee account operations

Registrant operations

Integrator operations

Match operations

Complete DocGen index

Show all the modules that "incentives" depends on directly or indirectly

Show all the modules that depend on "incentives" directly or indirectly

Resource EconiaFeeStore

Fields

Resource IncentiveParameters

Fields

Struct IntegratorFeeStore

Fields

Resource IntegratorFeeStores

Fields

Struct IntegratorFeeStoreTierParameters

Fields

Resource UtilityCoinStore

Module `0xc0deb00c::incentives`

Resource `EconiaFeeStore`

Resource `IncentiveParameters`

Struct `IntegratorFeeStore`

Resource `IntegratorFeeStores`

Struct `IntegratorFeeStoreTierParameters`

Resource `UtilityCoinStore`