@orderly.network/trading-points 1.0.1-rc.0 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +75 -159
  2. package/package.json +9 -9
package/README.md CHANGED
@@ -1,181 +1,97 @@
1
- # Rewards Calculation Module
1
+ # Trading Points Module
2
2
 
3
- This module provides functionality for calculating estimated rewards and estimated tickets earned.
3
+ This module provides a complete points system implementation for trading campaigns, including points tracking, leaderboards, referral links, and stage management.
4
4
 
5
5
  ## Features
6
6
 
7
- ### 1. Estimated Rewards
7
+ - 📊 **Points Dashboard**: Display user's trading points, PnL points, and referral points
8
+ - 🏆 **Leaderboard**: Show rankings with support for different time ranges (this week, last week, all time)
9
+ - 🎯 **Campaign Stages**: Support multiple campaign stages with different statuses (active, pending, completed)
10
+ - 🔗 **Referral System**: Generate and share referral links and codes
11
+ - ⏱️ **Countdown Timer**: Display countdown for pending campaigns
8
12
 
9
- - Supports multiple prize pool configurations
10
- - Supports different metrics based on trading volume and PnL (Profit and Loss)
11
- - Supports fixed position rewards and position range rewards
12
- - Automatically estimates user ranking and calculates corresponding rewards
13
+ ## Basic Usage
13
14
 
14
- ### 2. Estimated Tickets
15
+ ### Simple Integration
15
16
 
16
- - Supports tiered mode: Awards different ticket amounts based on different trading volume tiers
17
- - Supports linear mode: Earn Y tickets for every X trading volume
17
+ ```tsx
18
+ import { PointSystemPage } from "@orderly.network/trading-points";
18
19
 
19
- ## Type Definitions
20
+ function MyApp() {
21
+ const handleRouteChange = (option) => {
22
+ // Handle navigation
23
+ console.log("Navigate to:", option.href);
24
+ };
20
25
 
21
- ### Prize Pool Configuration
22
-
23
- ```typescript
24
- interface PrizePool {
25
- pool_id: string; // Prize pool ID
26
- label: string; // Prize pool label
27
- total_prize: number; // Total prize amount
28
- currency: string; // Reward currency
29
- metric: "volume" | "pnl"; // Evaluation metric
30
- tiers: PrizePoolTier[]; // Tier configuration
31
- }
32
- ```
33
-
34
- ### Ticket Rules
35
-
36
- ```typescript
37
- interface TicketRules {
38
- total_prize: number; // Total ticket prize amount
39
- currency: string; // Currency
40
- metric: "volume" | "pnl"; // Evaluation metric
41
- mode: "tiered" | "linear"; // Mode
42
- tiers?: TicketTierRule[]; // Tiered mode configuration
43
- linear?: TicketLinearRule; // Linear mode configuration
44
- }
45
- ```
46
-
47
- ## Usage Examples
48
-
49
- ### Basic Usage
50
-
51
- ```typescript
52
- import {
53
- calculateEstimatedRewards,
54
- calculateEstimatedTickets,
55
- CampaignConfig,
56
- UserData,
57
- } from "./utils";
58
-
59
- const userdata: UserData = {
60
- account_id: "user_001",
61
- trading_volume: 50000,
62
- pnl: 1500,
63
- current_rank: 5,
64
- total_participants: 1000,
65
- };
66
-
67
- const campaign: CampaignConfig = {
68
- // ... campaign configuration
69
- };
70
-
71
- // Calculate estimated rewards
72
- const rewards = calculateEstimatedRewards(userdata, campaign);
73
- console.log(`Estimated rewards: ${rewards?.amount} ${rewards?.currency}`);
74
-
75
- // Calculate estimated tickets
76
- if (campaign.ticket_rules) {
77
- const tickets = calculateEstimatedTickets(userdata, campaign.ticket_rules);
78
- console.log(`Estimated tickets: ${tickets}`);
26
+ return <PointSystemPage onRouteChange={handleRouteChange} />;
79
27
  }
