Community Leaderboards


The Community Leaderboard is a new primitive that allows NFT projects to build fully on-chain leaderboards.
Our Community Leaderboard primitive allows NFT projects to rally their communities in order to achieve their goals. Projects are able to do this by creating leaderboards for specific behaviors/goals/polls, allowing the community to vote on-chain, then rewarding the top addresses in the leaderboards with token allocations or airdrops.
Since the leaderboards are fully on-chain, anyone can build on top of the protocol and create their own frontend integrations, reward mechanisms, or even gate their protocol features.

User flow for project owner/admins:

  1. 1.
    Register the project by inputting a ERC-721 contract that their address owns and the name of the project. User will receive a project ID number.
  2. 2.
    Create a leaderboard by inputting the project ID number, the name of the leaderboard (should indicate the purpose of leaderboard, such as: “Best Character Lore“) and the epoch. The epoch indicates how long the leaderboard lasts before resetting. Leaderboard data will persist in smart contract and subgraph even after the leaderboard resets.

User flow for voters:

  1. 1.
    User finds the wallet address of the user they wish to vote for.
  2. 2.
    User navigates to the desired leaderboard in the project and inputs the address they wish to vote for and their token ID. Token ID indicates which NFT they own (will not be required in V2).
  3. 3.
    User can change their vote if the current epoch has not passed.

Smart Contract:

Our Community Leaderboard smart contract is located on Polygon mainnet:
Address: 0xe21e026ff9b4ad82e10ea25d248ecc5a647925ad
Network ID: 137 (Polygon mainnet)

Smart Contract Functions:

  • registerProject
    • Inputs: address _nftContract, string memory _name
    • Registers a new project in smart contract. Each project is uniquely identified by the address of its ERC-721 contract. Function will verify that the person calling it is an owner of the ERC-721 contract using Open Zeppelin Ownable standard.
  • addOwnerToProject
    • Inputs: uint256 _projectId, address _newOwner
    • Adds a new owner to an existing project. There is no limit on the number of owners. Must be called by an owner of the project in question. Each Project object contains an array of addresses of the owners (or admins) of the project.
  • createLeaderboard
    • Inputs: uint256 _projectId, string memory _leaderboardName, uint256 _time
    • Creates a new leaderboard that belongs to an existing project. The name of the leaderboard will be displayed on the frontend, should explain what the leaderboard tracks, for example: “Top Meme Creators”. Time input is measured in blocks.
    • Project ID is a required input. This is an integer that will be provided when you register the project.
  • castVote
    • Inputs: uint256 _projectId, uint256 _leaderboardId, address _member, uint256 _nftTokenId
    • Allows users to vote for a member of the project by inputing their address. Requires an input of the project ID and leaderboard ID, which will be provided by the frontend. Requires the user to input the token ID of the NFT that they own, will call ERC-721 contract to verify that they own this NFT. If the epoch of the leaderboard has past, it will create a new leaderboard instance.
    • V2 will not require the token ID of NFT owned to be inputted since we will automatically verify by calling the ERC-721 contract.
  • changeVote
    • Inputs: uint256 _projectId, uint256 _leaderboardId, address _member, address _newMember
    • Allows users to change their vote on a specific leaderboard. Requires the user to input the address of the previous member they voted for and the new member that they wish to change their vote into. Function will verify that their previous vote exists.


We have a subgraph for the Community Leaderboard that allows you to retrieve any information from the smart contract such as the number of votes on a leaderboard or the owners of a project.