@kodiak-finance/orderly-trading-leaderboard 2.7.4

package/README.md

@@ -0,0 +1,181 @@
+# 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
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+import { RewardsDesktopUI } from './rewards.desktop.ui';
+
+function MyComponent() {
+  return (
+    <RewardsDesktopUI
+      campaign={campaignConfig}
+      userdata={userData}
+    />
+  );
+}
+```
+
+## Configuration Examples
+
+### Tiered Mode Ticket Configuration
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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_rank` is 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
+
+1. Iterate through all prize pools
+2. Get user data based on the pool's metric (volume/pnl)
+3. Estimate user ranking for that metric
+4. 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
+
+1. Ranking estimation is based on simplified logic; it's recommended to use real leaderboard data in actual applications
+2. When user trading volume or PnL is 0 or negative, some calculations may return empty results
+3. It's recommended to integrate real API data sources in production environments

package/dist/index.d.mts

@@ -0,0 +1,538 @@
+import * as react from 'react';
+import react__default, { FC, ReactNode } from 'react';
+import * as _kodiak_finance_orderly_ui from '@kodiak-finance/orderly-ui';
+import { TableSort } from '@kodiak-finance/orderly-ui';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+type Campaign = {
+    title: string;
+    description: string;
+    image: string;
+    startTime: Date | string;
+    endTime: Date | string;
+    href: string | {
+        /** learn more url */
+        learnMore: string;
+        /** trading url, if provided, will override default trading now button url */
+        trading: string;
+    };
+};
+/**
+ * Trading leaderboard provider state
+ */
+type TradingLeaderboardState$1 = {
+    /** campaigns config, if not provided, will not show campaigns section */
+    campaigns?: Campaign[];
+    /** background src, it can be a image resource or video resource */
+    backgroundSrc?: string;
+    href?: {
+        /** default trading now button url */
+        trading: string;
+    };
+};
+type TradingLeaderboardProviderProps$1 = react__default.PropsWithChildren<TradingLeaderboardState$1>;
+
+type LeaderboardScriptReturn = ReturnType<typeof useLeaderboardScript>;
+type LeaderboardScriptOptions = {
+    backgroundSrc?: string;
+    campaigns?: Campaign[];
+};
+declare function useLeaderboardScript(options: LeaderboardScriptOptions): {
+    backgroundSrc: string | undefined;
+    isVideo: boolean;
+    showCampaigns: boolean;
+    isMobile: boolean;
+};
+
+type LeaderboardProps = {
+    style?: React.CSSProperties;
+    className?: string;
+} & LeaderboardScriptReturn;
+declare const Leaderboard: FC<LeaderboardProps>;
+
+type LeaderboardWidgetProps = TradingLeaderboardProviderProps$1 & Pick<LeaderboardProps, "style" | "className">;
+/**
+ * @deprecated use LeaderboardPage instead
+ * it will be removed in next version
+ */
+declare const LeaderboardWidget: FC<LeaderboardWidgetProps>;
+
+type CampaignsWidgetProps = {
+    className?: string;
+    style?: React.CSSProperties;
+};
+declare const CampaignsWidget: FC<CampaignsWidgetProps>;
+
+type CampaignsScriptReturn = ReturnType<typeof useCampaignsScript>;
+type CategorizedCampaigns = {
+    ongoing: Campaign[];
+    past: Campaign[];
+    future: Campaign[];
+};
+type CurrentCampaigns = Campaign & {
+    displayTime: string;
+    learnMoreUrl: string;
+    tradingUrl: string;
+};
+type TEmblaApi = {
+    scrollTo?: (index: number) => void;
+};
+type CategoryKey = keyof CategorizedCampaigns;
+declare function useCampaignsScript(): {
+    options: {
+        label: string;
+        value: CategoryKey;
+    }[];
+    currentCampaigns: {
+        displayTime: string;
+        learnMoreUrl: string;
+        tradingUrl: string;
+        title: string;
+        description: string;
+        image: string;
+        startTime: Date | string;
+        endTime: Date | string;
+        href: string | {
+            learnMore: string;
+            trading: string;
+        };
+    }[];
+    category: keyof CategorizedCampaigns;
+    onCategoryChange: (value: string) => void;
+    tradingUrl: string | undefined;
+    emblaRef: _kodiak_finance_orderly_ui.EmblaViewportRefType;
+    emblaApi: TEmblaApi;
+    scrollIndex: number;
+    enableScroll: boolean;
+    onLearnMore: (campaign: CurrentCampaigns) => void;
+    onTradeNow: (campaign: CurrentCampaigns) => void;
+};
+
+type CampaignsProps = {
+    className?: string;
+    style?: React.CSSProperties;
+} & CampaignsScriptReturn;
+declare const Campaigns: FC<CampaignsProps>;
+
+type TradingData = {
+    account_id: string;
+    address: string;
+    broker_fee: number;
+    date: string;
+    perp_maker_volume: number;
+    perp_taker_volume: number;
+    perp_volume: number;
+    total_fee: number;
+    key?: string;
+};
+type TradingListScriptReturn = ReturnType<typeof useTradingListScript>;
+declare const FilterDays$1: readonly [7, 14, 30, 90];
+type TFilterDays$1 = (typeof FilterDays$1)[number];
+type DateRange$1 = {
+    from?: Date;
+    to?: Date;
+};
+declare function useTradingListScript(): {
+    pagination: _kodiak_finance_orderly_ui.PaginationMeta;
+    dateRange: DateRange$1;
+    filterDay: 30 | 7 | 14 | 90 | null;
+    updateFilterDay: (day: TFilterDays$1) => void;
+    filterItems: any;
+    onFilter: (filter: {
+        name: string;
+        value: any;
+    }) => void;
+    initialSort: TableSort;
+    onSort: (sort?: TableSort) => void;
+    dataSource: TradingData[];
+    isLoading: boolean;
+    searchValue: string;
+    onSearchValueChange: (value: string) => void;
+    clearSearchValue: () => void;
+    isMobile: boolean;
+    sentinelRef: react.MutableRefObject<HTMLDivElement | null>;
+    dataList: TradingData[];
+    address: string | undefined;
+};
+
+type TradingListProps = {
+    style?: React.CSSProperties;
+    className?: string;
+} & TradingListScriptReturn;
+declare const TradingList: FC<TradingListProps>;
+
+type TradingListWidgetProps = Pick<TradingListProps, "style" | "className">;
+/**
+ * @deprecated use TradingListPage instead
+ * it will be removed in next version
+ */
+declare const TradingListWidget: FC<TradingListWidgetProps>;
+
+type RankingColumnFields = "rank" | "address" | "volume" | "pnl" | "rewards";
+
+type ListStyle = "disc" | "decimal" | "none" | "circle" | "square" | "decimal-leading-zero" | "lower-alpha" | "upper-alpha" | "lower-roman" | "upper-roman";
+type DescriptionItem = {
+    content: string;
+    type: "markdown" | "text" | "image";
+    alt?: string;
+    className?: string;
+    listStyle?: ListStyle;
+    listClassName?: string;
+    children?: DescriptionItem[];
+};
+type DescriptionConfig = {
+    listStyle?: ListStyle;
+    listClassName?: string;
+};
+
+declare enum CampaignTagEnum {
+    ONGOING = "ongoing",
+    COMING = "coming",
+    ENDED = "ended",
+    EXCLUSIVE = "exclusive"
+}
+interface CampaignStatistics {
+    total_participants?: number;
+    total_volume?: number;
+}
+interface PrizePoolTier {
+    position?: number;
+    position_range?: [number, number];
+    amount: number;
+}
+interface PrizePool {
+    pool_id: string;
+    label: string;
+    total_prize: number;
+    currency: string;
+    metric: "volume" | "pnl";
+    tiers: PrizePoolTier[];
+    volume_limit?: number;
+}
+interface TicketTierRule {
+    value: number;
+    tickets: number;
+}
+interface TicketLinearRule {
+    every: number;
+    tickets: number;
+}
+interface TicketRules {
+    total_prize: number;
+    currency: string;
+    metric: "volume" | "pnl";
+    mode: "tiered" | "linear";
+    tiers?: TicketTierRule[];
+    linear?: TicketLinearRule;
+}
+interface CampaignConfig {
+    campaign_id: number | string;
+    title: string;
+    subtitle?: string;
+    description: string;
+    content?: ReactNode;
+    classNames?: {
+        container?: string;
+        topContainer?: string;
+        title?: string;
+        description?: string;
+        descriptionContainer?: string;
+    };
+    register_time?: string;
+    start_time: string;
+    end_time: string;
+    reward_distribution_time?: string;
+    volume_scope?: string | string[];
+    referral_codes?: string[] | string;
+    prize_pools?: PrizePool[];
+    tiered_prize_pools?: Array<PrizePool[]>;
+    ticket_rules?: TicketRules;
+    image?: string;
+    rule_url?: string;
+    rule_config?: {
+        action?: "scroll" | "click";
+    };
+    trading_url?: string;
+    trading_config?: {
+        format?: string;
+    };
+    href?: string;
+    hide_arena?: boolean;
+    hide_rewards?: boolean;
+    hide_estimated_rewards?: boolean;
+    highlight_pool_id?: string;
+    user_account_label?: string;
+    rule?: {
+        rule: DescriptionItem[];
+        terms: DescriptionItem[];
+        ruleConfig?: DescriptionConfig;
+    };
+    leaderboard_config?: LeaderboardConfig;
+    emphasisConfig?: {
+        subtitle: string;
+        walletConnect: {
+            title: string;
+            description: string;
+        };
+        hideConnectWallet: boolean;
+    };
+}
+interface LeaderboardConfig {
+    use_general_leaderboard?: boolean;
+    exclude_leaderboard_columns?: RankingColumnFields[];
+    week_one_addresses?: string[];
+}
+interface UserData {
+    rank?: number | string;
+    pnl: number;
+    total_participants?: number;
+    volume: number;
+    referral_code?: string;
+}
+type CampaignStatsDetailsResponse = {
+    broker_id: string;
+    user_count: number;
+    volume: number;
+    symbol: string;
+}[];
+type CampaignStatsResponse = {
+    sign_up_count: number;
+    user_count: number;
+    volume: number;
+    updated_time: number;
+};
+type UserCampaignsResponse = {
+    id: string;
+    register_time: number;
+}[];
+
+/**
+ * Trading leaderboard provider state
+ */
+type TradingLeaderboardState = {
+    /** campaigns config, if not provided, will not show campaigns section */
+    campaigns?: CampaignConfig[];
+    /** background src, it can be a image resource or video resource */
+    backgroundSrc?: string;
+    href?: {
+        /** default trading now button url */
+        trading: string;
+    };
+    currentCampaignId: string | number;
+    currentCampaign?: CampaignConfig;
+    onCampaignChange: (campaignId: string | number) => void;
+    /** leaderboard user data, it will be used to calculate the rewards */
+    userData?: UserData;
+    /** set leaderboard user data */
+    setUserData?: (userdata: UserData) => void;
+    /** campaign ranking list updated time */
+    updatedTime?: number;
+    /** set snapshot time */
+    setUpdatedTime?: (updatedTime?: number) => void;
+    /** custom data, if use this, you can full control the data */
+    dataAdapter?: (info: {
+        page: number;
+        pageSize: number;
+    }) => {
+        loading: boolean;
+        dataSource?: any[];
+        dataList?: any[];
+        userData?: any;
+        updatedTime?: number;
+        meta?: {
+            total: number;
+            current_page: number;
+            records_per_page: number;
+        };
+    };
+    campaignDateRange?: {
+        start_time: Date | string;
+        end_time: Date | string;
+    };
+    statistics?: CampaignStatistics;
+    setStatistics?: (statistics: CampaignStatistics) => void;
+};
+/**
+ * Trading leaderboard context
+ */
+declare const TradingLeaderboardContext: react__default.Context<TradingLeaderboardState>;
+type TradingLeaderboardProviderProps = Pick<TradingLeaderboardState, "campaigns" | "href" | "backgroundSrc" | "dataAdapter"> & {
+    campaignId?: string | number;
+    onCampaignChange?: (campaignId: string | number) => void;
+};
+declare const TradingLeaderboardProvider: react__default.FC<react__default.PropsWithChildren<TradingLeaderboardProviderProps>>;
+declare const useTradingLeaderboardContext: () => TradingLeaderboardState;
+
+type CampaignRankingData = {
+    broker_id: string;
+    account_id: string;
+    address: string;
+    volume: number;
+    pnl: number;
+    total_deposit_amount: number;
+    total_withdrawal_amount: number;
+    start_account_value: number;
+    end_account_value: number;
+    key?: string;
+    rank?: number | string;
+    rewards?: {
+        amount: number;
+        currency: string;
+    };
+};
+type CampaignRankingScriptOptions = {
+    campaignId: number | string;
+    sortKey?: "volume" | "pnl";
+};
+declare function useCampaignRankingScript(options: CampaignRankingScriptOptions): {
+    pagination: _kodiak_finance_orderly_ui.PaginationMeta;
+    initialSort: TableSort;
+    dataSource: any[] | undefined;
+    isLoading: boolean | undefined;
+    isMobile: boolean;
+    sentinelRef: react.MutableRefObject<HTMLDivElement | null>;
+    dataList: any[] | undefined;
+    address: string | undefined;
+};
+
+type DateRange = {
+    from?: Date;
+    to?: Date;
+    label?: string;
+};
+declare enum LeaderboardTab {
+    Volume = "volume",
+    Pnl = "pnl"
+}
+
+type GeneralRankingData = {
+    account_id: string;
+    address: string;
+    broker_fee: number;
+    date: string;
+    perp_maker_volume: number;
+    perp_taker_volume: number;
+    perp_volume: number;
+    realized_pnl: number;
+    total_fee: number;
+    key?: string;
+    rank?: number | string;
+    volume?: number;
+    pnl?: number;
+};
+type GeneralRankingScriptReturn = ReturnType<typeof useGeneralRankingScript>;
+type GeneralRankingScriptOptions = {
+    dateRange?: DateRange | null;
+    address?: string;
+    sortKey?: "perp_volume" | "realized_pnl";
+};
+declare function useGeneralRankingScript(options?: GeneralRankingScriptOptions): {
+    pagination: _kodiak_finance_orderly_ui.PaginationMeta;
+    initialSort: TableSort;
+    onSort: (sort?: TableSort) => void;
+    dataSource: any[];
+    isLoading: boolean;
+    isMobile: boolean;
+    sentinelRef: react.MutableRefObject<HTMLDivElement | null>;
+    dataList: any[];
+    address: string | undefined;
+};
+
+type RankingData = GeneralRankingData | CampaignRankingData;
+type RankingProps = {
+    style?: React.CSSProperties;
+    className?: string;
+    fields: RankingColumnFields[];
+} & Omit<GeneralRankingScriptReturn, "dataList" | "dataSource"> & {
+    dataList: RankingData[];
+    dataSource: RankingData[];
+};
+declare const Ranking: FC<RankingProps>;
+
+type GeneralRankingWidgetProps = Pick<RankingProps, "style" | "className" | "fields"> & GeneralRankingScriptOptions;
+declare const GeneralRankingWidget: FC<GeneralRankingWidgetProps>;
+
+type CampaignRankingWidgetProps = Pick<RankingProps, "style" | "className" | "fields"> & CampaignRankingScriptOptions;
+declare const CampaignRankingWidget: FC<CampaignRankingWidgetProps>;
+
+type WeeklyDateRange = {
+    from: Date;
+    to: Date;
+    label: string;
+};
+
+type GeneralLeaderboardScriptReturn = ReturnType<typeof useGeneralLeaderboardScript>;
+declare const FilterDays: readonly [7, 14, 30, 90];
+type TFilterDays = (typeof FilterDays)[number];
+type GeneralLeaderboardScriptOptions = {
+    campaignDateRange?: {
+        start_time: Date | string;
+        end_time: Date | string;
+    };
+};
+declare function useGeneralLeaderboardScript(options?: GeneralLeaderboardScriptOptions): {
+    activeTab: LeaderboardTab;
+    onTabChange: react.Dispatch<react.SetStateAction<LeaderboardTab>>;
+    useCampaignDateRange: boolean;
+    weeklyRanges: WeeklyDateRange[];
+    currentOrAllTimeRange: WeeklyDateRange | undefined;
+    searchValue: string;
+    onSearchValueChange: (value: string) => void;
+    clearSearchValue: () => void;
+    filterItems: any;
+    onFilter: (filter: {
+        name: string;
+        value: any;
+    }) => void;
+    dateRange: DateRange;
+    filterDay: 30 | 7 | 14 | 90 | null;
+    updateFilterDay: (day: TFilterDays) => void;
+    setDateRange: react.Dispatch<react.SetStateAction<DateRange>>;
+};
+
+type GeneralLeaderboardProps = {
+    style?: React.CSSProperties;
+    className?: string;
+    campaignDateRange?: {
+        start_time: Date | string;
+        end_time: Date | string;
+    };
+} & GeneralLeaderboardScriptReturn;
+declare const GeneralLeaderboard: FC<GeneralLeaderboardProps>;
+
+type GeneralLeaderboardWidgetProps = Pick<GeneralLeaderboardProps, "style" | "className" | "campaignDateRange">;
+declare const GeneralLeaderboardWidget: FC<GeneralLeaderboardWidgetProps>;
+
+type CampaignLeaderboardScriptReturn = ReturnType<typeof useCampaignLeaderboardScript>;
+declare function useCampaignLeaderboardScript(): {
+    activeTab: LeaderboardTab;
+    onTabChange: react.Dispatch<react.SetStateAction<LeaderboardTab>>;
+    excludeColumns: RankingColumnFields[];
+};
+
+type CampaignLeaderboardProps = {
+    style?: React.CSSProperties;
+    className?: string;
+    campaignId: number | string;
+} & CampaignLeaderboardScriptReturn;
+declare const CampaignLeaderboard: FC<CampaignLeaderboardProps>;
+
+type CampaignLeaderboardWidgetProps = Pick<CampaignLeaderboardProps, "style" | "className" | "campaignId">;
+declare const CampaignLeaderboardWidget: FC<CampaignLeaderboardWidgetProps>;
+
+type LeaderboardPageProps = GeneralLeaderboardWidgetProps & TradingLeaderboardProviderProps & {
+    style?: React.CSSProperties;
+    className?: string;
+};
+declare const LeaderboardPage: FC<LeaderboardPageProps>;
+type LeaderboardSectionProps = {
+    style?: React.CSSProperties;
+    className?: string;
+};
+declare const LeaderboardSection: FC<LeaderboardSectionProps>;
+declare const LeaderboardTitle: (props: {
+    title: ReactNode;
+    isMobile?: boolean;
+}) => react_jsx_runtime.JSX.Element;
+
+export { type Campaign, type CampaignConfig, CampaignLeaderboard, type CampaignLeaderboardProps, CampaignLeaderboardWidget, type CampaignLeaderboardWidgetProps, CampaignRankingWidget, type CampaignRankingWidgetProps, type CampaignStatistics, type CampaignStatsDetailsResponse, type CampaignStatsResponse, CampaignTagEnum, Campaigns, type CampaignsProps, CampaignsWidget, GeneralLeaderboard, type GeneralLeaderboardProps, GeneralLeaderboardWidget, type GeneralLeaderboardWidgetProps, GeneralRankingWidget, type GeneralRankingWidgetProps, Leaderboard, type LeaderboardConfig, LeaderboardPage, type LeaderboardPageProps, type LeaderboardProps, LeaderboardSection, LeaderboardTitle, LeaderboardWidget, type LeaderboardWidgetProps, type PrizePool, type PrizePoolTier, Ranking, type RankingProps, type TicketLinearRule, type TicketRules, type TicketTierRule, TradingLeaderboardContext, TradingLeaderboardProvider, type TradingLeaderboardProviderProps, type TradingLeaderboardState, TradingList, type TradingListProps, TradingListWidget, type TradingListWidgetProps, type UserCampaignsResponse, type UserData, useCampaignLeaderboardScript, useCampaignRankingScript, useCampaignsScript, useGeneralLeaderboardScript, useGeneralRankingScript, useLeaderboardScript, useTradingLeaderboardContext, useTradingListScript };