@b3dotfun/leaderboards NPM

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.

Installation

You can install our TypeScript SDK using the commands below:

yarn add @b3dotfun/leaderboards

npm install @b3dotfun/leaderboards

Getting Started

Initialize the library for the Leaderboard SDK.

import { LeaderboardSDK } from '@b3dotfun/leaderboard';
import { LeaderboardContractAddress } from '@b3dotfun/leaderboard';
import { b3Sepolia } from 'viem/chains';

const leaderboard = new LeaderboardSDK(LeaderboardContractAddress, b3Sepolia);

Connecting RPC provider

Connecting the provider is only required for the write operations that interact with the contract. For read operations interact with the contract, and thus connecting to rpc provider is not required.

leaderboard.connect();
if (!isConnected) {
  console.error("Failed to connect to the leaderboard contract.");
  return;
}

console.log("Connected to the leaderboard contract");

Setting Up Wallet

Contract write call requires a wallet to be set up.

import { privateKeyToAccount } from 'viem/accounts';

const account = privateKeyToAccount(`0x${process.env.YOUR_PRIVATE_KEY}`);

Examples of interacting with contracts (Write & Read)

Create Leaderboard

The createLeaderboard method creates a new leaderboard with specified parameters.

// Initialize the LeaderboardSDK with the contract address and chain configuration
// Connect RPC provider
// Set up wallet

const label = "Test Leaderboard";
const maxLimit = 10;
const startTime = 1730202968;
const endTime = 1761738968;

const response = await leaderboard.createLeaderboard(label, maxLimit, startTime, endTime, account);

Set Score

The setScore method sets the scores for a leaderboard with specificed parameters.

// Initialize the LeaderboardSDK with the contract address and chain configuration
// Connect RPC provider
// Set up wallet

const label = "Test Leaderboard";
const players = ["address_1", "address_2"];
const scores = [10, 100];

const response = await leaderboard.setScore(label, players, scores, account);

Fetch Leaderboard

The getLeaderboard method fetches the leaderboard for a specific label.

// Initialize the LeaderboardSDK with the contract address and chain configuration
// Connect RPC provider

const label = "leaderboard_test";

const response = await leaderboard.getLeaderboard(label);

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

Methods

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

Leaderboard Write Methods:

addAdmin(newAdmin: address, account: PrivateKeyAccount) - Adds a new admin to the contract.
removeAdmin(admin: address, account: PrivateKeyAccount) - Removes an existing admin from the contract.
createLeaderboard(label: string, maxLimit: uint256, startTime: uint256, endTime: uint256, account: PrivateKeyAccount) - Creates a new leaderboard with specified parameters.
updateLeaderboard(label: string, maxLimit: uint256, startTime: uint256, endTime: uint256, account: PrivateKeyAccount) - Updates the properties of an existing leaderboard.
setScore(label: string, players: address[], scores: uint256[], account: PrivateKeyAccount) - Sets the score for a player on the specified leaderboard.
updateScore(label: string, players: address[], score: uint256[], account: PrivateKeyAccount) - Updates the scores for players on the specified leaderboard.
incrementScore(label: string, players: address[], increments: uint256[], account: PrivateKeyAccount) - Increments the scores for players on the specified leaderboard by certain amounts.
decrementScore(label: string, players: address[], decrements: uint256[], account: PrivateKeyAccount) - Decrements the scores for players on the specified leaderboard by certain amounts.

Leaderboard Read Methods:

getAdmins() - Retrieves the list of admin addresses.
isAdmin(account: address) - Checks if an address is an admin of the leaderboard.
getCurrentAdminCount() - Retrieves the current number of admins of the leaderboard.
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.