80
28
  ```
81
29
 
82
- ### Usage in React Components
83
-
84
- ```typescript
85
- import { RewardsDesktopUI } from './rewards.desktop.ui';
30
+ ## Advanced Usage
31
+
32
+ ### Using the Points Hook
33
+
34
+ The `usePoints` hook provides access to all points-related data and methods:
35
+
36
+ ```tsx
37
+ import { usePoints } from "@orderly.network/trading-points";
38
+
39
+ function CustomPointsComponent() {
40
+ const {
41
+ stages, // All campaign stages
42
+ userStatistics, // User's points statistics
43
+ currentStage, // Currently selected stage
44
+ setCurrentStage, // Function to change stage
45
+ isLoading, // Loading state
46
+ isNoCampaign, // Whether there's no active campaign
47
+ refLink, // Referral link
48
+ refCode, // Referral code
49
+ selectedTimeRange, // Current time range filter
50
+ setSelectedTimeRange, // Function to change time range
51
+ pointsDisplay, // Formatted points display data
52
+ allTimePointsDisplay, // All-time points display data
53
+ isCurrentStagePending, // Whether current stage is pending
54
+ isCurrentStageCompleted, // Whether current stage is completed
55
+ getRankingUrl, // Function to get ranking API URL
56
+ } = usePoints();
86
57
 
87
- function MyComponent() {
88
58
  return (
89
- <RewardsDesktopUI
90
- campaign={campaignConfig}
91
- userdata={userData}
92
- />
59
+ <div>
60
+ <h2>Total Points: {pointsDisplay.currentPointsDisplay}</h2>
61
+ <p>Trading Points: {pointsDisplay.tradingPointsDisplay}</p>
62
+ <p>PnL Points: {pointsDisplay.pnlPointsDisplay}</p>
63
+ <p>Referral Points: {pointsDisplay.referralPointsDisplay}</p>
64
+ <p>Rank: {pointsDisplay.rankingDisplay}</p>
65
+ </div>
93
66
  );
94
67
  }
95
68
  ```
96
69
 
97
- ## Configuration Examples
98
-
99
- ### Tiered Mode Ticket Configuration
100
-
101
- ```typescript
102
- ticket_rules: {
103
- total_prize: 2000,
104
- currency: "WIF",
105
- metric: "volume",
106
- mode: "tiered",
107
- tiers: [
108
- { value: 25000, tickets: 10 }, // ≥ 25,000 volume → 10 tickets
109
- { value: 10000, tickets: 5 }, // ≥ 10,000 volume → 5 tickets
110
- { value: 5000, tickets: 1 } // ≥ 5,000 volume → 1 ticket
111
- ]
112
- }
113
- ```
114
-
115
- ### Linear Mode Ticket Configuration
116
-
117
- ```typescript
118
- ticket_rules: {
119
- total_prize: 1000,
120
- currency: "WIF",
121
- metric: "volume",
122
- mode: "linear",
123
- linear: {
124
- every: 5000, // Every 5000 trading volume
125
- tickets: 1 // Earn 1 ticket
126
- }
127
- }
128
- ```
129
-
130
- ### Prize Pool Configuration Example
131
-
132
- ```typescript
133
- prize_pools: [
134
- {
135
- pool_id: "general",
136
- label: "General Pool",
137
- total_prize: 10000,
138
- currency: "USDC",
139
- metric: "volume",
140
- tiers: [
141
- { position: 1, amount: 3000 }, // 1st place: 3000 USDC
142
- { position: 2, amount: 2000 }, // 2nd place: 2000 USDC
143
- { position: 3, amount: 1000 }, // 3rd place: 1000 USDC
144
- { position_range: [4, 10], amount: 500 }, // 4th-10th place: 500 USDC each
145
- { position_range: [11, 50], amount: 100 }, // 11th-50th place: 100 USDC each
146
- ],
147
- },
148
- ];
149
- ```
150
-
151
- ## Calculation Logic
152
-
153
- ### Ranking Estimation
70
+ ## Components Overview
154
71
 
