Get Rewards Distribution By Selected Period

For more detailed examples and guidance on implementing the Myria Leaderboard SDK, please refer to our TypeScript SDK samples on GitHub here. This repository includes practical examples demonstrating how to create, manage, and interact with leaderboards, making it easier for you to integrate leaderboard functionality into your projects.

To retrieve rewards distribution details by selected period including all of information (rewards details data, rewardPoolAmount) using the @myria/leaderboard-ts-sdk, follow the steps below.

Step 1: Initialize the Leaderboard Manager

First, you need to initialize the LeaderboardManager with the appropriate parameters. These parameters include your environment type (e.g, STAGING, PRODUCTION) and the developerApiKey you received from the Myria Admin.

import { LeaderboardManager, InitLeaderboardParams, LeaderboardEnv } from '@myria/leaderboard-ts-sdk';

const developerApiKey = "YOUR_DEVELOPER_API_KEY";

const leaderboardParams: InitLeaderboardParams = {
  env: LeaderboardEnv.staging, // Use your desired environment type
  apiKey: developerApiKey,
};

const leaderboardManager = new LeaderboardManager(initLeaderboardParams);

Step 2: Define Query Parameters

Next, define the parameters for retrieving the details of a specific reward configuration in 1 selected period. You can specify either the leaderboardId or leaderboardName and period to fetch the details reward config for the specific period .

import { GetLeaderboardDetailsInfo } from '@myria/leaderboard-ts-sdk';

const leaderboardParams: GetRewardsByPeriod = {
        leaderboardIdOrName: "138",
        period: 1 // Select the period to query the reward config data
    };

Input Details:

Mandatory Fields:

• leaderboardIdOrName: string The unique ID or name of the leaderboard for which you want to retrieve details.

Note: The response includes details about the leaderboard and the user's score.

Step 3: Retrieve Reward Distribution Config In Current Period

Once you have defined the parameters, you can call the getRewardsWithPeriod method to fetch reward distribution details.

(async (): Promise<void> => {
    console.log("Get reward config in specific period...");
    const rewardConfigWithPeriod: RewardInPeriod = await leaderboardManager.getRewardsWithPeriod(leaderboardParams)
  
    console.log("Get reward config in specific period response:");
    console.log('rewardConfigWithPeriod', rewardConfigWithPeriod);
    console.log(JSON.stringify(rewardConfigWithPeriod, null, 2));
})();

Ouput Details:

The response from the RewardInCurrentPeriod method includes the following fields:

RewardInPeriod (RewardInPeriod Object Data)

• isApplyRewardAllPeriods (boolean): Indicates if the reward configuration applies to all periods of the leaderboard.
• period (number): The current active period of the leaderboard.
• data (RewardPeriod): A map of reward details organized by period.

Reward Period Object (RewardPeriod): The Rewards period object is organized by period and includes the following fields:

• rewardPoolAmount (number): The total reward pool for the period.
• distributionType (DistributionType): Indicates the type of distribution (FIXED or PERCENTAGE).
• items (RewardData[]): An array of RewardData objects representing individual reward configurations.

RewardData Object:

• name (string): The name of the reward.
• detail (RewardDetail): Detailed configuration of the reward (e.g., type, amount, token address).
• rank (RankRange): The rank range eligible for the reward.
• period (number): The period number for the reward.
• updatedAt (string): The timestamp of the last update, in ISO 8601 format.
• createdAt (string): The timestamp when the reward was created, in ISO 8601 format.
• id (number): The unique ID of the reward.
• metadata (JSONObject, optional): Additional metadata or custom fields related to the reward.

Reward Detail Fields:

• type (string): The type of the reward (e.g., ERC20).
• amount (string): The specific amount allocated for the reward.
• tokenAddress (string): The contract address of the token (applicable for ERC20 rewards).

Rank Range:

• min (number): Minimum rank eligible for the reward.
• max (number): Maximum rank eligible for the reward.

SampleResponse:

Sample response for fully rewards object:

{
  "isApplyRewardAllPeriods": true,
  "period": 2,
  "data": {
    "distributionType": "PERCENTAGE",
    "rewardPoolAmount": 1300,
    "items": [
      {
        "createdAt": "2024-11-08T12:56:54.216Z",
        "updatedAt": "2024-11-08T12:56:54.216Z",
        "id": 242,
        "name": "Distribution Period 1 Test",
        "period": 2,
        "detail": {
          "type": "ERC20",
          "amount": "100",
          "tokenAddress": "0x83a795E1E91560Aae4207fDae9199d384f11D9d2",
        },
        "rank": {
          "max": 20,
          "min": 11
        },
        "metadata": {}
      },
      {
        "createdAt": "2024-11-08T12:56:54.216Z",
        "updatedAt": "2024-11-08T12:56:54.216Z",
        "id": 248,
        "name": "Distribution Period 1 Test",
        "period": 2,
        "detail": {
          "type": "ERC20",
          "amount": "100",
          "tokenAddress": "0x83a795E1E91560Aae4207fDae9199d384f11D9d2",
        },
        "rank": {
          "max": 30,
          "min": 21
        },
        "metadata": {}
      },
      {
        "createdAt": "2024-11-08T12:56:54.216Z",
        "updatedAt": "2024-11-08T12:56:54.216Z",
        "id": 236,
        "name": "Distribution Period 1 Test",
        "period": 2,
        "detail": {
          "type": "ERC20",
          "amount": "100",
          "tokenAddress": "0x83a795E1E91560Aae4207fDae9199d384f11D9d2",
        },
        "rank": {
          "max": 10,
          "min": 1
        },
        "metadata": {}
      }
    ]
  }
}

Note: If the specified period is not set up or does not exist within the leaderboard, the SDK will throw an exception indicating that the leaderboard does not contain the requested period.

• Important: Ensure that the period you are querying exists. If the rewards object does not include the specified period, the SDK will throw an error as shown in the code example above:

if (!rewards[getRewardWithPeriod.period]) {
    throw new Error(`This leaderboard ${leaderboardDetails.id} does not contain period ${getRewardWithPeriod.period}`);
}

Summary

By following these steps, you can successfully retrieve a specific user's score from a leaderboard using the @myria/leaderboard-ts-sdk. This process involves initializing the LeaderboardManager, defining the query parameters, and invoking the getScoresByLeaderboardIdAndUserId method to get the user's score.

For more details on the available options and additional features, refer to the full documentation.