Control Reward Distribution 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 create a reward configuration for a leaderboard 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 reward distribution configuration that specifies how rewards are distributed across ranks and periods. This includes setting parameters like distribution type, period, reward pool, and reward items.

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

const rewardDistributionConfig: RewardDistribution = {
    distributionType: DistributionType.FIXED, // Specify the distribution type (e.g., FIXED)
    period: 1,                               // The period for which rewards apply
    isApplyRewardAllPeriods: true,                 // Apply this reward config to all periods
    rewardPoolAmount: 1000,                  // Total amount for the reward pool
    items: [
        {
            name: 'Distribution Week for Rank 1-10',              // Name of the reward
            rank: { min: 1, max: 10 },       // Rank range for the reward
            detail: {
                tokenAddress: '0x83a795E1E91560Aae4207fDae9199d384f11D9d2', // ERC20 token address
                type: 'ERC20',               // Token type (ERC20 in this case)
                amount: "100"                // Amount for each eligible user
            }
        }
    ]
};

Input Details:

Mandatory Fields:

• distributionType: string
  Specifies the type of reward distribution. Possible values include:

  • FIXED: Distribute a fixed amount to eligible users.

• period: number
  The specific period number for which this reward configuration applies.

• isApplyRewardAllPeriods: boolean
  A boolean flag to indicate whether this reward configuration applies to all periods.

• rewardPoolAmount: number
  The total amount available in the reward pool to be distributed among the eligible users.

• items: object[]
  An array of reward items, each containing the details for individual rewards. Each item includes:

  • name: string
    The name of the reward (e.g., 'Distribution Week 1', 'Distribution Week 2').

  • rank: object
    The rank range for eligibility. The reward will be given to users whose leaderboard ranks fall within this range:

    • min: number
      The minimum rank eligible for the reward.
    • max: number
      The maximum rank eligible for the reward.

  • detail: object
    Contains detailed information about the reward itself, including the token type and amount:

    • tokenAddress: string
      The address of the ERC20 token that will be used for this reward.
    • type: string
      The type of token (e.g., ERC20).
    • amount: string
      The amount of the token to be distributed to each eligible user.

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

Step 3: Create Reward Configuration

Once you have defined the reward configuration, you can create it by calling the createRewardDistributionConfig method on the LeaderboardManager instance.

const leaderboardParams: RewardDistributionConfigParams = {
    leaderboardId: "176",                  // The ID of the leaderboard for which the reward config is being created
    rewardConfig: rewardDistributionConfig  // The reward configuration
};

console.log("Creating reward config for the leaderboard...");
const leaderboardRewardConfigResp = await leaderboardManager.createOrUpdateRewardDistributionConfig(leaderboardParams);

console.log("Creating reward config of leaderboard response:");
console.log(JSON.stringify(leaderboardRewardConfigResp, 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:

{
  "distributionType": "PERCENTAGE",
  "period": 2,
  "isApplyRewardAllPeriods": false,
  "rewardPoolAmount": 1300,
  "items": [
    {
      "id": 254,
      "name": "Distribution Period 2 Test",
      "rank": {
        "max": 10,
        "min": 1
      },
      "detail": {
        "type": "ERC20",
        "amount": "100",
        "tokenAddress": "0x83a795E1E91560Aae4207fDae9199d384f11D9d2",
      },
      "createdAt": "2024-11-11T03:49:56.585Z",
      "updatedAt": "2024-11-11T03:49:56.585Z",
      "metadata": {}
    }
  ]
}

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 createOrUpdateRewardDistributionConfig method to get the user's score.

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