Quests

A quest is one thing you ask your community to do. Domino checks that they did it, counts it once, and hands out what they earned. For example:

• “Answer three questions about our launch”
• “Post about us on X”
• “Upload a selfie at our booth”
• “Invite a friend”

What members see

Each quest can show instructions, a list of steps with links, an image, a video, and quiz questions. It can also hint which account or wallet to link. Opening a link in a step doesn't complete the quest on its own: Domino still checks the activity.

Your developer sets the defaults in code. In Console you can replace the steps, the image and the account hints together, and reset them to the defaults later with Reset to type or Reset to code.

How Domino checks a submission

When a member sends their answer, link, or photo, Domino checks it, and can hand unclear ones to your team for a decision.

If a check fails for a technical reason, that's not counted against the member, and the submission can still go through.

Domino keeps a member's answer while they fill it in, so a lost connection or a second tab doesn't send it twice. If the quest changed since they opened it, Domino asks them to look again before sending, and keeps what they wrote. An unsent answer expires 7 days after its last change. You can discard one from the member's page in Console.

A member can have one unfinished try per quest at a time. Until it's decided, including while it waits for your team, they can't send another.

When your team reviews

A quest can send unclear submissions to your team. If human review is off for the quest, an evaluator's "send to review" becomes a rejection instead, and Console marks it "Would have gone to review; human review is off". Turn review on if unsure results should reach a person.

When Domino rejects a submission, the member sees the reason written for them. Your developer can also tag each kind of rejection with a code, so you can tell them apart in Console without the member ever seeing it.

Stop people guessing

Add a retry cooldown to make members wait before trying again after a wrong answer, so nobody solves a quiz by trying every option. New quiz quests in Console start with a 5-minute cooldown.

Retry cooldown

Without a cooldown, a member can try again as soon as an attempt is rejected. Set one in Console under Retry cooldown for quests made there; other quests, and quizzes defined in code, start with none. Only quests members submit themselves can have one.

The cooldown applies only to the member whose attempt was rejected. It always uses the quest's current length, so shortening or removing it helps members who are already waiting.

Submission limit

Every member can submit 120 attempts an hour in a project, across all its quests, counted separately in test and live. It is a ceiling for scripts, far above what a member needs to finish every quest in a starter. Past it, their submissions are refused until the hour moves on, and the answer they were submitting stays saved. Test members you act as in Console are not counted; a test member signed in to your staged app through the staging toolbar counts like any member.

How often someone can complete it

Your team can also take back a completion made by mistake, accept an attempt that was rejected by mistake, or delete the evidence a member submitted. See revoke a completion, accept a rejected attempt anyway and delete an attempt's evidence. Domino deletes evidence on its own 90 days after the decision unless you choose otherwise; see how long evidence is kept.

Completion cooldown

A quest members can complete more than once can make them wait between completions, for example so a second story counts only 90 minutes after the first was accepted. The wait starts each time a completion is accepted. A rejection doesn't start it, and a completion your team revokes doesn't count. If a retry cooldown is also running, the member waits for whichever ends later.

The cooldown applies only to that member, and always uses the quest's current length. Set it in Console under Completion cooldown for quests made there. Only quests members submit themselves can have one.

When a quest opens again

Your app can show members a countdown to when they can try again: after a cooldown, when a used-up budget resets, or when a once-a-day or once-a-week counter opens its next window. There is no countdown when the member can try now, or when nothing will reopen the quest, such as a lifetime budget that's used up or a quest whose dates end first.

Keys shared by members

A per-occurrence quest normally lets every member complete each occurrence once. A quest can instead give each occurrence to the first member who completes it: a code your backend issued that only one person may redeem, or a post that pays only one claimant. When someone else already holds the occurrence, a member's attempt is rejected and says another member already completed the quest with it. Two members who try at the same moment can't both be paid.

Console's attempt detail shows that rejection, and the quest's Completion reads Once per key, across members. To give the occurrence to someone else, revoke the holder's completion and free its occurrence, then accept the other member's attempt anyway. Member imports follow the same rule: a row is refused when another member, or an earlier row, already used one of its occurrences.

Who can take part

Prerequisites decide who can try a quest. A member can need to have completed another quest, hold a minimum number of points, or belong to a group, such as your VIPs.

