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.
You can install our TypeScript SDK using the commands below:
yarn add @b3dotfun/leaderboards
npm install @b3dotfun/leaderboards
-
ENV
: ("dev"
|"prod"
)- This parameter specifies the environment in which the SDK is operating. It can either be
"dev"
for development or"prod"
for production. The SDK will use the corresponding configuration settings based on this value.
- This parameter specifies the environment in which the SDK is operating. It can either be
-
walletKey
:string
(optional)- This is an optional parameter that represents the wallet key used for transactions. If provided, it should be a hexadecimal string starting with
0x
. - The
walletKey
is required for write operations that modify the state of the blockchain (e.g., deploying contracts, adding/removing admins, setting scores). For read operations (e.g., retrieving leaderboard data, player scores), thewalletKey
is not required.
- This is an optional parameter that represents the wallet key used for transactions. If provided, it should be a hexadecimal string starting with
-
contractAddress
:string
(optional)- This optional parameter specifies the address of the leaderboard contract. It should be a hexadecimal string starting with
0x
. - The
contractAddress
is used to interact with the specific leaderboard contract. If a valid contract address is provided, the SDK will use it for operations that require interaction with that contract.
- This optional parameter specifies the address of the leaderboard contract. It should be a hexadecimal string starting with
Factory Contract
import { LeaderboardSDK } from "@b3dotfun/leaderboards";
const ENV = "dev" | "prod";
const factoryContract = new LeaderboardSDK(ENV);
const isFactoryConnected = factoryContract.factoryConnect();
if (!isFactoryConnected) {
console.error("Failed to connect to the Factory contract.");
return;
}
console.log("Connected to the Factory contract");
Leaderboard Contract
import { LeaderboardSDK } from "@b3dotfun/leaderboards";
const ENV = "dev" | "prod";
const CONTRACT_LABEL = "label";
const factoryContract = new LeaderboardSDK(ENV);
const isFactoryConnected = factoryContract.factoryConnect();
if (!isFactoryConnected) {
console.error("Failed to connect to the Factory contract.");
return;
}
console.log("Connected to the Factory contract");
const leaderboardAddress = await factoryContract.getLeaderBoards(
CONTRACT_LABEL
);
if (leaderboardAddress) {
const leaderboard = new LeaderboardSDK(ENV, "", leaderboardAddress);
const isConnected = leaderboard.leaderBoardConnect();
if (!isConnected) {
console.error("Failed to connect to the Leaderboard contract.");
return;
}
console.log("Connected to the Leaderboard contract");
}
Contract write call requires wallet account which can be initiated in two ways.
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",
});
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}`;
The deployLeaderboardContract
method deploys a new leaderboard by a factory contract.
const ENV = "dev" | "prod";
const ACCOUNT = `0x${YOUR_PRIVATE_KEY}`; // Constant for account
const ADMIN_ADDRESS = "0x...";
const CONTRACT_LABEL = "label";
// Initialize the LeaderboardSDK with the ENV and ACCOUNT
const factoryContract = new LeaderboardSDK(ENV, ACCOUNT);
// Connect to the factory contract
const isFactoryConnected = factoryContract.factoryConnect();
if (!isFactoryConnected) {
console.error("Failed to connect to the Factory contract.");
return;
}
console.log("Connected to the Factory contract");
// Create a leaderboard by factory contract
const response = await factoryContract.deployLeaderboardContract(
ADMIN_ADDRESS,
CONTRACT_LABEL
);
The getLeaderBoards
method gets the address of the deployed leaderboard contract by a factory contract.
const ENV = "dev" | "prod";
const CONTRACT_LABEL = "label";
// Initialize the LeaderboardSDK with ENV
const factoryContract = new LeaderboardSDK(ENV);
// Connect to the factory contract
const isFactoryConnected = factoryContract.factoryConnect();
if (!isFactoryConnected) {
console.error("Failed to connect to the Factory contract.");
return;
}
console.log("Connected to the Factory contract");
const leaderboardAddress = await factoryContract.getLeaderBoards(
CONTRACT_LABEL
);
The createLeaderboardContract
method creates a new leaderboard with specified parameters.
const ENV = "dev" | "prod";
const ACCOUNT = `0x${YOUR_PRIVATE_KEY}`;
if (leaderboardAddress) {
// Initialize the LeaderboardSDK with the contract address and chain configuration
const leaderboard = new LeaderboardSDK(ENV, ACCOUNT, leaderboardAddress);
// Connect to the leaderboard contract
const isConnected = leaderboard.leaderBoardConnect();
if (!isConnected) {
console.error("Failed to connect to the Leaderboard contract.");
return;
}
console.log("Connected to the Leaderboard contract");
try {
const LEADERBOARD_ID = "TEST LEADERBOARD";
const MAX_LIMIT = Number.MAX_SAFE_INTEGER;
const START_TIME = 0;
const END_TIME = Number.MAX_SAFE_INTEGER;
// Create a leaderboard with specified parameters
const entries = await leaderboard.createLeaderboard(
LEADERBOARD_ID,
MAX_LIMIT,
START_TIME,
END_TIME
);
console.log("Leaderboard created successfully:", entries);
} catch (error) {
console.error("Error creating leaderboard:", error);
}
}
The setScore
method sets the scores for a leaderboard with specificed parameters.
const ENVIRONMENT = "dev" | "prod";
const ACCOUNT = `0x${YOUR_PRIVATE_KEY}`;
const PLAYERS = ["0x...", "0x...", "0x..."];
const SCORES = [100, 200, 300];
if (leaderboardAddress) {
// Initialize the LeaderboardSDK with the contract address and chain configuration
const leaderboard = new LeaderboardSDK(ENV, ACCOUNT, leaderboardAddress);
// Connect to the leaderboard contract
const isConnected = leaderboard.leaderBoardConnect();
if (!isConnected) {
console.error("Failed to connect to the Leaderboard contract.");
return;
}
console.log("Connected to the Leaderboard contract");
const LEADERBOARD_ID = "label";
const response = await leaderboard.setScore(LEADERBOARD_ID, PLAYERS, SCORES);
}
The getLeaderboard
method fetches the leaderboard.
const ENVIRONMENT = "dev" | "prod";
const CONTRACT_LABEL = "label";
const LEADERBOARD_ID = "label";
if (leaderboardAddress) {
// Initialize the LeaderboardSDK with the contract address and chain configuration
const leaderboard = new LeaderboardSDK(ENV, ACCOUNT, leaderboardAddress);
// Connect to the leaderboard contract
const isConnected = leaderboard.leaderBoardConnect();
if (!isConnected) {
console.error("Failed to connect to the Leaderboard contract.");
return;
}
console.log("Connected 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();
The listLeaderboards
method fetches the leaderboard and score for a specific label and player address.
const ENVIRONMENT = "dev" | "prod";
const LEADERBOARD_ID = "label";
const leaderboardAddress = "0xF577588bF5B0AF78Cb92711C3Eb66e03383af275";
const PAGE_NUMBER = 1;
const PAGE_SIZE = 10;
// Initialize the LeaderboardSDK with ENV
const leaderboard = new LeaderboardSDK(ENVIRONMENT);
// Connect to the Leaderboard contract
...
const response = await leaderboard.listLeaderboards(
LEADERBOARD_ID,
leaderboardAddress,
PAGE_NUMBER,
PAGE_SIZE
);
Example methods can be found in src/example
in the SDK package repository.