Leaderboards

Add competitiveness and gamification to your DApp and reward loyalty fairly to your customers and users.

Leaderboards allows the creator of a DApp deployed with DexAppBuilder to add several scoring systems to reward the users of their onchain application every time they execute any of the predefined actions in the system.

For the specific case of this feature we will create a demo DApp. It will be a semi-private NFT marketplace. The creator (we) may post NFTs for sale without restrictions and may also accept listings from the community.

Predefined configurable actions

Among those predefined actions are:

Swap tokens: Award N amount of points to the user who makes an exchange operation using the swap component.
DApp Login: Give N number of points to the user every time they log in with their wallet to the DApp. This is controlled by digital signatures.
Accept ERC721 listing: Grant N number of points to the user who is accepted to list a non-fungible token with ERC721 characteristics. For example, for our semi-private NFT marketplace, when “User” is an entrepreneur who wants to sell his ERC721 tokens there, we can accept the listing of tokens from “User” and the latter he will receive N number of points upon your acceptance as creator or superadmin.
Accept ERC1155 listing: This rule is similar to the previous one but with ERC1155 tokens.
Accept ERC721 Offer: Award N number of points to a user when they accept an offer for an ERC721 token. In other words, when user buys the token got the points for this action.
Accept ERC1155 Offer: Similar to the previous rule, except that it rewards users for purchasing ERC1155 tokens.
Buy Drop Collection: Awards N number of points to the user who purchases a token from a drop collection deployed using Thirdweb smart contracts included in DexAppBuilder.
Buy Drop Edition: Award N amount of points to the user who purchases an Edition Drop contract token.

Creating the first Leaderboard

Because it is much easier to explain a concept through examples, below we show you how to create your first leaderboard for your users.

First of all, you must keep in mind that several conditions apply for your leaderboards to be successful and to take the correct metrics for your onchain application.

You must have a DApp created with DexAppBuilder: it is the first step to be able to access the system. In turn, we recommend that you create the leaderboards once you have the DApp finished so that the scores are not contaminated and you can deliver a fair experience to your users. Read here about how tu create your first DApp.
You must have deployed the contracts you need to measure the predefined actions: In the cases of actions that involve Thirdweb contracts, it is necessary to have the contracts previously deployed for the scores to work.
Make sure one of your first steps are import the NFT collections and tokens that you want to accept in your DApp. This will make everything easier for you setting up all the features later. You can refer on this documentation about how to import custom tokens in your DApp and how to import custom NFT collections as well.
Use a testnet, to test: DexAppBuilder provides access to several test networks so you can “make mistakes for free” 😅 we don't want you to lose money creating your products, so we recommend using these networks to your advantage (Polygon Mumbai, Ethereum Goerli and Sepolia, Blast Sepolia). You can get test tokens here for Polygon Mumbai, here for Ethereum Goerli and here for Blast Sepolia (and other few ones).
Be patient: you are dealing with beta software, which, while safe, can sometimes present glitches in the graphical interface. If you see something strange, report it in our Discord or go to Canny and send us your Feature Requests.

Once inside we will observe the dashboard. Since it is the first time it will be empty.

We are going to add the first leaderboard by clicking on the blue “Add leaderboard” button.

In the modal that has been opened we proceed to give the table a name and an appropriate description. Later we can edit them.

Once we finish filling out both fields, we click on the «Save» button and we return to the dashboard. We can see our first created table in the list. At the end of the row we can see a list of actions, namely:

Preview app leaderboard: Take a look at how user rankings are going in this specific table.
Edit leaderboard: This is the first step to configure the table. In turn, it can be used later to edit the table's metadata.
Export leaderboard: for your convenience, you can export this data to your device using a csv file that allows you to process the information more flexibly.
Delete app leaderboard: Delete this table and all its data. Be careful! This action is irreversible! Not even DexKit will be able to recover this data.

Setting up our leaderboard

We have already created our first leaderboard and now we need to configure it to contain the predefined rules that will give various scores to the users of your DApp.

In the case of this example, we create a leaderboard called “Summer Season 2024” in which we will place a set of gamified rules (or actions) that will reward users who comply with them. Next, let's summarize the rules that we will use for this table. To access on table configuration click on the button at the end of the row.

Once we are in the leaderboard configuration we can see the following screen:

Rule 1: We want users who log in (authenticate to the DApp) to receive 1 point. These authentications will last exactly 24 hours, so this rule can help you know if a user is authenticated daily based on 1 point per day.

Rule 2: At the same time, we want users who use the token exchange platform to receive 3 points every time they make a token swap. With this we reward user preference in a balanced way.

This particular condition allows us to widely customize what, how, and who to reward with the specific score. We can choose the network, the token and the amount needed to satisfy this condition. Conditions for amounts are gt (greater than), gte (greater than or equal), lt (lower than), lte (lower than or equal) and eq (equal).

Rule 3: Since our example DApp is a semi-private NFT marketplace, we can also award points to users who suggest listings for NFTs of ERC721 and ERC1155 standards specifically. We as creators will accept the specific list and with that action we will award 5 points to the user.

Rule 4: This rule pertains to an event where an offer for an ERC721 token is accepted.

Points: This represent the points assigned to this particular action within the system.
Filter: Below the points, there is a section for setting filters.
Choose network: Select the target network. Must be the same for the NFT collection you are importing to.
Import: This option may allow the user to import data from their own NFT collections starting from the contract address.
Your collections: User can select from various collections they listed in the DApp.
Search token: You can choose a specific token within the collection.
Condition amount - This is a condition that will be applied to the amount field below it.
Amount - Enter an amount here to specify that the rule should only apply when the amount is greater than the specified figure (10 MATIC tokens on Mumbai Testnet on this example).

Once we finished setting up our leaderboard rules, we hit on «Save» button in the end of the page to record all the rules.

Checking our leaderboard

Once we have our leaderboard working with the rules you chose, you can go to the Leaderboards option, look for the board you just created and click on the first icon for a leaderboard preview as below 👇

Exporting our leaderboard data

To download all the data from this leaderboard you can click on the icon that will open a modal with a button to download a CSV (Comma-Separated Values) file 👇

This option is of great help when your DApp has many users and you need to refine information quickly.