• Completed another quest. For example "Welcome" before "Daily check-in", or a check-in today before today's bonus.
• Holds enough points. This is checked against the member's current balance, so spending points can make them miss it again.
• Belongs to a group. Your team adds members in Console Groups, or a quest's reward adds them. The same group can also limit leaderboards and referral rules.

A quest needs every prerequisite it lists. For a rule they can't express, such as "any two of these five quests", your developer can check it in the quest's own code.

Prerequisites control who can take part. Collections only control the order quests are shown in: listing a quest second doesn't require the first one.

Quest types and settings

A quest type is a reusable kind of quest, such as a quiz or a photo upload, with settings you fill in. In Console you can create quests from the types your app supports. Each quest has its own progress, even when it shares a type with another quest.

• Your app supports the interaction. The app must handle the quest's interaction, such as a photo, quiz, or claim.
• Console can customize a code quest. You can change the settings a code-authored quest exposes. Your values win over the code's defaults until you reset them; the rules themselves stay in code.
• Secret settings stay in Domino. A code quest can have a secret setting, such as a shared scan code. You set it in Console, and the quest reads it, but no deploy output, quest listing or Console screen shows it again (change a setting).
• Keys keep a quest's identity. Changing a title or renaming a source file keeps the same quest and its history, as long as its key stays the same.
• Duplicates are separate. Duplicating a quest starts a new completion history.

Pause and archive

A quest is active, paused, or archived. Console shows its state as Active, Paused or Archived under Participation. Where you pause it depends on where the quest comes from:

• A quest made in Console. Choose Pause or Resume under Participation, then review and publish.
• A quest synced from code. Choose Pause quest under Quest availability in its Activity & details, with a reason. This pause applies to the selected environment only, and works in live too. Participation doesn't offer a pause for these quests; it shows Paused only while a resource setting is empty.

• History stays. Completions, attempts, points, and rewards remain. Attempts already under way keep their rules. Content qualification and engagement settlement for an archived quest wait until it is unarchived.
• Members keep what they earned. Members who completed an archived quest still meet requirements on it.
• Deleting the code doesn't archive it. Deploying its code again keeps an archived quest archived. Archive and unarchive in Console or with domino quests.
• Live waits for promotion. Archive state is part of a quest's definition, so you can't archive in live directly; pause a live quest instead. See Archive a quest.

Revoke a completion

Someone on your team with review permission can take back a completion that was accepted by mistake or through fraud, with a reason. The completion then stops counting: it disappears from progress, counts and profiles, no longer unlocks other quests, and no longer qualifies a referral. The attempt stays accepted, and its history shows the revoke and the reason.

Everything the revoke changes happens at once, or not at all:

You choose whether the member can complete the quest again for the same occurrence (its completion key):

• Kept occurrence (default). The revoked completion still holds it, and the budget it used stays spent. Later attempts for it are rejected. A manual streak still records later days and pays nothing; a tracker-triggered once() or streak quest skips its observations, so it records no days at all.
• Freed occurrence. A new attempt can complete it and earn its rewards again. The quest's budgets get back what the completion used, so the occurrence can be completed again within its caps. An automatic quest without a tracker or content trigger queues a fresh attempt immediately if its prerequisites still hold. A tracker-triggered quest needs a new matching observation; replaying the original observation does not pay again. A manual keyed quest needs a new action ID and can reuse its freed completion key. A streak pays its milestone again on the next qualifying day, because its days stay.

On a quest whose keys are shared by members, the choice applies to every member: a kept occurrence keeps the key from everyone, and a freed one lets any member complete the quest with it.

Completions it already unlocked stay. Freeing the occurrence returns to each budget what the completion was charged, in the budget period it was charged to; a budget priced in points gets back the charge less the points the revoke couldn't reverse, because those stay paid out. Completions recorded before Domino kept their charges give no budget back. In Console, revoke from the member's Completions or from the accepted attempt.

Console keeps an unreversed point remainder on the revoked completion in the member and attempt drawers. A person with points permission can open the member's existing point adjustment from the warning and record a separate correction with its own reason. That adjustment is an operator decision; revocation itself never creates debt or deducts the remainder later.

To revoke every completion of a member who farms, ban the member and take back their completions: each one is revoked this way, keeping its occurrence.

Restore a revoked completion

