Vortex Reward Calculation

This guide will explain how developers can interact with the Vortex Pallet, focusing on the key concepts, API integration, and real-world usage.

Vortex Pallet

Overview

The Vortex Distribution Pallet is a module that manages the distribution of Vortex tokens within a blockchain network. It handles the creation, management, and execution of distribution cycles including reward calculation based on effective balances and work points.

Key Features

Create and manage distribution cycles
Set distribution parameters (eras, asset lists, asset prices)
Register rewards and effective balances
Trigger distribution calculations
Execute token distributions
Redeem tokens from a vault

Configuration

The pallet uses the following configuration traits:

Config: The main configuration trait, extending frame_system::Config and pallet_staking::Config.
MultiCurrency: Handles multi-currency operations.
NativeAssetId: The asset ID of the native token.
VtxAssetId: The asset ID of the Vortex token.
VtxHeldPotId, VtxDistPotId, RootPotId, TxFeePotId: Various pot IDs for managing funds.
UnsignedInterval: Interval for unsigned transactions.
PayoutBatchSize: Batch size for payouts.
MaxAssetPrices, MaxRewards, MaxStringLength: Maximum limits for various operations.
VtxDistIdentifier: Identifier type for Vortex distributions.
HistoryDepth: Depth of historical data to maintain.

Main Functions

Extrinsics

set_admin: Set the admin account for the pallet.
create_vtx_dist: Create a new Vortex distribution cycle.
disable_vtx_dist: Disable an existing distribution cycle.
start_vtx_dist: Start a triggered distribution cycle.
pay_unsigned: Execute unsigned payouts for a distribution cycle.
set_vtx_dist_eras: Set the start and end eras for a distribution cycle.
set_assets_list: Set the list of assets for a distribution cycle.
set_asset_prices: Set asset prices for a distribution cycle.
register_rewards: Register rewards for a distribution cycle.
register_eff_bal_n_wk_pts: Register effective balances and work points for accounts.
trigger_vtx_distribution: Trigger the calculation phase of a distribution cycle.
redeem_tokens_from_vault: Allow users to redeem tokens from the vault.

Internal Functions

do_disable_vtx_dist: Internal logic for disabling a distribution.
do_start_vtx_dist: Internal logic for starting a distribution.
do_assets_list_setter: Internal logic for setting the assets list.
do_asset_price_setter: Internal logic for setting asset prices.
do_collate_reward_tokens: Collate reward tokens into the vault account.
do_reward_calculation: Calculate rewards for each account.
vtx_dist_offchain_worker: Offchain worker logic for unsigned transactions.
safe_transfer: Safely transfer tokens between accounts.

Storage Items

AdminAccount: The admin account for the pallet.
NextVortexId: The next available Vortex distribution ID.
VtxDistStatuses: Status of each Vortex distribution.
VtxDistEras: Start and end eras for each distribution.
VtxDistOrderbook: Order book for each distribution.
RootAssetPrice: Root asset price for each distribution.
AssetsList: List of assets for each distribution.
AssetPrices: Asset prices for each distribution.
EffectiveBalancesWorkPoints: Effective balances and work points for accounts.
PenaltyEffectiveBalancesWorkPoints: Penalty balances and work points for accounts.
TotalNetworkReward, TotalBootstrapReward, TotalVortex: Total rewards for each distribution.
TotalEffectiveBalanceEra, TotalWorkPointsEra: Total balances and work points per era.
AccountTotalEffectiveBalance, AccountTotalWorkPoints: Total balances and work points per account.
NextUnsignedAt: Next block number for unsigned transactions.
VtxDistPayoutPivot: Payout pivot for each distribution.

Events

AdminAccountChanged: Admin account has been changed.
RewardRegistered: Rewards have been registered for a distribution.
VtxDistCreated: A new Vortex distribution has been created.
VtxDistDisabled: A Vortex distribution has been disabled.
VtxDistDone: A Vortex distribution has completed.
VtxDistPaidOut: A payout has been made for a Vortex distribution.
VtxDistStarted: A Vortex distribution has started.
SetVtxDistEras: Distribution eras have been set.
SetAssetsList: Assets list has been set for a distribution.
SetAssetPrices: Asset prices have been set for a distribution.
TriggerVtxDistribution: A Vortex distribution calculation has been triggered.

