Skip to main content

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

ActorRole
UserAnyone with a NFID Wallet who completes quests.
dApp CanisterYour smart‑contract canister where the quest action happens and where you expose the verification method.
ICQuests CanisterA 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

PatternWhen to useExample
BooleanSimple yes/no actionsHas the user staked at least once?
List ContainsPre‑compute a set on your sideIs the principal in completedSwaps?
Custom LogicNumeric 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.