Core Concepts
This page gives you the mental model for how ICQuests works under the hood.
Keep these terms in mind while you integrate your dApp.
1 Actors
Actor | Role |
---|---|
User | Anyone with a NFID Wallet who completes quests. |
dApp Canister | Your smart‑contract canister where the quest action happens and where you expose the verification method. |
ICQuests Canister | A public canister that stores quests, records XP, and calls your verification method. |
2 Quest
A Quest is a single actionable task a user performs inside your dApp.
Quest Type (Motoko)
type Quest = {
id : Nat;
title : Text;
subtitle : Text;
description : Text;
rewardXp : Nat;
campaignId : Nat;
tags : [Text];
estimatedTime : Text;
difficulty : Nat;
prerequisites : Text;
};
Example Quest (JSON)
{
"id": 1,
"title": "Swap at least 100 ICP",
"subtitle": "First big swap",
"description": "Make a swap worth ≥ 100 ICP on Sonic.",
"rewardXp": 400,
"campaignId": 10,
"tags": ["swap", "ICP", "sonic"],
"estimatedTime": "5 min",
"difficulty": 3,
"prerequisites": "None"
}
3 Campaign
A Campaign is a group of quests, usually for a specific partner or event.
Campaign Type (Motoko)
type Campaign = {
id : Nat;
title : Text;
image : Text;
description : Text;
logo : Text;
isActive : Bool;
partnerUrl : Text;
category : Text;
};
Example Campaign (JSON)
{
"id": 10,
"title": "Sonic Launch Campaign",
"image": "https://example.com/banner.png",
"description": "Complete Sonic quests to earn exclusive rewards!",
"logo": "https://example.com/logo.png",
"isActive": true,
"partnerUrl": "https://sonic.ooo",
"category": "DeFi"
}
4 XP (Experience Points)
- Purpose – Quantifies user engagement across all partner dApps.
- Persistence – Stored in the ICQuests canister keyed by
principal
.
Formula: XP is fixed per quest
5 Principal
Principal
is the canonical identity on the Internet Computer.
ICQuests passes the user's principal to your canister; you never need any other identifier.
6 Verification Method
You must expose a read‑only query
function that returns bool
.
#[ic_cdk::query]
fn verify_quest(principal: Principal, quest_id: String) -> bool
Common Patterns
Pattern | When to use | Example |
---|---|---|
Boolean | Simple yes/no actions | Has the user staked at least once? |
List Contains | Pre‑compute a set on your side | Is the principal in completedSwaps ? |
Custom Logic | Numeric thresholds, NFT checks, etc. | user_volume(principal) >= 100_000 |
Return false
on any error to avoid panics.
7 Quest Lifecycle
Quest Lifecycle Steps:
- Define – Submit metadata & deploy/upgrade your verification method.
- List – ICQuests re-deploys with a new quest listed.
- Act – Users complete the action.
- Verify – ICQuests queries your canister.
- Reward – XP is minted immutably.
8 Security Model
- Verification calls are query — no state mutation.
- Calls originate from ICQuests principal:
lyo6x-saaaa-aaaao-qjwlq-cai
(mainnet)
Whitelist if you restrict cross‑canister queries. - ICQuests stores only quest IDs, XP values, and principals—no PII.
Next Up
Ready to integrate? Continue to Integration Guide ▸ Requirements or jump directly to Quest Definition.