A revoke made by mistake can be undone. Someone with review permission restores the completion with a reason, and the completion counts again. Restoring re-applies what the revoke recorded, not the quest's current rewards, so it never gives back more than the revoke took, even if the quest's rewards changed since.

Everything the restore changes happens at once, or not at all:

Budgets stay as the revoke left them when it kept the occurrence. When it freed the occurrence, the restore charges each budget again what the revoke returned, against the budget's current limit (or the limit it was first charged under, if the quest removed the budget or changed its period or cost); if a budget has no room left, because other completions used it since, the restore is refused and nothing changes. The completion holds its occurrence again. If the revoke freed the occurrence and the member has completed it again since, the restore is refused, because two completions can't hold one occurrence.

The revoke stays in history: the attempt's history shows the revoke and the restore, each with its reason, and Audit history lists both. In Console, restore from a revoked completion in the member's Completions or on the accepted attempt.

Accept a rejected attempt anyway

When a reviewer or Domino's check rejects an attempt by mistake, someone on your team with review permission can accept it anyway, with a reason. It works for any member, in test and in live.

1. In Console, open the rejected attempt from Quest activity.
2. Choose Accept anyway, write why the rejection was a mistake, and confirm.

The attempt is accepted as if a reviewer had approved it: the member gets the completion and its rewards, budgets are spent, referrals can qualify, and the member's activity and your webhooks see a new acceptance. The rejection is not erased. The attempt's history shows the rejection and the reversal, each with its reason, and the rejection's retry cooldown ends.

Domino refuses, and leaves the attempt rejected, when:

A counter or streak quest counts the accepted attempt as one action, as an approval does, and its own rules decide whether that action completes it: the refusals above apply only when the acceptance would create a completion. A quest that completes per piece of content can't be accepted this way. To take back an acceptance, revoke the completion.

Delete an attempt's evidence

When a member asks you to delete what they submitted, such as a selfie or an email address they typed in, someone on your team with review permission can delete it, with a reason. The attempt and what it earned stay. It works for any member, in test and in live.

1. In Console, open the attempt from Quest activity.
2. Choose Delete evidence, write why, and confirm.

The attempt then shows who deleted its evidence and why, and Audit history lists the deletion. Other attempts that submitted the same photo lose it too, and are listed in the result. Duplicate-photo checks keep working, because Domino keeps a fingerprint of each photo it has seen, not the photo.

You can delete evidence once the attempt is decided: accepted, rejected, partly counted toward a counter, or failed. An attempt still waiting for its check or for review keeps its evidence until someone decides it. An attempt without evidence can't be checked again, so retrying it is refused. A rejected one can still be accepted anyway. Deleting evidence can't be undone.

How long evidence is kept

Domino deletes the evidence of decided attempts 90 days after the decision, in test and in live, exactly as deleting one attempt's evidence does. You choose a different period for your project, from 1 day to 10 years, or keep evidence until someone deletes it:

1. In Console, open Settings → General.
2. Under Evidence retention, choose how many days after review evidence is deleted, or keep it, and save.

The period counts from the decision, so an attempt still waiting for its check or for review keeps its evidence until it is decided and the period has passed. Failed attempts, which have no decision time, keep theirs. A photo also submitted by an attempt that isn't due yet stays until that attempt is due too. Domino deletes due evidence every hour, a batch per project at a time, and the deletions appear in Audit history.

Nothing is deleted in a project's first 90 days. For projects that existed when Domino started deleting evidence, on 20 October 2026, those 90 days count from then, so their first deletions are on 18 January 2027; the project's settings show the date while it is ahead.

Anyone who can publish can make the period longer or keep evidence. Making it shorter, or switching from keep to a number of days, deletes evidence sooner, possibly a whole project's at once, so it takes an organization admin or a service key holding publish. The project's access history records each change with the old and new period.

Delete old evidence on a schedule

When you promise members to keep what they submit for less time than your project's period, or for a different time per quest, such as selfies for 7 days after an event, a job deletes it for you: each pass deletes the evidence of one quest's attempts decided before a time you choose, exactly as deleting one attempt's evidence does. For different periods per kind of evidence, run one pass per quest. See delete old evidence nightly for a scheduled job that does it.

