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, extendingframe_system::Config
andpallet_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
andset_asset_prices
.Register rewards and effective balances using
register_rewards
andregister_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:
Determining Total Vortex Amount:
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:
Network Reward Calculation:
Bootstrap Reward Calculation:
Final Reward Calculation:
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.Rates
Similarly, it validates signed data from the
calculator
and facilitates its submission to the Blockchain.Work Points
This component retrieves work points, computes the associated balance, and ensures submission to the Blockchain.
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:
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%).
Last updated