Builder Points SDK

Installation

npm

View NPM Package

Code Examples

Getting Started

Intialize the library for AppRegistry.

import { AppRegistry } from '@b3dotfun/b3-points.sdk';
import { 
  B3PointIndexerURLOnB3Mainnet, 
  B3MainnetAppRegistryContractAddress
} from '@b3dotfun/b3-points';
import { b3 } from 'viem/chains';
import 'viem/window';

const registry = new AppRegistry(
  B3PointIndexerURLOnB3Mainnet,
  B3MainnetAppRegistryContractAddress,
  b3,
);
registry.connect(window.ethereum); // for browser only. For Script registry.connect() to use defaull provider

Intialize the library for B3PointService (BPS).

import {BPS} from '@b3dotfun/b3-points.sdk';
import {
  B3PointIndexerURLOnB3Mainnet, 
  B3MainnetPointServiceContractAddress
} from '@b3dotfun/b3-points';
import { b3 } from 'viem/chains';
import 'viem/window';

const bps = new BPS(
  B3PointIndexerURLOnB3Mainnet,
  B3MainnetPointServiceContractAddress,
  b3,
);
bps.connect(window.ethereum); // for browser only. For Script registry.connect() to use defaull provider

Setting Up an Account for Write Functions

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

JSON-RPC Account

Local Accounts (Private Key, Mnemonic, etc)

JSON-RPC Account

Local Accounts (Private Key, Mnemonic, etc)

JSON-RPC Account

Local Accounts (Private Key, Mnemonic, etc)

Step 1: Register your app

The register function allows you to register an application to the AppRegistry. This function returns the app ID.

There are 2 identifiers needed to register your app:

appName

This is your b3.fun ENS name registered on your profile on basement.fun

To get this, connect your wallet on basement.fun and register a username for your app, which used here.

operator

Operator wallet will be responsible for distributing points for each session (it can be different from the wallet used to register the ENS appName).

Choose an operator address where you are comfortable with executing the write functions to the contract with.

See example code

See full example code snippet

See example code

Example

// Init AppRegistry
// Init Account

const appName = 'game.b3.fun';
const operator = '0xFD50b031E778fAb33DfD2Fc3Ca66a1EeF0652165';

const appId = registry.register({
  appName: appName,
  operator: operator,
  account
});

Step 2: Distribute Points

The transferPoints function allows app operator to distribute granted points to users only for the current ongoing session. Once the season is finalized, the previously granted points cannot be updated anymore.

Example

// Init BPS
// Init Account

const appId = 2n; // app ID for 'game.b3.fun'

const transferUIDs = bps.transferPoints({
  appId,
  requests: [
    {recipient: '', point: 325},
    {recipient: '', point: 920},
    {recipient: '', point: 21},
    ...
  ]},
  account: account
);

Distribute Points With CSV file

In addition to using transferPoints, developers can leverage distributePointsCsv to distribute points on a larger scale by providing a CSV file. This function will break the entries into batch of 100, prepare the on-chain transactions, and send out with rate limiting to ensure the transaction can confirm on-chain.

We have built in dedup logic into this flow. Therefore it is safe to trigger the function multiple times with the same file until you see all the points are delivered.

Code examples are available here.

# Create .env file  in root folder with these variables

# moderator private key, used to transfer points
MODERATOR_PRIVATE_KEY=""

# environment: testnet or mainnet
ENV="testnet"

Example

import { transferPointsCsv } from "./transfer-points";

// appId is the id of the application
const appId = BigInt(5);
// filePath is the path to the csv file
const filePath = "./src/example/bps/transfer-requests.csv";

async function distributePointsCsv() {
  try {
    await transferPointsCsv(filePath, appId);
  } catch (error) {
    console.error(error);
  }
}

// main: call the function to transfer points from a csv file
void distributePointsCsv();

Then from root run

npx ts-node ./src/example/bps/transfer-points-csv.ts

Cancel Transfer (optional)

The app operator can optionally call cancelTransfer to cancel a pending transfer (that is in the current season) if needed to undo a transfer.

Example

// Init BPS
// Init Account

bps.cancelTransfer({
    uid: '0xb16fa048b0d597f5a821747eba64efa4762ee5143e9a80600d0005386edfc995'
  },
  account: account,
);

Public Read Functions

The following examples are functions that apps can use to read data from the points contract. These read functions do not need to be called with a wallet provider, and are publicly accessible.

You can use these functions to retrieve the total number of points a given user has on your app, or fetch the BP points a user has across the ecosystem.

See example code for fetching list of apps

See full example code snippet

See example code for fetching list of apps

List Apps

The listApps function returns all the registered apps. It accepts rankings and pagination arguments.

Example

// Init AppRegistry

const response = await registry.listApps({
  rankings: { direction: "DESC", attribute: "createdAt" },
  pageNumber: 1,
  pageSize: 10,
});

Get App Total Points

Returns the total point by the appId. Optionally you can provide session to get total points for the app for that session only.

Example

// Init BPS

const response = await bps.getAppTotalPoints({
  appId: 3n,
  session: 1n,
});

Get App Available Points

Returns the total point by the appId after distributing it to the user. Optionally you can provide session to get total points for the app for that session only.

Example

// Init BPS

await bps.getAppAvailablePoints({
  appId: 3n,
  session: 1n,
});

Aggregate App Points

Returns a list of total points grouped by the appId. Optionally you can provide session to get total points for each app for that session only. You can also provide rankings and pagination arguments.

Example

// Init BPS

const response = await bps.aggregateAppPoints({
  session: 1n,
  rankings: { direction: "ASC", attribute: "points" },
  pageNumber: 1,
  pageSize: 10,
});

Get User Total Points

Returns the points of a user. Provide session to get total points for a session.

Example

// Init BPS

await bps.getUserTotalPoints({
  account: "0x....",
});

Aggregate User Points

Returns a list of total points grouped by the user address. Optionally you can provide session to get total points for each user for that session only. You can also provide rankings and pagination arguments.

Example

// Init BPS

const response = await bps.aggregateUserPoints({
  appId: 3n,
  session: 1n,
  rankings: { direction: "DESC", attribute: "points" },
  pageNumber: 1,
  pageSize: 10,
});

List Points Transfers

Returns a list of point transfers. Optionally you can provide appId, session, user, status, rankings, and pagination arguments.

Example

// Init BPS

const response = await bps.listPointTransfers({
  appId: 3n,
  session: 1n,
  user: "0x....",
  rankings: { direction: "DESC", attribute: "points" },
  pageNumber: 1,
  pageSize: 10,
});

Discover B3 - the Based L3