155
- The system estimates user ranking based on trading performance:
72
+ ### Main Components
156
73
 
157
- - If `current_rank` is provided, it is used directly
158
- - Otherwise, a simple estimation is made based on trading volume/PnL:
159
- - ≥ 100,000: Rank 1
160
- - ≥ 50,000: Top 5%
161
- - ≥ 10,000: Top 20%
162
- - ≥ 1,000: Top 50%
163
- - < 1,000: Bottom 80%
74
+ - **PointSystemPage**: The main entry point component
75
+ - **Countdown**: Displays countdown timer for pending campaigns
76
+ - **Intro**: Shows campaign introduction and stage selection
77
+ - **User**: Displays user's points, stats, and referral information
78
+ - **GeneralLeaderboardWidget**: Shows the leaderboard/rankings
164
79
 
165
- ### Reward Calculation
80
+ ### Internal Structure
166
81
 
167
- 1. Iterate through all prize pools
168
- 2. Get user data based on the pool's metric (volume/pnl)
169
- 3. Estimate user ranking for that metric
170
- 4. Find matching tier and accumulate rewards
171
-
172
- ### Ticket Calculation
173
-
174
- - **Tiered Mode**: Find the highest tier that matches the user's trading volume
175
- - **Linear Mode**: Calculate proportionally using `Math.floor(volume / every) * tickets`
176
-
177
- ## Important Notes
178
-
179
- 1. Ranking estimation is based on simplified logic; it's recommended to use real leaderboard data in actual applications
180
- 2. When user trading volume or PnL is 0 or negative, some calculations may return empty results
181
- 3. It's recommended to integrate real API data sources in production environments
82
+ ```
83
+ pages/points/
84
+ ├── page.tsx # Main page component
85
+ ├── main.tsx # Layout and composition
86
+ ├── countdown.tsx # Countdown timer
87
+ ├── intro.tsx # Campaign intro
88
+ ├── user.tsx # User stats
89
+ └── faq.tsx # FAQ section
90
+
91
+ components/
92
+ ├── leaderboard/ # Leaderboard components
93
+ └── ranking/ # Ranking components
94
+
95
+ hooks/
96
+ └── usePointsData/ # Points data management
97
+ ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@orderly.network/trading-points",
3
- "version": "1.0.1-rc.0",
3
+ "version": "1.0.1",
4
4
  "description": "",
5
5
  "main": "dist/index.js",
6
6
  "module": "dist/index.mjs",
@@ -15,13 +15,13 @@
15
15
  "dependencies": {
16
16
  "date-fns": "^3.6.0",
17
17
  "ramda": "^0.29.0",
18
- "@orderly.network/hooks": "2.8.12-rc.0",
19
- "@orderly.network/types": "2.8.12-rc.0",
20
- "@orderly.network/react-app": "2.8.12-rc.0",
21
- "@orderly.network/i18n": "2.8.12-rc.0",
22
- "@orderly.network/ui": "2.8.12-rc.0",
23
- "@orderly.network/ui-connector": "2.8.12-rc.0",
24
- "@orderly.network/utils": "2.8.12-rc.0"
18
+ "@orderly.network/hooks": "2.8.13",
19
+ "@orderly.network/react-app": "2.8.13",
20
+ "@orderly.network/i18n": "2.8.13",
21
+ "@orderly.network/ui": "2.8.13",
22
+ "@orderly.network/types": "2.8.13",
23
+ "@orderly.network/ui-connector": "2.8.13",
24
+ "@orderly.network/utils": "2.8.13"
25
25
  },
26
26
  "devDependencies": {
27
27
  "@babel/core": "^7.22.9",
@@ -35,7 +35,7 @@
35
35
  "tailwindcss": "^3.4.4",
36
36
  "tsup": "^7.1.0",
37
37
  "typescript": "^5.1.6",
38
- "tsconfig": "0.11.12-rc.0"
38
+ "tsconfig": "0.11.13"
39
39
  },
40
40
  "peerDependencies": {
41
41
  "react": ">=18",