Skip to content

Latest commit

 

History

History
4048 lines (2522 loc) · 156 KB

incentives.md

File metadata and controls

4048 lines (2522 loc) · 156 KB

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

Dependency charts

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:

  1. The utility coin type.
  2. The fee, denominated in the utility coin, to register a market.
  3. The fee, denominated in the utility coin, to register as an underwriter for a generic market.
  4. The fee, denominated in the utility coin, to register as custodian.
  5. 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:

  1. 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.
  2. The cumulative fee, denominated in the utility coin, to activate to the given tier.
  3. 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:

Functions

View functions

Public getters

Other public functions

Public entry functions

Public friend functions

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:

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