In test, anyone with review permission can run a pass. In live, a pass deletes a whole quest's evidence at once and can't be undone, so it takes an organization admin or a service key with review, which only an admin can create. Reviewers who aren't admins can still delete one attempt's evidence in live.

A pass covers attempts that were accepted, rejected or partly counted toward a counter before the time you give. It skips attempts still waiting for their check or review, and failed attempts, which have no decision time. A photo also submitted by an attempt the pass doesn't cover, such as one waiting for review, one decided later, or one on another quest, stays with all its attempts. The time can't be in the future.

Calendar-day streaks

A streak quest rewards days of activity in a row, such as posting on X five days running or checking in every day for a week. Domino records the day of each accepted try and pays the milestone when the run reaches its goal.

Each day comes from a time Domino trusts, the same time budgets use:

• A submitted streak counts submission days. A member who submits on seven days in a row completes a seven-day streak, whatever day the evidence shows. A submission that waits for review still counts the day it was submitted. To count the days the activity happened, start the quest from a tracker.
• Days follow the project calendar. Every streak in a project and environment counts days of the project calendar, not each member's device timezone. Days end at midnight in the project timezone.
• One action per day counts. Several actions on one day fill a single day. Today stays open, so a run survives until a whole day passes without activity.
• Each quest has one milestone. It pays once per member. A broken run can restart, but it does not pay the milestone again. Use separate quests for 7-day and 30-day milestones. Changing the goal, or switching between submitted and tracker activity, also needs a new quest.
• Late evidence counts at its activity time. A delayed tracker record can repair a missing day. There are no implicit grace days.
• Progress is not completion. An accepted action below the goal records progress without a completion.

A timezone change takes effect at the next midnight, keeps a running streak going, and never rewrites recorded days. See when the timezone changes, and streak progress for what members see.

Distinct-action counters

A counter completes a quest after several separate actions, such as three different posts in a week. Each action is checked on its own, and Domino counts the ones it accepts. Each action counts once, and an accepted action below the goal shows as progress, with no completion or reward yet.

Quests members submit and tracker-triggered quests support counters; content quests and prerequisite-only automatic quests do not. Your team can exclude or restore an action that hasn't been settled yet, with a reason. A counter's goal, window and repeat rules can't change after publication: publish a new quest for different rules.

See counter progress for member and operator reads, and qualified referrals for composition.

Quests that run on their own

Not every quest waits for a member to submit something. Domino can start one itself:

• From a tracker. A new post on X, a Discord message or reaction, or a record your server sends starts a check for the member behind it. See tracker-triggered quests.
• From creator content. Each post a content quest collects is checked and rewarded at most once.
• When a member qualifies. A quest with only prerequisites is checked as soon as the member meets them, such as reaching 100 points. See outcomes for prerequisite-only automatic quests.

Content-backed quests

A quest can read a tracker's dataset while it checks, or be started by it. A content quest turns each collected item that belongs to a member into its own try, checked again when its body changes and rewarded at most once. See UGC programs for admission, performance gates, and engagement points.

Tracker-triggered quests

A tracker-triggered quest checks each new record a tracker collects, for the member it belongs to: by default the author, or for example the person an X post replies to. When a record is skipped, Domino records why, and your team can retry it.

Checks that wait

Some checks can't be decided right away, such as a post that needs more likes. Domino then checks again later, up to 24 hours from the first wait and 100 times, and can show the member how far they are, such as three of five. Showing progress never completes the quest, spends a budget or grants rewards on its own: only a later acceptance can.

If the wait runs out, the attempt is rejected. Pausing or archiving the quest stops new tries but lets waiting ones finish under their original rules. Someone on your team with review permission can reject a waiting attempt to stop it. While an attempt waits, the member can't send another for the same quest.

Attempts and completion

This section is the precise model behind the pages above, for your developer.

An attempt is one try under a particular release of the quest. Completion is a successful attempt.

An accepted attempt keeps its original release and promised rewards. New publication does not rewrite an attempt already in progress. See progress and review for recovery and review behavior.

import {
  balanceAtLeast,
  completed,
  defineGroup,
  defineLedger,
  defineQuest,
  inGroup,
  manual,
  once,
  settings,
} from "@domino-sdk/relay/authoring";

