Leaderboards
Rank members by their points, run weekly races, and hand out prizes to the winners.
A leaderboard ranks your members by the points they hold or earn. Use one to make taking part feel like a game. For example:
- A weekly race where the top three get a prize every Monday.
- An all-time "top contributors" list on your community page.
- A referral race that ranks members on a ledger only your referral program pays.
A board reads one of your point ledgers. You choose how it scores members, which time window it covers, and, if you want, which group of members or which quests count.
Scores are calculated from points
Members climb a board by earning points. When a quest pays points into the board's ledger and matches the board's filters, the member's score goes up. Your app never submits a separate leaderboard score.
| Score | Meaning |
|---|---|
| Balance | What the member holds now. Spending points lowers their rank. |
| Earned | Points earned in the window, with corrections. Spending doesn't count. |
| Net | Everything that changed in the window, including spending. |
Earned and net boards can cover all time, fixed dates, the last few days, or the current calendar day, week or month. A calendar window follows your project calendar, so a weekly board covers the same week as your weekly budgets. Weeks start on Monday. A point counts in the window it took effect in: a quest's points take effect when the attempt is accepted, while its budget is charged on the day of the activity, so the two can differ.
- Imported balances count on balance boards only. Opening balances a member import brought from another platform never decide an earned or net race, or its prizes.
- Referral points count too. They raise the same ledger's standings unless the board's filters leave them out. Decide how points enter the ledger separately from how a board ranks them.
External scores
Want to rank something measured outside Domino, like a game rating or a token balance? Give it its own ledger and keep that ledger equal to the score. A balance board then ranks it like any other.
Standings
- Ties share a rank, or go to whoever got there first. By default equal scores share ranks. A board can instead rank first whoever reached the score earliest, the same order a settlement with
earliestties uses, so every member who scored has their own rank. Either way, members without qualifying entries rank after every member with one. - No points, no rank, unless the board lists everyone. Members without qualifying entries stay unranked. A board can list all its eligible members, showing those who haven't scored at 0 points after everyone who has. Prizes still go only to members who scored.
- Use returned ranks. Your app should show the ranks Domino returns, not row positions.
- Members can see how they scored. A signed-in member can read the entries behind their own score on a board, and they add up to the score. See Show how a member earned their score.
- Looking changes nothing. Reading standings never triggers referral payouts or reward delivery.
Exclusions
You can leave a member out of a board, for example a team member or someone caught gaming it. Their points stay exactly as they were; they just don't appear in the standings or win its prizes.
A board leaves out the members of its exclusion group, a group like any other. A member counts when they are in the board's group (if it has one) and not in its exclusion group.
- Each board starts with its own group. Excluding a member from a board for the first time creates the board's exclusion group.
- Excluding is a group change. Exclude from this board in Console adds the member to the exclusion group, and reinstating removes them. Adding or removing them in Groups does the same.
- Share a group only on purpose. Change exclusion group in Console points a board at another group. Every board using one group leaves out its members, so excluding someone from one of those boards excludes them from all of them. Point the board back at its own group to undo it. Changing the group is a definition, so it reaches live by promotion; excluding and reinstating members work in live.
- A group in use can't be archived. You can't archive a group a board uses for exclusions, and you can't point a board at an archived group.
Prize settlements
A weekly or fixed-dates race can pay prizes when it ends. When the window closes, Domino freezes the result: the board as published, who was eligible, who was excluded, the ranks and who won what. Later points and board changes never rewrite it. Your team reviews the frozen result before anyone is paid.
- Approval pays the winners. Approving creates one completion for each winner and grants its points and tier rewards the same way a quest completion does.
- A single winner can be corrected. Revoking a winner's completion takes back their points and reward, and the reviewed result stays visible. It can't reopen the prize or pay it again.
- Rejection closes the window. See Reject a pending settlement.
- Only boards with an end can pay prizes. Balance, rolling and all-time boards never settle. Discord roles can't be leaderboard prizes.
- Late points don't count. Points must land inside the window and arrive by its end, or, on a board that takes a closing measurement, by the time the result freezes. Points backdated after the freeze never change it.
Ties need a rule. You choose one, separately from the order the live standings use; pick the same one for both so members see the order prizes will follow:
| Policy | Equal scores |
|---|---|
shared | Members share the same rank. Every member whose shared rank matches a prize range receives it. |
earliest | Members are ordered by the time of their last qualifying score entry, then by member ID for a stable final order. |
Pool prizes
A settlement can also split a pool prize, a fixed amount such as 10,000 USDC or 5,000 points, over the frozen eligible members in proportion to their scores. A board may have rank prizes, a pool, or both, and Relay computes them independently.
- Who shares. Only frozen rows share, so excluded members and members outside the board's group get nothing and their part goes to everyone else. A member scoring 0 or less gets nothing, and so does a member at or below the pool's
minScore. - Exact split. Each pool share is
amount × score ÷ total, rounded down, in whole base units of the pool's unit. The units left over go one each to the largest remainders, the earlier position first when remainders are equal, so the shares add up to the pool exactly. Relay uses integer arithmetic throughout. - Nothing to split. If no member scored above the minimum, nothing is allocated and the settlement shows the whole pool as unallocated.
- Frozen with the row. Each share is stored on its frozen row and never recomputed, so a later change to the board leaves earlier settlements as they were. Reviewers see every share before approving.
What approval does depends on the pool's unit:
| Unit | On approval |
|---|---|
"points" | Each share is a points reward into the pool's ledger, in the member's prize completion beside any rank prize. Revoking the completion reverses it. |
| A token or currency | Nothing moves. The approved shares are the record of what is owed, and the settlement's export lists each share with the member's verified wallets. |
Relay never holds or moves tokens or money. For a non-points pool, you pay each member yourself from the export and track the payment in your own system; revoking a member's rank-prize completion does not change their recorded share. A rejected settlement allocates nothing: its export owes no one, though its review keeps the frozen shares.
Closing measurement
Engagement points take effect when their growth was measured, but measurements arrive on the tracker's refresh schedule and are paid once a day. So a settling board whose score counts an engagement rule's points (the rule pays into the board's balance and, on an earned board with quests, qualifies through one of them) does not freeze at the cutoff. Its settlement starts closing instead: it reads as pending with no rows, and its closing field holds when the measurement started and its deadline. Console shows it as Measuring.
- Relay asks the scheduled trackers that collect the content those rules pay for to sample it again now, ahead of their refresh interval. A custom source that receives records by ingestion needs a fresh record from your app.
- A sample observed within 30 minutes after the cutoff counts as measured at the cutoff, so its growth lands in the window that closed. Relay pays it right away, off the daily schedule.
- When every item is measured, the settlement freezes: its rows appear and
closinggoes away. If 30 minutes pass first, each item without a closing sample settles its last good sample, and the settlement freezes once they have, at most 10 minutes later. Those items count at their last good sample and are listed in the settlement'sunmeasuredlist with that sample's time.
Content waiting on qualification or a paused quest, or that was removed, earns nothing and is not measured. Boards that count no engagement points freeze at the cutoff.
A reviewer can approve a settlement with unmeasured content as is, or choose Retry measurement in Console (retrySettlementMeasurement(id), or domino leaderboard-settlements retry-measurement SETTLEMENT). The settlement drops its frozen rows, closes again for another 30 minutes, and freezes again. Growth measured that late splits at the cutoff in proportion to time. While a settlement is closing it cannot be approved (settlement-closing); a pending settlement with nothing unmeasured has nothing to retry (settlement-measured).
Eligibility changes
Joining a group can also open automatic quests that were waiting on it. Points from a leaderboard prize can do the same once the prize is paid.
Where next
Definitions, prize review, member reads, external points, and moderation.
How points enter the ledger a board reads.
Where calendar windows begin and end.
Archive a leaderboard
Archive a board with Archive leaderboard under About this board, or in Settings → Resources, to hide it from members. Members can no longer read its standings; your team still can, with its history. Unarchive it to show it again under its existing access rules. Removing the board from code and redeploying keeps this decision. See resource lifecycle.
Read standings and exclusions from the CLI
domino leaderboards list lists published boards, domino leaderboards standings BOARD pages current standings best rank first, domino leaderboards history BOARD lists published definitions, and domino leaderboards exclusions BOARD lists excluded members. domino leaderboards exclude BOARD MEMBER --reason "…" removes a member from standings and settlements, and include adds them back. domino leaderboards exclusion-group BOARD shows the board's exclusion group, and domino leaderboards bind-exclusion-group BOARD GROUP --reason "…" binds another one. They call the same management methods as a trusted server, with the same permissions.
Reject a pending settlement
A reviewer can choose Reject settlement in Console with a reason, while the settlement is pending or still measuring. Rejection keeps the frozen result for the record, pays no prizes and closes that window for good. It does not freeze the window again. Once a settlement is approved, it can't be rejected.