@orderly.network/trading-leaderboard
v3.4.1
Published
Keywords
Readme
Rewards Calculation Module
This module provides functionality for calculating estimated rewards and estimated tickets earned.
Features
1. Estimated Rewards
- Supports multiple prize pool configurations
- Supports different metrics based on trading volume and PnL (Profit and Loss)
- Supports fixed position rewards and position range rewards
- Automatically estimates user ranking and calculates corresponding rewards
2. Estimated Tickets
- Supports tiered mode: Awards different ticket amounts based on different trading volume tiers
- Supports linear mode: Earn Y tickets for every X trading volume
Type Definitions
Prize Pool Configuration
interface PrizePool {
pool_id: string; // Prize pool ID
label: string; // Prize pool label
total_prize: number; // Total prize amount
currency: string; // Reward currency
metric: "volume" | "pnl"; // Evaluation metric
tiers: PrizePoolTier[]; // Tier configuration
}Ticket Rules
interface TicketRules {
total_prize: number; // Total ticket prize amount
currency: string; // Currency
metric: "volume" | "pnl"; // Evaluation metric
mode: "tiered" | "linear"; // Mode
tiers?: TicketTierRule[]; // Tiered mode configuration
linear?: TicketLinearRule; // Linear mode configuration
}Usage Examples
Basic Usage
import {
calculateEstimatedRewards,
calculateEstimatedTickets,
CampaignConfig,
UserData,
} from "./utils";
const userdata: UserData = {
account_id: "user_001",
trading_volume: 50000,
pnl: 1500,
current_rank: 5,
total_participants: 1000,
};
const campaign: CampaignConfig = {
// ... campaign configuration
};
// Calculate estimated rewards
const rewards = calculateEstimatedRewards(userdata, campaign);
console.log(`Estimated rewards: ${rewards?.amount} ${rewards?.currency}`);
// Calculate estimated tickets
if (campaign.ticket_rules) {
const tickets = calculateEstimatedTickets(userdata, campaign.ticket_rules);
console.log(`Estimated tickets: ${tickets}`);
}Usage in React Components
import { RewardsDesktopUI } from './rewards.desktop.ui';
function MyComponent() {
return (
<RewardsDesktopUI
campaign={campaignConfig}
userdata={userData}
/>
);
}Configuration Examples
Tiered Mode Ticket Configuration
ticket_rules: {
total_prize: 2000,
currency: "WIF",
metric: "volume",
mode: "tiered",
tiers: [
{ value: 25000, tickets: 10 }, // ≥ 25,000 volume → 10 tickets
{ value: 10000, tickets: 5 }, // ≥ 10,000 volume → 5 tickets
{ value: 5000, tickets: 1 } // ≥ 5,000 volume → 1 ticket
]
}Linear Mode Ticket Configuration
ticket_rules: {
total_prize: 1000,
currency: "WIF",
metric: "volume",
mode: "linear",
linear: {
every: 5000, // Every 5000 trading volume
tickets: 1 // Earn 1 ticket
}
}Prize Pool Configuration Example
prize_pools: [
{
pool_id: "general",
label: "General Pool",
total_prize: 10000,
currency: "USDC",
metric: "volume",
tiers: [
{ position: 1, amount: 3000 }, // 1st place: 3000 USDC
{ position: 2, amount: 2000 }, // 2nd place: 2000 USDC
{ position: 3, amount: 1000 }, // 3rd place: 1000 USDC
{ position_range: [4, 10], amount: 500 }, // 4th-10th place: 500 USDC each
{ position_range: [11, 50], amount: 100 }, // 11th-50th place: 100 USDC each
],
},
];Calculation Logic
Ranking Estimation
The system estimates user ranking based on trading performance:
- If
current_rankis provided, it is used directly - Otherwise, a simple estimation is made based on trading volume/PnL:
- ≥ 100,000: Rank 1
- ≥ 50,000: Top 5%
- ≥ 10,000: Top 20%
- ≥ 1,000: Top 50%
- < 1,000: Bottom 80%
Reward Calculation
- Iterate through all prize pools
- Get user data based on the pool's metric (volume/pnl)
- Estimate user ranking for that metric
- Find matching tier and accumulate rewards
Ticket Calculation
- Tiered Mode: Find the highest tier that matches the user's trading volume
- Linear Mode: Calculate proportionally using
Math.floor(volume / every) * tickets
Important Notes
- Ranking estimation is based on simplified logic; it's recommended to use real leaderboard data in actual applications
- When user trading volume or PnL is 0 or negative, some calculations may return empty results
- It's recommended to integrate real API data sources in production environments
