Rewards System Architecture
The Revenue module’s primary responsibility is to assess validator performance, calculate appropriate compensation, and distribute rewards according to configurable schedules. The system leverages real-time performance data and price information to ensure fair and timely compensation. The Revenue module operates through a continuous cycle of performance monitoring, assessment, and reward distribution. During each block, the system updates reward asset prices, processes validator participation data, and checks whether it’s time to distribute payments based on the configured schedule.Performance Assessment
Validators are evaluated on two critical metrics:- Block Production Participation: The percentage of blocks signed during the payment period
- Oracle Price Submissions: The percentage of oracle votes provided during the payment period
Performance Requirements
The module uses two configurable thresholds to determine reward eligibility:- Required At Least: The minimum performance required on both metrics to qualify for any rewards
- Allowed To Miss: The maximum percentage of misses allowed to still receive full rewards
Performance Rating Breakdown
The performance rating system has three zones based on validator performance: Zone 1: No Rewards (0.0 rating)- If either block participation OR oracle participation falls below the “required at least” threshold
- Example: If required_at_least = 90%, and validator signs only 88% of blocks → 0.0 rating (no rewards)
- Performance falls between “required at least” and “allowed to miss” thresholds
- Rating calculated using quadratic formula:
0.5 * ((1 - missedBlocksPerfQuo²) + (1 - missedOracleVotesPerfQuo²))
- The quadratic curve provides gentler penalties for validators near the “allowed to miss” threshold
- Both block participation AND oracle participation meet or exceed the “allowed to miss” threshold
- Example: If allowed_to_miss = 5%, and validator misses only 3% of blocks and 2% of oracle votes → 1.0 rating (full rewards)
Example with real thresholds:
required_at_least
= 90% (must sign at least 90% to get any rewards)allowed_to_miss
= 5% (can miss up to 5% and still get full rewards)- Partial reward zone: 90-95% performance
Calculation of Performance Quotients
BothmissedBlocksPerfQuo
and missedOracleVotesPerfQuo
are calculated using the same algorithm. The module uses the calCMissedPerfQuo
function to determine how much a validator’s performance falls within the partial performance range:
- Check Full Performance: If
missedShare <= allowedToMiss
, return 0.0 (no penalty, full rewards) - Calculate Excess Misses:
finedMissedShare = missedShare - allowedToMiss
(how much over the allowed threshold) - Calculate Evaluation Window:
perfEvalWindow = perfThreshold - allowedToMiss
(the range for partial performance) - Calculate Performance Quotient:
missedPerfQuo = finedMissedShare / perfEvalWindow
(normalized position within partial range)
- 0.0 = performance at the “allowed to miss” threshold (full rewards)
- 1.0 = performance at the “required at least” threshold (no rewards)
Payment Scheduling
The module supports multiple payment schedule types:- Monthly: Rewards are distributed at the beginning of each calendar month
- Block-Based: Rewards are distributed after a specified number of blocks
- Empty: No rewards are distributed (used for testing or disabling payments)
- The schedule type in the module parameters (controllable by governance)
- The schedule state in the module’s store (updated automatically)
- Calculates each validator’s performance rating
- Determines the reward amount in the reward asset
- Transfers rewards to eligible validators
- Resets performance metrics for the new period
Price Calculation
Rewards are defined in USD terms but paid in the token specified in module parameters. To accurately convert between USD and token amounts, the module:- Tracks the cumulative price of the reward asset in each block
- Calculates the Time-Weighted Average Price (TWAP) over a configurable window
- Uses this TWAP to determine the exact token amount equivalent to the USD reward
Treasury Management
The Revenue module maintains a treasury account that holds funds for validator compensation. This treasury:- Receives funds through the
FundTreasury
message - Automatically pays validators at the end of each payment period
- Can be managed through governance decisions