Errors

The pallet defines various error types to handle different failure scenarios, such as:

RequireAdmin: Action requires admin privileges.
VtxDistIdNotAvailable: No available distribution ID.
VtxDistAlreadyEnabled: Distribution is already enabled.
VtxDistDisabled: Distribution is disabled.
InvalidEndBlock: Invalid end block specified.
NoVtxAssetMinted: No Vortex asset has been minted.
InvalidAmount: Invalid amount specified.
VtxDistIdInUse: Distribution ID is already in use.
NotAValidator: Action requires validator status.
VortexPeriodNotSet: Vortex period has not been set.
PivotStringTooLong: Pivot string exceeds maximum length.
AssetsShouldNotIncludeVtxAsset: Assets list should not include Vortex asset.
CannotTrigger: Distribution cannot be triggered.
CannotRedeem: Tokens cannot be redeemed.
NotTriggered: Distribution has not been triggered.
MismatchedBalancesAndPointsLength: Mismatched lengths of balances and points vectors.
MismatchedBalancesAndRatesLength: Mismatched lengths of balances and rates vectors.
MismatchedAccountIdLists: Mismatched account ID lists.
ExceededMaxRewards: Exceeded maximum number of rewards.
WrongEra: Incorrect era specified.
AssetNotInList: Asset is not in the assets list.
VortexPriceIsZero: Vortex price is zero.
RootPriceIsZero: Root price is zero.

Usage

To use this pallet, include it in your runtime and configure it according to your network's requirements. Ensure that you have set up the necessary multi-currency support and configured the various pot accounts and asset IDs correctly.

The typical flow for a Vortex distribution would be:

Create a distribution using create_vtx_dist.
Set the distribution eras with set_vtx_dist_eras.
Set the assets list and prices using set_assets_list and set_asset_prices.
Register rewards and effective balances using register_rewards and register_eff_bal_n_wk_pts.
Trigger the distribution calculation with trigger_vtx_distribution.
Start the distribution using start_vtx_dist.
The pallet will automatically handle payouts through the offchain worker.
Users can redeem their tokens using redeem_tokens_from_vault.

Ensure that you have the necessary permissions (root or admin) to perform administrative actions on the pallet.

Vortex Token Determination and Reward Calculation

Vortex Token Determination

The vortex token amount is determined through a process that involves collating reward tokens and calculating their value. Here's how it works:

Collating Reward Tokens:
- Assets from the fee vault and root vault are transferred to the main vault account.
- The total value of these assets is calculated based on their prices.

Calculating Vortex Price:

vault_total_assets_root_value = vault_asset_value + vault_root_value
existing_vortex_supply = total_issuance(VtxAssetId)

vortex_price = if existing_vortex_supply == 0:
                  1
               else:
                  vault_total_assets_root_value / existing_vortex_supply

Determining Total Vortex Amount:

total_vortex_network_reward = (fee_vault_asset_value + fee_vault_root_value) / vortex_price
total_vortex_bootstrap = root_vault_root_value / vortex_price

total_vortex = total_vortex_network_reward + total_vortex_bootstrap

Vortex Reward Calculation

The vortex reward for each wallet address is calculated based on their effective balance and work points. Here's the process:

Accumulating Total Effective Balance and Work Points:
- For each era in the distribution period, the system accumulates:
  - Total effective balance (total_effective_balance)
  - Total work points (total_work_points)
  - Individual account's effective balance and work points

Calculating Reward Portions: For each account:

balance_portion = account_total_effective_balance / total_effective_balance
work_points_portion = account_total_work_points / total_work_points

Network Reward Calculation:

ind_vortex_balance_network_reward = balance_portion * 30% * total_vortex_network_reward
ind_vortex_wk_points_network_reward = work_points_portion * 70% * total_vortex_network_reward

ind_vortex_network_reward = ind_vortex_balance_network_reward + ind_vortex_wk_points_network_reward

Bootstrap Reward Calculation:

