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:

1. Define – Submit metadata & deploy/upgrade your verification method.
2. List – ICQuests re-deploys with a new quest listed.
3. Act – Users complete the action.
4. Verify – ICQuests queries your canister.
5. 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.