# Open Quest & Leaderboard

## Why?

Projects wanted their users to perform task with gamified activities in exchange of points that can be converted to rewards within their app and community. At the same time provide transparency to the community on how leaderboards are ranked without centralized control. Since we are launching our app templates with some tapper/clicker micro games, these leaderboards are essentials to make this possible to award points based on completed quest items by users.

### Transparent Community Building

This leaderboard allows to transparently showcase your growth number by tracking participating users for any implementing app wether from **Xircus** deployed apps or outside our platform. We are providing a GraphQL API endpoint where you can request these collected data for any future use. Take note that these leaderboard only collects authenticated wallet addresses and a randomly generated username, no other personal information requested. These data can be exported via CSV or JSON format by leaderboard owner only.

### On-Chain and Off-Chain Verification

What's unique about these quests is that they were fully integrated with web2 and web3 verification mechanism to verify users real activity from different platforms and TON based transactions and contract operations.

* **On-Chain** -> users transactions are verified wether from having token balances, processing a contract operation or simple transfer call
* **Off-Chain** -> user participation are verified from joining and interacting with platforms as part of the quest like following a twitter account, joining telegram, participating in mini apps and more

### Multi-App Implementation

Each quest can be implemented by any **Xircus** powered web3 app wether Telegram Mini App or TON Web App so there's no need to create new quest for each app they can just share the same resources specially if you have deployed multiple connecting apps. For example, a marketplace app that tells people to launch NFTs in auction app and stake JETTONs in a staking app.

### Gamified Quest Items

Each quest item has varying point value which is added up to the user points on completion which boost their standing in the leaderboard ranking and to unlock levels and badges

### The Leaderboard Explorer

Explore any public visible leaderboards who implemented our Leaderboard SDK or built-in leaderboard UI components in deployed TON web apps and Telegram Mini apps

## User Flow

* Join Quest
* Complete Item Tasks
* Rank In Leaderboard

## Use Cases

* A Collection Drop Campaign -> Create a quest for your upcoming NFT launch, let users participate and complete all quest item tasks to be part of the allowlist or whitelist. Those users in the top 3 of your leaderboard gets to mint for free, from 3 to 25 gets 50% discount, and 25 onwards gets 10% discount
* A Marketplace Campaign -> Create a quest for your marketplace where users receives points when they deploy their collection, mint their nfts and list them in your marketplace contracts
* An Auction Campaign -> Create a quest for your upcoming token auction that let users earn points by sharing and hyping your token in different social platforms to boost engagements and interest in your upcoming sale

## Quest Activity Types

* Invite / Referral -> sharing an invite link
* Link -> opening a link
* Login ->  hourly or daily login
* Prompt -> answering a question
* Telegram Join -> joining telegram
* Twitter Follow -> following a twitter account
* Twitter Share
* Deploy Telegram Mini App
* Deploy TON Web3 App
* Deploy Collection
* Deploy Jetton
* Mint NFT 
* Mint SBT 
* Deposit Supply

## Quest Components

* **Max Allocated Points** are maximum allowed points to be given
* **Schedule** contains the start time and end time of a quest
* **Allowlist** contains the user addresses that are allowed to join
* **Items** are the quest tasks with configurable conditions
* **Badges** are claimable based on consistency on X task
* **Levels** are claimable based on total points earned
* **Ranks** are assignable or given by app owner to any account

## DUST UI Blocks (dust-common)

<table><thead><tr><th>UI</th><th width="384">Description</th><th>Requires</th></tr></thead><tbody><tr><td>Leaderboard</td><td>List all users who joined the quest and rank them based on points and latest activity</td><td>Quest ID</td></tr><tr><td>Quests</td><td>Displays all quest created for the app</td><td>N/A</td></tr><tr><td>Quest</td><td>Displays the info of the quest including total users, total points awarded, total points available and </td><td>Quest ID<br>(Props or Query)</td></tr><tr><td>Quest Create</td><td>Displays a form to create the basic info of the quest</td><td></td></tr><tr><td>Quest Edit</td><td>Displays a form to modify the current quest info, items, badges, levels, ranks</td><td>Quest ID<br>(Props or Query)</td></tr><tr><td>Quest Account</td><td>Displays the quest journey and stats of the current account or specific account or wallet address</td><td>Quest ID<br>Account ID or Address</td></tr><tr><td>Quests Admin<br>(Editing Panel)</td><td>Displays all quests created by the current admin</td><td></td></tr></tbody></table>

## Quest Item Properties

* Repeatability or recurrence -> this is how often the item can be accomplished by the account. For example, Daily, Weekly or Monthly
* Max Claim Limit -> this the number of times an item can be awarded to an account
* Required Level -> these are item types that are locked until the account reaches a certain level
* Verification -> there are item types that requires on-chain or off-chain verification. For example, following a twitter account, requires to verify if a certain twitter account followed the requested account
* Mystery Type -> these items will only unlock if they are completed (TBA)

## React Hooks

{% tabs %}
{% tab title="Yarn" %}
`yarn add @xircus-web3/ton-react`
{% endtab %}

{% tab title="NPM" %}
`npm install @xircus-web3/ton-react`
{% endtab %}
{% endtabs %}

{% code title="How to use" %}

```javascript
import { useQuest } from "@xircus-web3/ton-react"
...
const { quest } = useQuest(QUEST_ID)
```

{% endcode %}

<table><thead><tr><th width="212">Name</th><th>Description</th></tr></thead><tbody><tr><td>useLeaderboard<br>(questId)</td><td>Returns the list of users that is ranked based on points and recent activity<br>Ability to extract to CSV or JSON (Admin Only)</td></tr><tr><td>useQuest<br>(questId)</td><td>Returns the quest info<br>update -> Ability to update all details (Admin Only)<br>assignTo -> Ability to assign to any app<br>allowlist -> Ability to add allowlist</td></tr><tr><td>useQuestAccount<br>(questId, appId)</td><td>Returns the current status of an account including points, rank, level and others<br>join -> Ability to join<br>award -> Ability to do task by awarding to account<br>verify -> Ability to verify quest item<br>claimLevel -> Ability to claim level  (if not awarded)<br>claimBadge -> Ability to claim badge (if not awarded)<br>claimRank -> Ability to claim rank  (if not awarded)<br>claimReward -> Ability to claim reward </td></tr><tr><td>useQuestAdmin</td><td>Returns all quests created by current account as admin<br>create -> Ability to create new quest<br>setVisibility -> Ability to toggle quest visibility to public or private<br>assignTo -> Ability to assign to any app</td></tr><tr><td>useAppQuests<br>(appId)</td><td>Returns all quests that are associated to an app<br>unassign -> Ability to remove association of an app<br>restrict -> Ability to prevent quests to associate the app (TBA)</td></tr><tr><td>useQuests</td><td>Returns all public quests created from Xircus Studio</td></tr></tbody></table>