ind_vortex_bootstrap_reward = balance_portion * total_vortex_bootstrap_reward

Final Reward Calculation:

final_reward = ind_vortex_network_reward + ind_vortex_bootstrap_reward

This final reward amount is then added to the existing reward (if any) for the account in the VtxDistOrderbook.

The calculation ensures that rewards are distributed based on both the effective balance (30% for network rewards, 100% for bootstrap rewards) and work points (70% for network rewards) of each account, providing a balanced incentive structure for participants in the network.

Vortex Reward Validator

The Validator node is used to validate and submit calculated results to Blockchain. It contains the following components:

Effective Balance
This component verifies signed data originating from the calculator and subsequently submits it to the Blockchain.
```
 // Create the transaction
 const tx = this.api.tx.vortexDistribution.registerEffBalNWkPts(id, era, balances, null, null);
```

Rates

Similarly, it validates signed data from the calculator and facilitates its submission to the Blockchain.

// Create the transaction
const tx = this.api.tx.vortexDistribution.registerEffBalNWkPts(id, era, null, null, rates);

Work Points
This component retrieves work points, computes the associated balance, and ensures submission to the Blockchain.
```
// Create the transaction
const tx = this.api.tx.vortexDistribution.registerEffBalNWkPts(id, era, null, points, null);
```

It's noteworthy that we leverage a unified Pallet for these operations, optimizing data transmission to the Blockchain and thereby reducing its operational load.

Signature Verification

Validating signatures necessitates the deployment of a KMS key, utilized by both the validator and calculator nodes. The following parameters are pivotal in this process:

    // Sign the digest
    const signParams = {
        KeyId: this.keyArn,
        Message: digest,
        MessageType: MessageType.DIGEST,
        SigningAlgorithm: SigningAlgorithmSpec.RSASSA_PKCS1_V1_5_SHA_256 // Signing algorithm
    };

Transaction Authorization

To execute transactions on the Blockchain, secure management of a designated wallet's secret key (SK) is imperative. Access to and utilization of this SK is confined exclusively to the validator node.

Effective Balance

Effective Balance is the balance that the user holds during a specific period of time or a range of blocks in order to calculate the interest of the period or block range that the user obtains.

Given the 90 Eras per reward cycle, based on the users’ transaction type bonded(same as a deposit) and withdrawn, users’ transactions can be used to figure out what balance and balance change are in the certain period of block ranges as well as in the certain Era. For example, if each Era has 10 blocks, the cycle starts from block 0 and user A deposits 10 $Root at block 1, as the Era 0 is from block 0 to 9, it is easy to figure out that the balance of 10 $Root takes over 9 blocks from block 1 to block 9. And if user A keeps the balance to Era 3, in the whole Era 2, the user A’s balance is 10 $Root.

Balance Change and Effective Era

For all the bonded and withdrawn transactions within the block range of the reward cycle, the balanceChange will hold a negative value for withdrawals and a positive value for deposits.

Effective block is the number of blocks that are effectively within the balance change and era ranges.

Effective era is the fraction of the era that is effectively covered by the balance change.

Example Scenario

To illustrate how this works, consider the following example values:

balance change.StartBlock = 5
balance change.EndBlock = 15
era.StartBlock = 10
era.EndBlock = 20

Determine Start and End Block: var startBlock = Math.Max(5, 10); // startBlock = 10 var endBlock = Math.Min(15, 20); // endBlock = 15 The overlapping range between change and era is from block 10 to block 15.
Calculate Effective Blocks: var effectiveBlocks = 15 - 10 + 1; // effectiveBlocks = 6 There are 6 blocks within this overlapping range.
Calculate Total Blocks in Era: var totalBlocksInEra = 20 - 10 + 1; // totalBlocksInEra = 11 The total number of blocks in the era is 11.
Calculate Effective Eras: var effectiveEras = new decimal(6) / new decimal(11); // effectiveEras ≈ 0.545454545454545 The fraction of the era that is effectively covered by the change is approximately 0.545 (or 54.5%).

PreviousBecome a Validator NextNetwork Status

Last updated 28 days ago