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/leaderboards";
import "viem/window";

// Call Read functions in factory contract
const leaderboard = new LeaderboardSDK("dev");

// Call Write functions in factory contract
const leaderboard = new LeaderboardSDK("dev", account);

// Call Read functions in leaderboard contract
const leaderboard = new LeaderboardSDK("dev", "", leaderboardAddress);

// Call Write functions in leaderboard contract
const leaderboard = new LeaderboardSDK("dev", account, leaderboardAddress);

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.

// Connect to Factory Contract RPC provider
leaderboard.factoryConnect(window.ethereum); // for browser only. For Script registry.connect() to use defaull provider
if (!isConnected) {
  console.error("Failed to connect to the factory contract.");
  return;
}

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

// Connect to Leaderboard Contract RPC provider
leaderboard.leaderBoardConnect(window.ethereum); // for browser only. For Script registry.connect() to use defaull provider
if (!isConnected) {
  console.error("Failed to connect to the leaderboard contract.");
  return;
}

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

Setting Up Account

Contract write call requires wallet account which can be initiated in two ways.

JSON-RPC Account

A JSON-RPC Account is an Account whose signing keys are stored on the external Wallet A JSON-RPC Account can just be initialized as an Address string. In the usage below, we are extracting the address from a Browser Extension Wallet (e.g. MetaMask) with the window.ethereum Provider via eth_requestAccounts

import "viem/window";

const [account] = await window.ethereum.request({
  method: "eth_requestAccounts",
});

Local Accounts (Private Key etc)

A Local Account is an Account whose signing keys are stored on the consuming user's machine. It performs signing of transactions & messages with a private key before broadcasting the transaction or message over JSON-RPC.

const account = `0x${process.env.YOUR_PRIVATE_KEY}` || `{0x}`;

Examples of interacting with contracts (Write & Read)

Deploy Leaderboard Contract

The deployLeaderboardContract method deploys a new leaderboard with specified parameters.

const ENVIRONMENT = "dev"; // Constant for environment
const ACCOUNT = `0x${YOUR_PRIVATE_KEY}`; // Constant for account
const ADMIN_ADDRESS = "0x..."; // Constant for contract address
const CONTRACT_LABEL = "label"; // Constant for created leaderboard contract ID
const MAX_ENTRIES = 10; // Constant for maximum entries
const START_TIME = 0; // Constant for start time
const END_TIME = 1762592785; // Constant for end time

// Initialize the LeaderboardSDK with the ENV and ACCOUNT
const leaderboard = new LeaderboardSDK(ENVIRONMENT, ACCOUNT);

// Connect to the factory contract
...

// Create a leaderboard by factory contract
const response = await leaderboard.deployLeaderboardContract(
  ADMIN_ADDRESS, 
  CONTRACT_LABEL, 
);

Set Score

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

const ENVIRONMENT = "dev"; // Constant for environment
const CONTRACT_LABEL = "label"; // Constant for created leaderboard contract ID
const LEADERBOARD_ID = "label"; // Constant for leaderboard label
const ACCOUNT = `0x${YOUR_PRIVATE_KEY}`; // Constant for account
const PLAYERS = [
  "0x...",
  "0x...",
  "0x..."
];
const SCORES = [
  100,
  200,
  300
];

// Initialize the LeaderboardSDK with ENV
const leaderboard = new LeaderboardSDK(ENVIRONMENT);

// Connect to the factory contract
...

const LEADERBOARD_ADDRESS = await leaderboard.getLeaderBoards(CONTRACT_LABEL);
if (LEADERBOARD_ADDRESS) {
  // Initialize the LeaderboardSDK with ENV, ACCOUNT, and LEADERBOARD_ADDRESS
  const leaderboard = new LeaderboardSDK(ENVIRONMENT, ACCOUNT, LEADERBOARD_ADDRESS);

  // Connect to the leaderboard contract
  ...

  const response = await leaderboard.setScore(LEADERBOARD_ID, PLAYERS, SCORES);
}

Fetch Leaderboard

The getLeaderboard method fetches the leaderboard.

const ENVIRONMENT = "dev"; // Constant for environment
const CONTRACT_LABEL = "label"; // Constant for created leaderboard contract ID
const LEADERBOARD_ID = "label"; // Constant for leaderboard label

// Initialize the LeaderboardSDK with ENV
const leaderboard = new LeaderboardSDK(ENVIRONMENT);

// Connect to the factory contract
...

const LEADERBOARD_ADDRESS = await leaderboard.getLeaderBoards(CONTRACT_LABEL);
if (LEADERBOARD_ADDRESS) {
  // Initialize the LeaderboardSDK with ENV, and LEADERBOARD_ADDRESS
  const leaderboard = new LeaderboardSDK(ENVIRONMENT, "", LEADERBOARD_ADDRESS);

  // Connect to the leaderboard contract
  ...

  const response = await leaderboard.getLeaderboard(LEADERBOARD_ID);
}

The getHydratedLeaderboard method fetches the leaderboard data including usernames and avatars.

// Initialize the LeaderboardSDK and etc like `getLeaderboard`

const response = await leaderboard.getHydratedLeaderboard();

Fetch Leaderboard and Score via GraphQL

The listLeaderboards method fetches the leaderboard and score for a specific label and player address.

const ENVIRONMENT = "dev"; // Constant for environment
const LEADERBOARD_ID = "label"; // Constant for leaderboard label
const CONTRACT_ADDRESS = "0xF577588bF5B0AF78Cb92711C3Eb66e03383af275"; // Constant for contract address
const PAGE_NUMBER = 1; // Constant for page number
const PAGE_SIZE = 10; // Constant for page size

// Initialize the LeaderboardSDK with ENV
const leaderboard = new LeaderboardSDK(ENVIRONMENT);

// Connect to the Leaderboard contract
...

const response = await leaderboard.listLeaderboards(
  LEADERBOARD_ID, 
  CONTRACT_ADDRESS, 
  PAGE_NUMBER, 
  PAGE_SIZE
);

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