Events Rewards

Reward Lifecycle

1. Event Creation

   • Rewards are pre-configured using the EventRewardType schema

2. User Participation

   • Users participate in the event

   • Become eligible for rewards based on criteria (e.g., leaderboard rank)

3. Reward Allocation

   • Eligible users receive reward allocations

   • Allocations can be fetched via useQuestEventRewardAllocations hook

4. Reward Claim

   • Users claim rewards after event conclusion

   • Claims processed using claimRewardAllocation mutation

Event Reward Structure

Type Definition

type EventRewardType = {
  eventRewardId: string;                // Unique identifier for the event reward
  name: string;                         // Display name of the reward
  resolutionType: QuestEventRewardResolutionType; // Type of resolution (e.g., based on rank or other criteria)
  resolutionValueRange: ResolutionValueType;      // Range of leaderboard ranks eligible for the reward
  rewardId: string;                     // Unique identifier for the reward entity
  reward: EventGiveResourcesReward | EventGiveAssetsReward; // Reward details (e.g., resources or assets)
  rewardHandlerArgs: EventGiveResourcesRewardHandler | EventGiveAssetsRewardHandler; // Backend handling configuration
  eventId: string;                      // ID of the associated event
  createdAt: Date;                      // Timestamp when the reward was created
  updatedAt: Date;                      // Timestamp when the reward was last updated
};

Key Fields Explained

• eventRewardId: Unique identifier for this specific reward in the event

• resolutionType: Specifies the reward's resolution method

• resolutionValueRange: Defines eligible leaderboard ranks

• reward: Contains actual reward data (resources or assets)

  • EventGiveResourcesReward: Virtual currencies, tokens, or points

  • EventGiveAssetsReward: In-game items, badges, or other assets

• rewardHandlerArgs: Configuration for reward distribution logic

• eventId: Associated event identifier

Example Configuration

const exampleReward: EventRewardType = {
  eventRewardId: "reward-12345",
  name: "Top Performer Reward",
  resolutionType: QUEST_EVENT_REWARD_RESOLUTION_TYPE.LEADERBOARD_RANK,
  resolutionValueRange: { start: 1, end: 3 }, // Reward for ranks 1–3
  rewardId: "resource-56789",
  reward: { resourceType: "COINS", amount: 1000 }, // 1000 coins
  rewardHandlerArgs: { ..., rarity: "mythic" }, // Unschematized field depending on item type
  eventId: "event-67890",
  createdAt: new Date(),
  updatedAt: new Date(),
};

Fetching Reward Allocations

Use the useQuestEventRewardAllocations hook to fetch user-specific reward allocations.

Hook Implementation

import { useQuestEventRewardAllocations } from "@xborglabs/ui-shared/dist/client";

const App = () => {
  const { data: rewardAllocations, status } = useQuestEventRewardAllocations({
    eventId: "event-67890",
    userId: "user-12345",
  });
  
  if (status === "pending") {
    return <p>Loading rewards...</p>;
  }
  
  if (status === "error") {
    return <p>Failed to fetch rewards.</p>;
  }
  
  return (
    <div>
      {rewardAllocations.map((allocation) => (
        <div key={allocation.rewardAllocationId}>
          <p>Reward: {allocation.rewardConfiguration.name}</p>
          <p>Status: {allocation.claimStatus}</p>
        </div>
      ))}
    </div>
  );
}

Allocation Type Definition

type QuestEventRewardAllocationsType = {
  rewardAllocationId: string;          // Unique identifier for the reward allocation
  type: "QUEST_EVENT";                 // The type of allocation (always QUEST_EVENT)
  userId: string;                      // The user receiving the reward
  rewardConfiguration: RewardConfigurationBaseSchema; // Configuration of the reward
  claimStatus: "CLAIMED" | "ALLOCATED"; // Whether the reward is claimed or still allocated
  distributionStatus: "DISTRIBUTED" | "ALLOCATED"; // Whether the reward is distributed or just allocated
  requirementSubmission: object;       // Requirement data for reward allocation (TBD)
  rewardConfigurationId: string;       // ID linking to the reward configuration
  eventId: string;                     // ID of the associated event
  createdAt: string;                   // Timestamp of allocation creation
  updatedAt: string;                   // Timestamp of last update
};

Example Allocation Data

const exampleAllocation = {
  rewardAllocationId: "allocation-123",
  type: "QUEST_EVENT",
  userId: "user-12345",
  rewardConfiguration: {
    name: "Participation Reward",
    rewardType: "COINS",
    amount: 500,
  },
  claimStatus: "ALLOCATED",
  distributionStatus: "ALLOCATED",
  requirementSubmission: {},
  rewardConfigurationId: "config-456",
  eventId: "event-67890",
  createdAt: "2024-01-01T00:00:00Z",
  updatedAt: "2024-01-02T00:00:00Z",
};

Claiming Rewards

Use the useMutateQuestEventReward hook to handle reward claims after event conclusion.

Implementation Example

import { useMutateQuestEventReward } from "@xborglabs/ui-shared/dist/client";

const App = () => {
  const { mutate: claimRewardAllocation, isPending: isClaiming } = useMutateQuestEventReward();
  
  function handleClaim(rewardAllocationId: string) {
    claimRewardAllocation(rewardAllocationId, {
      onSuccess: () => {
        console.log("Reward claimed successfully!");
      },
      onError: (error) => {
        console.error("Failed to claim reward:", error);
      },
    });
  }

  return (
    <div>
      {rewardAllocations.map((allocation) => (
        <div key={allocation.rewardAllocationId}>
          <p>Reward: {allocation.rewardConfiguration.name}</p>
          <button
            onClick={() => handleClaim(allocation.rewardAllocationId)}
            disabled={allocation.claimStatus === "CLAIMED" || isClaiming}
          >
            {allocation.claimStatus === "CLAIMED" ? "Claimed" : "Claim Reward"}
          </button>
        </div>
      ))}
    </div>
  );
}

Best Practices

1. Type Safety

   • Use TypeScript types for reward and allocation handling

   • Validate reward data structure before display

2. Error Handling

   • Implement proper error handling for claim operations

   • Show appropriate loading and error states

3. User Experience

   • Display clear claim status to users

   • Disable claim buttons for already claimed rewards

   • Show loading state during claim operations