Get Simplified Reward Config

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 simplified rewards distribution config 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: GetLeaderboardDetailsInfo = {
        leaderboardIdOrName: "138",
    };

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 getSimplifiedRewardConfig method to fetch reward distribution details.

By default, the method would return details reward config for current period.

(async (): Promise<void> => {
    console.log("Get reward config in the current period...");
    const simplifiedRewardConfig: RewardDistribution = await leaderboardManager.getSimplifiedRewardConfig(leaderboardParams)
  
    console.log("Get reward config in the current period");
    console.log('Reward Data', simplifiedRewardConfig);
    console.log(JSON.stringify(simplifiedRewardConfig, null, 2));
})();

If the developer specify the period, so we can pass to query the specific reward config in the specific period.

(async (): Promise<void> => {
    console.log("Get reward config in the specific period...");
    const period = 2;
    const simplifiedRewardConfig: RewardDistribution = await leaderboardManager.getSimplifiedRewardConfig(leaderboardParams, period)
  
    console.log("Get reward config in the specific period");
    console.log('Reward Data', simplifiedRewardConfig);
    console.log(JSON.stringify(simplifiedRewardConfig, null, 2));
})();

Ouput Details:

The response from the RewardDistribution method includes the following fields:

RewardDistribution (RewardDistribution Object Data)

• distributionType (DistributionType): The distribution type enum (PERCENTAGE, FIXED).
• period (number): The specified period of the leaderboard.
• isApplyRewardAllPeriods (boolean): Indicates if the reward configuration applies to all periods of the leaderboard.
• rewardPoolAmount (number): Reward pool amount which have been setup.
• items (RewardItem[]): An array of RewardItem data objects representing individual reward configurations.

RewardItem Object:

• id (number): The unique ID of the reward.
• 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.
• 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": false,
  "distributionType": "PERCENTAGE",
  "period": 2,
  "rewardPoolAmount": 1300,
  "items": [
    {
      "createdAt": "2024-11-11T03:49:56.585Z",
      "updatedAt": "2024-11-11T03:49:56.585Z",
      "id": 254,
      "name": "Distribution Period 2 Test",
      "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 (leaderboardDetails.rewards && period && !leaderboardDetails.rewards[period]) {
      throw new Error(`No reward configuration is available for the specified period: ${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 getSimplifiedRewardConfig method to get the user's score.

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