const community = defineLedger({ key: "community", name: "XP" });
const vips = defineGroup({ key: "vip", title: "VIP" });
const welcome = defineQuest({
  key: "welcome",
  title: "Welcome",
  settings: settings.object({}),
  trigger: manual(),
  completion: once(),
  rewards: [],
});
const dailyCheckIn = defineQuest({
  key: "daily-check-in",
  title: "Daily check-in",
  settings: settings.object({}),
  trigger: manual(),
  completion: once(),
  rewards: [],
});

requires: [
  completed(welcome),
  completed(dailyCheckIn, { scope: "period", period: "day" }),
  balanceAtLeast(community, 100),
  inGroup(vips),
]

Trigger and completion rules

The trigger decides which completion rules a quest can use. TypeScript checks authored quests, and publication validates the same rules for every client.

Only content stages can declare performance evaluation. Reusable prerequisite-only quest types may leave the prerequisite list for Console instances; each instance must supply it before publication. Tracker beneficiary roles follow the source: choosing an account the source does not name fails validation.

How the check runs

The code that checks a submission is the quest's evaluator. Its runtime rules (repeated runs, the frozen clock and randomness, what a missing account or a provider outage returns, and which accounts are pinned) are in the authoring reference:

• See evaluation time and randomness.
• See evaluator readers: null, errors and pinning.
• The testing kit runs an evaluator locally under the same rules.

A missing or broken Discord connection is a setup problem, not evidence that a member failed the quest. Such an attempt ends as failed straight away with a clear reason. Fix the connection, then retry it.

Declared integrations

A quest declares provider modules with integrations: [discord, x]. The declaration controls which provider readers its evaluator receives: ctx.discord and ctx.x exist only for declared integrations. The SDK types and the hosted evaluator enforce the same rule. A quest using Discord role rewards or resource selectors also declares discord. Wallet, tracker, member, image and review readers remain available; an image sourced from X still needs the X declaration.

A quest can also name a module by its provider, such as { provider: "future-chat" }, for a module Domino adds before your SDK knows it. Such a quest builds, and publishing it refuses a module Domino does not have with unknown-integration-module.

Use discord.grantRole(roleId) for a declared role reward. Evaluators read provider state; durable reward delivery happens after completion. See integrations and the v1 upgrade steps.

Announcements

An announcement is a message Domino's bot posts in one of the project's connected Telegram chats or Discord channels when a completion pays, such as "@ana just received +10 XP by getting a ⚡ from @sam". It isn't a reward: it is posted after the completion's rewards are saved, and a post that fails never undoes them. Each post is retried, shows on the member's page in Console with its status, and can be retried there once it fails for good. Posts in one chat or channel wait in line, paced to what Telegram and Discord allow.

The message comes from a template with a few placeholders: the member who earned, whoever triggered the completion (such as the admin who tipped), the points paid and the quest's title. People are mentioned through the account they linked on that platform. A Test environment posts only in its own connected chats and channels. See Announce tips in the group and Announce in a channel.

Shared SDK runtime

Quests import the installed SDK instead of each carrying their own copy, so a published quest is a few kilobytes and always runs with the SDK version it was built against. Each published bundle also declares the evaluator protocol it expects. See shared SDK runtime and evaluator protocol.

Activity and webhooks

Your app can show members what just happened, such as a review decision, an accepted attempt or a reward change, including completions of quests that ran on their own.

Resource lifecycle

The other things your quests use, such as trackers, leaderboards and point ledgers, can be archived too. Archive one when new activity should stop but its history should stay. Archive state belongs to one project and environment, and live changes it only through promotion.

Removing a declaration from source does not archive it, and deploying it again does not restore it. Unarchive it in Settings → Resources. A quest has its own archive controls. Archiving a reusable quest type does not archive its existing quest instances. Changes to archive state invalidate an earlier publication preview; review again before publishing.

Outcomes for prerequisite-only automatic quests

A quest with only prerequisites checks a member again whenever something changes that could qualify them: a completion, joining a group, enrolling in a campaign, a publication, or a freed occurrence. Any change to their points, such as a quest or referral award, a leaderboard prize, spending, a refund or an operator adjustment, also queues a check of their current balance.

Each check is recorded as admitted or skipped:

Your team can recover up to 50 paused or budget-blocked outcomes at once, after a preview of the new checks, rewards and budget capacity. See Recover automatic quest outcomes.

Where next