@b3dotfun/leaderboard v0.0.3

Leaderboard Smart Contract - TypeScript SDK

NPC Labs presents the TypeScript SDK for our On-Chain Leaderboard Smart Contract, a key contributor to B3 - the gaming ecosystem. This SDK enables game developers to seamlessly incorporate secure on-chain leaderboards for tracking and displaying player scores on the blockchain.

Overview

The SDK is built to facilitate the creation, management, and integration of an on-chain leaderboard, all from within your gaming platform. The primary users of this SDK are the game admins, authorized by the contract to create, set, update, increment, and decrement player scores using player wallet addresses. Players, on the other hand, will have their scores tracked and can retrieve their standings and score details.

Features

Fetch Leaderboard Data

Enables easy retrieval of leaderboard standings and scores associated with individual player addresses.

Update Scores

Adds functionality for admins to interact with the contract methods for setting, updating, incrementing, or decrementing player scores.

Installation

You can install our TypeScript SDK using the commands below:

With yarn:

yarn add @b3dotfun/leaderboard

With npm:

npm install @b3dotfun/leaderboard

Methods

The SDK includes the following methods for interacting with the leaderboard:

Leaderboard Write Methods:

• addAdmin(newAdmin: address) - Adds a new admin to the contract.
• removeAdmin(admin: address) - Removes an existing admin from the contract.
• createLeaderboard(label: string, maxLimit: uint256, startTime: uint256, endTime: uint256) - Creates a new leaderboard with specified parameters.
• updateLeaderboard(label: string, maxLimit: uint256, startTime: uint256, endTime: uint256) - Updates the properties of an existing leaderboard.
• setScore(label: string, player: address, score: uint256) - Sets the score for a player on the specified leaderboard.
• updateScore(label: string, player: address, score: uint256) - Updates the score for a player on the specified leaderboard.
• incrementScore(label: string, player: address, increment: uint256) - Increments the score for a player on the specified leaderboard by a certain amount.
• decrementScore(label: string, player: address, decrement: uint256) - Decrements the score for a player on the specified leaderboard by a certain amount.

Leaderboard Read Methods:

• getAdmins() - Retrieves the list of admin addresses.
• getLeaderboardStartTime(label: string) - Retrieves the start time of the specified leaderboard.
• getLeaderboardEndTime(label: string) - Retrieves the end time of the specified leaderboard.
• isLeaderboardActive(label: string) - Checks if the specified leaderboard is currently active.
• getLeaderboard(label: string) - Retrieves the players and their scores for the specified leaderboard.
• getScore(label: string, player: address) - Retrieves the score of a specific player in the specified leaderboard.
• getLeaderboardSize(label: string) - Retrieves the size of the specified leaderboard.
• getPlayerCount(label: string) - Retrieves the count of players in the specified leaderboard.
• getTopPercentage(label: string, percentage: uint256) - Retrieves the top percentage of players in the specified leaderboard.

Each method is performant and handles errors gracefully by returning meaningful messages.

Usage

Replace YOUR_RPC_URL, YOUR_PRIVATE_KEY, and CONTRACT_ADDRESS with appropriate values for your use case.

import { ethers } from 'ethers';
import { leaderboardSDK } from '@b3dotfun/leaderboard'; 

async function main() {
  // Initialize provider and signer
  const provider = new ethers.JsonRpcProvider('YOUR_RPC_URL');
  const signer = new ethers.Wallet('YOUR_PRIVATE_KEY', provider);

  // Create an instance of the leaderboardSDK
  const sdk = new leaderboardSDK(signer);

  const contractAddress = 'CONTRACT_ADDRESS';
  // Your code here
}

main().catch(console.error);

Examples

Example methods can be found in src/example in the SDK package repository.